生成 Python MCP 服务器

使用以下规范创建一个完整的模型上下文协议（MCP）Python 服务器：

要求

1. 项目结构：使用 uv 创建一个具有正确结构的新 Python 项目
2. 依赖项：使用 uv 包含 mcp[cli] 包
3. 传输类型：在 stdio（用于本地）或 streamable-http（用于远程）之间选择
4. 工具：创建至少一个具有正确类型提示的有用工具
5. 错误处理：包含全面的错误处理和验证

实现细节

项目设置

• 使用 uv init 项目名称 初始化
• 添加 MCP SDK：uv add "mcp[cli]"
• 创建主服务器文件（例如，server.py）
• 为 Python 项目添加 .gitignore
• 使用 if __name__ == "__main__" 配置直接执行

服务器配置

• 从 mcp.server.fastmcp 使用 FastMCP 类
• 设置服务器名称和可选说明
• 选择传输方式：stdio（默认）或 streamable-http
• 对于 HTTP：可选择配置主机、端口和无状态模式

工具实现

• 在函数上使用 @mcp.tool() 装饰器
• 始终包含类型提示——它们会自动生成模式
• 编写清晰的文档字符串——它们会成为工具的描述
• 对结构化输出使用 Pydantic 模型或 TypedDict
• 支持异步操作以处理 I/O 密集型任务
• 包含适当的错误处理

资源/提示设置（可选）

• 使用 @mcp.resource() 装饰器添加资源
• 对动态资源使用 URI 模板："resource://{参数}"
• 使用 @mcp.prompt() 装饰器添加提示
• 从提示返回字符串或消息列表

代码质量

• 为所有函数参数和返回值使用类型提示
• 为工具、资源和提示编写文档字符串
• 遵循 PEP 8 风格指南
• 对异步操作使用 async/await
• 为资源清理实现上下文管理器
• 为复杂逻辑添加内联注释

可考虑的工具类型示例

• 数据处理和转换
• 文件系统操作（读取、分析、搜索）
• 外部 API 集成
• 数据库查询
• 文本分析或生成（带有采样）
• 系统信息检索
• 数学或科学计算

配置选项

• 对于 stdio 服务器：
  • 简单的直接执行
  • 使用 uv run mcp dev server.py 进行测试
  • 安装到 Claude：uv run mcp install server.py
• 对于 HTTP 服务器：
  • 通过环境变量配置端口
  • 用于可扩展性的无状态模式：stateless_http=True
  • JSON 响应模式：json_response=True
  • 为浏览器客户端配置 CORS
  • 挂载到现有的 ASGI 服务器（Starlette/FastAPI）

测试指南

• 解释如何运行服务器：
  • stdio：python server.py 或 uv run server.py
  • HTTP：python server.py 然后连接到 http://localhost:端口/mcp
• 使用 MCP Inspector 进行测试：uv run mcp dev server.py
• 安装到 Claude Desktop：uv run mcp install server.py
• 包含示例工具调用
• 添加故障排除技巧

可考虑的其他功能

• 用于日志记录、进度和通知的上下文使用
• 用于 AI 驱动工具的 LLM 采样
• 用于交互式工作流的用户输入收集
• 用于共享资源（数据库、连接）的生命周期管理
• 使用 Pydantic 模型进行结构化输出
• 用于 UI 显示的图标
• 使用 Image 类处理图像
• 为更好的用户体验提供自动补全支持

最佳实践

• 处处使用类型提示——它们是必需的
• 尽可能返回结构化数据
• 记录到 stderr（或使用 Context 日志记录）以避免 stdout 污染
• 正确清理资源
• 尽早验证输入
• 提供清晰的错误消息
• 在集成到 LLM 之前独立测试工具

生成一个完整的、可用于生产的 MCP 服务器，具备类型安全、正确的错误处理和全面的文档。