Template MCP Server

🚀 Python MCP 服務器模板

這是一個用於創建和管理 MCP (Model Context Protocol) 服務器的通用 Python 模板。它遵循生產環境中 MCP 服務器的最佳實踐，提供結構化開發框架，能幫助開發者快速啟動項目。

🚀 快速開始

項目結構

template-mcp-server/
├── src/
│   ├── server.py                 # 主程序入口
│   └── mcp_server/              # 核心功能包
│       ├── config.py            # 配置加載與管理
│       ├── logger.py            # 日誌模塊
│       ├── service_client.py    # 服務客戶端實現
│       └── errors.py           # 定義自定義錯誤類
├── requirements.txt          # 項目依賴管理
└── .env.example              # 環境變量示例文件

安裝依賴

pip install -r requirements.txt

✨ 主要特性

• 結構清晰：提供了完整的代碼目錄結構和文件示例。
• 日誌系統：集成了靈活的日誌記錄機制，默認支持 INFO 級別日誌。
• 配置管理：使用 Pydantic 模型進行配置管理和環境變量處理。
• 錯誤處理：實現了統一的錯誤捕捉和響應機制。
• 服務狀態：提供了服務初始化和清理流程，確保資源管理正確。

📦 安裝指南

安裝依賴的命令如下：

pip install -r requirements.txt

💻 使用示例

基礎用法

環境變量配置

通過設置以下環境變量來配置服務器行為：

• SERVICE_API_KEY：你的服務 API 密鑰（必填）
• SERVICE_ENDPOINT：服務端點 URL（默認: https://api.example.com）
• SERVICE_TIMEOUT：請求超時時間（單位：秒，默認: 30）
• LOG_LEVEL：日誌級別（默認: INFO）

啟動服務器

# 基本啟動方式
python src/server.py

# 設置自定義配置
SERVICE_API_KEY=test python src/server.py

高級用法

配置管理

使用 Pydantic 模型加載和驗證配置：

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", ""])

日誌系統

實現一個簡單的日誌記錄類：

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)

服務客戶端

實現一個通用的服務客戶端：

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)}")

📚 詳細文檔

測試指南

手動測試

# 基本運行
python src/server.py

# 以 DEBUG 級別啟動
LOG_LEVEL=DEBUG python src/server.py

集成測試

編寫集成測試用例：

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()

資源

• FastAPI 官方文檔
• Pydantic 官方文檔
• HttpX 官方文檔

最佳實踐

代碼風格

遵循 PEP8 和 Google Python 代碼風格指南。

文檔編寫

為所有公共 API 編寫詳細的註釋和使用說明。

版本控制

採用 Semantic Versioning (MAJOR.MINOR.PATCH) 規範進行版本管理。

📄 許可證

MIT License

通過遵循此模板，你可以快速搭建一個穩定、可靠的 MCP 服務器，滿足各種業務需求。