---
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 服务器，要求类型安全、错误处理得当，并附带全面的文档。