verify-local-mcp

验证本地 MCP

分为两个层次，按顺序进行。协议层验证服务和提供方的行为；使用者层验证一个从未见过代码的 Agent 能否顺利使用这些工具。它们能发现不同的问题——协议测试发现了 DataForSEO 的异常情况（缩放级别相关的 SERP 为空），使用者探测发现了易用性问题（9KB 的提供方行数据超出客户端的令牌预算，小数输入被上游拒绝并返回原始提供方错误）。两者都要做。

1. 启动

• .env.local 需要设置 AUTH_MODE=local_noauth 和 DATAFORSEO_API_KEY（login:password 的 base64 编码）。绝不要打印密钥。
• 在后台启动 pnpm dev:agents。服务 URL 会带分支前缀：http://<branch-suffix>.open-seo.localhost:1355（启动时会打印确切 URL；日志会通过 tee 写入 .logs/dev-server.log）。
• 使用 local_noauth 时，/mcp 不需要令牌。Vite 会热重载服务端代码，因此修改后可直接重新调用，无需重启。
• 更改工具的输入或输出架构后，请刷新客户端的工具发现（tools/list），或重新连接 MCP 客户端，然后再调用。客户端可能会缓存上一次工具列表中的验证器，并在提供方调用已经产生费用后拒绝有效结果。

2. 协议冒烟测试（成本低、结果确定）

直接对 /mcp 发送原始 JSON-RPC——这一层用于断言确切的数据结构并测试边缘情况（恢复 taskId、空结果、无效输入）：

curl -sS http://<url>/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# tools/call: {"method":"tools/call","params":{"name":"<tool>","arguments":{...}}}

• 初始化：先调用 list_projects；如果没有项目，再调用 create_project——大多数工具都需要 projectId。
• 对每个已更改的工具，测试正常路径以及至少一种边缘情况：空结果（冷门查询）、无效标识符；对于排队工具，还要测试完整生命周期，包括使用返回的 taskId 恢复任务。
• 这些都是真实的 DataForSEO 调用，会产生费用（local_noauth 下计量本身会被短路——计费需要通过单元测试验证，而不是在这里测试）。深度保持在 10–20。

3. 使用者探测（易用性测试）

启动一个无头 Claude 子进程，并将其连接为真正的 MCP 客户端。编写配置：

{
  "mcpServers": {
    "openseo-local": { "type": "http", "url": "http://<url>/mcp" }
  }
}

然后运行一个自然语言任务——绝不要提及工具名称；模型能否仅凭描述找到工具，就是测试内容：

claude -p "<natural task a customer would ask>. Keep spend minimal: depths 10-20, one 3x3 grid max, ~10 paid calls.
Deliver two sections: 1. FINDINGS — the task result. 2. MCP FEEDBACK — critique the MCP as a first-time consumer:
were descriptions enough to pick tools without trial and error? confusing schemas, surprising output shapes or sizes,
unclear errors, credit-cost surprises? Did async/taskId flows behave as described? List anything that made you hesitate or retry." \
  --mcp-config mcp-local.json --strict-mcp-config \
  --allowedTools "mcp__openseo-local,mcp__openseo-local__*" \
  --model sonnet --max-turns 30

使用 --model sonnet 作为典型客户端的代表——如果 sonnet 在没有预先了解的情况下也能顺利使用，能力较弱的客户端很可能也可以。阅读 FINDINGS，检查正确性（是否获取了真实且合理的数据？）；再根据下文的评分标准阅读 MCP FEEDBACK。

4. 易用性评分标准——应对哪些反馈采取行动

• 工具选择：探测应一次就选对工具。重试或绕道使用错误工具，说明描述需要更明确地写出“何时使用／何时不使用”。
• 架构：提供方会静默强制执行的每项约束，都必须写在字段的 .describe() 中（单位、必须为整数的要求、默认值、哪些内容会被忽略）。如果探测时猜测输入后又重试，应在服务端编码规则（强制转换／取整），或加以说明；优先选择强制转换。
• 输出大小：每行大致控制在几 KB。包含 popular_times／属性树／照片 URL 的提供方行数据，应裁剪到工具任务所需的字段；完整数据结构可指向单实体工具。
• 错误：错误必须具有可操作性，不能只给出原始上游字段名而不提示修复方法。已产生费用的步骤失败后，错误消息必须保留恢复凭据（例如 taskId）。
• 异步说明：描述必须符合典型延迟（“通常会在本次调用期间完成”）；探测实际驱动时，恢复路径必须确实可用，而不只是通过 curl 可用。
• 费用说明准确性：每条描述中的费用说明都必须符合实际情况，包括缓存命中和恢复路径。

5. 迭代并清理

修复问题 → 热重载自动应用修改 → 通过 curl 重新验证改动过的行为（成本低）→ 每轮迭代完整重跑一次使用者探测（它会重新测试工具选择和流程，而不只是验证修复）。完成后：停止后台开发服务器任务，运行仓库测试和／或 ci:check，并将确实存在的提供方异常情况补充到代码注释或测试中，避免下一个 Agent 重新发现。