Template MCP Server

🚀 Python MCP Server Template

This is a general Python template for creating and managing MCP (Model Context Protocol) servers. It follows the best practices of MCP servers in a production environment and provides a structured development framework to facilitate quick project startup.

🚀 Quick Start

Project Structure

template-mcp-server/
├── src/
│   ├── server.py                 # Main program entry
│   └── mcp_server/              # Core functionality package
│       ├── config.py            # Configuration loading and management
│       ├── logger.py            # Logging module
│       ├── service_client.py    # Service client implementation
│       └── errors.py           # Define custom error classes
├── requirements.txt          # Project dependency management
└── .env.example              # Example file for environment variables

Install Dependencies

pip install -r requirements.txt

✨ Features

• Clear Structure: Provides a complete code directory structure and file examples.
• Logging System: Integrates a flexible logging mechanism, supporting INFO-level logs by default.
• Configuration Management: Uses Pydantic models for configuration management and environment variable handling.
• Error Handling: Implements a unified error capturing and response mechanism.
• Service Status: Provides service initialization and cleanup processes to ensure correct resource management.

💻 Usage Examples

Configure Environment Variables

Configure the server behavior by setting the following environment variables:

• SERVICE_API_KEY: Your service API key (required).
• SERVICE_ENDPOINT: Service endpoint URL (default: https://api.example.com).
• SERVICE_TIMEOUT: Request timeout in seconds (default: 30).
• LOG_LEVEL: Logging level (default: INFO).

Start the Server

# Basic startup
python src/server.py

# Set custom configuration
SERVICE_API_KEY=test python src/server.py

📚 Documentation

Configuration Management

Use Pydantic models to load and validate configurations:

from pydantic import BaseSettings

class Settings(BaseSettings):
    api_key: str
    endpoint: str = "https://api.example.com"
    timeout: int = 30
    log_level: str = "INFO"

settings = Settings(_env_file=["./.env", ""])

Logging System

Implement a simple logging class:

import logging

class Logger:
    def __init__(self, name: str, level: int = logging.INFO):
        self.logger = logging.getLogger(name)
        self.logger.setLevel(level)
        handler = logging.StreamHandler()
        formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
        handler.setFormatter(formatter)
        self.logger.addHandler(handler)

    def info(self, message: str):
        self.logger.info(message)

    def error(self, message: str):
        self.logger.error(message)

    def debug(self, message: str):
        self.logger.debug(message)

Service Client

Implement a general service client:

import httpx

class ServiceClient:
    def __init__(self, endpoint: str, timeout: int):
        self.client = httpx.Client(base_url=endpoint, timeout=timeout)

    async def fetch_data(self, path: str) -> dict:
        try:
            response = await self.client.get(path)
            response.raise_for_status()
            return response.json()
        except Exception as e:
            raise ServiceError(f"Failed to fetch data from {path}: {str(e)}")

🧪 Testing Guide

Manual Testing

# Basic run
python src/server.py

# Start with DEBUG level
LOG_LEVEL=DEBUG python src/server.py

Integration Testing

Write integration test cases:

import pytest
from fastapi.testclient import TestClient

from server import app

client = TestClient(app)

def test_health_check():
    response = client.get("/health")
    assert response.status_code == 200
    assert "status" in response.json()

📚 Resources

• FastAPI Official Documentation
• Pydantic Official Documentation
• HttpX Official Documentation

🌟 Best Practices

Code Style

Follow the PEP8 and Google Python code style guides.

Documentation Writing

Write detailed comments and usage instructions for all public APIs.

Version Control

Adopt the Semantic Versioning (MAJOR.MINOR.PATCH) specification for version management.

📄 License

MIT License

By following this template, you can quickly set up a stable and reliable MCP server to meet various business needs.