python-mcp-server-generator

生成 Python MCP 服务器

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

要求

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

实现细节

项目设置

• 使用 uv init project-name 初始化
• 添加 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://{param}"
• 使用 @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:PORT/mcp
• 使用 MCP Inspector 测试：uv run mcp dev server.py
• 安装到 Claude Desktop：uv run mcp install server.py
• 包含示例工具调用
• 添加故障排除提示

其他功能

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

最佳实践

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

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