MCP 服务器模板，助力更好的 AI 编程

受 MCP 官方教程 启发

概述

此模板为使用 Python 构建 Model Context Protocol (MCP) 服务器提供了一个简化的基础。它旨在使 MCP 工具的 AI 辅助开发变得更简单、更高效。

特性

• 即用型 MCP 服务器实现
• 可配置的传输模式（标准输入输出、SSE）
• 示例天气服务集成（NWS API）
• 清晰且文档齐全的代码结构
• 最小依赖项
• 嵌入式 MCP 规范和文档，以提高 AI 工具的理解能力

光标规则集成

该项目使用光标规则来改进 AI 编码辅助，并采用了 Awesome Cursor Rules 中的模式。

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

光标规则帮助 AI 编码助手和人类开发者维护高质量的代码标准并遵循最佳实践。

集成的 MCP 文档

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

• 完整的 MCP 规范 (protocals/mcp.md)：定义了 AI 模型如何与外部工具和资源交互的完整 Model Context Protocol 规范。这有助于 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. 克隆此仓库：
   bash
   git clone https://github.com/yourusername/mcp-server-python-template.git
   cd mcp-server-python-template

2. 创建虚拟环境并安装依赖项：
   bash
   python -m venv .venv
   source .venv/bin/activate # 在 Windows 上: .venv\Scripts\activate
   pip install -e .

运行示例服务器

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

bash

使用标准输入输出传输（适用于 CLI 工具）

python server.py --transport stdio

使用 SSE 传输（适用于 Web 应用程序）

python server.py --transport sse --host 0.0.0.0 --port 8080

创建您自己的 MCP 工具

要创建您自己的 MCP 工具：

1. 从 mcp 导入必要的组件：
   python
   from mcp.server.fastmcp import FastMCP

2. 使用命名空间初始化您的 MCP 服务器：
   python
   mcp = FastMCP("your-namespace")

3. 使用 @mcp.tool() 装饰器定义您的工具：
   python
   @mcp.tool()
   async def your_tool_function(param1: str, param2: int) -> str:
   """
   您的工具描述。

   参数：
       param1: param1 的描述
       param2: param2 的描述
   
   返回：
       您工具的结果
   """
   # 您的实现代码
   return result
   

4. 使用适当的传输方式运行您的服务器：
   python
   mcp.run(transport='stdio') # 或者按照 server.py 中所示设置 SSE

项目结构- server.py: 主要的MCP服务器实现，包含示例天气工具

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

理解MCP

模型上下文协议（MCP）是一种标准化的方式，用于AI模型与外部工具和资源进行交互。关键概念包括：

• 工具：模型可以调用以执行操作或检索信息的功能
• 资源：模型可以引用的外部数据源
• 传输：客户端与MCP服务器之间的通信通道（如标准输入输出、SSE）
• 命名空间：相关工具的逻辑分组

此模板特别设计为使MCP更易于使用，集成的文档有助于AI工具更好地理解和生成适用于MCP实现的适当代码。

学习资源

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

贡献

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

许可证

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