mcpware: Instructions file for Claude Code

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

# 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

# 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

# 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