FORUS Cortex Agent MCP Server

A production-ready Model Context Protocol (MCP) server that exposes the FORUS Cortex Agent's tools and capabilities to external LLM applications.

🌟 Features

• Memory Search: Semantic search across agent's FAISS vector database
• Knowledge Base: Query Master Services Agreement documents
• Code Execution: Safe Python and shell command execution
• System Monitoring: Real-time server and resource status
• MCP Compliance: Full JSON-RPC 2.0 protocol implementation
• Security Ready: Authentication hooks and input validation

🚀 Quick Start

Prerequisites

• Python 3.9+
• Access to FORUS Cortex Agent memory database
• Network access for HTTP server

Installation

# Clone the repository
git clone https://github.com/SingularityAI-Dev/FORUS-Cortex-MCP-Server.git
cd FORUS-Cortex-MCP-Server

# Install dependencies
pip install -r requirements.txt

# Start the server
python server.py

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# Or run directly
docker build -t forus-mcp-server .
docker run -p 8083:8083 forus-mcp-server

📡 API Usage

Server Information

curl http://localhost:8083/

List Available Tools

curl -X POST http://localhost:8083/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Execute a Tool

curl -X POST http://localhost:8083/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "memory_search",
      "arguments": {
        "query": "FORUS business model",
        "limit": 5
      }
    }
  }'

🛠️ Available Tools

Tool	Description	Parameters
memory_search	Search agent memory using semantic similarity	query, limit, area
query_msa	Query Master Services Agreement documents	query
execute_python	Execute Python code safely	code, timeout
execute_shell	Execute whitelisted shell commands	command, timeout
get_system_status	Get server and system status	None
list_mcp_tools	List all available tools	None

🔌 Client Integration

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "forus-cortex": {
      "command": "python",
      "args": ["/path/to/server.py", "--stdio"]
    }
  }
}

VS Code/Cursor

Create .vscode/mcp.json:

{
  "mcpServers": {
    "forus-cortex": {
      "url": "http://localhost:8083/mcp"
    }
  }
}

Python Client

import requests
import json

def call_mcp_tool(tool_name, **kwargs):
    response = requests.post('http://localhost:8083/mcp', json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": tool_name,
            "arguments": kwargs
        }
    })
    return response.json()

# Usage
result = call_mcp_tool("memory_search", query="FORUS", limit=3)
print(json.dumps(result, indent=2))

🏗️ Architecture

┌─────────────────────────────────────────────┐
│         External LLM Applications           │
└──────────────────┬──────────────────────────┘
                   │ MCP Protocol (JSON-RPC)
                   ↓
┌─────────────────────────────────────────────┐
│          FORUS MCP Server                   │
│  ┌─────────────────────────────────────┐   │
│  │     JSON-RPC Handler                │   │
│  └─────────────────────────────────────┘   │
│  ┌─────────────────────────────────────┐   │
│  │     Tool Registry & Router          │   │
│  └─────────────────────────────────────┘   │
│  ┌─────────────────────────────────────┐   │
│  │     Agent Context Manager           │   │
│  └─────────────────────────────────────┘   │
└──────────────────┬──────────────────────────┘
                   │
    ┌──────────────┴──────────────┐
    ↓                              ↓
┌───────────────┐          ┌───────────────┐
│ Memory Tools  │          │ Knowledge DB  │
│   - FAISS     │          │   - Qdrant    │
│   - Embeddings│          │   - MSA Docs  │
└───────────────┘          └───────────────┘
    ↓                              ↓
┌───────────────┐          ┌───────────────┐
│ Code Execute  │          │ System Tools  │
│   - Python    │          │   - Scheduler │
│   - Shell     │          │   - Browser   │
└───────────────┘          └───────────────┘

🔐 Security

Current Features

• Input validation on all tools
• Whitelisted shell commands only
• Sandboxed code execution
• Request timeout protection
• CORS support

Production Recommendations

• Enable API key authentication
• Add rate limiting per client
• Use HTTPS with SSL certificates
• Implement request logging and monitoring
• Set up firewall rules

Authentication Setup (Future)

# Add bearer token authentication
headers = {"Authorization": "Bearer your-api-token"}
response = requests.post(
    "https://your-server.com/mcp",
    headers=headers,
    json=request_data
)

📊 Configuration

Environment Variables

Variable	Description	Default
MCP_HOST	Server bind address	0.0.0.0
MCP_PORT	Server port	8083
MEMORY_PATH	Path to memory index	./memory/default/index.pkl
LOG_LEVEL	Logging level	INFO
AUTH_ENABLED	Enable authentication	false

Custom Configuration

Create config.yaml:

server:
  host: "0.0.0.0"
  port: 8083
  
security:
  auth_enabled: false
  rate_limit: 100
  allowed_origins:
    - "http://localhost:*"
  
tools:
  memory:
    enabled: true
    index_path: "./memory/default/index.pkl"
  execution:
    python_timeout: 30
    shell_timeout: 10
    allowed_commands:
      - ls
      - pwd
      - echo
      - cat
      - head
      - tail

🧪 Testing

Unit Tests

python -m pytest tests/

Manual Testing

# Test server health
python examples/test_server.py

# Test with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8083/mcp

Load Testing

# Install artillery
npm install -g artillery

# Run load test
artillery run load-test.yml

🚀 Deployment

Production Deployment

1. Set up SSL certificate:

   sudo certbot --nginx -d mcp.yourdomain.com

2. Configure reverse proxy (Nginx):

   server {
       listen 443 ssl;
       server_name mcp.yourdomain.com;
       
       location / {
           proxy_pass http://localhost:8083;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }

3. Run with process manager:

   # With PM2
   pm2 start server.py --name mcp-server --interpreter python3
   
   # With systemd
   sudo systemctl enable mcp-server
   sudo systemctl start mcp-server

Cloud Deployment

Google Cloud Run

gcloud run deploy mcp-server \
    --source . \
    --platform managed \
    --region us-central1 \
    --allow-unauthenticated

AWS Lambda

# Package and deploy with Serverless
serverless deploy

Vercel

# Deploy with Vercel CLI
vercel deploy

📈 Monitoring

Metrics Collection

• Request/response latency
• Tool execution times
• Error rates and types
• Memory usage patterns
• Concurrent connection counts

Health Checks

# Basic health check
curl -f http://localhost:8083/ || exit 1

# Tool availability check
curl -X POST http://localhost:8083/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Logging

• Structured JSON logging
• Request/response logging
• Error tracking with stack traces
• Performance metrics logging

🤝 Contributing

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

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest

# Run linting
flake8 .

# Format code
black .

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Check the examples directory
• Issues: Report bugs or request features via GitHub Issues
• Discussions: Join the conversation in GitHub Discussions
• Email: Contact rain.singlesource@gmail.com

🏆 Acknowledgments

• Built for the FORUS Cortex Agent ecosystem
• Implements the official Model Context Protocol
• Inspired by the MCP community and best practices
• Special thanks to the open-source MCP tools and examples

---

📊 Stats

🌟 Star this repo if you find it useful!