MCP提示词

2 个提示词

技能

用于创建高质量 MCP（模型上下文协议）服务器的指南，使 LLM 能够通过精心设计的工具与外部服务交互。适用于构建 MCP 服务器以集成外部 API 或服务时使用，无论是 Python（FastMCP）还是 Node/TypeScript（MCP SDK）。

---
name: mcp-builder
description: 创建高质量 MCP（模型上下文协议）服务器的指南，使 LLM 能够通过精心设计的工具与外部服务交互。在构建 MCP 服务器以集成外部 API 或服务时使用，无论是 Python（FastMCP）还是 Node/TypeScript（MCP SDK）。
license: 完整条款见 LICENSE.txt
---

# MCP 服务器开发指南

## 概述

创建 MCP（模型上下文协议）服务器，使 LLM 能够通过精心设计的工具与外部服务交互。MCP 服务器的质量以其帮助 LLM 完成现实世界任务的程度来衡量。

---

# 流程

## 🚀 高层工作流

创建高质量的 MCP 服务器涉及四个主要阶段：

### 阶段 1：深入研究和规划

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

**API 覆盖 vs. 工作流工具：**
在全面的 API 端点覆盖与专门的工作流工具之间取得平衡。工作流工具对于特定任务可能更方便，而全面的覆盖则赋予代理组合操作的灵活性。性能因客户端而异——一些客户端受益于结合基本工具的代码执行，而另一些则更适合使用更高层的工作流。当不确定时，优先考虑全面的 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）
- 工具、资源和提示定义

#### 1.3 研究框架文档

**推荐技术栈：**
- **语言**：TypeScript（高质量的 SDK 支持，在许多执行环境（如 MCPB）中具有良好的兼容性。此外，AI 模型擅长生成 TypeScript 代码，得益于其广泛使用、静态类型和良好的 linting 工具）
- **传输**：远程服务器使用可流式 HTTP，采用无状态 JSON（与有状态会话和流式响应相比，更易于扩展和维护）。本地服务器使用 stdio。

**加载框架文档：**

- **MCP 最佳实践**：[📋 查看最佳实践](./reference/mcp_best_practices.md) - 核心指南

**对于 TypeScript（推荐）：**
- **TypeScript SDK**：使用 WebFetch 加载 `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
- [⚡ TypeScript 指南](./reference/node_mcp_server.md) - TypeScript 模式和示例

**对于 Python：**
- **Python SDK**：使用 WebFetch 加载 `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
- [🐍 Python 指南](./reference/python_mcp_server.md) - Python 模式和示例

#### 1.4 规划你的实现

**理解 API：**
查看服务的 API 文档，以识别关键端点、认证要求和数据模型。根据需要利用网络搜索和 WebFetch。

**工具选择：**
优先考虑全面的 API 覆盖。列出要实现的端点，从最常见的操作开始。

---

### 阶段 2：实现

#### 2.1 设置项目结构

请参阅特定语言的指南进行项目设置：
- [⚡ TypeScript 指南](./reference/node_mcp_server.md) - 项目结构、package.json、tsconfig.json
- [🐍 Python 指南](./reference/python_mcp_server.md) - 模块组织、依赖项

#### 2.2 实现核心基础设施

创建共享工具：
- 带认证的 API 客户端
- 错误处理辅助函数
- 响应格式化（JSON/Markdown）
- 分页支持

#### 2.3 实现工具

对于每个工具：

**输入模式：**
- 使用 Zod（TypeScript）或 Pydantic（Python）
- 包含约束和清晰的描述
- 在字段描述中添加示例

**输出模式：**
- 尽可能为结构化数据定义 `outputSchema`
- 在工具响应中使用 `structuredContent`（TypeScript SDK 特性）
- 帮助客户端理解和处理工具输出

**工具描述：**
- 功能的简洁摘要
- 参数描述
- 返回类型模式

**实现：**
- 对 I/O 操作使用异步/等待
- 使用可操作的消息进行适当的错误处理
- 在适用的情况下支持分页
- 使用现代 SDK 时同时返回文本内容和结构化数据

**注解：**
- `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>查找讨论 ab推出以动物为代号的 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 | 工具与外部实体交互 |

**重要**：注解只是提示，不是安全保证。客户端不应仅基于注解做出安全关键决策。

---

## 错误处理

- 使用标准 JSON-RPC 错误码
- 在结果对象中报告工具错误（而非协议级错误）
- 提供有帮助、具体的错误消息并附带建议的后续步骤
- 不要暴露内部实现细节
- 在错误发生时正确清理资源

错误处理示例：
```typescript
try {
  const result = performOperation();
  return { content: [{ type: "text", text: result }] };
} catch (error) {
  return {
    isError: true,
    content: [{
      type: "text",
      text: `Error: error.message. Try using filter='active_only' to reduce results.`
    }]
  };
}
```

---

## 测试要求

全面的测试应覆盖：

- **功能测试**：验证在有效/无效输入下的正确执行
- **集成测试**：测试与外部系统的交互
- **安全测试**：验证认证、输入清理、速率限制
- **性能测试**：检查负载下的行为、超时
- **错误处理**：确保正确的错误报告和清理

---

## 文档要求

- 为所有工具和功能提供清晰的文档
- 包含可运行的示例（每个主要功能至少 3 个）
- 记录安全注意事项
- 说明所需的权限和访问级别
- 记录速率限制和性能特征
FILE:reference/evaluation.md
# MCP 服务器评估指南

## 概述

本文档提供关于为 MCP 服务器创建全面评估的指导。评估测试 LLM 能否仅使用所提供的工具，有效地使用你的 MCP 服务器来回答现实、复杂的问题。

---

## 快速参考

### 评估要求
- 创建 10 个人类可读的问题
- 问题必须是只读的、独立的、非破坏性的
- 每个问题需要多次工具调用（可能数十次）
- 答案必须是单一、可验证的值
- 答案必须是稳定的（不会随时间变化）

### 输出格式
```xml
<evaluation>
   <qa_pair>
      <question>你的问题写在这里</question>
      <answer>单一可验证的答案</answer>
   </qa_pair>
</evaluation>
```

---

## 评估的目的

衡量 MCP 服务器质量的标准不是服务器实现工具的程度或全面性，而是这些实现（输入/输出模式、文档字符串/描述、功能）在 LLM 没有其他上下文且仅能访问 MCP 服务器的情况下，能在多大程度上帮助 LLM 回答现实且困难的问题。

## 评估概述

创建 10 个人类可读的问题，仅需要只读、独立、非破坏性和幂等的操作来回答。每个问题应：
- 现实
- 清晰简洁
- 无歧义
- 复杂，可能需要数十次工具调用或步骤
- 能用你事先确定的单一、可验证的值来回答

## 问题指南

### 核心要求

1. **问题必须是独立的**
   - 每个问题不应依赖于任何其他问题的答案
   - 不应假设处理另一个问题时进行了先前的写操作

2. **问题必须仅需要非破坏性和幂等的工具使用**
   - 不应指示或要求修改状态才能得出正确答案

3. **问题必须是现实的、清晰的、简洁的和复杂的**
   - 必须要求另一个 LLM 使用多个（可能数十个）工具或步骤来回答

### 复杂性和深度

4. **问题必须要求深入探索**
   - 考虑需要多个子问题和顺序工具调用的多跳问题
   - 每一步都应受益于前面问题中发现的信息

5. **问题可能需要大量分页**
   - 可能需要翻阅多页结果
   - 可能需要查询旧数据（1-2 年前的）以找到小众信息
   - 问题必须是困难的

6. **问题必须要求深入理解**
   - 而非表面知识
   - 可以提出需要证据的复杂真/假问题
   - 可以使用多项选择格式，让 LLM 必须搜索不同的假设

7. **问题必须不能通过直接的关键词搜索解决**
   - 不要包含目标内容中的特定关键词
   - 使用同义词、相关概念或转述
   - 要求多次搜索、分析多个相关项、提取上下文，然后推导出答案

### 工具测试

8. **问题应对工具返回值进行压力测试**
   - 可能引出工具返回大型 JSON 对象或列表，使 LLM 不堪重负
   - 应要求理解多种数据模态：
     - ID 和名称
     - 时间戳和日期时间（月、日、年、秒）
     - 文件 ID、名称、扩展名和 MIME 类型
     - URL、GID 等
   - 应探查工具返回所有有用数据形式的能力

9. **问题应主要反映真实的人类用例**
   - 在 LLM 辅助下，人类会关心的那类信息检索任务

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

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

### 稳定性

12. **问题的设计必须使答案不会改变**
    - 不要问依赖于动态"当前状态"的问题
    - 例如，不要统计：
      - 帖子的反应数
      - 线程的回复数
      - 频道的成员数

13. **不要让 MCP 服务器限制你创建的问题类型**
    - 创建具有挑战性和复杂的问题
    - 有些可能无法用可用的 MCP 服ver 工具
    - 问题可能要求特定的输出格式（datetime 与 epoch 时间、JSON 与 MARKDOWN）
    - 问题可能需要数十次工具调用才能完成

## 答案指南

### 可验证性

1. **答案必须能通过直接字符串比较进行验证**
   - 如果答案可以用多种格式重写，请在问题中明确指定输出格式
   - 示例：“使用 YYYY/MM/DD。”、“回答 True 或 False。”、“回答 A、B、C 或 D，不要包含其他内容。”
   - 答案应为单个可验证的值，例如：
     - 用户 ID、用户名、显示名称、名字、姓氏
     - 频道 ID、频道名称
     - 消息 ID、字符串
     - URL、标题
     - 数值数量
     - 时间戳、日期时间
     - 布尔值（用于 True/False 问题）
     - 电子邮件地址、电话号码
     - 文件 ID、文件名、文件扩展名
     - 多项选择答案
   - 答案不得要求特殊格式或复杂的结构化输出
   - 答案将使用直接字符串比较进行验证

### 可读性

2. **答案通常应优先采用人类可读的格式**
   - 示例：姓名、名字、姓氏、日期时间、文件名、消息字符串、URL、是/否、真/假、a/b/c/d
   - 而不是不透明的 ID（尽管 ID 也可接受）
   - 绝大多数答案应为人类可读的

### 稳定性

3. **答案必须是稳定/不变的**
   - 查看旧内容（例如已结束的对话、已发布的项目、已回答的问题）
   - 基于“封闭”概念创建问题，这些概念将始终返回相同的答案
   - 问题可以要求考虑固定的时间窗口，以避免非稳定的答案
   - 依赖不太可能改变的上下文
   - 示例：如果查找论文名称，要足够具体，以免答案与后来发表的论文混淆

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

### 多样性

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

6. **答案不得是复杂结构**
   - 不是值列表
   - 不是复杂对象
   - 不是 ID 或字符串列表
   - 不是自然语言文本
   - 除非答案可以通过直接字符串比较直接验证
   - 并且可以真实地复现
   - LLM 不太可能以任何其他顺序或格式返回相同的列表

## 评估流程

### 步骤 1：文档检查

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

### 步骤 2：工具检查

列出 MCP 服务器中可用的工具：
- 直接检查 MCP 服务器
- 了解输入/输出模式、文档字符串和描述
- 在此阶段不要调用工具本身

### 步骤 3：加深理解

重复步骤 1 和 2，直到你有良好的理解：
- 多次迭代
- 思考你想创建的任务类型
- 完善你的理解
- 在任何阶段都不应阅读 MCP 服务器实现本身的代码
- 运用你的直觉和理解来创建合理、现实但极具挑战性的任务

### 步骤 4：只读内容检查

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

### 步骤 5：任务生成

检查内容后，创建 10 个人类可读的问题：
- LLM 应能够使用 MCP 服务器回答这些问题
- 遵循上述所有问题和答案指南

## 输出格式

每个问答对由一个问题和答案组成。输出应为具有以下结构的 XML 文件：

```xml
<evaluation>
   <qa_pair>
      <question>Find the project created in Q2 2024 with the highest number of completed tasks. What is the project name?</question>
      <answer>Website Redesign</answer>
   </qa_pair>
   <qa_pair>
      <question>Search for issues labeled as "bug" that were closed in March 2024. Which user closed the most issues? Provide their username.</question>
      <answer>sarah_dev</answer>
   </qa_pair>
   <qa_pair>
      <question>Look for pull requests that modified files in the /api directory and were merged between January 1 and January 31, 2024. How many different contributors worked on these PRs?</question>
      <answer>7</answer>
   </qa_pair>
   <qa_pair>
      <question>Find the repository with the most stars that was created before 2023. What is the repository name?</question>
      <answer>data-pipeline</answer>
   </qa_pair>
</evaluation>
```

## 评估示例

### 好的问题

**示例 1：需要深度探索的多跳问题（GitHub MCP）**
```xml
<qa_pair>
   <question>Find the repository that was archived in Q3 2023 and had previously been the most forked project in the organization. What was the primary programming language used in that repository?</question>
   <answer>Python</answer>
</qa_pair>
```

这个问题很好，因为：
- 需要多次搜索才能找到已归档的仓库
- 需要确定哪个在归档前拥有最多的 fork
- 需要检查仓库详情以获取语言
- 答案是一个简单、可验证的值
- 基于不会改变的历史（封闭）数据

**示例 2：需要理解上下文而非关键词匹配（项目管理 MCP）**
```xml
<qa_pair>
   <question>Locate the initiative focused on improving customer onboarding that was completed in late 2023. The project lead created a retrospective document after completion. What was the lead's role title at that time?</question>
   <answer>Product Manager</answer>
</qa_pair>
```

这个问题很好，因为：
- 不使用具体的项目名称（“专注于改善客户入职的倡议”）
- 需要从特定时间范围内查找已完成的项目
- 需要识别项目负责人及其角色
- 需要从回顾文档中理解上下文
- 答案是人类可读且稳定的
- 基于已完成的工作（不会改变）

**示例 3：需要多个步骤的复杂聚合（问题跟踪器 MCP）**
```xml
<qa_pair>
   <question>在2024年1月报告的所有被标记为关键优先级的错误中，哪个负责人在其分配的bug中48小时内解决的百分比最高？提供该负责人的用户名。</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>
```

这个问题很好，因为：
- 需要理解订阅层级变化
- 需要识别特定时间范围内的升级事件
- 需要比较合同价值
- 必须访问账户行业信息
- 答案简单且可验证
- 基于已完成的历史交易

### 差的问题

**示例 1：答案随时间变化**
```xml
<qa_pair>
   <question>当前有多少个未解决的问题分配给了工程团队？</question>
   <answer>47</answer>
</qa_pair>
```

这个问题很差，因为：
- 答案会随着问题的创建、关闭或重新分配而变化
- 不是基于稳定/静止的数据
- 依赖于“当前状态”，这是动态的

**示例 2：关键词搜索太简单**
```xml
<qa_pair>
   <question>找到标题为“添加身份验证功能”的拉取请求，并告诉我谁创建了它。</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或DESTRUCTIVE操作的操作**
4. **累积所有正确答案**并替换文档中的任何错误答案
5. **移除任何需要WRITE或DESTRUCTIVE操作的`<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

positional arguments:
  eval_file             Path to evaluation XML file

optional arguments:
  -h, --help            Show help message
  -t, --transport       Transport type: stdio, sse, or http (default: stdio)
  -m, --model           Claude model to use (default: claude-3-7-sonnet-20250219)
  -o, --output          Output 报告文件（默认：打印到标准输出）

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>Find the user who created the most issues in January 2024. What is their username?</question>
      <answer>alice_developer</answer>
   </qa_pair>
   <qa_pair>
      <question>Among all pull requests merged in Q1 2024, which repository had the highest number? Provide the repository name.</question>
      <answer>backend-api</answer>
   </qa_pair>
   <qa_pair>
      <question>Find the project that was completed in December 2023 and had the longest duration from start to finish. How many days did it take?</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 schema 集成
- 类型安全的工具处理程序实现

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

有关完整细节，请参阅参考资料中的 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          # Main entry point with McpServer initialization
│   ├── types.ts          # TypeScript type definitions and interfaces
│   ├── tools/            # Tool implementations (one file per domain)
│   ├── services/         # API clients and shared utilities
│   ├── schemas/          # Zod validation schemas
│   └── constants.ts      # Shared constants (API_URL, CHARACTER_LIMIT, etc.)
└── dist/                 # Built JavaScript files (entry point: 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 schema 进行运行时输入验证和类型安全
- 必须显式提供 `description` 字段 - JSDoc 注释不会被自动提取
- 显式提供`title`、`description`、`inputSchema` 和 `annotations`
- `inputSchema` 必须是 Zod schema 对象（不是 JSON schema）
- 显式地为所有参数和返回值标注类型

```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 schema
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();

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

server.registerTool(
  "example_search_users",
  {
    title: "Search Example Users",
    description: `Search for users in the Example system by name, email, or team.

This tool searches across all user profiles in the Example platform, supporting partial matches and various search filters. It does NOT create or modify users, only searches existing ones.

Args:
  - query (string): Search string to match against names/emails
  - limit (number): Maximum results to return, between 1-100 (default: 20)
  - offset (number): Number of results to skip for pagination (default: 0)
  - response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns:
  For JSON format: Structured data with schema:
  {
    "total": number,           // Total number of matches found
    "count": number,           // Number of results in this response
    "offset": number,          // Current pagination offset
    "users": [
      {
        "id": string,          // User ID (e.g., "U123456789")
        "name": string,        // Full name (e.g., "John Doe")
        "email": string,       // Email address
        "team": string,        // Team name (optional)
        "active": boolean      // Whether user is active
      }
    ],
    "has_more": boolean,       // Whether more results are available
    "next_offset": number      // Offset for next page (if has_more is true)
  }

Examples:
  - Use when: "Find all marketing team members" -> params with query="team:marketing"
  - Use when: "Search for John's account" -> params with query="john"
  - Don't use when: You need to create a user (use example_create_user instead)

Error Handling:
  - Returns "Error: Rate limit exceeded" if too many requests (429 status)
  - Returns "No users found matching '<query>'" if search returns empty`,
    inputSchema: UserSearchInputSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    }
  },
  async (params: UserSearchInput) => {
    try {
      // 输入验证由 Zod schema 处理
      // 使用已验证的参数发起 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 Schema

Zod 提供运行时类型验证：

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

// 带验证的基础 schema
const CreateUserSchema = z.object({
  name: z.string()
    .min(1, "Name is required")
    .max(100, "Name must not exceed 100 characters"),
  email: z.string()
    .email("Invalid email format"),
  age: z.number()
    .int("Age must be a whole number")
    .min(0, "Age cannot be negative")
    .max(150, "Age cannot be greater than 150")
}).strict();  // 使用 .strict() 禁止额外字段

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

const SearchSchema = z.object({
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("Output format")
});

// 带默认值的可选字段
const PaginationSchema = z.object({
  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")
});
```

## 响应格式选项

支持多种输出格式以提供灵活性：

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

const inputSchema = z.object({
  query: z.string(),
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
});
```

**Markdown 格式**：
- 使用标题、列表和格式以提升清晰度
- 将时间戳转换为人类可读格式
- 在括号中显示名称及 ID
- 省略冗长的元数据
- 按逻辑对相关信息进行分组

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

## 分页实现

对于列出资源的工具：

```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 `错误：发生意外错误：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
// 良好：异步网络请求
async function fetchData(resourceId: string): Promise<ResourceData> {
  const response = await axios.get(`API_URL/resource/resourceId`);
  return response.data;
}

// 不佳：Promise 链
function fetchData(resourceId: string): Promise<ResourceData> {
  return axios.get(`API_URL/resource/resourceId`)
    .then(response => response.data);  // 更难阅读和维护
}
```

## TypeScript 最佳实践

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

```typescript
// 良好：使用 Zod 和接口实现类型安全
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);  // 运行时验证
}

// 不佳：使用 any
async function getUser(id: string): Promise<any> {
  return await apiCall(`/users/id`);  // 无类型安全
}
```

## 包配置

### package.json

```json
{
  "name": "{service}-mcp-server",
  "version": "1.0.0",
  "description": "用于 {Service} API 集成的 MCP 服务器",
  "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
/**
 * 用于 Example Service 的 MCP 服务器。
 *
 * 此服务器提供与 Example API 交互的工具，包括用户搜索、
 * 项目管理和数据导出功能。
 */

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";

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

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

// Zod schema
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();

type UserSearchInput = z.infer<typeof UserSearchInputSchema>;

// 共享工具函数
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 "错误：资源未找到。请检查 ID 是否正确。";
        case 403:
          return "错误：权限被拒绝。您无权访问此资源。";
        case 429:
          return "错误：超出速率限制。请稍后再发起更多请求。";
        default:
          return `错误：API 请求失败，状态码 error.response.status`;
      }
    } else if (error.code === "ECONNABORTED") {
      return "错误：请求超时。请重试。";
    }
  }
  return `错误：发生意外错误：String(error)`;
}

// 创建 MCP 服务器实例
const server = new McpServer({
  name: "example-mcp",
  version: "1.0.0"
});

// 注册工具
server.registerTool(
  "example_search_users",
  {
    title: "搜索示例用户",
    description: `[完整描述如上所示]`,
    inputSchema: UserSearchInputSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    }
  },
  async (params: UserSearchInput) => {
    // 实现如上所示
  }
);

// 主函数
// 用于 stdio（本地）：
async function runStdio() {
  if (!process.env.EXAMPLE_API_KEY) {
    console.error("错误：需要 EXAMPLE_API_KEY 环境变量");
    process.exit(1);
  }

  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP 服务器通过 stdio 运行");
}

// 用于可流式 HTTP（远程）：
async function runHTTP() {
  if (!process.env.EXAMPLE_API_KEY) {
    console.error("错误：需要 EXAMPLE_API_KEY 环境变量");
    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 服务器运行在 http://localhost:port/mcp`);
  });
}

// 根据环境选择传输方式
const transport = process.env.TRANSPORT || 'stdio';
if (transport === 'http') {
  runHTTP().catch(error => {
    console.error("服务器错误：", error);
    process.exit(1);
  });
} else {
  runStdio().catch(error => {
    console.error("服务器错误：", error);
    process.exit(1);
  });
}
```

---

## 高级 MCP 功能

### 资源注册

将数据作为资源公开，以实现高效的基于 URI 的访问：

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

// 注册带有 URI 模板的资源
server.registerResource(
  {
    uri: "file://documents/{name}",
    name: "文档资源",
    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"
});
```

谨慎使用通知——仅在服务器能力真正变化时使用。

---

## 代码最佳实践

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

您的实现必须优先考虑可组合性和代码重用：

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

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

## 构建与运行

在运行之前，始终先构建 TypeScript 代码：

```bash
# 构建项目
npm run build

# 运行服务器
npm start

# 开发模式（自动重载）
npm run dev
```

在认为实现完成之前，始终确保 `npm run build` 成功完成。

## 质量检查清单

在最终确定 Node/TypeScript MCP 服务器实现之前，确保：

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

### 实现质量
- [ ] 聚焦实现：实现最重要和最有价值的工具
- [ ] 所有工具使用 `registerTool` 注册，并具有完整配置
- [ ] 所有工具包含 `title`、`description`、`inputSchema` 和 `annotations`
- [ ] 注解正确设置（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）
- [ ] 所有工具使用 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`
- [ ] 所有导入正确解析
- [ ] 示例工具调用按预期工作
FILE:reference/python_mcp_server.md
# Python MCP 服务器实现指南

## 概述

本文档提供了使用 MCP Python SDK 实现 MCP 服务器的 Python 特定最佳实践和示例。它涵盖了服务器设置、工具注册模式、使用 Pydantic 进行输入验证、错误处理以及完整的工作示例。

---

## 快速参考

### 关键导入
```python
from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field, field_validator, ConfigDict
from typing import Optional, List, Dict, Any
from enum import Enum
import httpx
```

### 服务器初始化
```python
mcp = FastMCP("service_mcp")
```

### 工具注册模式
```python
@mcp.tool(name="tool_name", annotations={...})
async def tool_function(params: InputModel) -> str:
    # 实现
    pass
```

---

## MCP Python SDK 和 FastMCP

官方 MCP Python SDK 提供了 FastMCP，一个用于构建 MCP 服务器的高级框架。它提供：
- 从函数签名和文档字符串自动生成描述和 inputSchema
- 用于输入验证的 Pydantic 模型集成
- 使用 `@mcp.tool` 的基于装饰器的工具注册

**获取完整的 SDK 文档，请使用 WebFetch 加载：**
`https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`

## 服务器命名约定

Python MCP 服务器必须遵循以下命名模式：
- **格式**：`{service}_mcp`（小写加下划线）
- **示例**：`github_mcp`、`jira_mcp`、`stripe_mcp`

名称应：
- 通用（不绑定特定功能）
- 描述所集成的服务/API
- 易于从任务描述中推断
- 不含版本号或日期

## 工具实现

### 工具命名

工具名称使用 snake_case（例如 "search_users"、"create_project"、"get_channel_info"），名称清晰且面向操作。

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

### 使用 FastMCP 的工具结构

工具使用 `@mcp.tool` 装饰器定义，并使用 Pydantic 模型进行输入验证：

```python
from pydantic import BaseModel, Field, ConfigDict
from mcp.server.fastmcp import FastMCP

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

# 定义用于输入验证的 Pydantic 模型
class ServiceToolInput(BaseModel):
    '''服务工具操作的输入模型。'''
    model_config = ConfigDict(
        str_strip_whitespace=True,  # 自动去除字符串空白
        validate_assignment=True,    # 赋值时验证
        extra='forbid'              # 禁止额外字段
    )

    param1: str = Field(..., description="第一个参数描述（例如 'user123'、'project-abc'）", min_length=1, max_length=100)
    param2: Optional[int] = Field(default=None, description="带约束的可选整数参数", ge=0, le=1000)
    tags: Optional[List[str]] = Field(default_factory=list, description="要应用的标签列表", max_items=10)

@mcp.tool(
    name="service_tool_name",
    annotations={
        "title": "人类可读的工具标题",
        "readOnlyHint": True,     # 工具不修改环境
        "destructiveHint": False,  # 工具不执行破坏性tive operations
        "idempotentHint": True,    # 重复调用不会产生额外效果
        "openWorldHint": False     # 工具不与外部实体交互
    }
)
async def service_tool_name(params: ServiceToolInput) -> str:
    '''工具描述自动成为 'description' 字段。

    此工具对服务执行特定操作。在处理之前，它使用 ServiceToolInput Pydantic 模型
    验证所有输入。

    Args:
        params (ServiceToolInput): 包含以下内容的已验证输入参数：
            - param1 (str): 第一个参数描述
            - param2 (Optional[int]): 带默认值的可选参数
            - tags (Optional[List[str]]): 标签列表

    Returns:
        str: 包含操作结果的 JSON 格式响应
    '''
    # 在此处实现
    pass
```

## 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="用户的全名", min_length=1, max_length=100)
    email: str = Field(..., description="用户的电子邮件地址", pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
    age: int = Field(..., description="用户的年龄", ge=0, le=150)

    @field_validator('email')
    @classmethod
    def validate_email(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("电子邮件不能为空")
        return v.lower()
```

## 响应格式选项

支持多种输出格式以提供灵活性：

```python
from enum import Enum

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

class UserSearchInput(BaseModel):
    query: str = Field(..., description="搜索查询")
    response_format: ResponseFormat = Field(
        default=ResponseFormat.MARKDOWN,
        description="输出格式：'markdown' 用于人类可读，'json' 用于机器可读"
    )
```

**Markdown 格式**：
- 使用标题、列表和格式以提高清晰度
- 将时间戳转换为人类可读格式（例如，"2024-01-15 10:30:00 UTC" 而不是 epoch）
- 在括号中显示显示名称和 ID（例如，"@john.doe (U123456)"）
- 省略冗长的元数据（例如，只显示一个个人资料图片 URL，而不是所有尺寸）
- 逻辑分组相关信息

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

## 分页实现

对于列出资源的工具：

```python
class ListInput(BaseModel):
    limit: Optional[int] = Field(default=20, description="返回的最大结果数", ge=1, le=100)
    offset: Optional[int] = Field(default=0, description="分页时跳过的结果数", ge=0)

async def list_items(params: ListInput) -> str:
    # 使用分页发起 API 请求
    data = await api_request(limit=params.limit, offset=params.offset)

    # 返回分页信息
    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:
    '''所有工具的一致错误格式。'''
    if isinstance(e, httpx.HTTPStatusError):
        if e.response.status_code == 404:
            return "错误：未找到资源。请检查 ID 是否正确。"
        elif e.response.status_code == 403:
            return "错误：权限被拒绝。您无权访问此资源。"
        elif e.response.status_code == 429:
            return "错误：超出速率限制。请等待后再发起更多请求。"
        return f"错误：API 请求失败，状态码 {e.response.status_code}"
    elif isinstance(e, httpx.TimeoutException):
        return "错误：请求超时。请重试。"
    return f"错误：发生意外错误：{type(e).__name__}"
```

## 共享工具

将常见功能提取为可重用函数：

```python
# 共享 API 请求函数
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()
```

## 异步/等待最佳实践

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

```python
# 良好：异步网络请求
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()

# 不良：同步请求
def fetch_data(resource_id: str) -> dict:
    response = requests.get(f"{API_URL}/resource/{resource_id}")  # 阻塞
    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"]}
```

## 工具文档字符串

每个工具都必须有包含显式类型信息的全面文档字符串：

```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: <error message>" 或 "No users found matching '<query>'"

    示例：
        - 使用场景："查找所有市场团队成员" -> params 中 query="team:marketing"
        - 使用场景："搜索 John 的账户" -> params 中 query="john"
        - 不使用场景：需要创建用户（改用 example_create_user）
        - 不使用场景：已有用户 ID 且需要完整详情（改用 example_get_user）

    错误处理：
        - 输入验证错误由 Pydantic 模型处理
        - 如果请求过多（429 状态），返回 "Error: Rate limit exceeded"
        - 如果 API 密钥无效（401 状态），返回 "Error: Invalid API authentication"
        - 返回格式化结果列表或 "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:
    '''按姓名、电子邮件或团队在 Example 系统中搜索用户。

    [完整 docstring 如上所示]
    '''
    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 功能

### Context 参数注入

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, "Starting search...")

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

    # 执行搜索
    results = await search_api(query)
    await ctx.report_progress(0.75, "Formatting results...")

    # 访问服务器配置
    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**：命令行工具、本地集成、子进程执行
- **可流式 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 Field 都有显式类型和带约束的描述
- [ ] 所有工具都有全面的 docstring，包含显式的输入/输出类型
- [ ] Docstring 包含 dict/JSON 返回的完整 schema 结构
- [ ] Pydantic 模型处理输入验证（无需手动验证）

### 高级功能（如适用）
- [ ] 使用上下文注入进行日志记录、进度报告或信息引导
- [ ] 为适当的数据端点注册资源
- [ ] 为持久连接实现生命周期管理
- [ ] Struc使用的结构化输出类型（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"Unexpected context result: {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 的 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 连接的工厂函数。

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

    Returns:
        MCPConnection 实例
    """
    transport = transport.lower()

    if transport == "stdio":
        if not command:
            raise ValueError("Command is required for stdio transport")
        return MCPConnectionStdio(command=command, args=args, env=env)

    elif transport == "sse":
        if not url:
            raise ValueError("URL is required for sse transport")
        return MCPConnectionSSE(url=url, headers=headers)

    elif transport in ["http", "streamable_http", "streamable-http"]:
        if not url:
            raise ValueError("URL is required for http transport")
        return MCPConnectionHTTP(url=url, headers=headers)

    else:
        raise ValueError(f"Unsupported transport type: {transport}. Use 'stdio', 'sse', or 'http'")
FILE:scripts/evaluation.py
"""MCP 服务器评估工具

此脚本通过使用 Claude 对 MCP 服务器运行测试问题来评估它们。
"""

import argparse
import asyncio
import json
import re
import sys
import time
import traceback
import xml.etree.ElementTree as ET
from pathlib import Path
from typing import Any

from anthropic import Anthropic

from connections import create_connection

EVALUATION_PROMPT = """你是一个可以访问工具的 AI 助手。

当给定任务时，你必须：
1. 使用可用工具完成任务
2. 在 <summary> 标签中提供你方法的每一步摘要
3. 在 <feedback> 标签中提供对所提供工具的反馈
4. 在 <response> 标签中提供你的最终回复

摘要要求：
- 在你的 <summary> 标签中，你必须解释：
  - 你为完成任务所采取的步骤
  - 你使用了哪些工具、以什么顺序以及为什么
  - 你为每个工具提供的输入
  - 你从每个工具收到的输出
  - 关于你如何得出该回复的摘要

反馈要求：
- 在你的 <feedback> 标签中，提供对工具的建设性反馈：
  - 评论工具名称：它们是否清晰且具有描述性？
  - 评论输入参数：它们是否有良好的文档？必需参数与可选参数是否清晰？
  - 评论描述描述：它们是否准确描述了工具的功能？
  - 评论工具使用过程中遇到的任何错误：工具是否执行失败？工具是否返回了过多 token？
  - 指出具体的改进领域并解释为什么这些改进会有帮助
  - 在你的建议中要具体且可操作

响应要求：
- 你的响应应简洁并直接回答所问内容
- 始终将最终响应包裹在 <response> 标签中
- 如果你无法解决该任务，返回 <response>NOT_FOUND</response>
- 对于数值响应，只提供数字
- 对于 ID，只提供 ID
- 对于名称或文本，提供所要求的确切文本
- 你的响应应放在最后"""


def parse_evaluation_file(file_path: Path) -> list[dict[str, Any]]:
    """解析包含 qa_pair 元素的 XML 评估文件。"""
    try:
        tree = ET.parse(file_path)
        root = tree.getroot()
        evaluations = []

        for qa_pair in root.findall(".//qa_pair"):
            question_elem = qa_pair.find("question")
            answer_elem = qa_pair.find("answer")

            if question_elem is not None and answer_elem is not None:
                evaluations.append({
                    "question": (question_elem.text or "").strip(),
                    "answer": (answer_elem.text or "").strip(),
                })

        return evaluations
    except Exception as e:
        print(f"解析评估文件 {file_path} 时出错：{e}")
        return []


def extract_xml_content(text: str, tag: str) -> str | None:
    """从 XML 标签中提取内容。"""
    pattern = rf"<{tag}>(.*?)</{tag}>"
    matches = re.findall(pattern, text, re.DOTALL)
    return matches[-1].strip() if matches else None


async def agent_loop(
    client: Anthropic,
    model: str,
    question: str,
    tools: list[dict[str, Any]],
    connection: Any,
) -> tuple[str, dict[str, Any]]:
    """使用 MCP 工具运行智能体循环。"""
    messages = [{"role": "user", "content": question}]

    response = await asyncio.to_thread(
        client.messages.create,
        model=model,
        max_tokens=4096,
        system=EVALUATION_PROMPT,
        messages=messages,
        tools=tools,
    )

    messages.append({"role": "assistant", "content": response.content})

    tool_metrics = {}

    while response.stop_reason == "tool_use":
        tool_use = next(block for block in response.content if block.type == "tool_use")
        tool_name = tool_use.name
        tool_input = tool_use.input

        tool_start_ts = time.time()
        try:
            tool_result = await connection.call_tool(tool_name, tool_input)
            tool_response = json.dumps(tool_result) if isinstance(tool_result, (dict, list)) else str(tool_result)
        except Exception as e:
            tool_response = f"执行工具 {tool_name} 时出错：{str(e)}\n"
            tool_response += traceback.format_exc()
        tool_duration = time.time() - tool_start_ts

        if tool_name not in tool_metrics:
            tool_metrics[tool_name] = {"count": 0, "durations": []}
        tool_metrics[tool_name]["count"] += 1
        tool_metrics[tool_name]["durations"].append(tool_duration)

        messages.append({
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use.id,
                "content": tool_response,
            }]
        })

        response = await asyncio.to_thread(
            client.messages.create,
            model=model,
            max_tokens=4096,
            system=EVALUATION_PROMPT,
            messages=messages,
            tools=tools,
        )
        messages.append({"role": "assistant", "content": response.content})

    response_text = next(
        (block.text for block in response.content if hasattr(block, "text")),
        None,
    )
    return response_text, tool_metrics


async def evaluate_single_task(
    client: Anthropic,
    model: str,
    qa_pair: dict[str, Any],
    tools: list[dict[str, Any]],
    connection: Any,
    task_index: int,
) -> dict[str, Any]:
    """使用给定工具评估单个 QA 对。"""
    start_time = time.time()

    print(f"任务 {task_index + 1}：使用以下问题运行任务：{qa_pair['question']}")
    response, tool_metrics = await agent_loop(client, model, qa_pair["question"], tools, connection)

    response_value = extract_xml_content(response, "response")
    summary = extract_xml_content(response, "summary")
    feedback = extract_xml_content(response, "feedback")

    duration_seconds = time.time() - start_time

    return {
        "question": qa_pair["question"],
        "expected": qa_pair["answer"],
        "actual": response_value,
        "score": int(response_value == qa_pair["answer"]) if response_value else 0,
        "total_duration": duration_seconds,
        "tool_calls": tool_metrics,
        "num_tool_calls": sum(len(metrics["durations"]) for metrics in tool_metrics.values()),
        "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"Warning: Ignoring malformed header: {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"Warning: Ignoring malformed environment variable: {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="'Key: Value' 格式的 HTTP 头部（仅 sse/http）")

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

    args = parser.parse_args()

    if not args.eval_file.exists():
        print(f"Error: Evaluation file not found: {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"Error: {e}")
        sys.exit(1)

    print(f"🔗 Connecting to MCP server via {args.transport}...")

    async with connection:
        print("✅ Connected successfully")
        report = await run_evaluation(args.eval_file, connection, args.model)

        if args.output:
            args.output.write_text(report)
            print(f"\n✅ Report saved to {args.output}")
        else:
            print("\n" + report)


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

Python TypeScript API+2

F@f

网站 + MCP 服务器的敌对消费者成熟度审计

文本

一个以证据为驱动的任务提示，用于审计、评分并修复网站及其 MCP 服务器在应对 Googlebot、AI 爬虫和激进 LLM 代理时的稳健程度。

角色
你是一名资深工程师，负责对一个网站及其 MCP（Model Context Protocol）服务器进行成熟度审计（SEO/抓取健康、安全、韧性、智能体就绪度）。像独立审计员一样工作：证据优先，不做假设，能修的就修，然后重新测试。

授权
只审计 owner_or_authorized_party 拥有或已明确授权你测试的系统。负载、模糊测试和攻击式测试只针对 STAGING 运行。针对生产环境，只做只读、限速的抓取，且必须获得我的明确批准。不进行真实支付，不进行真实预订或下单，不涉及真实个人数据。

上下文
- 站点：site_url   预发布环境：staging_url   MCP 端点：mcp_url   仓库：repo_path
- 业务类型与目录规模：例如 travel/e-commerce/marketplace，约 N 个页面，约 N 个产品
- 语言/货币：locales_and_currencies
- 目标 LLM 客户端：例如 Claude、ChatGPT、Gemini
- 测试账号/令牌：test_credentials
- 约束与合规制度：例如 GDPR、CCPA、PCI DSS、当地法律
假设消费者会具有攻击性：Googlebot、AI 爬虫、用户触发的 AI 抓取器、爬虫程序，以及会重试、循环、并行运行并发送畸形参数的 LLM 智能体。

规则
1. 先阅读：仓库、OpenAPI/工具定义、robots.txt、站点地图、模板、响应头。在测试前建立清单。
2. 每个结论都需要证据（命令、输出、日志、file:line、URL）。没有证据 = 未通过。
3. 将任何无法测试的内容标记为“NOT RUN + 原因”。绝不隐瞒失败。
4. 在陈述版本、规范和搜索引擎指南之前，先对照官方文档核实。
5. 在执行破坏性或高流量测试前先询问。修复严重/高优先级问题，重新测试，并记录修复前后情况。
6. 先制定包含 10 个项目的测试计划和任务清单，然后执行。

测试类别

A. 抓取与索引健康
- 获取 robots.txt 和所有站点地图；按类型统计 URL 数量；与预期页面数量核对。报告站点地图中返回 404/重定向/noindex/规范化到其他位置的 URL、站点地图中缺失的可索引页面，以及孤立页面。
- 以 Googlebot（智能手机 UA）和通用机器人身份、以礼貌速率抓取：状态码、重定向链、软 404、重复标题/描述、canonical、hreflang 互惠性（+ x-default）、分页、分面/搜索/参数 URL（抓取陷阱、无限日历）、URL/slug 一致性以及变体的 301 行为。
- 渲染：比较原始 HTML 与渲染后的 DOM；确认关键内容、链接、结构化数据和价格不是仅靠 JS 呈现。
- 机器人确定性：反复获取关键页面；检查随机化/个性化是否会给机器人带来不稳定或实质不同的内容（伪装风险）。
- 结构化数据：验证 JSON-LD（Organization、Product/Offer、Hotel/Place、BreadcrumbList、AggregateRating 等）的语法、必需属性以及与可见内容的一致性；检查评论标记政策合规性。
- 性能：对 30 个代表性模板运行 Lighthouse（移动端）；报告 LCP/INP/CLS。如提供 Search Console 数据则使用。
- robots.txt：使用真实解析器解析；验证每个机器人（Googlebot、GPTBot、ClaudeBot、Google-Extended、CCBot 等）的规则、特定机器人组与默认组之间的一致性，以及敏感路径（结账、账户、内部 API）保持屏蔽。确认 AI 训练/AI 输入政策（Content-Signal 或等效项）是有意为之。
- 站点地图卫生：lastmod 准确性、大小限制（50k URL/50MB）、gzip、内容类型、图片/视频站点地图。
- AI 搜索就绪度：验证 AI 抓取器/搜索机器人用户代理能获得 200 响应（无 WAF 挑战、无错误 403/429）；考虑 llms.txt 和干净的文本渲染。

B. 机器人、WAF 与负载韧性（预发布环境）
- k6/locust：正常负载、10 倍峰值、1 小时浸泡、混合爬虫模拟（Googlebot + 多个 AI 机器人 UA）、慢客户端。
- 缓存行为：命中率、缓存键与查询参数、stale-while-revalidate；价格/可用性/报价端点的保护（robots.txt 不是安全措施）。
- 上游放大：每次页面浏览和每次抓取触发的后端/供应商调用；机器人不得触发无限制的实时上游调用。测试超时、熔断器、重试风暴和降级模式页面（混沌测试）。
- 速率限制：429 + Retry-After、按 IP/令牌/UA 的限制；合法爬虫不被误限流。
- 测量 p50/p95/p99 延迟、错误率、CPU/RAM、数据库连接、每 1,000 次请求的成本。

C. MCP 协议与模式一致性
- MCP Inspector + SDK 客户端：initialize、tools/list、tools/call、流式传输（Streamable HTTP）、重连、大响应。
- 每个工具：有效的 JSON Schema、“何时使用/何时不使用”描述、注解（readOnly/destructive/idempotent）、结构化输出、带分页的有界结果。
- 将工具定义转换为 Claude、OpenAI 和 Gemini 的函数调用格式；标记不支持的构造。
- 工具返回的 ID、URL、语言和货币必须与网站的规范值一致。

D. 输入加固
- 对每个工具进行模糊测试（schemathesis/hypothesis）：错误类型、超大字符串、unicode/RTL/emoji、不可能的日期和数字、不支持的语言/货币、注入模式、路径遍历、SSRF URL。期望无 500、无堆栈跟踪、可恢复错误、服务器保持运行。

E. 智能体行为评估（端到端）
- 用你的用户所说的语言编写 50+ 个真实场景：清晰、模糊、多步骤、错误、更改/取消、售罄、价格变动、冲突请求。
- 在 3+ 个目标模型 × 5 次重复上运行。指标：工具选择准确性、参数准确性、任务成功率、pass^k、每任务调用次数和令牌数、错误恢复、写操作前的确认合规性。对失败进行根因分析（描述、模式、输出大小、模型）；先修复描述/模式并重新测量。

F. 安全
- 通过目录/用户生成内容（描述、评论、博客、表单字段）使用模拟上游数据和预发布内容进行间接提示注入。智能体不得采取未授权操作或泄露数据。
- 认证/授权：OAuth 2.1 + PKCE、受众绑定令牌、作用域强制、IDOR、过期/错误受众令牌、无令牌透传。
- 写操作安全：明确的用户确认、报价过期、价格/货币篡改、使用同一幂等键的 50 个并行请求 -> 恰好一次效果。
- 支付：不通过工具或日志传输卡数据；仅使用托管支付链接。
- Web 基础：对表单和端点执行 OWASP Top 10/API Top 10、CSRF、开放重定向、安全头、cookie 标志、依赖/容器/密钥扫描（pip-audit/npm audit、Trivy、gitleaks）、SBOM。
- 滥用：抗抓取和枚举、拒绝钱包限制。

G. 隐私与合规
- 同意：分析/营销标签不得在同意前触发；选择按声明持久化；第三方嵌入仅在同意后加载。
- 适用制度（regimes）：数据最小化、保留、数据主体请求、与 LLM 供应商的处理者协议、日志不含 PII/令牌。
- 内容/许可：图片和评论使用权、AI 训练/AI-input 策略一致性、展示评分的准确性以及“已验证”声明。

H. 可观测性与运维
- 按工具调用和页面类型记录追踪/日志（延迟、上游状态、缓存状态、机器人分类）；写操作的审计日志；仪表盘和告警。
- 健康/就绪检查、优雅关闭、配置校验、密钥管理、回滚计划、工具 schema 版本管理、
  CI 检查确保 robots.txt 和 sitemap 永不回退。

评分
将类别 A-H 从 0 到 4 评分：0 无，1 临时性，2 部分覆盖但有缺口，3 一致且经过测试，4 自动化、受监控、有证据。
生产门禁（全部必需）：
- 0 个未解决的严重/高危安全问题；0 次成功的未授权写入或重复交易。
- >= 99% 的 sitemap URL 返回 200、自规范且可索引；0 个 sitemap URL 为 noindex/重定向/404；hreflang 互惠 >= 99%。
- 搜索/筛选/参数 URL 不会产生无界可索引重复项。
- 关键模板的 Core Web Vitals 良好，或有注明日期的修复计划。
- 在 10 倍峰值和爬虫模拟下：错误率 < 1%，p95 < target_ms ms，每次页面浏览的上游调用在预算内，
  限流有效，没有合法爬虫被误封。
- Agent 评估：在每个目标模型上任务成功率 >= 90% 且 pass^5 >= 75%（或有记录的例外）。
- 日志中 0 PII/token/卡数据；遵守同意。
- 每个发现都有证据，并且要么有修复，要么有签署确认的已接受风险。

交付物（位于 /maturity-audit/）
1. REPORT.md：执行摘要、类别评分、门禁通过/失败、前 10 大风险。
2. FINDINGS.md：ID、类别、严重性、证据、影响、修复、状态、负责人。
3. SEO-CRAWL.md：sitemap 对账（类型、数量、健康百分比）、canonical/hreflang/重复问题、爬取陷阱、结构化数据结果。
4. EVAL.md：场景、模型、指标、前后对比。
5. 可运行测试：tests/、负载和爬虫脚本、注入测试夹具、CI 回归检查，以及单个 `make audit`。
6. ROADMAP.md：30/60/90 天计划和已接受风险。

最终回复：简要总结发现、修复、失败门禁，以及最重要的下一步。

Security AI Agent Audit+2

M@musatoktas

--- name: mcp-builder description: 创建高质量 MCP（模型上下文协议）服务器的指南，使 LLM 能够通过精心设计的工具与外部服务交互。在构建 MCP 服务器以集成外部 API 或服务时使用，无论是 Python（FastMCP）还是 Node/TypeScript（MCP SDK）。 license: 完整条款见 LICENSE.txt --- # MCP 服务器开发指南 ## 概述创建 MCP（模型上下文协议）服务器，使 LLM 能够通过精心设计的工具与外部服务交互。MCP 服务器的质量以其帮助 LLM 完成现实世界任务的程度来衡量。 --- # 流程 ## 🚀 高层工作流创建高质量的 MCP 服务器涉及四个主要阶段： ### 阶段 1：深入研究和规划 #### 1.1 理解现代 MCP 设计 **API 覆盖 vs. 工作流工具：** 在全面的 API 端点覆盖与专门的工作流工具之间取得平衡。工作流工具对于特定任务可能更方便，而全面的覆盖则赋予代理组合操作的灵活性。性能因客户端而异——一些客户端受益于结合基本工具的代码执行，而另一些则更适合使用更高层的工作流。当不确定时，优先考虑全面的 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） - 工具、资源和提示定义 #### 1.3 研究框架文档 **推荐技术栈：** - **语言**：TypeScript（高质量的 SDK 支持，在许多执行环境（如 MCPB）中具有良好的兼容性。此外，AI 模型擅长生成 TypeScript 代码，得益于其广泛使用、静态类型和良好的 linting 工具） - **传输**：远程服务器使用可流式 HTTP，采用无状态 JSON（与有状态会话和流式响应相比，更易于扩展和维护）。本地服务器使用 stdio。 **加载框架文档：** - **MCP 最佳实践**：[📋 查看最佳实践](./reference/mcp_best_practices.md) - 核心指南 **对于 TypeScript（推荐）：** - **TypeScript SDK**：使用 WebFetch 加载 `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` - [⚡ TypeScript 指南](./reference/node_mcp_server.md) - TypeScript 模式和示例 **对于 Python：** - **Python SDK**：使用 WebFetch 加载 `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` - [🐍 Python 指南](./reference/python_mcp_server.md) - Python 模式和示例 #### 1.4 规划你的实现 **理解 API：** 查看服务的 API 文档，以识别关键端点、认证要求和数据模型。根据需要利用网络搜索和 WebFetch。 **工具选择：** 优先考虑全面的 API 覆盖。列出要实现的端点，从最常见的操作开始。 --- ### 阶段 2：实现 #### 2.1 设置项目结构请参阅特定语言的指南进行项目设置： - [⚡ TypeScript 指南](./reference/node_mcp_server.md) - 项目结构、package.json、tsconfig.json - [🐍 Python 指南](./reference/python_mcp_server.md) - 模块组织、依赖项 #### 2.2 实现核心基础设施创建共享工具： - 带认证的 API 客户端 - 错误处理辅助函数 - 响应格式化（JSON/Markdown） - 分页支持 #### 2.3 实现工具对于每个工具： **输入模式：** - 使用 Zod（TypeScript）或 Pydantic（Python） - 包含约束和清晰的描述 - 在字段描述中添加示例 **输出模式：** - 尽可能为结构化数据定义 `outputSchema` - 在工具响应中使用 `structuredContent`（TypeScript SDK 特性） - 帮助客户端理解和处理工具输出 **工具描述：** - 功能的简洁摘要 - 参数描述 - 返回类型模式 **实现：** - 对 I/O 操作使用异步/等待 - 使用可操作的消息进行适当的错误处理 - 在适用的情况下支持分页 - 使用现代 SDK 时同时返回文本内容和结构化数据 **注解：** - `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>查找讨论 ab推出以动物为代号的 AI 模型。其中一个模型需要一个特定的安全标识，该标识使用 ASL-X 格式。对于以斑点野生猫命名的模型，正在确定哪个数字 X？</question> <answer>3</answer> </qa_pair>  </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 | 工具与外部实体交互 | **重要**：注解只是提示，不是安全保证。客户端不应仅基于注解做出安全关键决策。 --- ## 错误处理 - 使用标准 JSON-RPC 错误码 - 在结果对象中报告工具错误（而非协议级错误） - 提供有帮助、具体的错误消息并附带建议的后续步骤 - 不要暴露内部实现细节 - 在错误发生时正确清理资源错误处理示例： ```typescript try { const result = performOperation(); return { content: [{ type: "text", text: result }] }; } catch (error) { return { isError: true, content: [{ type: "text", text: `Error: error.message. Try using filter='active_only' to reduce results.` }] }; } ``` --- ## 测试要求全面的测试应覆盖： - **功能测试**：验证在有效/无效输入下的正确执行 - **集成测试**：测试与外部系统的交互 - **安全测试**：验证认证、输入清理、速率限制 - **性能测试**：检查负载下的行为、超时 - **错误处理**：确保正确的错误报告和清理 --- ## 文档要求 - 为所有工具和功能提供清晰的文档 - 包含可运行的示例（每个主要功能至少 3 个） - 记录安全注意事项 - 说明所需的权限和访问级别 - 记录速率限制和性能特征 FILE:reference/evaluation.md # MCP 服务器评估指南 ## 概述本文档提供关于为 MCP 服务器创建全面评估的指导。评估测试 LLM 能否仅使用所提供的工具，有效地使用你的 MCP 服务器来回答现实、复杂的问题。 --- ## 快速参考 ### 评估要求 - 创建 10 个人类可读的问题 - 问题必须是只读的、独立的、非破坏性的 - 每个问题需要多次工具调用（可能数十次） - 答案必须是单一、可验证的值 - 答案必须是稳定的（不会随时间变化） ### 输出格式 ```xml <evaluation> <qa_pair> <question>你的问题写在这里</question> <answer>单一可验证的答案</answer> </qa_pair> </evaluation> ``` --- ## 评估的目的衡量 MCP 服务器质量的标准不是服务器实现工具的程度或全面性，而是这些实现（输入/输出模式、文档字符串/描述、功能）在 LLM 没有其他上下文且仅能访问 MCP 服务器的情况下，能在多大程度上帮助 LLM 回答现实且困难的问题。 ## 评估概述创建 10 个人类可读的问题，仅需要只读、独立、非破坏性和幂等的操作来回答。每个问题应： - 现实 - 清晰简洁 - 无歧义 - 复杂，可能需要数十次工具调用或步骤 - 能用你事先确定的单一、可验证的值来回答 ## 问题指南 ### 核心要求 1. **问题必须是独立的** - 每个问题不应依赖于任何其他问题的答案 - 不应假设处理另一个问题时进行了先前的写操作 2. **问题必须仅需要非破坏性和幂等的工具使用** - 不应指示或要求修改状态才能得出正确答案 3. **问题必须是现实的、清晰的、简洁的和复杂的** - 必须要求另一个 LLM 使用多个（可能数十个）工具或步骤来回答 ### 复杂性和深度 4. **问题必须要求深入探索** - 考虑需要多个子问题和顺序工具调用的多跳问题 - 每一步都应受益于前面问题中发现的信息 5. **问题可能需要大量分页** - 可能需要翻阅多页结果 - 可能需要查询旧数据（1-2 年前的）以找到小众信息 - 问题必须是困难的 6. **问题必须要求深入理解** - 而非表面知识 - 可以提出需要证据的复杂真/假问题 - 可以使用多项选择格式，让 LLM 必须搜索不同的假设 7. **问题必须不能通过直接的关键词搜索解决** - 不要包含目标内容中的特定关键词 - 使用同义词、相关概念或转述 - 要求多次搜索、分析多个相关项、提取上下文，然后推导出答案 ### 工具测试 8. **问题应对工具返回值进行压力测试** - 可能引出工具返回大型 JSON 对象或列表，使 LLM 不堪重负 - 应要求理解多种数据模态： - ID 和名称 - 时间戳和日期时间（月、日、年、秒） - 文件 ID、名称、扩展名和 MIME 类型 - URL、GID 等 - 应探查工具返回所有有用数据形式的能力 9. **问题应主要反映真实的人类用例** - 在 LLM 辅助下，人类会关心的那类信息检索任务 10. **问题可能需要数十次工具调用** - 这对上下文有限的 LLM 构成挑战 - 鼓励 MCP 服务器工具减少返回的信息 11. **包含模糊的问题** - 可能模糊或需要就调用哪些工具做出困难决定 - 迫使 LLM 可能犯错或误解 - 确保尽管存在模糊性，仍然有单一可验证的答案 ### 稳定性 12. **问题的设计必须使答案不会改变** - 不要问依赖于动态"当前状态"的问题 - 例如，不要统计： - 帖子的反应数 - 线程的回复数 - 频道的成员数 13. **不要让 MCP 服务器限制你创建的问题类型** - 创建具有挑战性和复杂的问题 - 有些可能无法用可用的 MCP 服ver 工具 - 问题可能要求特定的输出格式（datetime 与 epoch 时间、JSON 与 MARKDOWN） - 问题可能需要数十次工具调用才能完成 ## 答案指南 ### 可验证性 1. **答案必须能通过直接字符串比较进行验证** - 如果答案可以用多种格式重写，请在问题中明确指定输出格式 - 示例：“使用 YYYY/MM/DD。”、“回答 True 或 False。”、“回答 A、B、C 或 D，不要包含其他内容。” - 答案应为单个可验证的值，例如： - 用户 ID、用户名、显示名称、名字、姓氏 - 频道 ID、频道名称 - 消息 ID、字符串 - URL、标题 - 数值数量 - 时间戳、日期时间 - 布尔值（用于 True/False 问题） - 电子邮件地址、电话号码 - 文件 ID、文件名、文件扩展名 - 多项选择答案 - 答案不得要求特殊格式或复杂的结构化输出 - 答案将使用直接字符串比较进行验证 ### 可读性 2. **答案通常应优先采用人类可读的格式** - 示例：姓名、名字、姓氏、日期时间、文件名、消息字符串、URL、是/否、真/假、a/b/c/d - 而不是不透明的 ID（尽管 ID 也可接受） - 绝大多数答案应为人类可读的 ### 稳定性 3. **答案必须是稳定/不变的** - 查看旧内容（例如已结束的对话、已发布的项目、已回答的问题） - 基于“封闭”概念创建问题，这些概念将始终返回相同的答案 - 问题可以要求考虑固定的时间窗口，以避免非稳定的答案 - 依赖不太可能改变的上下文 - 示例：如果查找论文名称，要足够具体，以免答案与后来发表的论文混淆 4. **答案必须清晰且无歧义** - 问题的设计必须确保只有一个清晰明确的答案 - 答案可以通过使用 MCP 服务器工具得出 ### 多样性 5. **答案必须多样化** - 答案应为不同模态和格式的单个可验证值 - 用户概念：用户 ID、用户名、显示名称、名字、姓氏、电子邮件地址、电话号码 - 频道概念：频道 ID、频道名称、频道主题 - 消息概念：消息 ID、消息字符串、时间戳、月、日、年 6. **答案不得是复杂结构** - 不是值列表 - 不是复杂对象 - 不是 ID 或字符串列表 - 不是自然语言文本 - 除非答案可以通过直接字符串比较直接验证 - 并且可以真实地复现 - LLM 不太可能以任何其他顺序或格式返回相同的列表 ## 评估流程 ### 步骤 1：文档检查阅读目标 API 的文档以了解： - 可用的端点和功能 - 如果存在歧义，从网络获取额外信息 - 尽可能并行执行此步骤 - 确保每个子代理仅检查来自文件系统或网络的文档 ### 步骤 2：工具检查列出 MCP 服务器中可用的工具： - 直接检查 MCP 服务器 - 了解输入/输出模式、文档字符串和描述 - 在此阶段不要调用工具本身 ### 步骤 3：加深理解重复步骤 1 和 2，直到你有良好的理解： - 多次迭代 - 思考你想创建的任务类型 - 完善你的理解 - 在任何阶段都不应阅读 MCP 服务器实现本身的代码 - 运用你的直觉和理解来创建合理、现实但极具挑战性的任务 ### 步骤 4：只读内容检查在理解 API 和工具后，使用 MCP 服务器工具： - 仅使用只读和非破坏性操作检查内容 - 目标：识别特定内容（例如用户、频道、消息、项目、任务）以创建现实的问题 - 不应调用任何修改状态的工具 - 不会阅读 MCP 服务器实现本身的代码 - 将此步骤与各个子代理并行执行，进行独立探索 - 确保每个子代理仅执行只读、非破坏性和幂等操作 - 注意：某些工具可能返回大量数据，导致上下文耗尽 - 进行增量、小型且有针对性工具调用以进行探索 - 在所有工具调用请求中，使用 `limit` 参数限制结果（<10） - 使用分页 ### 步骤 5：任务生成检查内容后，创建 10 个人类可读的问题： - LLM 应能够使用 MCP 服务器回答这些问题 - 遵循上述所有问题和答案指南 ## 输出格式每个问答对由一个问题和答案组成。输出应为具有以下结构的 XML 文件： ```xml <evaluation> <qa_pair> <question>Find the project created in Q2 2024 with the highest number of completed tasks. What is the project name?</question> <answer>Website Redesign</answer> </qa_pair> <qa_pair> <question>Search for issues labeled as "bug" that were closed in March 2024. Which user closed the most issues? Provide their username.</question> <answer>sarah_dev</answer> </qa_pair> <qa_pair> <question>Look for pull requests that modified files in the /api directory and were merged between January 1 and January 31, 2024. How many different contributors worked on these PRs?</question> <answer>7</answer> </qa_pair> <qa_pair> <question>Find the repository with the most stars that was created before 2023. What is the repository name?</question> <answer>data-pipeline</answer> </qa_pair> </evaluation> ``` ## 评估示例 ### 好的问题 **示例 1：需要深度探索的多跳问题（GitHub MCP）** ```xml <qa_pair> <question>Find the repository that was archived in Q3 2023 and had previously been the most forked project in the organization. What was the primary programming language used in that repository?</question> <answer>Python</answer> </qa_pair> ``` 这个问题很好，因为： - 需要多次搜索才能找到已归档的仓库 - 需要确定哪个在归档前拥有最多的 fork - 需要检查仓库详情以获取语言 - 答案是一个简单、可验证的值 - 基于不会改变的历史（封闭）数据 **示例 2：需要理解上下文而非关键词匹配（项目管理 MCP）** ```xml <qa_pair> <question>Locate the initiative focused on improving customer onboarding that was completed in late 2023. The project lead created a retrospective document after completion. What was the lead's role title at that time?</question> <answer>Product Manager</answer> </qa_pair> ``` 这个问题很好，因为： - 不使用具体的项目名称（“专注于改善客户入职的倡议”） - 需要从特定时间范围内查找已完成的项目 - 需要识别项目负责人及其角色 - 需要从回顾文档中理解上下文 - 答案是人类可读且稳定的 - 基于已完成的工作（不会改变） **示例 3：需要多个步骤的复杂聚合（问题跟踪器 MCP）** ```xml <qa_pair> <question>在2024年1月报告的所有被标记为关键优先级的错误中，哪个负责人在其分配的bug中48小时内解决的百分比最高？提供该负责人的用户名。</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> ``` 这个问题很好，因为： - 需要理解订阅层级变化 - 需要识别特定时间范围内的升级事件 - 需要比较合同价值 - 必须访问账户行业信息 - 答案简单且可验证 - 基于已完成的历史交易 ### 差的问题 **示例 1：答案随时间变化** ```xml <qa_pair> <question>当前有多少个未解决的问题分配给了工程团队？</question> <answer>47</answer> </qa_pair> ``` 这个问题很差，因为： - 答案会随着问题的创建、关闭或重新分配而变化 - 不是基于稳定/静止的数据 - 依赖于“当前状态”，这是动态的 **示例 2：关键词搜索太简单** ```xml <qa_pair> <question>找到标题为“添加身份验证功能”的拉取请求，并告诉我谁创建了它。</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或DESTRUCTIVE操作的操作** 4. **累积所有正确答案**并替换文档中的任何错误答案 5. **移除任何需要WRITE或DESTRUCTIVE操作的`<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 positional arguments: eval_file Path to evaluation XML file optional arguments: -h, --help Show help message -t, --transport Transport type: stdio, sse, or http (default: stdio) -m, --model Claude model to use (default: claude-3-7-sonnet-20250219) -o, --output Output 报告文件（默认：打印到标准输出） 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>Find the user who created the most issues in January 2024. What is their username?</question> <answer>alice_developer</answer> </qa_pair> <qa_pair> <question>Among all pull requests merged in Q1 2024, which repository had the highest number? Provide the repository name.</question> <answer>backend-api</answer> </qa_pair> <qa_pair> <question>Find the project that was completed in December 2023 and had the longest duration from start to finish. How many days did it take?</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 schema 集成 - 类型安全的工具处理程序实现 **重要 - 仅使用现代 API：** - **应使用**：`server.registerTool()`、`server.registerResource()`、`server.registerPrompt()` - **不要使用**：旧的已弃用 API，例如 `server.tool()`、`server.setRequestHandler(ListToolsRequestSchema, ...)` 或手动处理程序注册 - `register*` 方法提供更好的类型安全、自动 schema 处理，并且是推荐方式有关完整细节，请参阅参考资料中的 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 # Main entry point with McpServer initialization │ ├── types.ts # TypeScript type definitions and interfaces │ ├── tools/ # Tool implementations (one file per domain) │ ├── services/ # API clients and shared utilities │ ├── schemas/ # Zod validation schemas │ └── constants.ts # Shared constants (API_URL, CHARACTER_LIMIT, etc.) └── dist/ # Built JavaScript files (entry point: 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 schema 进行运行时输入验证和类型安全 - 必须显式提供 `description` 字段 - JSDoc 注释不会被自动提取 - 显式提供`title`、`description`、`inputSchema` 和 `annotations` - `inputSchema` 必须是 Zod schema 对象（不是 JSON schema） - 显式地为所有参数和返回值标注类型 ```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 schema 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(); // 从 Zod schema 推导出的类型定义 type UserSearchInput = z.infer<typeof UserSearchInputSchema>; server.registerTool( "example_search_users", { title: "Search Example Users", description: `Search for users in the Example system by name, email, or team. This tool searches across all user profiles in the Example platform, supporting partial matches and various search filters. It does NOT create or modify users, only searches existing ones. Args: - query (string): Search string to match against names/emails - limit (number): Maximum results to return, between 1-100 (default: 20) - offset (number): Number of results to skip for pagination (default: 0) - response_format ('markdown' | 'json'): Output format (default: 'markdown') Returns: For JSON format: Structured data with schema: { "total": number, // Total number of matches found "count": number, // Number of results in this response "offset": number, // Current pagination offset "users": [ { "id": string, // User ID (e.g., "U123456789") "name": string, // Full name (e.g., "John Doe") "email": string, // Email address "team": string, // Team name (optional) "active": boolean // Whether user is active } ], "has_more": boolean, // Whether more results are available "next_offset": number // Offset for next page (if has_more is true) } Examples: - Use when: "Find all marketing team members" -> params with query="team:marketing" - Use when: "Search for John's account" -> params with query="john" - Don't use when: You need to create a user (use example_create_user instead) Error Handling: - Returns "Error: Rate limit exceeded" if too many requests (429 status) - Returns "No users found matching '<query>'" if search returns empty`, inputSchema: UserSearchInputSchema, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true } }, async (params: UserSearchInput) => { try { // 输入验证由 Zod schema 处理 // 使用已验证的参数发起 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 Schema Zod 提供运行时类型验证： ```typescript import { z } from "zod"; // 带验证的基础 schema const CreateUserSchema = z.object({ name: z.string() .min(1, "Name is required") .max(100, "Name must not exceed 100 characters"), email: z.string() .email("Invalid email format"), age: z.number() .int("Age must be a whole number") .min(0, "Age cannot be negative") .max(150, "Age cannot be greater than 150") }).strict(); // 使用 .strict() 禁止额外字段 // 枚举 enum ResponseFormat { MARKDOWN = "markdown", JSON = "json" } const SearchSchema = z.object({ response_format: z.nativeEnum(ResponseFormat) .default(ResponseFormat.MARKDOWN) .describe("Output format") }); // 带默认值的可选字段 const PaginationSchema = z.object({ 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") }); ``` ## 响应格式选项支持多种输出格式以提供灵活性： ```typescript enum ResponseFormat { MARKDOWN = "markdown", JSON = "json" } const inputSchema = z.object({ query: z.string(), response_format: z.nativeEnum(ResponseFormat) .default(ResponseFormat.MARKDOWN) .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable") }); ``` **Markdown 格式**： - 使用标题、列表和格式以提升清晰度 - 将时间戳转换为人类可读格式 - 在括号中显示名称及 ID - 省略冗长的元数据 - 按逻辑对相关信息进行分组 **JSON 格式**： - R返回完整、结构化的数据，适合程序化处理 - 包含所有可用字段和元数据 - 使用一致的字段名和类型 ## 分页实现对于列出资源的工具： ```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 `错误：发生意外错误：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 // 良好：异步网络请求 async function fetchData(resourceId: string): Promise<ResourceData> { const response = await axios.get(`API_URL/resource/resourceId`); return response.data; } // 不佳：Promise 链 function fetchData(resourceId: string): Promise<ResourceData> { return axios.get(`API_URL/resource/resourceId`) .then(response => response.data); // 更难阅读和维护 } ``` ## TypeScript 最佳实践 1. **使用严格 TypeScript**：在 tsconfig.json 中启用严格模式 2. **定义接口**：为所有数据结构创建清晰的接口定义 3. **避免 `any`**：使用正确的类型或 `unknown` 代替 `any` 4. **使用 Zod 进行运行时验证**：使用 Zod schema 验证外部数据 5. **类型守卫**：为复杂类型检查创建类型守卫函数 6. **错误处理**：始终使用 try-catch 并进行正确的错误类型检查 7. **空值安全**：使用可选链（`?.`）和空值合并（`??`） ```typescript // 良好：使用 Zod 和接口实现类型安全 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); // 运行时验证 } // 不佳：使用 any async function getUser(id: string): Promise<any> { return await apiCall(`/users/id`); // 无类型安全 } ``` ## 包配置 ### package.json ```json { "name": "{service}-mcp-server", "version": "1.0.0", "description": "用于 {Service} API 集成的 MCP 服务器", "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 /** * 用于 Example Service 的 MCP 服务器。 * * 此服务器提供与 Example API 交互的工具，包括用户搜索、 * 项目管理和数据导出功能。 */ 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"; // 常量 const API_BASE_URL = "https://api.example.com/v1"; const CHARACTER_LIMIT = 25000; // 枚举 enum ResponseFormat { MARKDOWN = "markdown", JSON = "json" } // Zod schema 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(); type UserSearchInput = z.infer<typeof UserSearchInputSchema>; // 共享工具函数 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 "错误：资源未找到。请检查 ID 是否正确。"; case 403: return "错误：权限被拒绝。您无权访问此资源。"; case 429: return "错误：超出速率限制。请稍后再发起更多请求。"; default: return `错误：API 请求失败，状态码 error.response.status`; } } else if (error.code === "ECONNABORTED") { return "错误：请求超时。请重试。"; } } return `错误：发生意外错误：String(error)`; } // 创建 MCP 服务器实例 const server = new McpServer({ name: "example-mcp", version: "1.0.0" }); // 注册工具 server.registerTool( "example_search_users", { title: "搜索示例用户", description: `[完整描述如上所示]`, inputSchema: UserSearchInputSchema, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true } }, async (params: UserSearchInput) => { // 实现如上所示 } ); // 主函数 // 用于 stdio（本地）： async function runStdio() { if (!process.env.EXAMPLE_API_KEY) { console.error("错误：需要 EXAMPLE_API_KEY 环境变量"); process.exit(1); } const transport = new StdioServerTransport(); await server.connect(transport); console.error("MCP 服务器通过 stdio 运行"); } // 用于可流式 HTTP（远程）： async function runHTTP() { if (!process.env.EXAMPLE_API_KEY) { console.error("错误：需要 EXAMPLE_API_KEY 环境变量"); 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 服务器运行在 http://localhost:port/mcp`); }); } // 根据环境选择传输方式 const transport = process.env.TRANSPORT || 'stdio'; if (transport === 'http') { runHTTP().catch(error => { console.error("服务器错误：", error); process.exit(1); }); } else { runStdio().catch(error => { console.error("服务器错误：", error); process.exit(1); }); } ``` --- ## 高级 MCP 功能 ### 资源注册将数据作为资源公开，以实现高效的基于 URI 的访问： ```typescript import { ResourceTemplate } from "@modelcontextprotocol/sdk/types.js"; // 注册带有 URI 模板的资源 server.registerResource( { uri: "file://documents/{name}", name: "文档资源", 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" }); ``` 谨慎使用通知——仅在服务器能力真正变化时使用。 --- ## 代码最佳实践 ### 代码可组合性与可重用性您的实现必须优先考虑可组合性和代码重用： 1. **提取通用功能**： - 为跨多个工具使用的操作创建可重用的辅助函数 - 为 HTTP 请求构建共享 API 客户端，而不是重复代码 - 将错误处理逻辑集中到实用函数中 - 将业务逻辑提取到可组合的专用函数中 - 提取共享的 markdown 或 JSON 字段选择与格式化功能 2. **避免重复**： - 绝不在工具之间复制粘贴相似的代码 - 如果发现自己两次编写相似的逻辑，将其提取为函数 - 分页、过滤、字段选择和格式化等常见操作应共享 - 认证/授权逻辑应集中管理 ## 构建与运行在运行之前，始终先构建 TypeScript 代码： ```bash # 构建项目 npm run build # 运行服务器 npm start # 开发模式（自动重载） npm run dev ``` 在认为实现完成之前，始终确保 `npm run build` 成功完成。 ## 质量检查清单在最终确定 Node/TypeScript MCP 服务器实现之前，确保： ### 战略设计 - [ ] 工具支持完整的工作流，而不仅仅是 API 端点包装器 - [ ] 工具名称反映自然任务细分 - [ ] 响应格式针对代理上下文效率进行优化 - [ ] 在适当的地方使用人类可读的标识符 - [ ] 错误消息引导代理正确使用 ### 实现质量 - [ ] 聚焦实现：实现最重要和最有价值的工具 - [ ] 所有工具使用 `registerTool` 注册，并具有完整配置 - [ ] 所有工具包含 `title`、`description`、`inputSchema` 和 `annotations` - [ ] 注解正确设置（readOnlyHint、destructiveHint、idempotentHint、openWorldHint） - [ ] 所有工具使用 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` - [ ] 所有导入正确解析 - [ ] 示例工具调用按预期工作 FILE:reference/python_mcp_server.md # Python MCP 服务器实现指南 ## 概述本文档提供了使用 MCP Python SDK 实现 MCP 服务器的 Python 特定最佳实践和示例。它涵盖了服务器设置、工具注册模式、使用 Pydantic 进行输入验证、错误处理以及完整的工作示例。 --- ## 快速参考 ### 关键导入 ```python from mcp.server.fastmcp import FastMCP from pydantic import BaseModel, Field, field_validator, ConfigDict from typing import Optional, List, Dict, Any from enum import Enum import httpx ``` ### 服务器初始化 ```python mcp = FastMCP("service_mcp") ``` ### 工具注册模式 ```python @mcp.tool(name="tool_name", annotations={...}) async def tool_function(params: InputModel) -> str: # 实现 pass ``` --- ## MCP Python SDK 和 FastMCP 官方 MCP Python SDK 提供了 FastMCP，一个用于构建 MCP 服务器的高级框架。它提供： - 从函数签名和文档字符串自动生成描述和 inputSchema - 用于输入验证的 Pydantic 模型集成 - 使用 `@mcp.tool` 的基于装饰器的工具注册 **获取完整的 SDK 文档，请使用 WebFetch 加载：** `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` ## 服务器命名约定 Python MCP 服务器必须遵循以下命名模式： - **格式**：`{service}_mcp`（小写加下划线） - **示例**：`github_mcp`、`jira_mcp`、`stripe_mcp` 名称应： - 通用（不绑定特定功能） - 描述所集成的服务/API - 易于从任务描述中推断 - 不含版本号或日期 ## 工具实现 ### 工具命名工具名称使用 snake_case（例如 "search_users"、"create_project"、"get_channel_info"），名称清晰且面向操作。 **避免命名冲突**：包含服务上下文以防止重叠： - 使用 "slack_send_message" 而不是仅 "send_message" - 使用 "github_create_issue" 而不是仅 "create_issue" - 使用 "asana_list_tasks" 而不是仅 "list_tasks" ### 使用 FastMCP 的工具结构工具使用 `@mcp.tool` 装饰器定义，并使用 Pydantic 模型进行输入验证： ```python from pydantic import BaseModel, Field, ConfigDict from mcp.server.fastmcp import FastMCP # 初始化 MCP 服务器 mcp = FastMCP("example_mcp") # 定义用于输入验证的 Pydantic 模型 class ServiceToolInput(BaseModel): '''服务工具操作的输入模型。''' model_config = ConfigDict( str_strip_whitespace=True, # 自动去除字符串空白 validate_assignment=True, # 赋值时验证 extra='forbid' # 禁止额外字段 ) param1: str = Field(..., description="第一个参数描述（例如 'user123'、'project-abc'）", min_length=1, max_length=100) param2: Optional[int] = Field(default=None, description="带约束的可选整数参数", ge=0, le=1000) tags: Optional[List[str]] = Field(default_factory=list, description="要应用的标签列表", max_items=10) @mcp.tool( name="service_tool_name", annotations={ "title": "人类可读的工具标题", "readOnlyHint": True, # 工具不修改环境 "destructiveHint": False, # 工具不执行破坏性tive operations "idempotentHint": True, # 重复调用不会产生额外效果 "openWorldHint": False # 工具不与外部实体交互 } ) async def service_tool_name(params: ServiceToolInput) -> str: '''工具描述自动成为 'description' 字段。此工具对服务执行特定操作。在处理之前，它使用 ServiceToolInput Pydantic 模型验证所有输入。 Args: params (ServiceToolInput): 包含以下内容的已验证输入参数： - param1 (str): 第一个参数描述 - param2 (Optional[int]): 带默认值的可选参数 - tags (Optional[List[str]]): 标签列表 Returns: str: 包含操作结果的 JSON 格式响应 ''' # 在此处实现 pass ``` ## 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="用户的全名", min_length=1, max_length=100) email: str = Field(..., description="用户的电子邮件地址", pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$') age: int = Field(..., description="用户的年龄", ge=0, le=150) @field_validator('email') @classmethod def validate_email(cls, v: str) -> str: if not v.strip(): raise ValueError("电子邮件不能为空") return v.lower() ``` ## 响应格式选项支持多种输出格式以提供灵活性： ```python from enum import Enum class ResponseFormat(str, Enum): '''工具响应的输出格式。''' MARKDOWN = "markdown" JSON = "json" class UserSearchInput(BaseModel): query: str = Field(..., description="搜索查询") response_format: ResponseFormat = Field( default=ResponseFormat.MARKDOWN, description="输出格式：'markdown' 用于人类可读，'json' 用于机器可读" ) ``` **Markdown 格式**： - 使用标题、列表和格式以提高清晰度 - 将时间戳转换为人类可读格式（例如，"2024-01-15 10:30:00 UTC" 而不是 epoch） - 在括号中显示显示名称和 ID（例如，"@john.doe (U123456)"） - 省略冗长的元数据（例如，只显示一个个人资料图片 URL，而不是所有尺寸） - 逻辑分组相关信息 **JSON 格式**： - 返回完整、结构化的数据，适合程序化处理 - 包含所有可用字段和元数据 - 使用一致的字段名称和类型 ## 分页实现对于列出资源的工具： ```python class ListInput(BaseModel): limit: Optional[int] = Field(default=20, description="返回的最大结果数", ge=1, le=100) offset: Optional[int] = Field(default=0, description="分页时跳过的结果数", ge=0) async def list_items(params: ListInput) -> str: # 使用分页发起 API 请求 data = await api_request(limit=params.limit, offset=params.offset) # 返回分页信息 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: '''所有工具的一致错误格式。''' if isinstance(e, httpx.HTTPStatusError): if e.response.status_code == 404: return "错误：未找到资源。请检查 ID 是否正确。" elif e.response.status_code == 403: return "错误：权限被拒绝。您无权访问此资源。" elif e.response.status_code == 429: return "错误：超出速率限制。请等待后再发起更多请求。" return f"错误：API 请求失败，状态码 {e.response.status_code}" elif isinstance(e, httpx.TimeoutException): return "错误：请求超时。请重试。" return f"错误：发生意外错误：{type(e).__name__}" ``` ## 共享工具将常见功能提取为可重用函数： ```python # 共享 API 请求函数 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() ``` ## 异步/等待最佳实践始终对网络请求和 I/O 操作使用 async/await： ```python # 良好：异步网络请求 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() # 不良：同步请求 def fetch_data(resource_id: str) -> dict: response = requests.get(f"{API_URL}/resource/{resource_id}") # 阻塞 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"]} ``` ## 工具文档字符串每个工具都必须有包含显式类型信息的全面文档字符串： ```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: <error message>" 或 "No users found matching '<query>'" 示例： - 使用场景："查找所有市场团队成员" -> params 中 query="team:marketing" - 使用场景："搜索 John 的账户" -> params 中 query="john" - 不使用场景：需要创建用户（改用 example_create_user） - 不使用场景：已有用户 ID 且需要完整详情（改用 example_get_user）错误处理： - 输入验证错误由 Pydantic 模型处理 - 如果请求过多（429 状态），返回 "Error: Rate limit exceeded" - 如果 API 密钥无效（401 状态），返回 "Error: Invalid API authentication" - 返回格式化结果列表或 "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: '''按姓名、电子邮件或团队在 Example 系统中搜索用户。 [完整 docstring 如上所示] ''' 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 功能 ### Context 参数注入 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, "Starting search...") # 记录信息用于调试 await ctx.log_info("Processing query", {"query": query, "timestamp": datetime.now()}) # 执行搜索 results = await search_api(query) await ctx.report_progress(0.75, "Formatting results...") # 访问服务器配置 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**：命令行工具、本地集成、子进程执行 - **可流式 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 Field 都有显式类型和带约束的描述 - [ ] 所有工具都有全面的 docstring，包含显式的输入/输出类型 - [ ] Docstring 包含 dict/JSON 返回的完整 schema 结构 - [ ] Pydantic 模型处理输入验证（无需手动验证） ### 高级功能（如适用） - [ ] 使用上下文注入进行日志记录、进度报告或信息引导 - [ ] 为适当的数据端点注册资源 - [ ] 为持久连接实现生命周期管理 - [ ] Struc使用的结构化输出类型（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"Unexpected context result: {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 的 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 连接的工厂函数。 Args: transport: 连接类型（"stdio"、"sse" 或 "http"） command: 要运行的命令（仅 stdio） args: 命令参数（仅 stdio） env: 环境变量（仅 stdio） url: 服务器 URL（仅 sse 和 http） headers: HTTP 头（仅 sse 和 http） Returns: MCPConnection 实例 """ transport = transport.lower() if transport == "stdio": if not command: raise ValueError("Command is required for stdio transport") return MCPConnectionStdio(command=command, args=args, env=env) elif transport == "sse": if not url: raise ValueError("URL is required for sse transport") return MCPConnectionSSE(url=url, headers=headers) elif transport in ["http", "streamable_http", "streamable-http"]: if not url: raise ValueError("URL is required for http transport") return MCPConnectionHTTP(url=url, headers=headers) else: raise ValueError(f"Unsupported transport type: {transport}. Use 'stdio', 'sse', or 'http'") FILE:scripts/evaluation.py """MCP 服务器评估工具此脚本通过使用 Claude 对 MCP 服务器运行测试问题来评估它们。 """ import argparse import asyncio import json import re import sys import time import traceback import xml.etree.ElementTree as ET from pathlib import Path from typing import Any from anthropic import Anthropic from connections import create_connection EVALUATION_PROMPT = """你是一个可以访问工具的 AI 助手。当给定任务时，你必须： 1. 使用可用工具完成任务 2. 在 <summary> 标签中提供你方法的每一步摘要 3. 在 <feedback> 标签中提供对所提供工具的反馈 4. 在 <response> 标签中提供你的最终回复摘要要求： - 在你的 <summary> 标签中，你必须解释： - 你为完成任务所采取的步骤 - 你使用了哪些工具、以什么顺序以及为什么 - 你为每个工具提供的输入 - 你从每个工具收到的输出 - 关于你如何得出该回复的摘要反馈要求： - 在你的 <feedback> 标签中，提供对工具的建设性反馈： - 评论工具名称：它们是否清晰且具有描述性？ - 评论输入参数：它们是否有良好的文档？必需参数与可选参数是否清晰？ - 评论描述描述：它们是否准确描述了工具的功能？ - 评论工具使用过程中遇到的任何错误：工具是否执行失败？工具是否返回了过多 token？ - 指出具体的改进领域并解释为什么这些改进会有帮助 - 在你的建议中要具体且可操作响应要求： - 你的响应应简洁并直接回答所问内容 - 始终将最终响应包裹在 <response> 标签中 - 如果你无法解决该任务，返回 <response>NOT_FOUND</response> - 对于数值响应，只提供数字 - 对于 ID，只提供 ID - 对于名称或文本，提供所要求的确切文本 - 你的响应应放在最后""" def parse_evaluation_file(file_path: Path) -> list[dict[str, Any]]: """解析包含 qa_pair 元素的 XML 评估文件。""" try: tree = ET.parse(file_path) root = tree.getroot() evaluations = [] for qa_pair in root.findall(".//qa_pair"): question_elem = qa_pair.find("question") answer_elem = qa_pair.find("answer") if question_elem is not None and answer_elem is not None: evaluations.append({ "question": (question_elem.text or "").strip(), "answer": (answer_elem.text or "").strip(), }) return evaluations except Exception as e: print(f"解析评估文件 {file_path} 时出错：{e}") return [] def extract_xml_content(text: str, tag: str) -> str | None: """从 XML 标签中提取内容。""" pattern = rf"<{tag}>(.*?)</{tag}>" matches = re.findall(pattern, text, re.DOTALL) return matches[-1].strip() if matches else None async def agent_loop( client: Anthropic, model: str, question: str, tools: list[dict[str, Any]], connection: Any, ) -> tuple[str, dict[str, Any]]: """使用 MCP 工具运行智能体循环。""" messages = [{"role": "user", "content": question}] response = await asyncio.to_thread( client.messages.create, model=model, max_tokens=4096, system=EVALUATION_PROMPT, messages=messages, tools=tools, ) messages.append({"role": "assistant", "content": response.content}) tool_metrics = {} while response.stop_reason == "tool_use": tool_use = next(block for block in response.content if block.type == "tool_use") tool_name = tool_use.name tool_input = tool_use.input tool_start_ts = time.time() try: tool_result = await connection.call_tool(tool_name, tool_input) tool_response = json.dumps(tool_result) if isinstance(tool_result, (dict, list)) else str(tool_result) except Exception as e: tool_response = f"执行工具 {tool_name} 时出错：{str(e)}\n" tool_response += traceback.format_exc() tool_duration = time.time() - tool_start_ts if tool_name not in tool_metrics: tool_metrics[tool_name] = {"count": 0, "durations": []} tool_metrics[tool_name]["count"] += 1 tool_metrics[tool_name]["durations"].append(tool_duration) messages.append({ "role": "user", "content": [{ "type": "tool_result", "tool_use_id": tool_use.id, "content": tool_response, }] }) response = await asyncio.to_thread( client.messages.create, model=model, max_tokens=4096, system=EVALUATION_PROMPT, messages=messages, tools=tools, ) messages.append({"role": "assistant", "content": response.content}) response_text = next( (block.text for block in response.content if hasattr(block, "text")), None, ) return response_text, tool_metrics async def evaluate_single_task( client: Anthropic, model: str, qa_pair: dict[str, Any], tools: list[dict[str, Any]], connection: Any, task_index: int, ) -> dict[str, Any]: """使用给定工具评估单个 QA 对。""" start_time = time.time() print(f"任务 {task_index + 1}：使用以下问题运行任务：{qa_pair['question']}") response, tool_metrics = await agent_loop(client, model, qa_pair["question"], tools, connection) response_value = extract_xml_content(response, "response") summary = extract_xml_content(response, "summary") feedback = extract_xml_content(response, "feedback") duration_seconds = time.time() - start_time return { "question": qa_pair["question"], "expected": qa_pair["answer"], "actual": response_value, "score": int(response_value == qa_pair["answer"]) if response_value else 0, "total_duration": duration_seconds, "tool_calls": tool_metrics, "num_tool_calls": sum(len(metrics["durations"]) for metrics in tool_metrics.values()), "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"Warning: Ignoring malformed header: {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"Warning: Ignoring malformed environment variable: {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="'Key: Value' 格式的 HTTP 头部（仅 sse/http）") parser.add_argument("-o", "--output", type=Path, help="评估报告的输出文件（默认：stdout）") args = parser.parse_args() if not args.eval_file.exists(): print(f"Error: Evaluation file not found: {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"Error: {e}") sys.exit(1) print(f"🔗 Connecting to MCP server via {args.transport}...") async with connection: print("✅ Connected successfully") report = await run_evaluation(args.eval_file, connection, args.model) if args.output: args.output.write_text(report) print(f"\n✅ Report saved to {args.output}") else: print("\n" + report) if __name__ == "__main__": asyncio.run(main()) FILE:scripts/example_evaluation.xml <evaluation> <qa_pair> <question>计算以 5% 年利率投资 $10,000、按月复利、为期 3 年的复利。最终金额是多少美元（四舍五入到 2 位小数）？</question> <answer>11614.72</answer> </qa_pair> <qa_pair> <question>一个抛射体以 45 度角发射，初速度为 50 m/s。假设 g=9.8 m/s²，计算它在 2 秒后从发射点起总共行进的距离（以米为单位）。四舍五入到 2 位小数。</question> <answer>87.25</answer> </qa_pair> <qa_pair> <question>一个球体的体积为 500 立方米。计算其表面积（以平方米为单位）。四舍五入到 2 位小数。</question> <answer>304.65</answer> </qa_pair> <qa_pair> <question>计算该数据集的总体标准差：[12, 15, 18, 22, 25, 30, 35]。四舍五入到 2 位小数。</question> <answer>7.61</answer> </qa_pair> <qa_pair> <question>计算氢离子浓度为 3.5 × 10^-5 M 的溶液的 pH。四舍五入到 2 位小数。</question> <answer>4.46</answer> </qa_pair> </evaluation> FILE:scripts/requirements.txt anthropic>=0.39.0 mcp>=1.1.0

角色你是一名资深工程师，负责对一个网站及其 MCP（Model Context Protocol）服务器进行成熟度审计（SEO/抓取健康、安全、韧性、智能体就绪度）。像独立审计员一样工作：证据优先，不做假设，能修的就修，然后重新测试。授权只审计 owner_or_authorized_party 拥有或已明确授权你测试的系统。负载、模糊测试和攻击式测试只针对 STAGING 运行。针对生产环境，只做只读、限速的抓取，且必须获得我的明确批准。不进行真实支付，不进行真实预订或下单，不涉及真实个人数据。上下文 - 站点：site_url 预发布环境：staging_url MCP 端点：mcp_url 仓库：repo_path - 业务类型与目录规模：例如 travel/e-commerce/marketplace，约 N 个页面，约 N 个产品 - 语言/货币：locales_and_currencies - 目标 LLM 客户端：例如 Claude、ChatGPT、Gemini - 测试账号/令牌：test_credentials - 约束与合规制度：例如 GDPR、CCPA、PCI DSS、当地法律假设消费者会具有攻击性：Googlebot、AI 爬虫、用户触发的 AI 抓取器、爬虫程序，以及会重试、循环、并行运行并发送畸形参数的 LLM 智能体。规则 1. 先阅读：仓库、OpenAPI/工具定义、robots.txt、站点地图、模板、响应头。在测试前建立清单。 2. 每个结论都需要证据（命令、输出、日志、file:line、URL）。没有证据 = 未通过。 3. 将任何无法测试的内容标记为“NOT RUN + 原因”。绝不隐瞒失败。 4. 在陈述版本、规范和搜索引擎指南之前，先对照官方文档核实。 5. 在执行破坏性或高流量测试前先询问。修复严重/高优先级问题，重新测试，并记录修复前后情况。 6. 先制定包含 10 个项目的测试计划和任务清单，然后执行。测试类别 A. 抓取与索引健康 - 获取 robots.txt 和所有站点地图；按类型统计 URL 数量；与预期页面数量核对。报告站点地图中返回 404/重定向/noindex/规范化到其他位置的 URL、站点地图中缺失的可索引页面，以及孤立页面。 - 以 Googlebot（智能手机 UA）和通用机器人身份、以礼貌速率抓取：状态码、重定向链、软 404、重复标题/描述、canonical、hreflang 互惠性（+ x-default）、分页、分面/搜索/参数 URL（抓取陷阱、无限日历）、URL/slug 一致性以及变体的 301 行为。 - 渲染：比较原始 HTML 与渲染后的 DOM；确认关键内容、链接、结构化数据和价格不是仅靠 JS 呈现。 - 机器人确定性：反复获取关键页面；检查随机化/个性化是否会给机器人带来不稳定或实质不同的内容（伪装风险）。 - 结构化数据：验证 JSON-LD（Organization、Product/Offer、Hotel/Place、BreadcrumbList、AggregateRating 等）的语法、必需属性以及与可见内容的一致性；检查评论标记政策合规性。 - 性能：对 30 个代表性模板运行 Lighthouse（移动端）；报告 LCP/INP/CLS。如提供 Search Console 数据则使用。 - robots.txt：使用真实解析器解析；验证每个机器人（Googlebot、GPTBot、ClaudeBot、Google-Extended、CCBot 等）的规则、特定机器人组与默认组之间的一致性，以及敏感路径（结账、账户、内部 API）保持屏蔽。确认 AI 训练/AI 输入政策（Content-Signal 或等效项）是有意为之。 - 站点地图卫生：lastmod 准确性、大小限制（50k URL/50MB）、gzip、内容类型、图片/视频站点地图。 - AI 搜索就绪度：验证 AI 抓取器/搜索机器人用户代理能获得 200 响应（无 WAF 挑战、无错误 403/429）；考虑 llms.txt 和干净的文本渲染。 B. 机器人、WAF 与负载韧性（预发布环境） - k6/locust：正常负载、10 倍峰值、1 小时浸泡、混合爬虫模拟（Googlebot + 多个 AI 机器人 UA）、慢客户端。 - 缓存行为：命中率、缓存键与查询参数、stale-while-revalidate；价格/可用性/报价端点的保护（robots.txt 不是安全措施）。 - 上游放大：每次页面浏览和每次抓取触发的后端/供应商调用；机器人不得触发无限制的实时上游调用。测试超时、熔断器、重试风暴和降级模式页面（混沌测试）。 - 速率限制：429 + Retry-After、按 IP/令牌/UA 的限制；合法爬虫不被误限流。 - 测量 p50/p95/p99 延迟、错误率、CPU/RAM、数据库连接、每 1,000 次请求的成本。 C. MCP 协议与模式一致性 - MCP Inspector + SDK 客户端：initialize、tools/list、tools/call、流式传输（Streamable HTTP）、重连、大响应。 - 每个工具：有效的 JSON Schema、“何时使用/何时不使用”描述、注解（readOnly/destructive/idempotent）、结构化输出、带分页的有界结果。 - 将工具定义转换为 Claude、OpenAI 和 Gemini 的函数调用格式；标记不支持的构造。 - 工具返回的 ID、URL、语言和货币必须与网站的规范值一致。 D. 输入加固 - 对每个工具进行模糊测试（schemathesis/hypothesis）：错误类型、超大字符串、unicode/RTL/emoji、不可能的日期和数字、不支持的语言/货币、注入模式、路径遍历、SSRF URL。期望无 500、无堆栈跟踪、可恢复错误、服务器保持运行。 E. 智能体行为评估（端到端） - 用你的用户所说的语言编写 50+ 个真实场景：清晰、模糊、多步骤、错误、更改/取消、售罄、价格变动、冲突请求。 - 在 3+ 个目标模型 × 5 次重复上运行。指标：工具选择准确性、参数准确性、任务成功率、pass^k、每任务调用次数和令牌数、错误恢复、写操作前的确认合规性。对失败进行根因分析（描述、模式、输出大小、模型）；先修复描述/模式并重新测量。 F. 安全 - 通过目录/用户生成内容（描述、评论、博客、表单字段）使用模拟上游数据和预发布内容进行间接提示注入。智能体不得采取未授权操作或泄露数据。 - 认证/授权：OAuth 2.1 + PKCE、受众绑定令牌、作用域强制、IDOR、过期/错误受众令牌、无令牌透传。 - 写操作安全：明确的用户确认、报价过期、价格/货币篡改、使用同一幂等键的 50 个并行请求 -> 恰好一次效果。 - 支付：不通过工具或日志传输卡数据；仅使用托管支付链接。 - Web 基础：对表单和端点执行 OWASP Top 10/API Top 10、CSRF、开放重定向、安全头、cookie 标志、依赖/容器/密钥扫描（pip-audit/npm audit、Trivy、gitleaks）、SBOM。 - 滥用：抗抓取和枚举、拒绝钱包限制。 G. 隐私与合规 - 同意：分析/营销标签不得在同意前触发；选择按声明持久化；第三方嵌入仅在同意后加载。 - 适用制度（regimes）：数据最小化、保留、数据主体请求、与 LLM 供应商的处理者协议、日志不含 PII/令牌。 - 内容/许可：图片和评论使用权、AI 训练/AI-input 策略一致性、展示评分的准确性以及“已验证”声明。 H. 可观测性与运维 - 按工具调用和页面类型记录追踪/日志（延迟、上游状态、缓存状态、机器人分类）；写操作的审计日志；仪表盘和告警。 - 健康/就绪检查、优雅关闭、配置校验、密钥管理、回滚计划、工具 schema 版本管理、 CI 检查确保 robots.txt 和 sitemap 永不回退。评分将类别 A-H 从 0 到 4 评分：0 无，1 临时性，2 部分覆盖但有缺口，3 一致且经过测试，4 自动化、受监控、有证据。生产门禁（全部必需）： - 0 个未解决的严重/高危安全问题；0 次成功的未授权写入或重复交易。 - >= 99% 的 sitemap URL 返回 200、自规范且可索引；0 个 sitemap URL 为 noindex/重定向/404；hreflang 互惠 >= 99%。 - 搜索/筛选/参数 URL 不会产生无界可索引重复项。 - 关键模板的 Core Web Vitals 良好，或有注明日期的修复计划。 - 在 10 倍峰值和爬虫模拟下：错误率 < 1%，p95 < target_ms ms，每次页面浏览的上游调用在预算内，限流有效，没有合法爬虫被误封。 - Agent 评估：在每个目标模型上任务成功率 >= 90% 且 pass^5 >= 75%（或有记录的例外）。 - 日志中 0 PII/token/卡数据；遵守同意。 - 每个发现都有证据，并且要么有修复，要么有签署确认的已接受风险。交付物（位于 /maturity-audit/） 1. REPORT.md：执行摘要、类别评分、门禁通过/失败、前 10 大风险。 2. FINDINGS.md：ID、类别、严重性、证据、影响、修复、状态、负责人。 3. SEO-CRAWL.md：sitemap 对账（类型、数量、健康百分比）、canonical/hreflang/重复问题、爬取陷阱、结构化数据结果。 4. EVAL.md：场景、模型、指标、前后对比。 5. 可运行测试：tests/、负载和爬虫脚本、注入测试夹具、CI 回归检查，以及单个 `make audit`。 6. ROADMAP.md：30/60/90 天计划和已接受风险。最终回复：简要总结发现、修复、失败门禁，以及最重要的下一步。