MCP Server template for better AI Coding

用于更好地辅助 AI 编码的 MCP 服务模板

灵感来自 MCP 官方教程

概述

此模板为使用 Python 构建 Model Context Protocol（MCP）服务提供了精简的基础，旨在让借助 AI 开发 MCP 工具变得更轻松、更高效。

功能

• 开箱即用的 MCP 服务实现
• 可配置的传输模式（stdio、SSE）
• 天气服务集成示例（NWS API）
• 清晰且文档完善的代码结构
• 最少的依赖项
• 内置 MCP 规范和文档，帮助 AI 工具更好地理解

Cursor 规则集成

本项目使用 Cursor Rules 来增强 AI 编码辅助能力，并采用了 Awesome Cursor Rules 中的模式。

• 整洁代码指南：内置的整洁代码规则有助于保持一致性和质量
• 增强 AI 理解能力：规则提供上下文，帮助 AI 助手生成更好的代码
• 标准化模式：遵循 MCP 服务实现的成熟最佳实践

Cursor Rules 可帮助 AI 编码助手和开发者保持高代码质量标准并遵循最佳实践。

集成的 MCP 文档

此模板在项目中直接包含了全面的 MCP 文档：

• 完整的 MCP 规范（protocals/mcp.md）：完整的 Model Context Protocol 规范，定义 AI 模型如何与外部工具和资源交互。这有助于 AI 助手理解 MCP 概念和实现细节，无需查阅外部资料。

• Python SDK 指南（protocals/sdk.md）：MCP Python SDK 的详细文档，让 AI 工具更容易提供准确的代码建议并了解库的功能。

• 实现示例（protocals/example_weather.py）：实用的天气服务实现，展示真实场景中的 MCP 服务模式和最佳实践。

将这些资源嵌入项目中，有助于 AI 编码助手更好地理解 MCP 概念，并在开发过程中提供更准确、贴合上下文的建议。

要求

• Python 3.12+
• 依赖项：
  • mcp>=1.4.1
  • httpx>=0.28.1
  • starlette>=0.46.1
  • uvicorn>=0.34.0

入门

安装

1. 克隆此仓库：

   git clone https://github.com/yourusername/mcp-server-python-template.git
   cd mcp-server-python-template
   

2. 创建虚拟环境并安装依赖项：

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e .
   

运行示例服务

此模板包含一个天气服务示例，演示如何构建 MCP 工具：

# Run with stdio transport (for CLI tools)
python server.py --transport stdio

# Run with SSE transport (for web applications)
python server.py --transport sse --host 0.0.0.0 --port 8080

创建自己的 MCP 工具

创建自己的 MCP 工具：

1. 从 mcp 导入所需组件：

   from mcp.server.fastmcp import FastMCP
   

2. 使用命名空间初始化 MCP 服务：

   mcp = FastMCP("your-namespace")
   

3. 使用 @mcp.tool() 装饰器定义工具：

   @mcp.tool()
   async def your_tool_function(param1: str, param2: int) -> str:
       """
       Your tool description.
       
       Args:
           param1: Description of param1
           param2: Description of param2
           
       Returns:
           The result of your tool
       """
       # Your implementation here
       return result
   

4. 使用合适的传输方式运行服务：

   mcp.run(transport='stdio')  # or set up SSE as shown in server.py
   

项目结构

• server.py：包含天气工具示例的 MCP 服务主实现
• main.py：自定义代码的简单入口
• protocals/：文档和协议示例
  • mcp.md：完整 MCP 规范（约 7000 行）
  • sdk.md：MCP Python SDK 文档
  • example_weather.py：天气服务实现示例
• pyproject.toml：项目依赖项和元数据

了解 MCP

模型上下文协议（MCP）是一种标准化方式，可让 AI 模型与外部工具和资源交互。核心概念包括：

• 工具：模型可调用以执行操作或获取信息的函数
• 资源：模型可引用的外部数据源
• 传输方式：客户端与 MCP 服务之间的通信渠道（stdio、SSE）
• 命名空间：相关工具的逻辑分组

此模板专为简化 MCP 使用而设计，集成的文档可帮助 AI 工具更好地理解 MCP 实现，并生成适当的代码。

学习资源

• MCP 官方文档
• 协议文档
• SDK 指南

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。