improving-mcp-tools

改进 MCP 工具

MCP 服务只有通过可衡量的方式才能变得更好。这是一套改进流程：评估当前 Agent 体验，修复最大的问题，再次评估，并且只发布数据证明合理的更改。这是“改进我的 MCP”循环的操作手册——每次迭代只处理一项，并记录在案，以便后续迭代（或其他 Agent）可以接着进行，而不必重复工作。

目标函数

services/mcp/evals/ 是测试框架。benchmark/tasks.yaml 是一组固定的 Agent 任务，包含 expected_tools 和 success_criteria；只有使用相同基准测试 version 的运行结果才具有可比性。

• 探测模式（确定性，无 LLM）： 从 services/mcp/ 运行 LIVE_MCP_URL=... LIVE_MCP_TOKEN=... pnpm exec tsx evals/runner/probe.ts --out score.json。报告工具缺失情况（可发现性）、探测失败，以及延迟 p50/p95。非零退出码表示发生回归。
• Agent 模式（LLM 重放 + 评判器）：评估任务成功率和工具选择准确率。用于更改描述或可发现性——探测无法检测 Agent 是否选错工具。

请在植入种子数据的本地或 devbox 堆栈上运行测试框架，绝不要在客户项目上运行。本地配置：NODE_ENV=development PORT=9876 POSTHOG_API_BASE_URL=http://localhost:8000 pnpm dev:hono，个人 API 密钥用作 LIVE_MCP_TOKEN。

一次迭代

1. 测量。 运行测试框架，建立基线。使用 MCP 分析工具（query-mcp-tool-stats、query-mcp-tool-failures、query-mcp-tool-descriptions、query-mcp-tool-sample-intents）以及信号侦察操作手册中的分析方法，获取生产环境证据（products/signals/skills/signals-scout-mcp-tool-calls/references/queries.md）：失败排行榜、重试/困难情况、延迟、未匹配任何工具的意图。
2. 选定一个问题。 按影响范围 × 严重程度排序。跳过日志中显示已尝试两次且均失败的问题。每次迭代只处理一个问题——如果一个 PR 修复了三件事，分数变化时就无法判断是哪一项带来的效果。
3. 限定范围修复。 只修改允许列表中的文件（见下文）。常见修复包括：改进工具描述，让正确的意图能找到它；收紧 Agent 总是填错的输入架构；修正注释；更新技能。
4. 验证。 重新运行受影响的基准测试子集，以及一个无回归样本。只有目标指标有所改善且其他指标均未变差时，才保留更改。放弃更改是正常结果——将其记录在日志中，然后继续。
5. 发布。 每次迭代创建一个 PR，并在正文中注明更改前后的分数（格式见 references/campaign-journal.md）。确保更改可盖章：更改行数 ≤400，只修改下方允许列表中的文件，并应用 stamphog 标签。自主程度由活动配置决定——默认是供人工审查的草稿 PR；只有操作人员明确启用了自动驾驶实验时，才启用自动合并（见防护措施）。
6. 记录日志。 结束本轮前，追加本次迭代记录。

严格护栏

这些不是建议；违反任何一条都会导致本轮活动未通过。

• 允许列表 — 活动 PR 只能修改：products/*/mcp/tools.yaml、 products/*/skills/**、services/mcp/evals/**、pnpm generate-tools / scaffold-yaml 的代码生成输出（services/mcp/src/tools/generated/** 和 services/mcp/schema/generated-tool-definitions.json），以及文档。 其他任何内容（处理程序代码、包清单、工作流、迁移、身份验证路径）→ 停止，并将发现的问题交给人工处理，以草稿 PR 或报告的形式提交。
• 对数据只读。 测试工具和所有生产环境查询都只能读取。测量期间，绝不要创建、修改或删除客户可见对象。
• 没有证据，就等于没做。 PR 必须包含基线评分、改进后评分，以及使用的确切测试工具命令。
• 基准测试完整性。 切勿在验证修复的同一个 PR 中编辑 benchmark/tasks.yaml ——同时修改考题和答案毫无证明力。基准测试变更必须单独提交 PR，并递增 version。
• 预算。 遵守操作者设定的迭代、令牌和 PR 上限（默认：有 3 个尚未合并的活动 PR 时停止）。同一问题尝试失败两次后，永久搁置。
• 终止开关。 如果活动配置、其功能标志或操作者要求停止——立即停止当前迭代，记录状态，并妥善结束。

预期故障模式

• 有助于匹配一种意图的描述变更，可能会让正确工具在另一种意图下失去流量——这就是必须采样检查是否有回退的原因。意图簇快照中的 tool_overlaps（参见 exploring-mcp-intent-clusters） 会准确列出哪些工具对在哪些意图上存在竞争：改写描述前先保存快照，之后重新计算；并将重叠工具对之间的捕获率变化视为回退信号。
• 探测延迟会随技术栈的预热状态而变化；至少运行 3 次并比较中位数，再判断延迟变化是否由修复导致。
• 工具缺失可能是功能标志门控所致，而不是目录中没有该工具——在“修复”可发现性之前，先检查 getToolsForFeatures 门控。