MCP服务器Python模板

Name: MCP服务器Python模板
Author: sontallive

作者：sontallive12 星标更新：2025-03-20

安装使用来源：spider==github.com

项目介绍

用于更好AI编码的MCP服务器模板

受MCP官方教程启发

概述

此模板提供了一个流线型的基础，用于在Python中构建模型上下文协议（MCP）服务器。它旨在使MCP工具的AI辅助开发更加容易和高效。

特性

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

Cursor规则集成

本项目使用Cursor规则来改进AI编码辅助，规则来自Awesome Cursor Rules。

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

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

集成的MCP文档

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

完整的MCP规范（protocals/mcp.md）：定义了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

快速开始

安装

克隆此仓库：

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

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

python -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
pip install -e .

运行示例服务器

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

# 使用标准I/O传输运行（适用于CLI工具）
python server.py --transport stdio

# 使用SSE传输运行（适用于Web应用程序）
python server.py --transport sse --host 0.0.0.0 --port 8080

创建自己的MCP工具

要创建自己的MCP工具：

从mcp导入必要的组件：
```
from mcp.server.fastmcp import FastMCP
```
使用命名空间初始化您的MCP服务器：
```
mcp = FastMCP("your-namespace")
```

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

@mcp.tool()
async def your_tool_function(param1: str, param2: int) -> str:
    """
    您的工具描述。
    
    参数：
        param1: 参数1的描述
        param2: 参数2的描述
        
    返回值：
        您的工具的结果
    """
    # 您的实现代码在这里
    return result

使用适当的传输运行您的服务器：

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服务器之间的通信通道（标准I/O，SSE）
命名空间：相关工具的逻辑分组

此模板特别设计为使使用MCP更加便捷，集成的文档帮助AI工具更好地理解和生成适合MCP实现的代码。