verdict-mcp

Name: verdict-mcp
Author: Dgotlieb

本地服务

github.com/Dgotlieb开发工具09 周前更新

代码仓库

关于 verdict-mcp

verdict-mcp 是面向编码 Agent 的 MCP 服务，可在隔离容器中运行 Python 检查并返回精简的类型化结果。失败指纹和历史记录有助于区分新回归与长期存在的问题。

主要功能

01选择受工作区更改影响的测试
02在隔离容器中运行检查
03返回类型化判定和失败指纹
04按需获取完整回溯
05记录失败的首次和最近出现时间

适用场景

01验证更改而不运行整个测试套件
02判断测试失败是否早于当前更改
03以统一结果运行 ruff 和 mypy

MCP 相关

该 MCP 服务提供按影响范围验证、按需解释失败、查询指纹历史以及运行 lint 或类型检查的工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "dgotlieb-verdict": {
      "command": "uvx",
      "args": [
        "verdict-mcp"
      ],
      "env": {
        "VERDICT_PROJECT": "<VERDICT_PROJECT>"
      }
    }
  }
}

启动命令uvx verdict-mcp

需要配置的环境变量

VERDICT_PROJECTPath to the project to verify (defaults to cwd)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiverdict-mcp0.1.0a4stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
base	any	否	用于比较差异的 git 引用（默认值：HEAD，即未提交的变更）。
scope	any	否	基于影响范围选择时为 None（默认值）；完整测试套件使用 'all'；运行单个文件时使用类似 'tests/test_api.py' 的路径。

详细介绍

verdict

https://github.com/user-attachments/assets/62923912-98aa-4246-8bc8-4adf55ae3ff8

为编码 Agent 提供结构化、沙箱化的验证反馈。

一个 MCP 服务，用于替代 Agent 调用 pytest shell 命令的做法，提供专为 Agent 内部循环打造的方案：基于影响范围选择测试，在隔离环境中运行，并返回精简的类型化判定结果，而非 40,000 个 token 的原始运行器输出；同时提供失败指纹，告知 Agent 某个失败是它引入的回归，还是原本就已存在的问题。

raw pytest dump:  ~40,000 tokens, unstructured, run un-sandboxed on your machine
verdict:              ~400 tokens, typed JSON, run in a rootless container, with memory

为什么需要

在 Agent 编码过程中，调用频率最高的工具是验证，但验证的结构化程度却最低。只改动一个模块，Agent 却重新运行整个测试套件；解析带 ANSI 颜色代码的回溯信息，耗费上下文；直接在你的机器上运行任意代码；还经常把原有故障误诊为自己引入的回归（然后去“修复”原本没坏的代码）。verdict 一举解决这四个问题。

工具

工具	功能
`verify(scope?, base?)`	通过静态导入图（使用 grimp）选择受工作树差异影响的测试；通过 podman/docker 运行，工作树以只读方式挂载；返回带指纹和 `preexisting` 标记的类型化失败结果
`explain_failure(check_id)`	按需查看单个失败的完整回溯信息——摘要中不会包含大批量信息
`history(fingerprint)`	首次发现时间 / 最近发现时间 / 出现次数——判断是回归还是长期存在的故障
`run_checks(["ruff","mypy"])`	运行 lint 和类型检查，并将结果规范化为相同的判定结果结构

每个失败都有一个指纹：对规范化后的失败特征进行稳定哈希（地址、临时路径、ID、耗时等易变 token 会被合并）。同一种逻辑失败，在不同运行和重构中都会得到相同指纹。指纹赋予 verdict 记忆能力。

快速开始

无需安装——首次使用时，uvx 会自动获取它。（也可使用 uv tool install verdict-mcp / pip install verdict-mcp，永久安装 verdict-mcp 命令。）

Claude Code——在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "verdict": {
      "command": "uvx",
      "args": ["verdict-mcp"],
      "env": { "VERDICT_PROJECT": "." }
    }
  }
}

Cursor——在 .cursor/mcp.json 中使用相同格式。

可选：在仓库根目录创建 verdict.toml：

[project]
packages = ["your_package"]          # for impact selection (auto-guessed if omitted)

[runner]
image = "ghcr.io/you/yourproj-test"  # prebuilt env with your deps
setup_cmd = "pip install -e .[test]" # or install on the fly (runs with network; tests don't)
# prefer = "local"                   # escape hatch if you have no container runtime

[limits]
max_failures = 10

不使用 Agent，直接试用：

cd examples/demo_project
VERDICT_PROJECT=. verdict-mcp   # then connect any MCP client, or use the MCP inspector

沙箱安全态势（v0.1）

检查会在临时容器中运行（优先使用 podman，无法使用时回退到 docker）：工作树以只读方式挂载到 /src，再复制到容器内可写的 /work 目录；运行检查时使用 --network=none。测试运行不会修改你的主机环境。如果配置了 setup_cmd，该步骤会在检查前联网运行；如需更严格的安全态势，建议使用预构建镜像。没有容器运行时 → 显式设置 prefer = "local"，将检查回退到工作树的临时副本上运行（仍不会直接在原位置运行）。完整威胁模型和已知限制请参阅 SECURITY.md。

**故障排除：**如果判定结果提示 container engine 'podman' could not start the check，请手动运行建议的 podman pull <image>——容器引擎本身的错误信息就是答案。在 macOS 上有一个已知陷阱：~/.docker/config.json 中的 "credsStore": "gcloud" 会导致 podman 对每个镜像仓库（包括 docker.io）都调用 gcloud 凭据助手；如果 gcloud 登录已过期，所有拉取操作都会失败。可运行 gcloud auth login 修复，或删除该配置行。

诚实说明局限

影响范围选择基于静态导入图，设计上只是近似结果。动态导入、按名称解析的 fixture，以及数据驱动测试可能会遗漏；始终可以使用 verify(scope="all")，如果发生回退，verdict 会在 selection_note 中说明。
目前仅支持 Python/pytest，以及 ruff/mypy。适配器接口精简且有文档说明；vitest 和 go test -json 适配器是最受期待的贡献（CONTRIBUTING.md）。
Flake 检测和基于覆盖率映射的选择将在 v0.2 中推出（路线图）。

路线图

v0.2： 基于覆盖率的影响范围映射（精准选择）、通过指纹交替进行 Flake 检测、支持 devcontainer.json、以（树哈希、检查项、镜像摘要）为键的结果缓存。后续： vitest/jest、go test、cargo test 适配器；每个仓库的 verdict 守护进程模式。