wehub-skill-sync
106 lines
3.8 KiB
Markdown
106 lines
3.8 KiB
Markdown
---
|
||
name: python-mcp-server-generator
|
||
description: '生成一个完整的 Python MCP 服务器项目，包含工具、资源和正确配置'
|
||
---
|
||
|
||
# 生成 Python MCP 服务器
|
||
|
||
创建一个符合以下规范的完整模型上下文协议（Model Context Protocol，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()` 装饰器装饰函数
|
||
- 始终包含类型提示——它们会自动生成 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`
|
||
- 使用 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 服务器，要求类型安全、错误处理得当，并附带全面的文档。
|