返回提示词目录第 1663 页

MCP Builder

指导开发者按研究规划、实现、测试、评估四阶段构建高质量MCP服务器,让大语言模型通过规范工具对接外部API

完整提示词

---
name: mcp-builder
description: 指导如何创建高质量的 MCP(Model Context Protocol)服务器,使大语言模型(LLM)能够通过精心设计的工具与外部服务交互。在构建用于集成外部 API 或服务的 MCP 服务器时使用,无论是使用 Python(FastMCP)还是 Node/TypeScript(MCP SDK)。
license: 完整条款见 LICENSE.txt
---

# MCP 服务器开发指南

## 概述

创建 MCP(Model Context Protocol)服务器,使大语言模型(LLM)能够通过设计良好的工具与外部服务交互。MCP 服务器的质量取决于其在多大程度上帮助 LLM 完成真实世界任务的能力。

---

# 流程

## 🚀 高层次工作流

创建高质量的 MCP 服务器包含四个主要阶段:

### 第一阶段:深入研究与规划

#### 1.1 理解现代 MCP 设计

**API 覆盖 vs. 工作流工具:**
在全面覆盖 API 端点与专用工作流工具之间取得平衡。工作流工具在特定任务中可能更方便,而全面覆盖则赋予智能体(agent)组合操作的灵活性。不同客户端表现各异——某些客户端受益于结合基础工具的代码执行,而其他客户端则在高层级工作流下表现更佳。当不确定时,优先考虑全面的 API 覆盖。

**工具命名与可发现性:**
清晰、描述性强的工具名称有助于智能体快速找到合适的工具。使用一致的前缀(例如 `github_create_issue`、`github_list_repos`)和以动作为导向的命名方式。

**上下文管理:**
智能体受益于简洁的工具描述以及过滤/分页结果的能力。设计返回聚焦且相关数据的工具。某些客户端支持代码执行,这有助于智能体高效地过滤和处理数据。

**可操作的错误消息:**
错误消息应通过具体建议和后续步骤引导智能体解决问题。

#### 1.2 学习 MCP 协议文档

**浏览 MCP 规范:**

从站点地图开始查找相关页面:`https://modelcontextprotocol.io/sitemap.xml`

然后以 `.md` 后缀获取特定页面以获得 Markdown 格式(例如 `https://modelcontextprotocol.io/specification/draft.md`)。

需重点查阅的关键页面:
- 规范概述与架构
- 传输机制(可流式 HTTP、stdio)
- 工具、资源和提示词(prompt)定义

#### 1.3 学习框架文档

**推荐技术栈:**
- **语言**:TypeScript(具备高质量的 SDK 支持,并在多种执行环境中具有良好兼容性,例如 MCPB。此外,AI 模型擅长生成 TypeScript 代码,得益于其广泛使用、静态类型和良好的 linting 工具)
- `readOnlyHint`:true/false
- `destructiveHint`:true/false
- `idempotentHint`:true/false
- `openWorldHint`:true/false

---

### 第 3 阶段:审查与测试

#### 3.1 代码质量

审查以下内容:
- 无重复代码(DRY 原则)
- 一致的错误处理
- 完整的类型覆盖
- 清晰的工具描述

#### 3.2 构建与测试

**TypeScript:**
- 运行 `npm run build` 以验证编译
- 使用 MCP Inspector 测试:`npx @modelcontextprotocol/inspector`

**Python:**
- 验证语法:`python -m py_compile your_server.py`
- 使用 MCP Inspector 测试

参见语言特定指南,了解详细的测试方法和质量检查清单。

---

### 第 4 阶段:创建评估

在实现你的 MCP 服务器后,创建全面的评估以测试其有效性。

**加载 [✅ 评估指南](./reference/evaluation.md) 获取完整的评估指导。**

#### 4.1 理解评估目的

使用评估来测试 LLM 是否能够有效利用你的 MCP 服务器回答现实且复杂的问题。

#### 4.2 创建 10 个评估问题

要创建有效的评估,请遵循评估指南中概述的流程:

1. **工具检查**:列出可用工具并理解其功能
2. **内容探索**:使用只读操作探索可用数据
3. **问题生成**:创建 10 个复杂、现实的问题
4. **答案验证**:自行解答每个问题以验证答案

#### 4.3 评估要求

确保每个问题都满足以下条件:
- **独立性**:不依赖于其他问题
- **只读性**:仅需非破坏性操作
- **复杂性**:需要多次工具调用和深入探索
- **现实性**:基于人类关心的真实用例
- **可验证性**:具有单一、明确的答案,可通过字符串比较验证
- **稳定性**:答案不会随时间改变

#### 4.4 输出格式

创建一个具有如下结构的 XML 文件:

```xml
<evaluation>
  <qa_pair>
    <question>查找有关以动物为代号命名的 AI 模型发布的讨论。其中一个模型需要一个特定的安全标识,其格式为 ASL-X。名为斑点野猫的模型所确定的 X 数字是多少?</question>
    <answer>3</answer>
  </qa_pair>
<!-- 更多 qa_pairs... -->
</evaluation>
```

---

# 参考文件

## 📚 文档库

开发过程中按需加载以下资源:

### 核心 MCP 文档(优先加载)
- **MCP 协议**:从 `https://modelcontextprotocol.io/sitemap.xml` 开始,然后使用 `.md` 后缀获取特定页面
- [📋 MCP 最佳实践](./reference/mcp_best_practices.md) — 包括通用 MCP 指南:
  - 服务器和工具命名规范
  - 响应格式指南(JSON 与 Markdown)
  - 分页最佳实践
  - 传输方式选择(可流式 HTTP 与 stdio)
  - 安全性和错误处理标准

### SDK 文档(第 1/2 阶段加载)
- **Python SDK**:从 `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` 获取
- **TypeScript SDK**:从 `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` 获取

### 语言特定实现指南(第 2 阶段加载)
- [🐍 Python 实现指南](./reference/python_mcp_server.md) — 完整的 Python/FastMCP 指南,包括:
  - 服务器初始化模式
  - Pydantic 模型示例
  - 使用 `@mcp.tool` 注册工具
  - 完整的工作示例
  - 质量检查清单

- [⚡ TypeScript 实现指南](./reference/node_mcp_server.md) — 完整的 TypeScript 指南,包括:
  - 项目结构
  - Zod 模式模式
  - 使用 `server.registerTool` 注册工具
  - 完整的工作示例
  - 质量检查清单

### 评估指南(第 4 阶段加载)
- [✅ 评估指南](./reference/evaluation.md) — 完整的评估创建指南,包括:
  - 问题创建指南
  - 答案验证策略
  - XML 格式规范
  - 示例问题和答案
  - 使用提供的脚本运行评估
FILE:reference/mcp_best_practices.md
# MCP 服务器最佳实践

## 快速参考

### 服务器命名
- **Python**:`{service}_mcp`(例如 `slack_mcp`)
- **Node/TypeScript**:`{service}-mcp-server`(例如 `slack-mcp-server`)

### 工具命名
- 使用带服务前缀的 snake_case
- 格式:`{service}_{action}_{resource}`
- 示例:`slack_send_message`、`github_create_issue`

### 响应格式
- 支持 JSON 和 Markdown 格式
- JSON 用于程序化处理
- Markdown 用于人类可读性

### 分页
- 始终遵守 `limit` 参数
- 返回 `has_more`、`next_offset`、`total_count`
- 默认返回 20-50 项

### 传输
- **可流式 HTTP**:适用于远程服务器、多客户端场景
- **stdio**:适用于本地集成、命令行工具
- 避免 SSE(已弃用,推荐使用可流式 HTTP)

---

## 服务器命名规范

遵循以下标准化命名模式:
**Python**:使用格式 `{service}_mcp`(小写字母加下划线)
- 示例:`slack_mcp`、`github_mcp`、`jira_mcp`

**Node/TypeScript**:使用格式 `{service}-mcp-server`(小写字母加连字符)
- 示例:`slack-mcp-server`、`github-mcp-server`、`jira-mcp-server`

名称应具有通用性,能够描述所集成的服务,从任务描述中易于推断,且不包含版本号。

---

## 工具命名与设计

### 工具命名

1. **使用 snake_case**:`search_users`、`create_project`、`get_channel_info`
2. **包含服务前缀**:需考虑到你的 MCP 服务器可能与其他 MCP 服务器共存
   - 使用 `slack_send_message` 而不是仅用 `send_message`
   - 使用 `github_create_issue` 而不是仅用 `create_issue`
3. **以动作为导向**:以动词开头(get、list、search、create 等)
4. **具体明确**:避免可能与其他服务器冲突的通用名称

### 工具设计

- 工具描述必须精确且无歧义地描述功能
- 描述必须与实际功能完全一致
- 提供工具注解(readOnlyHint、destructiveHint、idempotentHint、openWorldHint)
- 保持工具操作的聚焦性和原子性

---

## 响应格式

所有返回数据的工具都应支持多种格式:

### JSON 格式(`response_format="json"`)
- 机器可读的结构化数据
- 包含所有可用字段和元数据
- 字段名称和类型保持一致
- 用于程序化处理

### Markdown 格式(`response_format="markdown"`,通常为默认值)
- 人类可读的格式化文本
- 使用标题、列表和格式化以提高可读性
- 将时间戳转换为人类可读格式
- 显示名称后括号内附带 ID
- 省略冗长的元数据

---

## 分页

对于列出资源的工具:

- **始终遵守 `limit` 参数**
- **实现分页**:使用 `offset` 或基于游标的分页
- **返回分页元数据**:包含 `has_more`、`next_offset`/`next_cursor`、`total_count`
- **切勿将所有结果加载到内存中**:对大型数据集尤其重要
- **默认设置合理限制**:20-50 项为典型值

示例分页响应:
```json
{
  "total": 150,
  "count": 20,
  "offset": 0,
  "items": [...],
  "has_more": true,
  "next_offset": 20
}
```

---

## 传输选项

### 可流式 HTTP

**最适合**:远程服务器、Web 服务、多客户端场景

**特点**:
- 通过 HTTP 实现双向通信
- 支持多个客户端同时连接
- 可部署为 Web 服务
- 支持服务器向客户端发送通知

**适用场景**:
- 同时服务多个客户端
- 作为云服务部署
- 与 Web 应用集成

### stdio

**最适合**:本地集成、命令行工具

**特点**:
- 通过标准输入/输出流通信
- 设置简单,无需网络配置
- 作为客户端的子进程运行

**适用场景**:
- 为本地开发环境构建工具
- 与桌面应用程序集成
- 单用户、单会话场景

**注意**:stdio 服务器不应将日志输出到 stdout(应使用 stderr 进行日志记录)

### 传输方式选择

| 判定条件 | stdio | 可流式 HTTP |
|-----------|-------|-----------------|
| **部署方式** | 本地 | 远程 |
| **客户端数量** | 单个 | 多个 |
| **复杂度** | 低 | 中等 |
| **实时性** | 否 | 是 |

---

## 安全最佳实践

### 认证与授权

**OAuth 2.1**:
- 使用由公认机构签发证书的 OAuth 2.1 安全实现
- 在处理请求前验证访问令牌
- 仅接受专为你的服务器签发的令牌

**API 密钥**:
- 将 API 密钥存储在环境变量中,切勿硬编码在代码中
- 在服务器启动时验证密钥
- 当认证失败时提供清晰的错误信息

### 输入验证

- 对文件路径进行清理以防止目录遍历
- 验证 URL 和外部标识符
- 检查参数大小和范围
- 防止系统调用中的命令注入
- 对所有输入使用模式验证(Pydantic/Zod)

### 错误处理

- 不向客户端暴露内部错误
- 在服务器端记录与安全相关的错误
- 提供有帮助但不泄露信息的错误消息
- 在错误后清理资源

### DNS 重绑定保护

对于本地运行的可流式 HTTP 服务器:
- 启用 DNS 重绑定保护
- 对所有传入连接验证 `Origin` 头
- 绑定到 `127.0.0.1` 而非 `0.0.0.0`

---

## 工具注解

提供注解以帮助客户端理解工具行为:

| 注解 | 类型 | 默认值 | 说明 |
|-----------|------|---------|-------------|
| `readOnlyHint` | boolean | false | 工具不会修改其运行环境 |
| `destructiveHint` | boolean | true | 工具可能执行破坏性更新 |
| `idempotentHint` | boolean | false | 使用相同参数重复调用不会产生额外影响 |
| `openWorldHint` | boolean | true | 工具与外部实体交互 |

  
9. **问题应主要反映真实的人类使用场景**  
   - 即人类在 LLM 辅助下会关心的信息检索任务类型

10. **问题可需要数十次工具调用**  
    - 这对上下文长度有限的 LLM 构成挑战  
    - 鼓励 MCP 服务器工具减少返回的信息量

11. **包含模糊性问题**  
    - 问题可能是模糊的,或需要在调用哪些工具上做出困难决策  
    - 迫使 LLM 可能犯错或误解  
    - 确保尽管存在**模糊性**,仍存在**唯一可验证的答案**

### 稳定性

12. **问题设计必须确保答案不会改变**  
    - 不要提出依赖“当前状态”的问题,因其是动态的  
    - 例如,不要统计:  
      - 帖子的反应数  
      - 帖子的回复数  
      - 频道中的成员数

13. **不要让 MCP 服务器限制你创建问题的类型**  
    - 创建具有挑战性和复杂性的问题  
    - 有些问题可能无法通过现有的 MCP 服务器工具解决  
    - 问题可要求特定输出格式(datetime 与 epoch time,JSON 与 MARKDOWN)  
    - 问题可能需要数十次工具调用才能完成

## 答案指南

### 验证性

1. **答案必须可通过直接字符串比较进行验证**  
    - 如果答案可用多种格式表达,需在问题中明确指定输出格式  
    - 示例:“使用 YYYY/MM/DD。”、“回答 True 或 False。”、“仅回答 A、B、C 或 D。”  
    - 答案应为单一可验证值,例如:  
      - 用户 ID、用户名、显示名称、名字、姓氏  
      - 频道 ID、频道名称  
      - 消息 ID、字符串  
      - URL、标题  
      - 数值  
      - 时间戳、日期时间  
      - 布尔值(用于 True/False 问题)  
      - 电子邮件地址、电话号码  
      - 文件 ID、文件名、文件扩展名  
      - 多选题答案  
    - 答案不得要求特殊格式或复杂的结构化输出  
    - 答案将通过**直接字符串比较**进行验证

### 可读性

2. **答案通常应优先采用人类可读的格式**  
    - 示例:姓名、名字、姓氏、日期时间、文件名、消息字符串、URL、yes/no、true/false、a/b/c/d  
    - 而非不透明的 ID(尽管 ID 是可接受的)  
    - **绝大多数**答案应为人类可读

### 稳定性

3. **答案必须是稳定/静态的**  
    - 查看旧内容(例如已结束的对话、已发布的项目、已回答的问题)  
    - 基于“已关闭”的概念创建问题,以确保答案始终一致  
    - 问题可要求考虑固定时间窗口,以避免非静态答案  
    - 依赖**不太可能改变**的上下文  
    - 示例:若查找论文名称,应足够具体,以免与后续发表的论文混淆

4. **答案必须清晰且无歧义**  
    - 问题必须设计成只有一个明确答案  
    - 答案可通过使用 MCP 服务器工具推导得出

### 多样性

5. **答案必须多样化**  
    - 答案应为单一可验证值,涵盖多样的模态和格式  
    - 用户概念:用户 ID、用户名、显示名称、名字、姓氏、电子邮件地址、电话号码  
    - 频道概念:频道 ID、频道名称、频道主题  
    - 消息概念:消息 ID、消息字符串、时间戳、月份、日期、年份

6. **答案不得是复杂结构**  
    - 不得是值的列表  
    - 不得是复杂对象  
    - 不得是 ID 或字符串的列表  
    - 不得是自然语言文本  
    - **除非**答案可通过**直接字符串比较**轻松验证  
    - 并且能够被现实地复现  
    - LLM 返回相同列表但顺序或格式不同的可能性应极低

## 评估流程

### 第 1 步:文档检查

阅读目标 API 的文档以理解:  
- 可用的端点和功能  
- 若存在歧义,从网络获取额外信息  
- 尽可能并行化此步骤  
- 确保每个子代理仅从文件系统或网络检查文档

### 第 2 步:工具检查

列出 MCP 服务器中可用的工具:  
- 直接检查 MCP 服务器  
- 理解输入/输出模式、docstrings 和描述  
- **在此阶段不得调用工具本身**

### 第 3 步:建立理解

重复第 1 和第 2 步,直到充分理解:  
- 多次迭代  
- 思考你想创建的任务类型  
- 不断优化你的理解  
- **在任何阶段都不得阅读 MCP 服务器实现本身的代码**  
- 利用你的直觉和理解,创建合理、真实但**极具挑战性**的任务

### 第 4 步:只读内容检查

在理解 API 和工具之后,**使用** MCP 服务器工具:  
- 仅使用**只读**和**非破坏性**操作来检查内容
  
- 目标:识别特定内容(例如用户、频道、消息、项目、任务),以创建符合实际的问题  
- 不应调用任何修改状态的工具  
- 不会读取 MCP 服务器实现本身的代码  
- 将此步骤并行化,由各个子代理进行独立探索  
- 确保每个子代理仅执行只读、非破坏性和幂等的操作  
- 注意:某些工具可能返回大量数据,导致上下文耗尽  
- 为探索进行增量式、小规模且有针对性的工具调用  
- 在所有工具调用请求中,使用 `limit` 参数限制结果数量(<10)  
- 使用分页  

### 步骤 5:任务生成  

检查内容后,创建 10 个易于理解的问题:  
- LLM 应能够使用 MCP 服务器回答这些问题  
- 遵循上述所有问题和答案的指导原则  

## 输出格式  

每个问答对包含一个问题和一个答案。输出应为具有以下结构的 XML 文件:  

```xml
<evaluation>
   <qa_pair>
      <question>找出在 2024 年第二季度创建且已完成任务数最多的项目。该项目的名称是什么?</question>
      <answer>Website Redesign</answer>
   </qa_pair>
   <qa_pair>
      <question>搜索在 2024 年 3 月已关闭且标记为“bug”的问题。哪位用户关闭的问题最多?提供其用户名。</question>
      <answer>sarah_dev</answer>
   </qa_pair>
   <qa_pair>
      <question>查找在 2024 年 1 月 1 日至 1 月 31 日期间合并且修改了 /api 目录下文件的拉取请求。有多少个不同的贡献者参与了这些拉取请求?</question>
      <answer>7</answer>
   </qa_pair>
   <qa_pair>
      <question>找出在 2023 年之前创建且获得最多星标的仓库。该仓库的名称是什么?</question>
      <answer>data-pipeline</answer>
   </qa_pair>
</evaluation>
```  

## 评估示例  

### 优质问题  

**示例 1:需要深入探索的多跳问题(GitHub MCP)**  
```xml
<qa_pair>
   <question>找出在 2023 年第三季度被归档且此前是组织内被 fork 次数最多的项目。该仓库使用的主要编程语言是什么?</question>
   <answer>Python</answer>
</qa_pair>
```  

此问题优秀的原因:  
- 需要多次搜索以找到被归档的仓库  
- 需确定哪个项目在归档前拥有最多 fork  
- 需检查仓库详细信息以获取编程语言  
- 答案是一个简单且可验证的值  
- 基于不会改变的历史(已关闭)数据  

**示例 2:需要理解上下文而非关键词匹配的问题(项目管理 MCP)**  
```xml
<qa_pair>
   <question>找到一个专注于改进客户上手流程、并于 2023 年底完成的计划。项目负责人在完成后创建了一份复盘文档。该负责人当时的职位头衔是什么?</question>
   <answer>Product Manager</answer>
</qa_pair>
```  

此问题优秀的原因:  
- 未使用具体项目名称(“专注于改进客户上手流程”)  
- 需要查找特定时间段内已完成的项目  
- 需识别项目负责人及其职位  
- 需从复盘文档中理解上下文  
- 答案是人类可读且稳定的  
- 基于已完成的工作(不会改变)  

**示例 3:需要多步操作的复杂聚合问题(问题追踪 MCP)**  
```xml
<qa_pair>
   <question>在 2024 年 1 月报告的所有被标记为“关键”优先级的 bug 中,哪位被指派人能在 48 小时内解决其名下最高比例的 bug?提供该被指派人的用户名。</question>
   <answer>alex_eng</answer>
</qa_pair>
```  

此问题优秀的原因:  
- 需按日期、优先级和状态筛选 bug  
- 需按被指派人分组并计算解决率  
- 需理解时间戳以确定 48 小时窗口  
- 测试分页能力(可能需处理大量 bug)  
- 答案是单一用户名  
- 基于特定时间段的历史数据  

**示例 4:需要跨多种数据类型综合分析的问题(CRM MCP)**  
```xml
<qa_pair>
   <question>找出在 2023 年第四季度从 Starter 升级到 Enterprise 套餐且年度合同价值最高的账户。该账户所处的行业是什么?</question>
   <answer>Healthcare</answer>
</qa_pair>
```  

此问题优秀的原因:  
- 需理解订阅层级的变化  
- 需识别特定时间段内的升级事件  
- 需比较合同价值  
- 必须访问账户的行业信息  
- 答案简单且可验证  
- 基于已完成的历史交易
  
- 答案会随着问题的创建、关闭或重新分配而发生变化  
- 不基于稳定/静态的数据  
- 依赖动态的“当前状态”  

**示例 2:通过关键词搜索过于简单**  
```xml
<qa_pair>
   <question>找到标题为 "Add authentication feature" 的拉取请求,并告诉我是谁创建了它。</question>
   <answer>developer123</answer>
</qa_pair>
```

此问题不佳的原因是:  
- 可通过针对确切标题的简单关键词搜索解决  
- 不需要深入探索或理解  
- 无需综合或分析  

**示例 3:答案格式模糊**  
```xml
<qa_pair>
   <question>列出所有将 Python 作为主要语言的仓库。</question>
   <answer>repo1, repo2, repo3, data-pipeline, ml-tools</answer>
</qa_pair>
```

此问题不佳的原因是:  
- 答案是一个列表,可能以任意顺序返回  
- 难以通过直接字符串比较进行验证  
- 大型语言模型(LLM)可能会以不同格式输出(JSON 数组、逗号分隔、换行分隔)  
- 更好是要求特定聚合值(如数量)或极值(如最多星标)  

## 验证流程  

创建评估后:  

1. **检查 XML 文件** 以了解其模式  
2. **加载每个任务指令**,并使用 MCP 服务器和工具并行地尝试自己解决问题,以确定正确答案  
3. **标记任何需要 WRITE 或破坏性操作** 的操作  
4. **收集所有正确答案**,并在文档中替换任何错误的答案  
5. **删除任何需要 WRITE 或破坏性操作的 `<qa_pair>`**  

请记住要并行化任务求解以避免上下文耗尽,然后在最后汇总所有答案并对文件进行修改。  

## 创建高质量评估的提示  

1. **提前深入思考并做好规划**,再生成任务  
2. **在有机会时进行并行化**,以加快进程并管理上下文  
3. **聚焦于真实使用场景**,即人类真正想要完成的任务  
4. **创建具有挑战性的问题**,以测试 MCP 服务器能力的极限  
5. **确保稳定性**,使用历史数据和已关闭的概念  
6. **自行验证答案**,使用 MCP 服务器工具亲自解答问题  
7. **根据过程中学到的内容进行迭代和优化**  

---  

# 运行评估  

创建评估文件后,可使用提供的评估套件来测试你的 MCP 服务器。  

## 设置  

1. **安装依赖项**  

   ```bash
   pip install -r scripts/requirements.txt
   ```

   或手动安装:  
   ```bash
   pip install anthropic mcp
   ```

2. **设置 API 密钥**  

   ```bash
   export ANTHROPIC_API_KEY=your_api_key_here
   ```

## 评估文件格式  

评估文件采用 XML 格式,包含 `<qa_pair>` 元素:  

```xml
<evaluation>
   <qa_pair>
      <question>找出在 2024 年第二季度创建且已完成任务数最多的项目。该项目名称是什么?</question>
      <answer>Website Redesign</answer>
   </qa_pair>
   <qa_pair>
      <question>搜索在 2024 年 3 月已关闭且标记为 "bug" 的问题。哪位用户关闭的问题最多?提供其用户名。</question>
      <answer>sarah_dev</answer>
   </qa_pair>
</evaluation>
```

## 运行评估  

评估脚本 (`scripts/evaluation.py`) 支持三种传输类型:  

**重要提示:**  
- **stdio 传输**:评估脚本会自动启动并管理 MCP 服务器进程。请勿手动运行服务器。  
- **sse/http 传输**:你必须先单独启动 MCP 服务器,然后评估脚本才会连接到指定 URL 上正在运行的服务器。  

### 1. 本地 STDIO 服务器  

用于本地运行的 MCP 服务器(脚本自动启动服务器):  

```bash
python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_mcp_server.py \
  evaluation.xml
```

带环境变量:  
```bash
python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_mcp_server.py \
  -e API_KEY=abc123 \
  -e DEBUG=true \
  evaluation.xml
```

### 2. 服务器发送事件(SSE)  

用于基于 SSE 的 MCP 服务器(你必须先启动服务器):  

```bash
python scripts/evaluation.py \
  -t sse \
  -u https://example.com/mcp \
  -H "Authorization: Bearer token123" \
  -H "X-Custom-Header: value" \
  evaluation.xml
```

### 3. HTTP(可流式 HTTP)  

用于基于 HTTP 的 MCP 服务器(你必须先启动服务器):  

```bash
python scripts/evaluation.py \
  -t http \
  -u https://example.com/mcp \
  -H "Authorization: Bearer token123" \
  evaluation.xml
```

## 命令行选项  

```
usage: evaluation.py [-h] [-t {stdio,sse,http}] [-m MODEL] [-c COMMAND]
                     [-a ARGS [ARGS ...]] [-e ENV [ENV ...]] [-u URL]
                     [-H HEADERS [HEADERS ...]] [-o OUTPUT]
                     eval_file

位置参数:
  eval_file             评估 XML 文件的路径

可选参数:
  -h, --help            显示帮助信息
  -t, --transport       传输类型:stdio、sse 或 http(默认:stdio)
  -m, --model           要使用的 Claude 模型(默认:claude-3-7-sonnet-20250219)
  -o, --output          报告的输出文件(默认:打印到 stdout)

stdio 选项:
  -c, --command         用于运行 MCP 服务器的命令(例如,python、node)
  -a, --args            命令的参数(例如,server.py)
  -e, --env             KEY=VALUE 格式的环境变量

sse/http 选项:
  -u, --url             MCP 服务器 URL
  -H, --header          'Key: Value' 格式的 HTTP 头
```

## 输出

评估脚本会生成一份详细报告,包含以下内容:

- **摘要统计信息**:
  - 准确率(正确数/总数)
  - 平均任务耗时
  - 每个任务的平均工具调用次数
  - 总工具调用次数

- **逐任务结果**:
  - 提示词及预期响应
  - 代理的实际响应
  - 答案是否正确(✅/❌)
  - 耗时和工具调用详情
  - 代理对其方法的总结
  - 代理对工具的反馈

### 将报告保存到文件

```bash
python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_server.py \
  -o evaluation_report.md \
  evaluation.xml
```

## 完整示例工作流

以下是一个创建和运行评估的完整示例:

1. **创建你的评估文件** (`my_evaluation.xml`):

```xml
<evaluation>
   <qa_pair>
      <question>找出在2024年1月创建最多问题的用户。他们的用户名是什么?</question>
      <answer>alice_developer</answer>
   </qa_pair>
   <qa_pair>
      <question>在2024年第一季度合并的所有拉取请求中,哪个仓库的数量最多?提供仓库名称。</question>
      <answer>backend-api</answer>
   </qa_pair>
   <qa_pair>
      <question>找出在2023年12月完成且从开始到结束持续时间最长的项目。它花了多少天?</question>
      <answer>127</answer>
   </qa_pair>
</evaluation>
```

2. **安装依赖项**:

```bash
pip install -r scripts/requirements.txt
export ANTHROPIC_API_KEY=your_api_key
```

3. **运行评估**:

```bash
python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a github_mcp_server.py \
  -e GITHUB_TOKEN=ghp_xxx \
  -o github_eval_report.md \
  my_evaluation.xml
```

4. **查看 `github_eval_report.md` 中的报告**,以:
   - 查看哪些问题通过/失败
   - 阅读代理对你的工具的反馈
   - 识别需要改进的地方
   - 迭代优化你的 MCP 服务器设计

## 故障排除

### 连接错误

如果出现连接错误:
- **STDIO**:验证命令和参数是否正确
- **SSE/HTTP**:检查 URL 是否可访问且头部是否正确
- 确保所需 API 密钥已设置在环境变量或头部中

### 准确率低

如果许多评估失败:
- 查看代理对每个任务的反馈
- 检查工具描述是否清晰且全面
- 验证输入参数是否已充分记录
- 考虑工具返回的数据是否过多或过少
- 确保错误消息具有可操作性

### 超时问题

如果任务超时:
- 使用更强大的模型(例如 `claude-3-7-sonnet-20250219`)
- 检查工具是否返回了过多数据
- 验证分页是否正常工作
- 考虑简化复杂问题
FILE:reference/node_mcp_server.md
# Node/TypeScript MCP 服务器实现指南

## 概述

本文档提供了使用 MCP TypeScript SDK 实现 MCP 服务器的 Node/TypeScript 特定最佳实践和示例。涵盖内容包括项目结构、服务器设置、工具注册模式、使用 Zod 进行输入验证、错误处理以及完整的可运行示例。

---

## 快速参考

### 关键导入
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import express from "express";
import { z } from "zod";
```

### 服务器初始化
```typescript
const server = new McpServer({
  name: "service-mcp-server",
  version: "1.0.0"
});
```

### 工具注册模式
```typescript
server.registerTool(
  "tool_name",
  {
    title: "Tool Display Name",
    description: "What the tool does",
    inputSchema: { param: z.string() },
    outputSchema: { result: z.string() }
  },
  async ({ param }) => {
    const output = { result: `Processed: ${param}` };
    return {
      content: [{ type: "text", text: JSON.stringify(output) }],
      structuredContent: output // Modern pattern for structured data
    };
  }
);
```

---

## MCP TypeScript SDK

官方 MCP TypeScript SDK 提供以下功能:
- 用于服务器初始化的 `McpServer` 类
- 用于工具注册的 `registerTool` 方法
- 与 Zod 模式的集成以实现运行时输入验证
- 类型安全的工具处理器实现

**重要 - 仅使用现代 API**:
- **应使用**:`server.registerTool()`、`server.registerResource()`、`server.registerPrompt()`
- **不应使用**:已弃用的旧 API,例如 `server.tool()`、`server.setRequestHandler(ListToolsRequestSchema, ...)` 或手动处理器注册
- `register*` 方法提供更好的类型安全性、自动模式处理,是推荐的方法

详见参考资料中的 MCP SDK 文档。

## 服务器命名规范

Node/TypeScript MCP 服务器必须遵循以下命名模式:
- **格式**:`{service}-mcp-server`(小写,使用连字符)
```
- **示例**: `github-mcp-server`, `jira-mcp-server`, `stripe-mcp-server`

名称应满足以下条件:
- 通用(不绑定特定功能)
- 能描述被集成的服务/API
- 可从任务描述中轻松推断
- 不包含版本号或日期

## 项目结构

为 Node/TypeScript MCP 服务器创建以下结构:

```
{service}-mcp-server/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts          # 主入口点,包含 McpServer 初始化
│   ├── types.ts          # TypeScript 类型定义和接口
│   ├── tools/            # 工具实现(每个领域一个文件)
│   ├── services/         # API 客户端和共享工具
│   ├── schemas/          # Zod 验证模式
│   └── constants.ts      # 共享常量(API_URL、CHARACTER_LIMIT 等)
└── dist/                 # 构建后的 JavaScript 文件(入口点:dist/index.js)
```

## 工具实现

### 工具命名

使用 snake_case 命名工具(例如 "search_users"、"create_project"、"get_channel_info"),名称应清晰且以动作为导向。

**避免命名冲突**:包含服务上下文以防止重叠:
- 使用 "slack_send_message" 而不是仅用 "send_message"
- 使用 "github_create_issue" 而不是仅用 "create_issue"
- 使用 "asana_list_tasks" 而不是仅用 "list_tasks"

### 工具结构

使用 `registerTool` 方法注册工具,需满足以下要求:
- 使用 Zod 模式进行运行时输入验证和类型安全
- 必须显式提供 `description` 字段 —— JSDoc 注释不会自动提取
- 显式提供 `title`、`description`、`inputSchema` 和 `annotations`
- `inputSchema` 必须是 Zod 模式对象(而非 JSON 模式)
- 显式声明所有参数和返回值的类型

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({
  name: "example-mcp",
  version: "1.0.0"
});

// 用于输入验证的 Zod 模式
const UserSearchInputSchema = z.object({
  query: z.string()
    .min(2, "查询字符串至少需 2 个字符")
    .max(200, "查询字符串不得超过 200 个字符")
    .describe("用于匹配姓名/邮箱的搜索字符串"),
  limit: z.number()
    .int()
    .min(1)
    .max(100)
    .default(20)
    .describe("返回结果的最大数量"),
  offset: z.number()
    .int()
    .min(0)
    .default(0)
    .describe("分页时跳过的结果数量"),
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("输出格式:'markdown' 表示人类可读,'json' 表示机器可读")
}).strict();

// 从 Zod 模式推导的类型定义
type UserSearchInput = z.infer<typeof UserSearchInputSchema>;

server.registerTool(
  "example_search_users",
  {
    title: "搜索 Example 用户",
    description: `在 Example 系统中按姓名、邮箱或团队搜索用户。

该工具在 Example 平台的所有用户档案中进行搜索,支持模糊匹配和多种搜索过滤器。它不会创建或修改用户,仅用于搜索现有用户。

参数:
  - query (string): 用于匹配姓名/邮箱的搜索字符串
  - limit (number): 返回结果的最大数量,范围为 1-100(默认值:20)
  - offset (number): 分页时跳过的结果数量(默认值:0)
  - response_format ('markdown' | 'json'): 输出格式(默认值:'markdown')

返回值:
  JSON 格式时:结构化数据,模式如下:
  {
    "total": number,           // 找到的匹配总数
    "count": number,           // 当前响应中的结果数量
    "offset": number,          // 当前分页偏移量
    "users": [
      {
        "id": string,          // 用户 ID(例如 "U123456789")
        "name": string,        // 全名(例如 "John Doe")
        "email": string,       // 邮箱地址
        "team": string,        // 团队名称(可选)
        "active": boolean      // 用户是否处于活跃状态
      }
    ],
    "has_more": boolean,       // 是否还有更多结果
    "next_offset": number      // 下一页的偏移量(当 has_more 为 true 时)
  }

使用示例:
  - 适用场景:"查找所有市场团队成员" -> 参数中 query="team:marketing"
  - 适用场景:"搜索 John 的账户" -> 参数中 query="john"
  - 不适用场景:你需要创建用户(应使用 example_create_user)

错误处理:
  - 若请求过多(状态码 429),返回 "Error: Rate limit exceeded"
  - 若搜索无结果,返回 "No users found matching '<query>'"`,
    inputSchema: UserSearchInputSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    }
  },
  async (params: UserSearchInput) => {
    try {
      // 输入验证由 Zod 模式处理
      // 使用已验证的参数发起 API 请求
      const data = await makeApiRequest<any>(
        "users/search",
        "GET",
        undefined,
        {
          q: params.query,
          limit: params.limit,
          offset: params.offset
        }
      );

      const users = data.users || [];
      const total = data.total || 0;

      if (!users.length) {
        return {
          content: [{
            type: "text",
            text: `No users found matching '${params.query}'`
          }]
        };
      }

      // 准备结构化输出
      const output = {
        total,
        count: users.length,
        offset: params.offset,
        users: users.map((user: any) => ({
          id: user.id,
          name: user.name,
          email: user.email,
          ...(user.team ? { team: user.team } : {}),
          active: user.active ?? true
        })),
        has_more: total > params.offset + users.length,
        ...(total > params.offset + users.length ? {
          next_offset: params.offset + users.length
        } : {})
      };

      // 根据请求的格式生成文本表示
      let textContent: string;
      if (params.response_format === ResponseFormat.MARKDOWN) {
        const lines = [`# User Search Results: '${params.query}'`, "",
          `Found ${total} users (showing ${users.length})`, ""];
        for (const user of users) {
          lines.push(`## ${user.name} (${user.id})`);
          lines.push(`- **Email**: ${user.email}`);
          if (user.team) lines.push(`- **Team**: ${user.team}`);
          lines.push("");
        }
        textContent = lines.join("\n");
      } else {
        textContent = JSON.stringify(output, null, 2);
      }

      return {
        content: [{ type: "text", text: textContent }],
        structuredContent: output // 结构化数据的现代模式
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: handleApiError(error)
        }]
      };
    }
  }
);
## Zod 输入验证模式

Zod 提供运行时类型验证:

```typescript
import { z } from "zod";

// 带验证的基本模式
const CreateUserSchema = z.object({
  name: z.string()
    .min(1, "姓名为必填项")
    .max(100, "姓名长度不得超过 100 个字符"),
  email: z.string()
    .email("邮箱格式无效"),
  age: z.number()
    .int("年龄必须为整数")
    .min(0, "年龄不能为负数")
    .max(150, "年龄不能超过 150")
}).strict();  // 使用 .strict() 禁止额外字段

// 枚举
enum ResponseFormat {
  MARKDOWN = "markdown",
  JSON = "json"
}

const SearchSchema = z.object({
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("输出格式")
});

// 带默认值的可选字段
const PaginationSchema = z.object({
  limit: z.number()
    .int()
    .min(1)
    .max(100)
    .default(20)
    .describe("返回结果的最大数量"),
  offset: z.number()
    .int()
    .min(0)
    .default(0)
    .describe("跳过的结果数量")
});
```

## 响应格式选项

支持多种输出格式以提高灵活性:

```typescript
enum ResponseFormat {
  MARKDOWN = "markdown",
  JSON = "json"
}

const inputSchema = z.object({
  query: z.string(),
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("输出格式:'markdown' 用于人类可读,'json' 用于机器可读")
});
```

**Markdown 格式**:
- 使用标题、列表和格式化以提高可读性
- 将时间戳转换为人类可读格式
- 显示名称并在括号中附带 ID
- 省略冗长的元数据
- 逻辑性地分组相关信息

**JSON 格式**:
- 返回完整、结构化的数据,适用于程序化处理
- 包含所有可用字段和元数据
- 使用一致的字段名和类型

## 分页实现

用于列出资源的工具:

```typescript
const ListSchema = z.object({
  limit: z.number().int().min(1).max(100).default(20),
  offset: z.number().int().min(0).default(0)
});

async function listItems(params: z.infer<typeof ListSchema>) {
  const data = await apiRequest(params.limit, params.offset);

  const response = {
    total: data.total,
    count: data.items.length,
    offset: params.offset,
    items: data.items,
    has_more: data.total > params.offset + data.items.length,
    next_offset: data.total > params.offset + data.items.length
      ? params.offset + data.items.length
      : undefined
  };

  return JSON.stringify(response, null, 2);
}
```

## 字符限制与截断

添加 CHARACTER_LIMIT 常量以防止响应过大:

```typescript
// 在 constants.ts 中作为模块级变量
export const CHARACTER_LIMIT = 25000;  // 响应最大字符数

async function searchTool(params: SearchInput) {
  let result = generateResponse(data);

  // 检查字符限制并在需要时截断
  if (result.length > CHARACTER_LIMIT) {
    const truncatedData = data.slice(0, Math.max(1, data.length / 2));
    response.data = truncatedData;
    response.truncated = true;
    response.truncation_message =
      `响应已从 ${data.length} 截断至 ${truncatedData.length} 项。` +
      `使用 'offset' 参数或添加过滤条件以查看更多结果。`;
    result = JSON.stringify(response, null, 2);
  }

  return result;
}
```

## 错误处理

提供清晰且可操作的错误信息:

```typescript
import axios, { AxiosError } from "axios";

function handleApiError(error: unknown): string {
  if (error instanceof AxiosError) {
    if (error.response) {
      switch (error.response.status) {
        case 404:
          return "错误:资源未找到。请检查 ID 是否正确。";
        case 403:
          return "错误:权限被拒绝。您无权访问此资源。";
        case 429:
          return "错误:请求频率超限。请稍后再试。";
        default:
          return `错误:API 请求失败,状态码 ${error.response.status}`;
      }
    } else if (error.code === "ECONNABORTED") {
      return "错误:请求超时。请重试。";
    }
  }
  return `错误:发生意外错误:${error instanceof Error ? error.message : String(error)}`;
}
```

## 共享工具函数

将通用功能提取为可复用函数:

```typescript
// 共享的 API 请求函数
async function makeApiRequest<T>(
  endpoint: string,
  method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
  data?: any,
  params?: any
): Promise<T> {
  try {
    const response = await axios({
      method,
      url: `${API_BASE_URL}/${endpoint}`,
      data,
      params,
      timeout: 30000,
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/json"
      }
    });
    return response.data;
  } catch (error) {
    throw error;
  }
}
```

## Async/Await 最佳实践
  
始终对网络请求和 I/O 操作使用 async/await:

```typescript
// Good: Async network request
async function fetchData(resourceId: string): Promise<ResourceData> {
  const response = await axios.get(`${API_URL}/resource/${resourceId}`);
  return response.data;
}

// Bad: Promise chains
function fetchData(resourceId: string): Promise<ResourceData> {
  return axios.get(`${API_URL}/resource/${resourceId}`)
    .then(response => response.data);  // Harder to read and maintain
}
```

## TypeScript 最佳实践

1. **使用严格的 TypeScript**:在 tsconfig.json 中启用严格模式  
2. **定义接口**:为所有数据结构创建清晰的接口定义  
3. **避免使用 `any`**:使用合适的类型或 `unknown` 而不是 `any`  
4. **使用 Zod 进行运行时验证**:使用 Zod 模式验证外部数据  
5. **类型守卫**:为复杂类型检查创建类型守卫函数  
6. **错误处理**:始终使用 try-catch 并进行正确的错误类型检查  
7. **空值安全**:使用可选链(`?.`)和空值合并(`??`)

```typescript
// Good: Type-safe with Zod and interfaces
interface UserResponse {
  id: string;
  name: string;
  email: string;
  team?: string;
  active: boolean;
}

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
  team: z.string().optional(),
  active: z.boolean()
});

type User = z.infer<typeof UserSchema>;

async function getUser(id: string): Promise<User> {
  const data = await apiCall(`/users/${id}`);
  return UserSchema.parse(data);  // Runtime validation
}

// Bad: Using any
async function getUser(id: string): Promise<any> {
  return await apiCall(`/users/${id}`);  // No type safety
}
```

## 包配置

### package.json

```json
{
  "name": "{service}-mcp-server",
  "version": "1.0.0",
  "description": "MCP server for {Service} API integration",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "start": "node dist/index.js",
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "clean": "rm -rf dist"
  },
  "engines": {
    "node": ">=18"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.6.1",
    "axios": "^1.7.9",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "tsx": "^4.19.2",
    "typescript": "^5.7.2"
  }
}
```

### tsconfig.json

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

## 完整示例

```typescript
#!/usr/bin/env node
/**
 * MCP Server for Example Service.
 *
 * This server provides tools to interact with Example API, including user search,
 * project management, and data export capabilities.
 */

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import axios, { AxiosError } from "axios";

// Constants
const API_BASE_URL = "https://api.example.com/v1";
const CHARACTER_LIMIT = 25000;

// Enums
enum ResponseFormat {
  MARKDOWN = "markdown",
  JSON = "json"
}

// Zod schemas
const UserSearchInputSchema = z.object({
  query: z.string()
    .min(2, "Query must be at least 2 characters")
    .max(200, "Query must not exceed 200 characters")
    .describe("Search string to match against names/emails"),
  limit: z.number()
    .int()
    .min(1)
    .max(100)
    .default(20)
    .describe("Maximum results to return"),
  offset: z.number()
    .int()
    .min(0)
    .default(0)
    .describe("Number of results to skip for pagination"),
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
}).strict();

type UserSearchInput = z.infer<typeof UserSearchInputSchema>;

// Shared utility functions
async function makeApiRequest<T>(
  endpoint: string,
  method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
  data?: any,
  params?: any
): Promise<T> {
  try {
    const response = await axios({
      method,
      url: `${API_BASE_URL}/${endpoint}`,
      data,
      params,
      timeout: 30000,
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/json"
      }
    });
    return response.data;
  } catch (error) {
    throw error;
  }
}

function handleApiError(error: unknown): string {
  if (error instanceof AxiosError) {
    if (error.response) {
      switch (error.response.status) {
        case 404:
          return "Error: Resource not found. Please check the ID is correct.";
        case 403:
          return "Error: Permission denied. You don't have access to this resource.";
        case 429:
          return "Error: Rate limit exceeded. Please wait before making more requests.";
        default:
          return `Error: API request failed with status ${error.response.status}`;
      }
    } else if (error.code === "ECONNABORTED") {
      return "Error: Request timed out. Please try again.";
    }
  }
  return `Error: Unexpected error occurred: ${error instanceof Error ? error.message : String(error)}`;
}

// Create MCP server instance
const server = new McpServer({
  name: "example-mcp",
  version: "1.0.0"
});

// Register tools
server.registerTool(
  "example_search_users",
  {
    title: "Search Example Users",
    description: `[Full description as shown above]`,
    inputSchema: UserSearchInputSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    }
  },
  async (params: UserSearchInput) => {
    // Implementation as shown above
  }
);

// Main function
// For stdio (local):
async function runStdio() {
  if (!process.env.EXAMPLE_API_KEY) {
    console.error("ERROR: EXAMPLE_API_KEY environment variable is required");
    process.exit(1);
  }

  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP server running via stdio");
}

// For streamable HTTP (remote):
async function runHTTP() {
  if (!process.env.EXAMPLE_API_KEY) {
    console.error("ERROR: EXAMPLE_API_KEY environment variable is required");
    process.exit(1);
  }

  const app = express();
  app.use(express.json());

  app.post('/mcp', async (req, res) => {
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,
      enableJsonResponse: true
    });
    res.on('close', () => transport.close());
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  });

  const port = parseInt(process.env.PORT || '3000');
  app.listen(port, () => {
    console.error(`MCP server running on http://localhost:${port}/mcp`);
  });
}

// Choose transport based on environment
const transport = process.env.TRANSPORT || 'stdio';
if (transport === 'http') {
  runHTTP().catch(error => {
    console.error("Server error:", error);
    process.exit(1);
  });
} else {
  runStdio().catch(error => {
    console.error("Server error:", error);
    process.exit(1);
  });
}
```
## 高级 MCP 功能

### 资源注册

将数据作为资源暴露,以实现基于 URI 的高效访问:

```typescript
import { ResourceTemplate } from "@modelcontextprotocol/sdk/types.js";

// 使用 URI 模板注册资源
server.registerResource(
  {
    uri: "file://documents/{name}",
    name: "Document Resource",
    description: "通过名称访问文档",
    mimeType: "text/plain"
  },
  async (uri: string) => {
    // 从 URI 中提取参数
    const match = uri.match(/^file:\/\/documents\/(.+)$/);
    if (!match) {
      throw new Error("无效的 URI 格式");
    }

    const documentName = match[1];
    const content = await loadDocument(documentName);

    return {
      contents: [{
        uri,
        mimeType: "text/plain",
        text: content
      }]
    };
  }
);

// 动态列出可用资源
server.registerResourceList(async () => {
  const documents = await getAvailableDocuments();
  return {
    resources: documents.map(doc => ({
      uri: `file://documents/${doc.name}`,
      name: doc.name,
      mimeType: "text/plain",
      description: doc.description
    }))
  };
});
```

**资源与工具的使用场景对比:**
- **资源**:适用于具有简单基于 URI 参数的数据访问
- **工具**:适用于需要验证和业务逻辑的复杂操作
- **资源**:当数据相对静态或基于模板时
- **工具**:当操作具有副作用或复杂工作流时

### 传输选项

TypeScript SDK 支持两种主要的传输机制:

#### 可流式 HTTP(推荐用于远程服务器)

```typescript
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";

const app = express();
app.use(express.json());

app.post('/mcp', async (req, res) => {
  // 为每个请求创建新的传输实例(无状态,防止请求 ID 冲突)
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true
  });

  res.on('close', () => transport.close());

  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000);
```

#### stdio(用于本地集成)

```typescript
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const transport = new StdioServerTransport();
await server.connect(transport);
```

**传输方式选择:**
- **可流式 HTTP**:Web 服务、远程访问、多个客户端
- **stdio**:命令行工具、本地开发、子进程集成

### 通知支持

在服务器状态更改时通知客户端:

```typescript
// 当工具列表更改时通知
server.notification({
  method: "notifications/tools/list_changed"
});

// 当资源列表更改时通知
server.notification({
  method: "notifications/resources/list_changed"
});
```

请谨慎使用通知——仅在服务器功能真正发生变化时才发送。
- [ ] 所有工具均使用 Zod 模式并通过 `.strict()` 实施运行时输入验证
- [ ] 所有 Zod 模式均具备适当的约束条件和描述性错误消息
- [ ] 所有工具均具有详尽的描述,明确说明输入/输出类型
- [ ] 描述中包含返回值示例和完整的模式文档
- [ ] 错误消息清晰、可操作且具有教育意义

### TypeScript 质量
- [ ] 为所有数据结构定义了 TypeScript 接口
- [ ] 在 tsconfig.json 中启用了严格的 TypeScript 模式
- [ ] 不使用 `any` 类型——应使用 `unknown` 或适当的类型替代
- [ ] 所有异步函数均具有显式的 Promise<T> 返回类型
- [ ] 错误处理使用了适当的类型守卫(例如 `axios.isAxiosError`、`z.ZodError`)

### 高级功能(如适用)
- [ ] 为适当的数据端点注册了资源
- [ ] 配置了适当的传输方式(stdio 或可流式 HTTP)
- [ ] 实现了通知机制以支持动态服务器能力
- [ ] 使用 SDK 接口实现类型安全

### 项目配置
- [ ] package.json 包含所有必要的依赖项
- [ ] 构建脚本在 dist/ 目录中生成可工作的 JavaScript
- [ ] 主入口点正确配置为 dist/index.js
- [ ] 服务器名称遵循格式:`{service}-mcp-server`
- [ ] tsconfig.json 正确配置并启用严格模式

### 代码质量
- [ ] 在适用情况下正确实现了分页
- [ ] 大型响应检查 CHARACTER_LIMIT 常量,并截断后附带清晰消息
- [ ] 为可能产生大量结果集的操作提供过滤选项
- [ ] 所有网络操作均能优雅地处理超时和连接错误
- [ ] 公共功能被提取为可复用的函数
- [ ] 类似操作的返回类型保持一致

### 测试与构建
- [ ] `npm run build` 成功完成且无错误
- [ ] 生成 dist/index.js 且可执行
- [ ] 服务器可运行:`node dist/index.js --help`
- [ ] 所有导入均能正确解析
- [ ] 示例工具调用按预期工作
## Pydantic v2 关键特性

- 使用 `model_config` 替代嵌套的 `Config` 类
- 使用 `field_validator` 替代已弃用的 `validator`
- 使用 `model_dump()` 替代已弃用的 `dict()`
- 验证器方法必须带有 `@classmethod` 装饰器
- 验证器方法必须包含类型提示

```python
from pydantic import BaseModel, Field, field_validator, ConfigDict

class CreateUserInput(BaseModel):
    model_config = ConfigDict(
        str_strip_whitespace=True,
        validate_assignment=True
    )

    name: str = Field(..., description="User's full name", min_length=1, max_length=100)
    email: str = Field(..., description="User's email address", pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
    age: int = Field(..., description="User's age", ge=0, le=150)

    @field_validator('email')
    @classmethod
    def validate_email(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("Email cannot be empty")
        return v.lower()
```

## 响应格式选项

支持多种输出格式以提高灵活性:

```python
from enum import Enum

class ResponseFormat(str, Enum):
    '''Output format for tool responses.'''
    MARKDOWN = "markdown"
    JSON = "json"

class UserSearchInput(BaseModel):
    query: str = Field(..., description="Search query")
    response_format: ResponseFormat = Field(
        default=ResponseFormat.MARKDOWN,
        description="Output format: 'markdown' for human-readable or 'json' for machine-readable"
    )
```

**Markdown 格式**:
- 使用标题、列表和格式化以提高可读性
- 将时间戳转换为人类可读格式(例如,使用 "2024-01-15 10:30:00 UTC" 而非时间戳)
- 显示名称后附带 ID(例如,"@john.doe (U123456)")
- 省略冗长的元数据(例如,仅显示一个头像 URL,而非所有尺寸)
- 逻辑性地分组相关信息

**JSON 格式**:
- 返回完整、结构化的数据,适用于程序化处理
- 包含所有可用字段和元数据
- 使用一致的字段名和类型

## 分页实现

针对列出资源的工具:

```python
class ListInput(BaseModel):
    limit: Optional[int] = Field(default=20, description="Maximum results to return", ge=1, le=100)
    offset: Optional[int] = Field(default=0, description="Number of results to skip for pagination", ge=0)

async def list_items(params: ListInput) -> str:
    # Make API request with pagination
    data = await api_request(limit=params.limit, offset=params.offset)

    # Return pagination info
    response = {
        "total": data["total"],
        "count": len(data["items"]),
        "offset": params.offset,
        "items": data["items"],
        "has_more": data["total"] > params.offset + len(data["items"]),
        "next_offset": params.offset + len(data["items"]) if data["total"] > params.offset + len(data["items"]) else None
    }
    return json.dumps(response, indent=2)
```

## 错误处理

提供清晰、可操作的错误消息:

```python
def _handle_api_error(e: Exception) -> str:
    '''Consistent error formatting across all tools.'''
    if isinstance(e, httpx.HTTPStatusError):
        if e.response.status_code == 404:
            return "Error: Resource not found. Please check the ID is correct."
        elif e.response.status_code == 403:
            return "Error: Permission denied. You don't have access to this resource."
        elif e.response.status_code == 429:
            return "Error: Rate limit exceeded. Please wait before making more requests."
        return f"Error: API request failed with status {e.response.status_code}"
    elif isinstance(e, httpx.TimeoutException):
        return "Error: Request timed out. Please try again."
    return f"Error: Unexpected error occurred: {type(e).__name__}"
```

## 共享工具函数

将通用功能提取为可复用的函数:

```python
# Shared API request function
async def _make_api_request(endpoint: str, method: str = "GET", **kwargs) -> dict:
    '''Reusable function for all API calls.'''
    async with httpx.AsyncClient() as client:
        response = await client.request(
            method,
            f"{API_BASE_URL}/{endpoint}",
            timeout=30.0,
            **kwargs
        )
        response.raise_for_status()
        return response.json()
```

## Async/Await 最佳实践

始终对网络请求和 I/O 操作使用 async/await:

```python
# Good: Async network request
async def fetch_data(resource_id: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(f"{API_URL}/resource/{resource_id}")
        response.raise_for_status()
        return response.json()

# Bad: Synchronous request
def fetch_data(resource_id: str) -> dict:
    response = requests.get(f"{API_URL}/resource/{resource_id}")  # Blocks
    return response.json()
```

## 类型提示

在整个代码中使用类型提示:

```python
from typing import Optional, List, Dict, Any

async def get_user(user_id: str) -> Dict[str, Any]:
    data = await fetch_user(user_id)
    return {"id": data["id"], "name": data["name"]}
```
## 工具文档字符串(Docstrings)

每个工具都必须包含带有明确类型信息的完整文档字符串(docstrings):

```python
async def search_users(params: UserSearchInput) -> str:
    '''
    通过姓名、邮箱或团队在 Example 系统中搜索用户。

    此工具会在 Example 平台的所有用户资料中进行搜索,
    支持模糊匹配和多种搜索过滤器。它不会
    创建或修改用户,仅用于搜索现有用户。

    Args:
        params (UserSearchInput): 已验证的输入参数,包含:
            - query (str): 用于匹配姓名/邮箱的搜索字符串(例如:"john"、"@example.com"、"team:marketing")
            - limit (Optional[int]): 返回结果的最大数量,范围为 1-100(默认值:20)
            - offset (Optional[int]): 分页时跳过的结果数量(默认值:0)

    Returns:
        str: JSON 格式的字符串,包含以下结构的搜索结果:

        成功响应:
        {
            "total": int,           # 找到的匹配总数
            "count": int,           # 当前响应中的结果数量
            "offset": int,          # 当前分页偏移量
            "users": [
                {
                    "id": str,      # 用户 ID(例如:"U123456789")
                    "name": str,    # 全名(例如:"John Doe")
                    "email": str,   # 邮箱地址(例如:"john@example.com")
                    "team": str     # 团队名称(例如:"Marketing")- 可选
                }
            ]
        }

        错误响应:
        "Error: <错误信息>" 或 "No users found matching '<query>'"

    Examples:
        - 使用场景:"查找所有市场部成员" -> query="team:marketing" 的 params
        - 使用场景:"搜索 John 的账户" -> query="john" 的 params
        - 不要使用场景:你需要创建用户(请改用 example_create_user)
        - 不要使用场景:你已有用户 ID 并需要完整详情(请改用 example_get_user)

    错误处理:
        - 输入验证错误由 Pydantic 模型处理
        - 若请求过多则返回 "Error: Rate limit exceeded"(429 状态)
        - 若 API 密钥无效则返回 "Error: Invalid API authentication"(401 状态)
        - 返回格式化结果列表或 "No users found matching 'query'"
    '''
```

## 完整示例

请参见以下完整的 Python MCP 服务器示例:

```python
#!/usr/bin/env python3
'''
Example 服务的 MCP 服务器。

该服务器提供与 Example API 交互的工具,包括用户搜索、
项目管理和数据导出功能。
'''

from typing import Optional, List, Dict, Any
from enum import Enum
import httpx
from pydantic import BaseModel, Field, field_validator, ConfigDict
from mcp.server.fastmcp import FastMCP

# 初始化 MCP 服务器
mcp = FastMCP("example_mcp")

# 常量
API_BASE_URL = "https://api.example.com/v1"

# 枚举
class ResponseFormat(str, Enum):
    '''工具响应的输出格式。'''
    MARKDOWN = "markdown"
    JSON = "json"

# 用于输入验证的 Pydantic 模型
class UserSearchInput(BaseModel):
    '''用户搜索操作的输入模型。'''
    model_config = ConfigDict(
        str_strip_whitespace=True,
        validate_assignment=True
    )

    query: str = Field(..., description="用于匹配姓名/邮箱的搜索字符串", min_length=2, max_length=200)
    limit: Optional[int] = Field(default=20, description="返回结果的最大数量", ge=1, le=100)
    offset: Optional[int] = Field(default=0, description="分页时跳过的结果数量", ge=0)
    response_format: ResponseFormat = Field(default=ResponseFormat.MARKDOWN, description="输出格式")

    @field_validator('query')
    @classmethod
    def validate_query(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("查询内容不能为空或仅包含空白字符")
        return v.strip()

# 共享工具函数
async def _make_api_request(endpoint: str, method: str = "GET", **kwargs) -> dict:
    '''所有 API 调用的可复用函数。'''
    async with httpx.AsyncClient() as client:
        response = await client.request(
            method,
            f"{API_BASE_URL}/{endpoint}",
            timeout=30.0,
            **kwargs
        )
        response.raise_for_status()
        return response.json()

def _handle_api_error(e: Exception) -> str:
    '''所有工具中一致的错误格式化处理。'''
    if isinstance(e, httpx.HTTPStatusError):
        if e.response.status_code == 404:
            return "Error: Resource not found. Please check the ID is correct."
        elif e.response.status_code == 403:
            return "Error: Permission denied. You don't have access to this resource."
        elif e.response.status_code == 429:
            return "Error: Rate limit exceeded. Please wait before making more requests."
        return f"Error: API request failed with status {e.response.status_code}"
    elif isinstance(e, httpx.TimeoutException):
        return "Error: Request timed out. Please try again."
    return f"Error: Unexpected error occurred: {type(e).__name__}"

# 工具定义
@mcp.tool(
    name="example_search_users",
    annotations={
        "title": "Search Example Users",
        "readOnlyHint": True,
        "destructiveHint": False,
        "idempotentHint": True,
        "openWorldHint": True
    }
)
async def example_search_users(params: UserSearchInput) -> str:
    '''Search for users in the Example system by name, email, or team.

    [上方所示的完整文档字符串]
    '''
    try:
        # 使用已验证的参数发起 API 请求
        data = await _make_api_request(
            "users/search",
            params={
                "q": params.query,
                "limit": params.limit,
                "offset": params.offset
            }
        )

        users = data.get("users", [])
        total = data.get("total", 0)

        if not users:
            return f"No users found matching '{params.query}'"

        # 根据请求的格式进行响应格式化
        if params.response_format == ResponseFormat.MARKDOWN:
            lines = [f"# User Search Results: '{params.query}'", ""]
            lines.append(f"Found {total} users (showing {len(users)})")
            lines.append("")

            for user in users:
                lines.append(f"## {user['name']} ({user['id']})")
                lines.append(f"- **Email**: {user['email']}")
                if user.get('team'):
                    lines.append(f"- **Team**: {user['team']}")
                lines.append("")

            return "\n".join(lines)

        else:
            # 机器可读的 JSON 格式
            import json
            response = {
                "total": total,
                "count": len(users),
                "offset": params.offset,
                "users": users
            }
            return json.dumps(response, indent=2)

    except Exception as e:
        return _handle_api_error(e)

if __name__ == "__main__":
    mcp.run()
```
```

---

## 高级 FastMCP 功能

### 上下文参数注入

FastMCP 可以自动将 `Context` 参数注入工具中,以实现日志记录、进度报告、资源读取和用户交互等高级功能:

```python
from mcp.server.fastmcp import FastMCP, Context

mcp = FastMCP("example_mcp")

@mcp.tool()
async def advanced_search(query: str, ctx: Context) -> str:
    '''具有上下文访问权限的高级工具,用于日志记录和进度报告。'''

    # 报告长时间操作的进度
    await ctx.report_progress(0.25, "正在开始搜索...")

    # 记录用于调试的信息
    await ctx.log_info("处理查询", {"query": query, "timestamp": datetime.now()})

    # 执行搜索
    results = await search_api(query)
    await ctx.report_progress(0.75, "正在格式化结果...")

    # 访问服务器配置
    server_name = ctx.fastmcp.name

    return format_results(results)

@mcp.tool()
async def interactive_tool(resource_id: str, ctx: Context) -> str:
    '''能够请求用户提供额外输入的工具。'''

    # 在需要时请求敏感信息
    api_key = await ctx.elicit(
        prompt="请提供您的 API 密钥:",
        input_type="password"
    )

    # 使用提供的密钥
    return await api_call(resource_id, api_key)
```

**上下文能力:**
- `ctx.report_progress(progress, message)` - 报告长时间操作的进度
- `ctx.log_info(message, data)` / `ctx.log_error()` / `ctx.log_debug()` - 日志记录
- `ctx.elicit(prompt, input_type)` - 请求用户输入
- `ctx.fastmcp.name` - 访问服务器配置
- `ctx.read_resource(uri)` - 读取 MCP 资源

### 资源注册

将数据作为资源公开,以实现基于模板的高效访问:

```python
@mcp.resource("file://documents/{name}")
async def get_document(name: str) -> str:
    '''将文档作为 MCP 资源公开。

    资源适用于不需要复杂参数的静态或半静态数据。
    它们使用 URI 模板实现灵活访问。
    '''
    document_path = f"./docs/{name}"
    with open(document_path, "r") as f:
        return f.read()

@mcp.resource("config://settings/{key}")
async def get_setting(key: str, ctx: Context) -> str:
    '''通过上下文将配置作为资源公开。'''
    settings = await load_settings()
    return json.dumps(settings.get(key, {}))
```

**资源与工具的使用场景对比:**
- **资源**:适用于具有简单参数(URI 模板)的数据访问
- **工具**:适用于具有验证和业务逻辑的复杂操作

### 结构化输出类型

FastMCP 支持除字符串之外的多种返回类型:

```python
from typing import TypedDict
from dataclasses import dataclass
from pydantic import BaseModel

# 用于结构化返回的 TypedDict
class UserData(TypedDict):
    id: str
    name: str
    email: str

@mcp.tool()
async def get_user_typed(user_id: str) -> UserData:
    '''返回结构化数据 —— FastMCP 处理序列化。'''
    return {"id": user_id, "name": "John Doe", "email": "john@example.com"}

# 用于复杂验证的 Pydantic 模型
class DetailedUser(BaseModel):
    id: str
    name: str
    email: str
    created_at: datetime
    metadata: Dict[str, Any]

@mcp.tool()
async def get_user_detailed(user_id: str) -> DetailedUser:
    '''返回 Pydantic 模型 —— 自动生成 schema。'''
    user = await fetch_user(user_id)
    return DetailedUser(**user)
```

### 生命周期管理

初始化可在多个请求间持久存在的资源:

```python
from contextlib import asynccontextmanager

@asynccontextmanager
async def app_lifespan():
    '''管理生命周期与服务器相同的资源。'''
    # 初始化连接、加载配置等
    db = await connect_to_database()
    config = load_configuration()

    # 使所有工具均可访问
    yield {"db": db, "config": config}

    # 关闭时清理
    await db.close()

mcp = FastMCP("example_mcp", lifespan=app_lifespan)

@mcp.tool()
async def query_data(query: str, ctx: Context) -> str:
    '''通过上下文访问生命周期资源。'''
    db = ctx.request_context.lifespan_state["db"]
    results = await db.query(query)
    return format_results(results)
```

### 传输选项

FastMCP 支持两种主要的传输机制:

```python
# stdio 传输(用于本地工具)- 默认
if __name__ == "__main__":
    mcp.run()

# 可流式 HTTP 传输(用于远程服务器)
if __name__ == "__main__":
    mcp.run(transport="streamable_http", port=8000)
```

**传输方式选择:**
- **stdio**:命令行工具、本地集成、子进程执行
- **Streamable HTTP**:Web 服务、远程访问、多客户端

---

## 代码最佳实践

### 代码可组合性与可重用性

你的实现必须优先考虑可组合性和代码复用:

1. **提取通用功能**:
   - 为在多个工具中使用的操作创建可重用的辅助函数
```
   - 为 HTTP 请求构建共享的 API 客户端,而不是复制代码
   - 将错误处理逻辑集中到工具函数中
   - 将业务逻辑提取到可组合的专用函数中
   - 提取共享的 markdown 或 JSON 字段选择与格式化功能

2. **避免重复**:
   - 绝不允许在工具之间复制粘贴相似代码
   - 如果你发现自己写了两次相似的逻辑,请将其提取为一个函数
   - 分页、过滤、字段选择和格式化等常见操作应被共享
   - 认证/授权逻辑应集中管理

### Python 特定最佳实践

1. **使用类型提示**:始终为函数参数和返回值包含类型注解
2. **Pydantic 模型**:为所有输入验证定义清晰的 Pydantic 模型
3. **避免手动验证**:让 Pydantic 使用约束条件处理输入验证
4. **正确的导入**:对导入进行分组(标准库、第三方、本地)
5. **错误处理**:使用特定的异常类型(如 httpx.HTTPStatusError,而非通用 Exception)
6. **异步上下文管理器**:对需要清理的资源使用 `async with`
7. **常量**:在模块级别以 UPPER_CASE 定义常量

## 质量检查清单

在最终确定你的 Python MCP 服务器实现之前,请确保:

### 战略设计
- [ ] 工具支持完整的流程,而不仅仅是 API 端点包装器
- [ ] 工具名称反映自然的任务划分
- [ ] 响应格式优化了智能体上下文效率
- [ ] 在适当的地方使用人类可读的标识符
- [ ] 错误消息引导智能体正确使用

### 实现质量
- [ ] 聚焦实现:实现了最重要和最有价值的工具
- [ ] 所有工具都有描述性名称和文档
- [ ] 返回类型在相似操作中保持一致
- [ ] 所有外部调用都实现了错误处理
- [ ] 服务器名称遵循格式:`{service}_mcp`
- [ ] 所有网络操作使用 async/await
- [ ] 共同功能被提取为可重用函数
- [ ] 错误消息清晰、可操作且具教育意义
- [ ] 输出经过正确验证和格式化

### 工具配置
- [ ] 所有工具在装饰器中实现了 'name' 和 'annotations'
- [ ] 注解正确设置(readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
- [ ] 所有工具使用 Pydantic BaseModel 进行输入验证,并使用 Field() 定义
- [ ] 所有 Pydantic 字段具有明确的类型、描述和约束
- [ ] 所有工具都有完整的文档字符串,明确输入/输出类型
- [ ] 文档字符串包含 dict/JSON 返回值的完整 schema 结构
- [ ] Pydantic 模型处理输入验证(无需手动验证)

### 高级功能(如适用)
- [ ] 使用上下文注入进行日志记录、进度跟踪或提示获取
- [ ] 为适当的数据端点注册了资源
- [ ] 实现了生命周期管理以维持持久连接
- [ ] 使用了结构化输出类型(TypedDict, Pydantic 模型)
- [ ] 配置了适当的传输方式(stdio 或可流式 HTTP)

### 代码质量
- [ ] 文件包含正确的导入,包括 Pydantic 导入
- [ ] 在适用情况下正确实现了分页
- [ ] 为潜在的大结果集提供了过滤选项
- [ ] 所有异步函数都使用 `async def` 正确定义
- [ ] HTTP 客户端使用遵循异步模式并正确使用上下文管理器
- [ ] 代码中始终使用类型提示
- [ ] 常量在模块级别以 UPPER_CASE 定义

### 测试
- [ ] 服务器成功运行:`python your_server.py --help`
- [ ] 所有导入正确解析
- [ ] 示例工具调用按预期工作
- [ ] 错误场景被优雅处理
FILE:scripts/connections.py
"""轻量级 MCP 服务器连接处理。"""

from abc import ABC, abstractmethod
from contextlib import AsyncExitStack
from typing import Any

from mcp import ClientSession, StdioServerParameters
from mcp.client.sse import sse_client
from mcp.client.stdio import stdio_client
from mcp.client.streamable_http import streamablehttp_client


class MCPConnection(ABC):
    """MCP 服务器连接的基类。"""

    def __init__(self):
        self.session = None
        self._stack = None

    @abstractmethod
    def _create_context(self):
        """根据连接类型创建连接上下文。"""

    async def __aenter__(self):
        """初始化 MCP 服务器连接。"""
        self._stack = AsyncExitStack()
        await self._stack.__aenter__()

        try:
            ctx = self._create_context()
            result = await self._stack.enter_async_context(ctx)

            if len(result) == 2:
                read, write = result
            elif len(result) == 3:
                read, write, _ = result
            else:
                raise ValueError(f"意外的上下文结果:{result}")

            session_ctx = ClientSession(read, write)
            self.session = await self._stack.enter_async_context(session_ctx)
            await self.session.initialize()
            return self
        except BaseException:
            await self._stack.__aexit__(None, None, None)
            raise

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        """清理 MCP 服务器连接资源。"""
        if self._stack:
            await self._stack.__aexit__(exc_type, exc_val, exc_tb)
        self.session = None
        self._stack = None

    async def list_tools(self) -> list[dict[str, Any]]:
        """从 MCP 服务器检索可用工具。"""
        response = await self.session.list_tools()
        return [
            {
                "name": tool.name,
                "description": tool.description,
                "input_schema": tool.inputSchema,
            }
            for tool in response.tools
        ]

    async def call_tool(self, tool_name: str, arguments: dict[str, Any]) -> Any:
        """使用提供的参数调用 MCP 服务器上的工具。"""
        result = await self.session.call_tool(tool_name, arguments=arguments)
        return result.content


class MCPConnectionStdio(MCPConnection):
    """使用标准输入/输出的 MCP 连接。"""

    def __init__(self, command: str, args: list[str] = None, env: dict[str, str] = None):
        super().__init__()
        self.command = command
        self.args = args or []
        self.env = env

    def _create_context(self):
        return stdio_client(
            StdioServerParameters(command=self.command, args=self.args, env=self.env)
        )


class MCPConnectionSSE(MCPConnection):
    """使用服务器发送事件(Server-Sent Events)的 MCP 连接。"""

    def __init__(self, url: str, headers: dict[str, str] = None):
        super().__init__()
        self.url = url
        self.headers = headers or {}

    def _create_context(self):
        return sse_client(url=self.url, headers=self.headers)


class MCPConnectionHTTP(MCPConnection):
    """使用可流式 HTTP(Streamable HTTP)的 MCP 连接。"""

    def __init__(self, url: str, headers: dict[str, str] = None):
        super().__init__()
        self.url = url
        self.headers = headers or {}

    def _create_context(self):
        return streamablehttp_client(url=self.url, headers=self.headers)


def create_connection(
    transport: str,
    command: str = None,
    args: list[str] = None,
    env: dict[str, str] = None,
    url: str = None,
    headers: dict[str, str] = None,
) -> MCPConnection:
    """工厂函数,用于创建适当的 MCP 连接。

    参数:
        transport: 连接类型("stdio"、"sse" 或 "http")
        command: 要运行的命令(仅 stdio)
        args: 命令参数(仅 stdio)
        env: 环境变量(仅 stdio)
        url: 服务器 URL(仅 sse 和 http)
        headers: HTTP 头(仅 sse 和 http)

    返回:
        MCPConnection 实例
    """
    transport = transport.lower()

    if transport == "stdio":
        if not command:
            raise ValueError("stdio 传输需要命令")
        return MCPConnectionStdio(command=command, args=args, env=env)

    elif transport == "sse":
        if not url:
            raise ValueError("sse 传输需要 URL")
        return MCPConnectionSSE(url=url, headers=headers)

    elif transport in ["http", "streamable_http", "streamable-http"]:
        if not url:
            raise ValueError("http 传输需要 URL")
        return MCPConnectionHTTP(url=url, headers=headers)

    else:
        raise ValueError(f"不支持的传输类型:{transport}。请使用 'stdio'、'sse' 或 'http'")
  - 评论描述:它们是否准确描述了工具的功能?
  - 评论工具使用过程中遇到的任何错误:工具是否未能执行?工具是否返回了过多 token?
  - 指出具体的改进领域,并解释为何这些改进会有帮助
  - 你的建议应具体且可操作

响应要求:
- 你的回应应简洁,并直接回答所提问题
- 始终将最终回应用 <response> 标签包裹
- 如果你无法完成任务,请返回 <response>NOT_FOUND</response>
- 对于数值响应,仅提供数字
- 对于 ID,仅提供 ID
- 对于名称或文本,提供所请求的确切文本
- 你的回应应放在最后
        "summary": summary,
        "feedback": feedback,
    }


REPORT_HEADER = """
# 评估报告

## 摘要

- **准确率**: {correct}/{total} ({accuracy:.1f}%)
- **平均任务耗时**: {average_duration_s:.2f}s
- **平均每任务工具调用次数**: {average_tool_calls:.2f}
- **工具调用总次数**: {total_tool_calls}

---
"""

TASK_TEMPLATE = """
### 任务 {task_num}

**问题**: {question}
**真实答案**: `{expected_answer}`
**实际答案**: `{actual_answer}`
**正确性**: {correct_indicator}
**耗时**: {total_duration:.2f}s
**工具调用**: {tool_calls}

**摘要**
{summary}

**反馈**
{feedback}

---
"""


async def run_evaluation(
    eval_path: Path,
    connection: Any,
    model: str = "claude-3-7-sonnet-20250219",
) -> str:
    """使用 MCP 服务器工具运行评估。"""
    print("🚀 开始评估")

    client = Anthropic()

    tools = await connection.list_tools()
    print(f"📋 从 MCP 服务器加载了 {len(tools)} 个工具")

    qa_pairs = parse_evaluation_file(eval_path)
    print(f"📋 加载了 {len(qa_pairs)} 个评估任务")

    results = []
    for i, qa_pair in enumerate(qa_pairs):
        print(f"正在处理任务 {i + 1}/{len(qa_pairs)}")
        result = await evaluate_single_task(client, model, qa_pair, tools, connection, i)
        results.append(result)

    correct = sum(r["score"] for r in results)
    accuracy = (correct / len(results)) * 100 if results else 0
    average_duration_s = sum(r["total_duration"] for r in results) / len(results) if results else 0
    average_tool_calls = sum(r["num_tool_calls"] for r in results) / len(results) if results else 0
    total_tool_calls = sum(r["num_tool_calls"] for r in results)

    report = REPORT_HEADER.format(
        correct=correct,
        total=len(results),
        accuracy=accuracy,
        average_duration_s=average_duration_s,
        average_tool_calls=average_tool_calls,
        total_tool_calls=total_tool_calls,
    )

    report += "".join([
        TASK_TEMPLATE.format(
            task_num=i + 1,
            question=qa_pair["question"],
            expected_answer=qa_pair["answer"],
            actual_answer=result["actual"] or "N/A",
            correct_indicator="✅" if result["score"] else "❌",
            total_duration=result["total_duration"],
            tool_calls=json.dumps(result["tool_calls"], indent=2),
            summary=result["summary"] or "N/A",
            feedback=result["feedback"] or "N/A",
        )
        for i, (qa_pair, result) in enumerate(zip(qa_pairs, results))
    ])

    return report


def parse_headers(header_list: list[str]) -> dict[str, str]:
    """将格式为 'Key: Value' 的头部字符串解析为字典。"""
    headers = {}
    if not header_list:
        return headers

    for header in header_list:
        if ":" in header:
            key, value = header.split(":", 1)
            headers[key.strip()] = value.strip()
        else:
            print(f"警告:忽略格式错误的头部:{header}")
    return headers


def parse_env_vars(env_list: list[str]) -> dict[str, str]:
    """将格式为 'KEY=VALUE' 的环境变量字符串解析为字典。"""
    env = {}
    if not env_list:
        return env

    for env_var in env_list:
        if "=" in env_var:
            key, value = env_var.split("=", 1)
            env[key.strip()] = value.strip()
        else:
            print(f"警告:忽略格式错误的环境变量:{env_var}")
    return env


async def main():
    parser = argparse.ArgumentParser(
        description="使用测试问题评估 MCP 服务器",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
示例:
  # 评估本地 stdio MCP 服务器
  python evaluation.py -t stdio -c python -a my_server.py eval.xml

  # 评估 SSE MCP 服务器
  python evaluation.py -t sse -u https://example.com/mcp -H "Authorization: Bearer token" eval.xml

  # 使用自定义模型评估 HTTP MCP 服务器
  python evaluation.py -t http -u https://example.com/mcp -m claude-3-5-sonnet-20241022 eval.xml
        """,
    )

    parser.add_argument("eval_file", type=Path, help="指向评估 XML 文件的路径")
    parser.add_argument("-t", "--transport", choices=["stdio", "sse", "http"], default="stdio", help="传输类型(默认:stdio)")
    parser.add_argument("-m", "--model", default="claude-3-7-sonnet-20250219", help="使用的 Claude 模型(默认:claude-3-7-sonnet-20250219)")

    stdio_group = parser.add_argument_group("stdio 选项")
    stdio_group.add_argument("-c", "--command", help="运行 MCP 服务器的命令(仅限 stdio)")
    stdio_group.add_argument("-a", "--args", nargs="+", help="命令参数(仅限 stdio)")
    stdio_group.add_argument("-e", "--env", nargs="+", help="KEY=VALUE 格式的环境变量(仅限 stdio)")

    remote_group = parser.add_argument_group("sse/http 选项")
    remote_group.add_argument("-u", "--url", help="MCP 服务器 URL(仅限 sse/http)")
    remote_group.add_argument("-H", "--header", nargs="+", dest="headers", help="HTTP headers in 'Key: Value' format (sse/http only)")

    parser.add_argument("-o", "--output", type=Path, help="评估报告的输出文件(默认:stdout)")

    args = parser.parse_args()

    if not args.eval_file.exists():
        print(f"错误:未找到评估文件:{args.eval_file}")
        sys.exit(1)

    headers = parse_headers(args.headers) if args.headers else None
    env_vars = parse_env_vars(args.env) if args.env else None

    try:
        connection = create_connection(
            transport=args.transport,
            command=args.command,
            args=args.args,
            env=env_vars,
            url=args.url,
            headers=headers,
        )
    except ValueError as e:
        print(f"错误:{e}")
        sys.exit(1)

    print(f"🔗 正在通过 {args.transport} 连接到 MCP 服务器...")

    async with connection:
        print("✅ 连接成功")
        report = await run_evaluation(args.eval_file, connection, args.model)

        if args.output:
            args.output.write_text(report)
            print(f"\n✅ 报告已保存至 {args.output}")
        else:
            print("\n" + report)


if __name__ == "__main__":
    asyncio.run(main())
FILE:scripts/example_evaluation.xml
<evaluation>
   <qa_pair>
      <question>计算将 10,000 美元以每年 5% 的利率投资,每月复利,3 年后的复利。最终金额是多少美元(四舍五入到小数点后两位)?</question>
      <answer>11614.72</answer>
   </qa_pair>
   <qa_pair>
      <question>一个抛射体以 45 度角、初速度 50 m/s 发射。假设 g=9.8 m/s²,在 2 秒后它从发射点移动的总距离是多少米?四舍五入到小数点后两位。</question>
      <answer>87.25</answer>
   </qa_pair>
   <qa_pair>
      <question>一个球体的体积为 500 立方米。计算其表面积(平方米)。四舍五入到小数点后两位。</question>
      <answer>304.65</answer>
   </qa_pair>
   <qa_pair>
      <question>计算该数据集的总体标准差:[12, 15, 18, 22, 25, 30, 35]。四舍五入到小数点后两位。</question>
      <answer>7.61</answer>
   </qa_pair>
   <qa_pair>
      <question>计算氢离子浓度为 3.5 × 10^-5 M 的溶液的 pH 值。四舍五入到小数点后两位。</question>
      <answer>4.46</answer>
   </qa_pair>
</evaluation>
FILE:scripts/requirements.txt
anthropic>=0.39.0
mcp>=1.1.0

可替换内容

  • [✅ 评估指南]
  • [📋 MCP 最佳实践]
  • [🐍 Python 实现指南]
  • [⚡ TypeScript 实现指南]
  • [...]
  • [-h]
  • [-t {stdio,sse,http}]
  • [-m MODEL]
  • [-c COMMAND]
  • [-a ARGS [ARGS ...]
  • [-e ENV [ENV ...]
  • [-u URL]
  • [-H HEADERS [HEADERS ...]
  • [-o OUTPUT]
  • [{ type: "text", text: textContent }]
  • ["ES2022"]
  • ["src/**/*"]
  • ["node_modules", "dist"]
  • [Full description as shown above]
  • [1]
  • [ ]
  • [\w\.-]
  • [int]
  • ["total"]
  • ["items"]
  • [str, Any]
  • ["id"]
  • ["name"]
  • [上方所示的完整文档字符串]
  • ['name']
  • ['id']
  • ['email']
  • ['team']
  • ["db"]
  • [dict[str, Any]
  • [str]
  • [str, str]
  • ["score"]
  • ["total_duration"]
  • ["num_tool_calls"]

分类与标签

编程开发、编程开发、学习教育、语言处理、结构化输出

前往 AI 图片创作