Python MCP Server Template

Python MCP 服务模板

用于使用 Python 创建 VS Code Model Context Protocol（MCP）服务的模板仓库。此模板遵循生产级 MCP 服务所确立的模式和最佳实践。

用途

此模板为构建 MCP 服务提供基础：

• 与 VS Code 的 AI 功能集成
• 遵循生产级 MCP 服务中确立的模式
• 以一致的方式处理配置、日志记录和错误情况
• 遵循异步 Python 和 MCP 工具的最佳实践

架构

此模板遵循生产级 MCP 服务中常见的以下关键架构模式：

1. 服务配置

   • 使用 Pydantic 模型验证配置
   • 基于环境变量进行配置
   • 在服务生命周期中初始化服务客户端

2. 服务生命周期

   • 使用异步上下文管理器管理服务生命周期
   • 妥善处理启动和关闭
   • 在 finally 块中清理资源

3. 工具实现

   • 基于装饰器注册工具
   • 以一致的方式处理错误和记录日志
   • 使用结构化响应格式

4. 开发模式

   • 全面使用类型提示
   • 使用可配置的级别记录详细日志
   • 验证服务状态

项目结构

基于生产级模式的标准 MCP 服务结构：

.
├── src/                     # Python source code
│   ├── server.py           # Main MCP server implementation
│   ├── services/           # Service client implementations
│   │   └── client.py       # Your service client code
│   ├── models.py           # Data models and schemas
│   ├── config.py           # Configuration models
│   └── utils/              # Utility functions
├── docs/                   # Documentation
│   └── mcp-server-guide.md # Server implementation guide
├── tests/                  # Test files
├── requirements.txt        # Python dependencies
└── README.md              # Project documentation

代码组织

此模板遵循生产级 MCP 服务中的以下约定：

1. 服务入口点（src/server.py）：

   # Configuration models
   class ServiceConfig(BaseModel):
       api_key: str
       # ...
   
   # Server lifespan
   @asynccontextmanager
   async def server_lifespan(server: FastMCP):
       try:
           # Initialize services
           yield
       finally:
           # Cleanup
   
   # FastMCP instance
   mcp = FastMCP(
       name="Your Server",
       instructions="Your server description",
       lifespan=server_lifespan
   )
   
   # Tools
   @mcp.tool()
   async def your_tool(ctx: Context):
       # Tool implementation
   

2. 服务客户端（src/services/）：

   • 实现特定于服务的客户端
   • 处理身份验证和重试
   • 管理连接状态

3. 模型（src/models.py）：

   • 定义用于数据验证的 Pydantic 模型
   • 构建工具输入和输出
   • 定义特定于服务的类型

实现指南

1. 配置：

   • 添加符合服务需求的配置模型
   • 使用环境变量存储机密
   • 为必填字段添加验证

2. 服务客户端：

   • 在 services/ 中实现服务客户端
   • 添加连接和重试处理
   • 包含适当的清理逻辑

3. 工具：

   • 使用 @mcp.tool() 装饰器
   • 添加类型提示和文档字符串
   • 遵循以下错误处理模式：

   @mcp.tool()
   async def your_tool(ctx: Context) -> Dict[str, Any]:
       try:
           # Implementation
           return {"status": "success", "result": result}
       except Exception as e:
           await ctx.error(f"Error: {e}")
           return {"status": "error", "message": str(e)}
   

4. 错误处理：

   • 使用结构化错误响应
   • 记录错误及其上下文
   • 返回对用户友好的消息

开始使用

1. 使用此模板创建新仓库：

   git clone https://github.com/username/template-mcp-server.git your-server
   cd your-server
   

2. 设置开发环境：

   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

3. 在 src/server.py 中更新服务名称和描述

4. 添加服务配置和客户端

VS Code 配置

若要将此服务与 VS Code 的 MCP 功能配合使用，请将以下配置添加到 VS Code 的 settings.json 中：

"mcp": {
  "inputs": [
    {
      "type": "promptString",
      "id": "service-api-key",
      "description": "Service API Key",
      "password": true
    }
  ],
  "servers": {
    "template-mcp": {
      "type": "stdio",
      "command": "${userHome}/git/template-mcp-server/venv/bin/python",
      "args": [
        "${userHome}/git/template-mcp-server/src/server.py"
      ],
      "env": {
        "SERVICE_API_KEY": "${input:service-api-key}",
        "SERVICE_ENDPOINT": "https://api.example.com",
        "SERVICE_TIMEOUT": "30",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

配置选项

• 环境变量：
  • SERVICE_API_KEY：服务 API 密钥（必填）
  • SERVICE_ENDPOINT：服务端点 URL（默认值：https://api.example.com）
  • SERVICE_TIMEOUT：请求超时时间，单位为秒（默认值：30）
  • LOG_LEVEL：日志级别（默认值：INFO）

测试

遵循生产级 MCP 服务中的模式：

1. 手动测试：

   # Run the server directly
   python src/server.py
   
   # Test with different log levels
   LOG_LEVEL=DEBUG python src/server.py
   

2. 集成测试：

   # Start server with test configuration
   SERVICE_API_KEY=test-key python src/server.py
   

3. 开发提示：

   • 使用 VS Code 的 Python 调试器逐步调试工具执行过程
   • 在服务客户端中设置断点，以调试集成问题
   • 开发期间使用 DEBUG 日志级别，以获取详细输出

常见模式

通过分析生产环境中的 MCP 服务，总结出以下关键模式：

1. 服务客户端状态：

   • 在服务生命周期中初始化
   • 存储在全局变量中
   • 使用前检查是否已初始化
   • 在 finally 块中清理

2. 错误处理：

   • 记录错误及其上下文
   • 返回结构化的错误响应
   • 使用 ctx.error() 向用户反馈
   • 同时包含状态和消息

3. 配置：

   • 使用 Pydantic 模型
   • 设置合理的默认值
   • 在启动时验证
   • 支持环境变量覆盖

4. 工具实现：

   • 编写包含 Args 部分的清晰文档字符串
   • 为所有参数添加类型提示
   • 返回结构化响应
   • 使用一致的错误格式

资源

• MCP 服务指南
• Python SDK 文档
• VS Code MCP 文档

VS Code 配置

若要在 VS Code 中使用此服务的 MCP（模型上下文协议）功能，请将以下配置添加到 VS Code 的 settings.json 中：

"mcp": {
  "inputs": [
    {
      "type": "promptString",
      "id": "service-api-key",
      "description": "Service API Key",
      "password": true
    }
  ],
  "servers": {
    "template-mcp": {
      "type": "stdio",
      "command": "${userHome}/git/template-mcp-server/venv/bin/python",
      "args": [
        "${userHome}/git/template-mcp-server/src/server.py"
      ],
      "env": {
        "SERVICE_API_KEY": "${input:service-api-key}",
        "SERVICE_ENDPOINT": "https://api.example.com",
        "SERVICE_TIMEOUT": "30",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

配置选项

• 环境变量：
  • SERVICE_API_KEY：您的服务 API 密钥（必需）
  • SERVICE_ENDPOINT：服务端点 URL（默认值：https://api.example.com）
  • SERVICE_TIMEOUT：请求超时时间（秒，默认值：30）
  • LOG_LEVEL：日志级别（默认值：INFO）

前置条件

使用服务之前：

1. 在项目目录中设置 Python 虚拟环境：

   python -m venv venv
   source venv/bin/activate  # or `venv\Scripts\activate` on Windows
   pip install -r requirements.txt
   

2. 配置 VS Code：

   • 创建包含 stdio 配置的 .vscode/mcp.json
   • 在 VS Code 中设置 Python 解释器
   • 使用集成终端运行命令
   • 使用 VS Code 的 Python 调试器调试 MCP 服务

3. 测试 MCP 服务：

   • 使用 VS Code 内置的 MCP 服务测试功能
   • 使用断点和 VS Code 的调试控制台进行调试
   • 在输出面板中监控 stdio 通信

参与贡献

1. Fork 此仓库
2. 创建功能分支
3. 提交拉取请求

许可证

[您选择的许可证]