MCP Template

# MCP Template Production-ready MCP (Model Context Protocol) server template in Python with registry integration, comprehensive configuration management, and extensibility patterns. ## Features - **Production-Ready**: Enterprise-grade error handling, structured logging, and graceful shutdown - **Registry Integration**: Automatic server registration, heartbeats, and deregistration - **Configuration Management**: YAML-based config with environment variable overrides and Pydantic validation - **Extensible Architecture**: Easy-to-extend base classes for tools, resources, and prompts - **Type Safety**: Full type hints throughout the codebase - **Developer Experience**: Comprehensive CLI, extensive documentation, and example implementations - **Testing**: Unit and integration test examples with pytest ## Quick Start ### Installation ```bash # Clone or copy this template cd mcp-template # Create virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -e ".[dev]" # Or using requirements.txt pip install -r requirements-dev.txt ``` ### Initialize Configuration ```bash # Initialize default configuration mcp-template init # This creates: # - config/config.yaml (server configuration) # - .env (environment variables) ``` ### Run the Server ```bash # Run with default configuration mcp-template run # Run with custom config mcp-template run --config path/to/config.yaml # Run in debug mode mcp-template run --debug # Validate configuration mcp-template validate # Check health mcp-template health ``` ## Project Structure ``` mcp-template/ ├── src/mcp_template/ │ ├── core/ # Core server components │ │ ├── server.py # Base MCP server implementation │ │ ├── settings.py # Pydantic settings models │ │ ├── config_loader.py # Configuration loader │ │ └── logger.py # Structured logging setup │ ├── registry/ # Registry integration │ │ ├── base.py # Registry client interface │ │ ├── http_client.py # HTTP registry implementation │ │ └── manager.py # Registry lifecycle manager │ ├── tools/ # MCP tools │ │ ├── calculator.py # Example calculator tool │ │ └── search.py # Example search tool │ ├── resources/ # MCP resources │ │ ├── config.py # Configuration resource │ │ └── status.py # Status resource │ ├── prompts/ # MCP prompts │ │ └── example.py # Example prompt │ ├── app.py # Main application │ └── cli.py # Command-line interface ├── config/ │ └── config.yaml # Server configuration ├── tests/ │ ├── unit/ # Unit tests │ └── integration/ # Integration tests ├── pyproject.toml # Project metadata and dependencies ├── requirements.txt # Production dependencies ├── requirements-dev.txt # Development dependencies ├── Makefile # Development commands └── README.md # This file ``` ## Configuration ### Configuration File (config/config.yaml) The main configuration file supports: - **Server settings**: Name, version, description, debug mode - **Logging**: Level, format (JSON/text), file output - **Registry**: URL, authentication, heartbeat settings, metadata - **Tools/Resources/Prompts**: Enable/disable specific components Example: ```yaml server: name: "my-mcp-server" version: "0.1.0" description: "My custom MCP server" logging: level: "INFO" format: "json" registry: enabled: true url: "https://registry.example.com/api/v1" auth: type: "api_key" api_key: "${REGISTRY_API_KEY}" heartbeat: enabled: true interval: 60 tools: enabled: - "example_calculator" - "example_search" ``` ### Environment Variables Override configuration using environment variables with double underscore as separator: ```bash # Override server name export SERVER__NAME="production-server" # Override registry URL export REGISTRY__URL="https://prod-registry.example.com" # Set API key export REGISTRY__AUTH__API_KEY="your-api-key" # Override logging level export LOGGING__LEVEL="DEBUG" ``` ### Environment Variables File (.env) Create a `.env` file for local development: ```bash # Registry REGISTRY_API_KEY=your-api-key-here # Server overrides SERVER__DEBUG=false # Logging LOGGING__LEVEL=INFO ``` ## Adding Custom Components ### Adding a New Tool 1. Create a new file in `src/mcp_template/tools/`: ```python # src/mcp_template/tools/my_tool.py import mcp.types as types async def my_tool_handler(arguments: dict) -> str: """Handle the tool call.""" # Your implementation here return "Result" MY_TOOL_SCHEMA = types.Tool( name="my_tool", description="Description of what the tool does", inputSchema={ "type": "object", "properties": { "param1": { "type": "string", "description": "Parameter description" } }, "required": ["param1"] } ) ``` 2. Register it in `src/mcp_template/app.py`: ```python from .tools.my_tool import my_tool_handler, MY_TOOL_SCHEMA # In MCPTemplateApp._register_components(): self.server.register_tool( "my_tool", my_tool_handler, MY_TOOL_SCHEMA, ) ``` 3. Enable it in `config/config.yaml`: ```yaml tools: enabled: - "my_tool" ``` ### Adding a New Resource Similar pattern - create handler and schema, register in `app.py`, enable in config. ```python # src/mcp_template/resources/my_resource.py import mcp.types as types async def my_resource_handler(uri: str) -> str: """Handle resource read.""" return "Resource data" MY_RESOURCE_SCHEMA = types.Resource( uri="myresource://example", name="My Resource", description="Resource description", mimeType="application/json" ) ``` ### Adding a New Prompt ```python # src/mcp_template/prompts/my_prompt.py import mcp.types as types async def my_prompt_handler(arguments: dict) -> types.GetPromptResult: """Handle prompt request.""" return types.GetPromptResult( description="Prompt description", messages=[ types.PromptMessage( role="user", content=types.TextContent( type="text", text="Prompt text" ) ) ] ) MY_PROMPT_SCHEMA = types.Prompt( name="my_prompt", description="Prompt description", arguments=[ types.PromptArgument( name="arg1", description="Argument description", required=True ) ] ) ``` ## Registry Integration The template includes a pluggable registry system for server discovery and management. ### How It Works 1. **Registration**: On startup, server registers with the registry 2. **Heartbeat**: Periodic heartbeats maintain the registration 3. **Deregistration**: Graceful shutdown deregisters the server ### Custom Registry Backend Implement the `RegistryClient` interface for custom backends: ```python from mcp_template.registry.base import RegistryClient class MyRegistryClient(RegistryClient): async def register(self, server_info: dict) -> dict: # Your implementation pass async def deregister(self, server_id: str) -> bool: # Your implementation pass # Implement other methods... ``` Then use it in your application: ```python from mcp_template.registry.manager import RegistryManager registry_manager = RegistryManager(settings, client=MyRegistryClient()) ``` ## Development ### Setup Development Environment ```bash # Install with development dependencies pip install -e ".[dev]" # Or using make make install ``` ### Running Tests ```bash # Run all tests pytest # Run with coverage pytest --cov # Run only unit tests pytest tests/unit # Run only integration tests pytest tests/integration -m integration # Using make make test ``` ### Code Quality ```bash # Format code make format # Lint code make lint # Type check make typecheck # Run all checks make check ``` ### Pre-commit Hooks ```bash # Install pre-commit hooks pre-commit install # Run manually pre-commit run --all-files ``` ## Deployment ### Docker Create a `Dockerfile`: ```dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY src/ src/ COPY config/ config/ RUN pip install -e . CMD ["mcp-template", "run"] ``` Build and run: ```bash docker build -t mcp-template . docker run -e REGISTRY_API_KEY=your-key mcp-template ``` ### Environment-Specific Configuration Create different config files for each environment: ```bash config/ ├── config.yaml # Default ├── config.dev.yaml # Development ├── config.staging.yaml # Staging └── config.prod.yaml # Production ``` Run with specific config: ```bash mcp-template run --config config/config.prod.yaml ``` ## Monitoring and Observability ### Structured Logging All logs are structured (JSON format by default) for easy parsing: ```json { "timestamp": "2024-01-01T12:00:00.000Z", "level": "info", "event": "Server started", "server": "my-server", "version": "0.1.0" } ``` ### Health Checks ```bash # CLI health check mcp-template health # Programmatic health check from mcp_template.app import create_app app = create_app() health = await app.server.health_check() ``` ## Troubleshooting ### Common Issues **Configuration file not found** ```bash # Initialize configuration mcp-template init # Or specify path mcp-template run --config path/to/config.yaml ``` **Registry connection failed** ```bash # Check registry health mcp-template health # Disable registry temporarily # In config.yaml: registry: enabled: false ``` **Import errors** ```bash # Reinstall in editable mode pip install -e . ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests 5. Run code quality checks: `make check` 6. Submit a pull request ## License MIT License - see LICENSE file for details ## Resources - [MCP Documentation](https://modelcontextprotocol.io/) - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [Pydantic Documentation](https://docs.pydantic.dev/) - [Structlog Documentation](https://www.structlog.org/) ## Support For issues, questions, or contributions, please open an issue on GitHub.