用途
mcp-qa 用于在提交代码或创建 PR 之前，对 MCP 工具变更进行端到端 QA。它强调优先使用可通过 agent 调用的路径，而不是浏览器或 inspector 工作流。
主要能力
- 质量门禁：运行
pnpm run tsc && pnpm run lint && pnpm run test，先修复所有失败。 - Stdio CLI 验证：这是验证工具行为的主要路径。Stdio 使用本地 MCP 服务器访问生产 Sentry，不依赖 Cloudflare worker、本地 /mcp 路由或 Cloudflare OAuth 配置。
- 真实 agent 客户端验证：用于验证 Claude Code、Codex，或仅在真实 agent 客户端中复现的行为。
- Cloudflare HTTP 验证：仅在变更涉及 Cloudflare、HTTP 传输、/mcp 路由、OAuth、Web UI 或托管服务器兼容性时执行。
- 源码构建 Stdio 验证：仅在需要检查构建后的本地 stdio 服务器而非开发期源码执行时使用。
使用方式
Stdio CLI
验证代码或工具变更时需先构建，因为测试客户端会启动 packages/mcp-server/dist/index.js：
pnpm -w run build
先检查认证状态：
pnpm --filter @sentry/mcp-server start auth status
若无缓存，预热设备码缓存：
pnpm --filter @sentry/mcp-server start auth login
设备码认证使用内置 stdio 公共客户端 ID，无需客户端密钥，独立于 Cloudflare OAuth 应用，令牌缓存在 ~/.sentry/mcp.json。
先证明启动与认证：
pnpm -w run cli --transport stdio --list-tools
pnpm -w run cli --transport stdio "who am I?"
再用真实的生产提示词证明变更行为，提示词需覆盖新增或修改的工具路径、使用真实组织/项目/资源输入，并要求足够细节以证明端点响应可用：
pnpm -w run cli --transport stdio \
"<prompt that exercises the changed MCP behavior against prod data>"
通过 QA 的标准：本地 CLI 输出 Connected to MCP server (stdio)，使用预期的 MCP 工具路径，并返回展示该行为的真实生产数据。对应目录型工具，应看到 search_sentry_tools 后跟 execute_sentry_tool(name: <changed_tool>)；对应直接工具，转录中应出现该工具名。仅运行 --list-tools 不算通过 QA。
对于仅目录型且有变更副作用的工具，除非准备了可丢弃资源用于测试，避免改动生产数据。可添加或运行带 MSW 覆盖的服务端级 execute_sentry_tool 分发测试，以证明目录发现、生成的 schema 暴露、约束注入和工具分发。
对于输出格式变更，还应尽可能检查原始 MCP 工具结果，而不只是 LLM 最终答案。最终答案可能附加模型特定文本，不属于工具响应。对照 docs/contributing/tool-responses.md 审查原始工具输出：应面向用户、结构化，且不含原始 API JSON、内部实现 ID、空占位符和不相关指令。
真实 agent 客户端
用于验证 Claude Code、Codex 或仅在真实 agent 客户端中复现的行为时，先构建：
pnpm -w run build
该验证检查：CLI 已安装且能看到指定的 MCP 服务器；提供方可以针对 Sentry MCP 运行连通性提示词；最终答案包含来自 whoami 的已认证邮箱。
对于 agent 客户端特定行为，将默认 harness 提示词替换为 Stdio QA 所用的同一真实生产提示词。通过 QA 同样需要变更工具的转录证据，而不仅是 whoami。
真实客户端不会为 stdio 子进程提供 TTY，因此运行 harness 前需预热缓存。它同样运行构建后的 packages/mcp-server/dist/index.js，因此需先构建以避免过期代码。
Cloudflare HTTP（仅在相关时）
仅当变更涉及 Cloudflare、HTTP 传输、/mcp 路由、OAuth、Web UI 或托管服务器兼容性时运行；普通工具处理器变更不需要。
在单独终端或后台进程启动开发服务器：
pnpm dev
验证可访问：
curl -s -o /dev/null -w "%{http_code}" http://localhost:5173/
若 pnpm dev 因本地 Cloudflare/Wrangler 未配置而失败，记录该失败并继续用 Stdio QA 验证工具行为。
pnpm -w run cli "who am I?"
pnpm -w run cli "list all available tools"
pnpm -w run cli "<same realistic prod prompt used for stdio QA>"
pnpm -w run cli --mcp-host=http://localhost:5173/mcp/<org> \
"<same realistic prod prompt used for stdio QA>"
pnpm -w run cli --mcp-host=http://localhost:5173/mcp/<org>/<project> \
"<same realistic prod prompt used for stdio QA>"
查找 Connected to MCP server (<resolved MCP URL>) 以确认 HTTP 传输，并取得与 Stdio QA 相同的变更工具转录证据。验证路由、OAuth 或资源范围行为时，使用带作用域的 /mcp/<org> 或 /mcp/<org>/<project> URL。使用 --setup repo --server sentry 测试托管服务器。
源码构建 Stdio（仅在相关时）
用于专门检查构建后的本地 stdio 服务器而非开发期源码执行：
pnpm -w run build
pnpm --filter @sentry/mcp-server start auth status
pnpm -w run cli --transport stdio "who am I?"
查找 Connected to MCP server (stdio) 以确认 stdio 传输。
适用场景
适用于 MCP 工具的端到端变更验证，包括工具行为、输出格式、目录型工具分发，以及在 Claude Code、Codex 等真实 agent 客户端中的表现。也适用于涉及 Cloudflare HTTP 传输、路由、OAuth 或托管服务器兼容性的场景。
限制
仅运行 --list-tools 不构成 QA。目录型变更工具若涉及生产数据修改，需可丢弃资源或改用 MSW 测试。Cloudflare HTTP 验证仅在相关变更时必要，且本地 Cloudflare/Wrangler 未配置时可能无法运行。运行真实 agent 客户端前需预热缓存，且需先构建以避免过期代码。