wehub-skill-sync
3.8 KiB
3.8 KiB
name, description
| name | description |
|---|---|
| python-mcp-server-generator | 生成一个完整的 Python MCP 服务器项目，包含工具、资源和正确配置 |
生成 Python MCP 服务器
创建一个符合以下规范的完整模型上下文协议（Model Context Protocol，MCP）Python 服务器：
需求
- 项目结构：使用 uv 创建一个结构合理的 Python 新项目
- 依赖管理：使用 uv 引入 mcp[cli] 包
- 传输类型：选择 stdio（本地）或 streamable-http（远程）
- 工具：创建至少一个带有正确类型提示的实用工具
- 错误处理：包含全面的错误处理与验证机制
实现细节
项目搭建
- 使用
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()装饰器装饰函数 - 始终包含类型提示——它们会自动生成 schema
- 编写清晰的文档字符串——它们会作为工具描述
- 使用 Pydantic 模型或 TypedDict 处理结构化输出
- 支持 I/O 密集型任务的异步操作
- 包含恰当的错误处理
资源/提示设置（可选）
- 使用
@mcp.resource()装饰器添加资源 - 使用 URI 模板实现动态资源：
"resource://{param}" - 使用
@mcp.prompt()装饰器添加提示 - 从提示返回字符串或 Message 列表
代码质量
- 所有函数参数和返回值均使用类型提示
- 为工具、资源和提示编写文档字符串
- 遵循 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
- stdio：
- 使用 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 服务器，要求类型安全、错误处理得当，并附带全面的文档。