eval-mcp

评估 MCP 工具

工具描述属于提示词工程——它们会直接进入 Claude 的上下文窗口，并决定 Claude 是否会为某个意图选择正确的工具并提供正确的参数。这项技能让工具质量变得可衡量、可改进，而不再依赖猜测。

三个测试层级，逐步递进：

1. 静态分析——确定性的架构质量检查（不调用 Claude）
2. 选择测试——Claude 是否会针对每种意图选择正确的工具？
3. 描述优化——根据混淆模式进行迭代改进

适用场景

• 用户想检查自己的 MCP 工具架构设计是否合理
• 用户想测试 Claude 是否会针对用户意图选择正确的工具
• 用户正在调试工具混淆问题（Claude 选择了错误的工具）
• 用户想优化工具描述，提高选择准确率
• 用户已使用 build-mcp-server 完成脚手架搭建，并想验证质量

工作流概览

Phase 1: Connect → Phase 2: Static Analysis → Phase 3: Selection Testing → Phase 4: Optimize
                                                            ↑__________________________|

第 4 阶段会循环执行：应用改写 → 重新获取架构 → 重新测试 → 比较准确率。

前置条件

• Node.js >= 18——MCP Inspector CLI（npx）的必需条件
• jq——架构分析脚本的必需条件
• 正在运行的 MCP 服务——该服务必须能响应 tools/list。先使用 build-mcp-server/scripts/test-server.sh 验证连接。

---

阶段 1 — 连接并盘点

连接用户的 MCP 服务并获取工具架构。

1a：获取连接详情

询问用户如何连接其服务：

• HTTP/SSE：URL（例如：http://localhost:3000/mcp）
• stdio：启动命令（例如：node dist/server.js）

1b：获取工具架构

bash scripts/fetch-tools.sh <url-or-command> <transport> <workspace>/tools.json

此操作通过 MCP Inspector CLI 调用 tools/list 并保存架构。

1c：显示清单

显示摘要表格：

| # | Tool | Description (preview) | Params | Annotations |
|---|------|-----------------------|--------|-------------|
| 1 | search_issues | Search issues by keyword... | 3 | readOnlyHint |
| 2 | create_issue | Create a new issue... | 4 | — |

标示工具数量：1-15 个为理想，15-30 个为警告，30 个以上为过多（考虑采用搜索+执行模式）。

1d：创建工作区

在技能目录旁边或用户项目中创建 {server-name}-eval/ 工作区：

{server-name}-eval/
├── tools.json
├── evals/
│   └── evals.json
└── iteration-N/

---

阶段 2 — 静态分析

运行确定性的质量检查——无需调用 Claude。这样可以在开发过程中立即获得反馈。

2a：运行分析

bash scripts/analyze-schemas.sh <workspace>/tools.json <workspace>/iteration-N/static-analysis.json

2b：显示结果

显示每个工具的质量评分。阅读 references/quality-checklist.md 了解所检查的标准。

| Tool | Desc | Params | Schema | Annotations | Overall | Issues |
|------|------|--------|--------|-------------|---------|--------|
| search_issues | 3/3 | 3/3 | 2/3 | 2/3 | 2.5 | No negation |
| create_issue | 1/3 | 1/3 | 0/3 | 0/3 | 0.5 | 4 issues |

2c：标示相似工具对

如果分析发现工具描述之间存在较高重叠，请将它们标示为潜在混淆风险：

### Sibling Pairs (confusion risk)
| Tool A | Tool B | Overlap | Risk |
|--------|--------|---------|------|
| search_issues | list_issues | 52% | HIGH |

2d：决策点

如果存在严重问题（缺少描述、没有任何注解），建议在进入阶段 3 之前先修复。这些静态问题会干扰选择测试——先修复明显的问题，再衡量细微的问题。

如果所有工具的评分都不错，则进入阶段 3。

---

阶段 3 — 选择测试

测试 Claude 是否会针对每种用户意图选择正确的工具。这是评估的核心。

3a：生成测试意图

阅读 references/eval-patterns.md 了解意图生成模式。

针对每个工具，生成：

• 3 个应触发意图——直接、隐含和随意的表述
• 2 个不应触发意图——近似匹配和关键词重叠

针对阶段 2 标示的每对相似工具：

• 每个工具生成 1 个消歧意图——测试 Claude 是否会选择正确的相似工具

将所有意图展示给用户审核。询问是否需要添加、删除或修改任何意图。

3b：保存意图

保存到 {workspace}/evals/evals.json：

{
  "server_name": "my-server",
  "generated_from": "tools.json",
  "intents": [
    {
      "id": 1,
      "intent": "Are there any open bugs related to checkout?",
      "expected_tool": "search_issues",
      "type": "should_trigger",
      "target_tool": "search_issues",
      "notes": "Implicit intent — doesn't name the action"
    }
  ]
}

3c：运行选择测试

针对每种意图，启动一个子 Agent，并向其提供：

1. tools.json 中的完整工具架构（格式与其在 Claude 上下文中显示的格式一致）
2. 用户意图文本
3. 指示其恰好选择一个工具并提供参数；如果没有合适的工具，则拒绝选择

子 Agent 提示词：

You have access to the following MCP tools:

{tool schemas as JSON}

A user sends this message:
"{intent text}"

Which tool would you call? Respond with JSON:
{
  "selected_tool": "tool_name" or null,
  "arguments": { ... } or {},
  "reasoning": "One sentence explaining your choice"
}

If no tool fits the user's request, set selected_tool to null.
Select exactly ONE tool. Do not suggest calling multiple tools.

为提高效率，并行启动所有选择测试。

3d：评分结果

bash scripts/grade-selection.sh \
  <workspace>/iteration-N/selection \
  <workspace>/evals/evals.json \
  <workspace>/iteration-N/benchmark.json

3e：显示结果

## Selection Results — Iteration N

**Accuracy:** 82% (41/50 correct)

| Metric | Count |
|--------|-------|
| Correct | 41 |
| Wrong tool | 5 |
| False accept | 2 |
| False reject | 2 |

### Per-Tool Accuracy
| Tool | Precision | Recall |
|------|-----------|--------|
| search_issues | 0.90 | 0.85 |
| create_issue | 1.00 | 1.00 |

### Worst Confusions
| Expected | Selected Instead | Times |
|----------|-----------------|-------|
| list_issues | search_issues | 3 |
| get_user | find_user_by_email | 2 |

---

阶段 4 — 优化与迭代

分析混淆模式，并提出描述改进建议。阅读 references/optimization.md 了解改写模式。

4a：分析混淆

针对每一对混淆工具（来自 worst_confusions）：

1. 阅读两个工具当前的描述
2. 找出导致混淆的原因（缺少否定表述、范围重叠、缺少交叉引用）
3. 根据 optimization.md 中的消歧模式，起草具体的改写内容

4b：提出建议

## Suggested Improvements

### search_issues ↔ list_issues (confused 3 times)

**search_issues — Before:**
> Search issues by keyword.

**search_issues — After:**
> Search issues by keyword across title and body. Returns up to `limit` results ranked by relevance. Does NOT filter by status, assignee, or date — use list_issues for structured filtering.

**Reason:** Adding scope boundary and cross-reference to disambiguate from list_issues.

保存到 {workspace}/iteration-N/suggestions.json（格式定义见 optimization.md）。

4c：应用改写并重新测试

用户将改写应用到服务端代码后：

1. 重启服务
2. 重新运行阶段 1，重新获取 tools.json（描述可能已更改）
3. 重新运行阶段 2，进行更新后的静态分析
4. 使用相同的 evals.json，在 iteration-N+1 中重新运行阶段 3
5. 比较准确率：

## Iteration Comparison

| Metric | Iteration 1 | Iteration 2 | Delta |
|--------|------------|------------|-------|
| Accuracy | 82% | 94% | +12% |
| search↔list confusion | 3 | 0 | -3 |

4d：迭代指导

• 每次迭代只更改一对同级工具，以便明确判断改进效果
• 如果准确率陷入停滞，剩余的混淆可能需要通过架构调整解决（合并工具、重命名或重构工具接口）
• 当准确率超过 90%，或剩余混淆属于人类也难以判断的模糊边缘情况时，停止迭代

---

参考文件

到达相关阶段时再阅读这些文件，无需提前阅读：

• references/quality-checklist.md — 工具架构的可测试质量标准（阶段 2）
• references/eval-patterns.md — 如何编写工具选择测试意图（阶段 3）
• references/optimization.md — 如何根据评估结果改进描述（阶段 4）

相关技能

• build-mcp-server — 设计并搭建 MCP 服务（先运行此技能，再运行 eval-mcp 进行验证）
• build-mcp-app — 带有交互式 UI 组件的 MCP 服务