SIM-ONE MCP Server

A Model Context Protocol (MCP) server providing cognitive AI tools from the SIM-ONE framework, including emotional analysis, logical reasoning, validation, and cognitive governance.

Features

• 13 Production-Ready Tools across 4 cognitive domains
• HTTP Transport with API key authentication
• STDIO Transport for local development
• SQLite Database for secure API key management
• All Tools Available via authenticated HTTP endpoints

Cognitive Domains

1. ESL (Emotional State Layer)

• esl_analyze_emotion - Multi-dimensional emotion detection
• esl_analyze_emotional_progression - Track emotional changes over time
• esl_generate_empathetic_response - Generate contextually appropriate responses

2. Five Laws Validator (Cognitive Governance)

• five_laws_validate_single_text - Validate AI responses against Five Laws
• five_laws_validate_batch - Batch validation with comparison
• five_laws_validate_iteratively - Iterative validation with refinement tracking

3. REP (Reasoning & Explanation Protocol)

• rep_perform_deductive_reasoning - Apply general rules to specific cases
• rep_perform_inductive_reasoning - Identify patterns from observations
• rep_perform_abductive_reasoning - Infer best explanations
• rep_perform_analogical_reasoning - Transfer knowledge across domains
• rep_perform_causal_reasoning - Identify cause-and-effect relationships
• rep_perform_integrated_reasoning - Apply all reasoning types comprehensively

4. VVP (Validation & Verification Protocol)

• vvp_validate_rules - Validate logical rule structures

Installation

Prerequisites

• Python 3.11+
• FastMCP 2.11.0+

Setup

1. Clone the repository

git clone https://github.com/dansasser/SIM-ONE-MCP.git
cd SIM-ONE-MCP

2. Install dependencies

pip install fastmcp

3. Generate your first API key

python src/manage_keys.py generate --name "My First Client"

Save the generated key securely - it won't be shown again!

Usage

HTTP Mode (Default)

Start the server with API key authentication:

python src/SIM-ONE_mcp.py

The server will start on http://0.0.0.0:8000/mcp/

Make authenticated requests:

curl -H "Authorization: Bearer sk-simone-xxxxxxxxxxxxxxxxxxxxx" \
     http://localhost:8000/mcp/

STDIO Mode (Local Development)

For local development without authentication:

python src/SIM-ONE_mcp.py --stdio

API Key Management

Generate New Key

python src/manage_keys.py generate --name "Production Client"

With metadata:

python src/manage_keys.py generate --name "Test Client" --metadata '{"env":"test","team":"qa"}'

List All Keys

python src/manage_keys.py list

Output:

================================================================================
ID    Name                      Created              Last Used            Active  
================================================================================
1     Production Client         2025-10-12 13:45:22  2025-10-12 14:30:15  ✓ Yes  
2     Test Client               2025-10-12 13:50:10  Never                ✓ Yes  
================================================================================
Total: 2 key(s)

Show Key Details

python src/manage_keys.py info --id 1

Revoke Key

python src/manage_keys.py revoke --id 2

Configuration

Environment Variables

Configure the server using environment variables:

# Database location
export SIMONE_DB_PATH="data/api_keys.db"

# Server host and port
export SIMONE_HOST="0.0.0.0"
export SIMONE_PORT="8000"

# Run server
python src/SIM-ONE_mcp.py

Custom Database Location

python src/manage_keys.py --db /path/to/custom.db generate --name "Client"

Production Deployment

Using Nginx Reverse Proxy

1. Configure Nginx (/etc/nginx/sites-available/simone-mcp):

server {
    listen 443 ssl http2;
    server_name mcp.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /mcp/ {
        proxy_pass http://127.0.0.1:8000/mcp/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. Enable site:

sudo ln -s /etc/nginx/sites-available/simone-mcp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

3. Start server:

python src/SIM-ONE_mcp.py

Your server is now accessible at https://mcp.yourdomain.com/mcp/

Using Systemd Service

Create /etc/systemd/system/simone-mcp.service:

[Unit]
Description=SIM-ONE MCP Server
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/SIM-ONE-MCP
Environment="SIMONE_HOST=127.0.0.1"
Environment="SIMONE_PORT=8000"
ExecStart=/usr/bin/python3 /home/ubuntu/SIM-ONE-MCP/src/SIM-ONE_mcp.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable simone-mcp
sudo systemctl start simone-mcp
sudo systemctl status simone-mcp

Security

API Key Security

• Cryptographically Secure Generation: Uses secrets.token_urlsafe(32) for 256-bit entropy
• Hashed Storage: Keys stored as SHA-256 hashes, never plaintext
• One-Time Display: Keys shown only once during generation
• Revocation Support: Keys can be deactivated without deletion
• Audit Trail: last_used_at timestamps track key usage

Best Practices

1. Never commit API keys to version control
2. Use HTTPS in production (nginx/caddy with SSL)
3. Rotate keys regularly (revoke old, generate new)
4. Use unique keys per client for better audit trails
5. Store keys securely (environment variables, secrets manager)
6. Monitor key usage via last_used_at timestamps

Database Security

The SQLite database (data/api_keys.db) contains hashed keys and is excluded from git via .gitignore.

Backup recommendations:

# Backup database
cp data/api_keys.db data/api_keys.db.backup

# Restore from backup
cp data/api_keys.db.backup data/api_keys.db

Architecture

File Structure

SIM-ONE-MCP/
├── src/
│   ├── SIM-ONE_mcp.py          # Main server with HTTP/STDIO transport
│   ├── auth/                    # Authentication module
│   │   ├── __init__.py
│   │   ├── api_key_db.py       # SQLite database manager
│   │   └── api_key_verifier.py # FastMCP auth integration
│   ├── manage_keys.py           # CLI tool for key management
│   └── tools/                   # Tool implementations
│       ├── esl_emotional_analysis_tutorial.py
│       ├── five_laws_validator_tutorial.py
│       ├── rep_reasoning_tutorial.py
│       └── vvp_validation_tutorial.py
├── data/                        # Database directory (gitignored)
│   └── api_keys.db             # SQLite database
├── tmp/                         # Tool input/output files
│   ├── inputs/
│   └── outputs/
└── README.md

Authentication Flow

1. Client sends request with Authorization: Bearer sk-simone-... header
2. FastMCP extracts token and calls APIKeyVerifier.verify_token()
3. Verifier hashes token and queries SQLite database
4. If valid and active, updates last_used_at and returns user info
5. FastMCP allows request to proceed to tools
6. If invalid, FastMCP returns 401 Unauthorized

Transport Modes

Mode	Command	Authentication	Use Case
HTTP	python src/SIM-ONE_mcp.py	API Key Required	Production, remote access
STDIO	python src/SIM-ONE_mcp.py --stdio	None (local security)	Local development, testing

Troubleshooting

Server won't start

Error: ModuleNotFoundError: No module named 'fastmcp'

Solution:

pip install fastmcp

Authentication fails

Error: 401 Unauthorized

Check:

1. API key is valid: python src/manage_keys.py list
2. Key is active (not revoked)
3. Header format: Authorization: Bearer sk-simone-...
4. No extra spaces or newlines in key

Database locked

Error: sqlite3.OperationalError: database is locked

Solution:

# Close any open connections
pkill -f manage_keys.py

# If persists, restart server
pkill -f SIM-ONE_mcp.py
python src/SIM-ONE_mcp.py

Port already in use

Error: OSError: [Errno 98] Address already in use

Solution:

# Find process using port 8000
lsof -i :8000

# Kill process
kill -9 <PID>

# Or use different port
export SIMONE_PORT=8001
python src/SIM-ONE_mcp.py

Development

Running Tests

# Test key generation
python src/manage_keys.py generate --name "Test"

# Test server startup
python src/SIM-ONE_mcp.py &
SERVER_PID=$!

# Test authentication (replace with your key)
curl -H "Authorization: Bearer sk-simone-..." http://localhost:8000/mcp/

# Cleanup
kill $SERVER_PID

Adding New Tools

Tools are automatically mounted from the tools/ directory. To add new tools:

1. Create tool file in src/tools/
2. Import in src/SIM-ONE_mcp.py
3. Mount using mcp.mount(new_tool_mcp)

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

License

This project is part of the SIM-ONE framework. See the main SIM-ONE repository for license information.

Related Projects

• SIM-ONE Framework - Core cognitive framework
• FastMCP - MCP server framework

Support

For issues, questions, or contributions:

• Open an issue on GitHub
• See the SIM-ONE documentation

Changelog

v2.0.0 - HTTP Transport with Authentication

• Added HTTP transport support
• Implemented SQLite-based API key authentication
• Created key management CLI
• Maintained backward compatibility with STDIO mode
• Added comprehensive documentation

v1.0.0 - Initial Release

• 13 cognitive tools from SIM-ONE framework
• STDIO transport
• Basic tool implementations