Verdict QA MCP Skill 技能

Verdict QA MCP（verdict-qa-mcp）

技能简介

Verdict 是一个面向 Claude Code 的 QA 智能体，它为代码库维护一个测试基线，并能够主动报告「自上次运行以来哪些内容出现了问题」——包括稳定 ID 和存在周期的 Bug 发现、每个失败测试的分类、带过期时间的 flaky test 隔离区，以及 pass | pass with risks | blocked | fail 四级质量判决结果，明确标注「哪些内容没有被测试」。

verdict-qa-mcp 是 Verdict 项目中负责对外暴露能力的 MCP Server 部分。它以只读方式读取 Verdict 智能体写入的相同状态文件，不对状态进行任何写入操作。这意味着：控制合并门禁的 orchestrator、使用 Cursor 或 Codex 的开发会话、或者在 PR 上发表评论的 CI 步骤，都可以向 Verdict 询问「测试员最后一次发现了什么」，而无需运行完整的测试流程。

该 MCP Server 的核心价值在于将 QA 记忆变成了公共 API——测试员的记忆可以被任何 MCP 兼容工具读取，但测试员的「笔」（写入权限）永远保留在智能体手中。

核心能力

• get_verdict：查询项目最后一次运行的质量判决结果，返回发布拦截项、报告路径及未测试清单
• get_findings：按状态筛选 Bug 发现列表，支持 NEW / STILL_OPEN / RESOLVED / REGRESSED，回归问题优先展示
• get_quarantine：查看 flaky test 隔离台账，每条记录包含自动计算的 expired（是否过期）标记
• get_history：解析报告索引，输出跨轮次趋势数据
• get_report：读取完整报告内容，路径受 QA 根目录保护，CI 可直接引用证据而非仅提供链接
• get_profile：获取隔离规则、风险区域、真实测试命令，以及经验教训记录
• get_trends：输出项目缺陷轨迹、当前压力指标（按严重程度和年龄分布的 open 数量、隔离区规模），并标注热点区域——即该项目缺陷实际集中在哪里
• list_projects / get_state：列出所有已建基线的项目，或获取原始状态数据

安装配置

方式一：通过 Claude Code MCP 添加（推荐）

claude mcp add verdict -- uvx --from verdict-qa-mcp verdict-mcp

方式二：pip 安装

pip install verdict-qa-mcp
# 或
uv pip install verdict-qa-mcp

安装后，系统会注册 verdict-mcp 控制台脚本，同时生成 verdict-gate（CI 发布门禁）、verdict-validate（状态文件校验）、verdict-run（运行一次测试）等辅助命令。

使用步骤

1. 在 Claude Code 项目中安装 Verdict 插件（与 MCP Server 分开安装）：

   # 在目标代码库目录下
   claude mcp add verdict -- uvx --from verdict-qa-mcp verdict-mcp

2. 首次运行建立基线：

   verdict-run

   这会在 ~/.claude/verdict/（solo 模式）或 /.qa/（团队模式）目录下生成初始 QA 状态文件。

3. 日常开发中查询质量状态： 在 Claude Code 对话中直接询问：「上次测试的结果如何？有哪些回归问题？」MCP Server 返回判决结果和发现列表。

4. CI 集成——自动化质量门禁：

   verdict-gate

   返回码含义：0 = 通过，1 = 有风险，2 = 阻塞，3 = 失败。区分「从未运行过」和「运行了但判定为不通过」两种状态。

适用场景

• 持续集成质量门禁：PR 合并前自动检查测试员是否有新发现的回归问题，阻断低质量代码进入主干
• Cursor/Copilot 会话辅助：开发者在 IDE 中启动新任务前，先查询「这个代码库上次测出了哪些问题」，避免重复引入已知的缺陷
• 跨团队 QA 知识共享：测试经理通过只读 MCP 工具查阅各项目的测试状态，无需运行完整测试套件
• Flaky Test 管理：隔离区中的 flaky test 自动过期，团队无需手动清理，长期无人认领的 flaky 记录会自动失效
• 发布决策辅助：质量判决 pass with risks 模式下，清晰列出「哪些风险已知但未修复」，帮助发布经理做出知情决策

适用人群

• 使用 Claude Code 进行日常开发的工程师
• 关注代码质量的 Tech Lead 和 QA 工程师
• 需要在 CI/CD 流水线中嵌入质量门禁的 DevOps 团队
• 维护多项目测试状态的技术管理者

工作原理

Verdict QA 的工作流分为「测试员」和「查询方」两个角色：

• 测试员角色（Claude Code 插件）：每次 verdict-run 时，在目标代码库上运行测试，生成发现（finding）列表，更新基线状态文件，并将结果写入 ~/.claude/verdict/ 或 /.qa/ 目录。
• 查询方角色（MCP Server）：verdict-qa-mcp 部署后，以只读方式暴露上述状态文件中的数据。所有 MCP 工具均为读操作，Server 本身不修改任何状态文件。

状态文件采用结构化 JSON 格式，包含：基线版本、open findings（含 ID/严重程度/年龄）、隔离区记录（flaky tests）、运行历史索引。get_trends 工具对原始数据进行聚合分析，输出缺陷集中区域和趋势。

官方链接

• PyPI 包地址：https://pypi.org/project/verdict-qa-mcp/
• GitHub 仓库（含插件安装与评测结果）：https://github.com/ArtJack/verdict
• 状态文件格式文档：https://github.com/ArtJack/verdict/blob/main/docs/state-schema.md
• 已发布的评测结果：https://github.com/ArtJack/verdict/blob/main/eval/README.md