MCP Platform

# MCP Backend OpenRouter A high-performance chatbot platform connecting MCP servers with LLM APIs for intelligent tool execution. ## 🚀 Quick Start ```bash # Install dependencies uv install # Start the platform uv run python src/main.py # Reset configuration to defaults uv run mcp-reset-config ``` **Connect:** `ws://localhost:8000/ws/chat` ## 📡 WebSocket API ### Send Messages ```json { "type": "user_message", "message": "Hello, how can you help me today?" } ``` ### Receive Responses ```json { "type": "assistant_message", "message": "I'm here to help! What would you like to know?", "thinking": "The user is greeting me...", "usage": { "prompt_tokens": 15, "completion_tokens": 12, "total_tokens": 27 } } ``` ### Message Types | Type | Purpose | Payload | |------|---------|---------| | `user_message` | Send user input | `{"type": "user_message", "message": "text"}` | | `clear_history` | Start new session | `{"type": "clear_history"}` | | `assistant_message` | AI response | `{"type": "assistant_message", "message": "text", "thinking": "reasoning"}` | | `tool_execution` | Tool status | `{"type": "tool_execution", "tool_name": "name", "status": "executing"}` | ## ⚙️ Configuration ### Essential Settings (`src/runtime_config.yaml`) ```yaml chat: websocket: port: 8000 # WebSocket server port service: max_tool_hops: 8 # Maximum tool call iterations streaming: enabled: true # Enable streaming responses storage: persistence: db_path: "chat_history.db" retention: max_age_hours: 24 max_messages: 1000 llm: active: "openrouter" # Active LLM provider providers: openrouter: base_url: "https://openrouter.ai/api/v1" model: "openai/gpt-4o-mini" temperature: 0.7 max_tokens: 4096 ``` ### MCP Servers (`servers_config.json`) ```json { "mcpServers": { "demo": { "enabled": true, "command": "uv", "args": ["run", "python", "Servers/config_server.py"], "cwd": "/path/to/your/project" } } } ``` ## 🔧 Performance Tuning ### Streaming Optimization ```yaml chat: service: streaming: persistence: persist_deltas: false # Maximum speed (no DB writes during streaming) interval_ms: 200 # Flush every 200ms min_chars: 1024 # Or when buffer reaches 1024 chars ``` ### HTTP/2 Support ```bash uv add h2 # Required for HTTP/2 optimization ``` ## 🛠️ Development ### Code Standards - Use `uv` for package management - Pydantic for data validation - Type hints required - Fail-fast error handling ### Available Scripts ```bash uv run python src/main.py # Start platform uv run python scripts/format.py # Format code uv run mcp-reset-config # Reset configuration ``` ### Code Formatting ```bash # Quick format (ignores line length issues) ./format.sh # Full check including line length uv run ruff check src/ # Format specific files uv run ruff format src/chat/ src/clients/ ``` ## 📁 Project Structure ``` MCP_BACKEND_OPENROUTER/ ├── src/ # Main source code │ ├── main.py # Application entry point │ ├── config.py # Configuration management │ ├── websocket_server.py # WebSocket communication │ ├── chat/ # Chat system modules │ ├── clients/ # LLM and MCP clients │ └── history/ # Storage and persistence ├── Servers/ # MCP server implementations ├── config.yaml # Default configuration ├── runtime_config.yaml # Runtime overrides ├── servers_config.json # MCP server config └── uv.lock # Dependency lock file ``` ## 🔑 Environment Variables ```bash # Required for LLM APIs export OPENAI_API_KEY="your-key" export OPENROUTER_API_KEY="your-key" export GROQ_API_KEY="your-key" ``` ## 🚨 Troubleshooting ### Common Issues | Problem | Solution | |---------|----------| | Configuration not updating | Check file permissions on `runtime_config.yaml` | | WebSocket connection fails | Verify server is running and port is correct | | MCP server errors | Check `servers_config.json` and server availability | | LLM API issues | Verify API keys and model configuration | ### Debug Mode ```yaml # In runtime_config.yaml logging: level: "DEBUG" ``` ### Component Testing ```python # Test configuration from src.config import Configuration config = Configuration() print(config.get_config_dict()) # Test LLM client from src.clients.llm_client import LLMClient llm = LLMClient(config.get_llm_config()) ``` ## ✅ Features - **Full MCP Protocol** - Tools, prompts, resources - **High Performance** - SQLite with WAL mode, optimized indexes - **Real-time Streaming** - WebSocket with delta persistence - **Multi-Provider** - OpenRouter (100+ models), OpenAI, Groq - **Type Safe** - Pydantic validation throughout - **Dynamic Configuration** - Runtime changes without restart - **Auto-Persistence** - Automatic conversation storage ## 📚 Quick Reference | Command | Purpose | |---------|---------| | `uv run python src/main.py` | Start the platform | | `uv run mcp-reset-config` | Reset to default config | | Edit `runtime_config.yaml` | Change settings (auto-reload) | | Edit `servers_config.json` | Configure MCP servers | ## 🆘 Support - Check logs for detailed error messages - Verify configuration syntax with YAML validator - Test individual components for isolation - Monitor WebSocket connections and database size --- **Requirements:** Python 3.13+, `uv` package manager