mcpware

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is **mcpware** - a Python-based MCP (Model Context Protocol) Gateway Server that routes requests to multiple backend MCP servers. The primary purpose is to bypass tool limits in MCP clients by providing a single entry point to access multiple backend services. ## Key Architecture ### Core Components - **`gateway_server.py`** - Main entry point with async stdio handling and signal management - **`src/mcp_protocol_handler.py`** - Handles MCP protocol operations and message routing - **`src/backend_forwarder.py`** - Manages request forwarding to backend servers - **`src/config.py`** - Configuration management with environment variable substitution - **`src/jsonrpc_handler.py`** - JSON-RPC request/response handling ### Request Flow 1. MCP client sends request via stdio → gateway_server.py 2. JSONRPCHandler parses request → routes to MCPProtocolHandler 3. MCPProtocolHandler determines backend → BackendForwarder executes 4. Backend response flows back through the same chain ### Backend Management - Backends are configured in `config.json` with command/args/env - Each backend runs as a separate process (Docker containers, npm packages, etc.) - Gateway manages backend lifecycle and handles process communication via stdio ## Common Development Commands ### Setup and Installation ```bash # Install dependencies make install # or pip install -r requirements.txt # Create virtual environment (recommended) python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` ### Testing ```bash # Run all tests make test # or pytest # Run tests with coverage pytest --cov=src --cov=gateway_server --cov-report=html # Run specific test file pytest tests/test_config.py # Run in watch mode (requires pytest-watch) pytest-watch ``` ### Development ```bash # Run locally (requires config.json) python gateway_server.py --config config.json # Run with debug logging python gateway_server.py --config config.json --log-level DEBUG # Clean build artifacts make clean ``` ### Docker ```bash # Build Docker image docker build -t mcpware . --no-cache # Run with config docker run -it --rm \ -v $(pwd)/config.json:/app/config.json:ro \ -v /var/run/docker.sock:/var/run/docker.sock \ --env-file .env \ mcpware ``` ## Configuration ### Backend Configuration (`config.json`) Backends are defined with: - `command`: Executable to run (docker, npx, python, etc.) - `args`: Arguments array for the command - `env`: Environment variables (supports `${VAR}` substitution) - `description`: Optional description - `timeout`: Optional timeout in seconds ### Environment Variables Create `.env` file with: ```bash GITHUB_PERSONAL_ACCESS_TOKEN=your_token BUILDKITE_API_TOKEN=your_token # Add other backend-specific tokens ``` ## Testing Strategy ### Test Structure - **Unit tests**: `tests/test_*.py` - Test individual components - **Integration tests**: Test backend communication and request routing - **Configuration tests**: Test config loading and environment substitution ### Test Configuration - Uses pytest with asyncio support - Coverage target: 87%+ (current achievement) - Tests run in Docker CI environment ### Key Test Files - `tests/test_config.py` - Configuration loading and validation - `tests/test_backend.py` - Backend communication - `tests/test_protocol.py` - Protocol handling - `tests/test_gateway_server.py` - Main server functionality ## Important Implementation Details ### Async Architecture - All I/O operations are async/await based - Uses asyncio for concurrent backend communication - Proper resource cleanup with context managers ### Error Handling - Comprehensive error handling with custom exceptions - Graceful shutdown with signal handling (SIGTERM, SIGINT) - Backend process management with cleanup ### Security - Environment variable substitution prevents secret exposure - Docker socket access required for Docker-based backends - No secrets stored in configuration files ### Backend Types Supported Current backends in `config.json`: - **github**: GitHub MCP Server via npm - **buildkite**: CI/CD pipeline integration - **redis-banners**: Redis banner management - **opensearch-mcp-server**: Search engine integration - **sequential-thinking**: Logical reasoning backend - **memory**: Persistent memory backend - **rollbar**: Error tracking integration ## Development Notes ### Code Style - Uses Python standard library where possible - Minimal external dependencies (only testing frameworks) - Type hints throughout codebase - Comprehensive logging with structured messages ### Protocol Compliance - Implements MCP protocol specification - Handles JSON-RPC 2.0 requests/responses - Supports tool discovery and execution - Maintains session state for multi-request operations ### Performance Considerations - Concurrent backend communication - Process reuse for performance - Proper resource cleanup to prevent leaks - Timeout handling for backend requests