verimcp

面向 MCP 的可信 Agent 技术栈

已列入官方 MCP Registry，名称为 io.github.rudranaresh0201/verimcp 和 io.github.rudranaresh0201/devmcp。

观看控制台 → — 浏览器中回放的一段录制会话：三次经过验证的调用、五次被识破的谎言，以及一个诚实的后端错误。

问题

默认情况下，MCP 工具调用会受到信任；而在生产环境的 Agent 工作流中，这会以两种不同的方式带来问题：

1. 声明未经验证。 当服务声称提交已成功、文件已写入或 CI 检查已通过时，Host 无从得知这是否属实——isError: false 只表示工具没有崩溃，并不代表它完成了声称的操作。通过 MCP 接入 git、CI 或基础设施的 Agent，只要收到一次信心十足但错误的工具响应，就可能据此采取错误行动。
2. 重试并不安全。 当 Host 在收到模糊响应（超时、连接中断）后重新发送 tools/call 时，MCP 没有任何机制阻止后端再次执行——再次提交、再次运行 CI、再次扣费。该协议没有“我是不是已经做过这件事？”的概念。

解决方案

verimcp 是一个透明代理，位于 MCP Host 与后端服务之间，并原样转发每条消息，仅在每次调用前后执行两项独立检查：

• 转发前 （预检查） — 如果本会话中已发送过完全相同的调用，并且已独立验证为成功，则使用已确认的结果响应重试，而不再访问后端。参见 --idempotent-replay，详见下文的证明，而非空口声明。
• 后端响应后 （后检查） — 对于已知如何检查的调用，独立重新推导真实结果（重新读取文件、重新检查 git 日志、重新运行 CI 步骤中安全的部分），并将结果与后端的声明进行比较。在 Host 将其视为成功之前，谎报的结果会被改写为真实错误。

devmcp 是经过验证的后端——一个真实的 git/CI MCP 服务，专门按完整协议面构建（工具、资源、提示词、roots、采样），因为代理是否有说服力，取决于它能展示自己识破了什么。

Host  <--stdio-->  verimcp (pre-check: dedupe retries + post-check: verify claims)  <--stdio-->  devmcp (git/CI server)

两者均可独立安装，彼此之间没有导入依赖——verimcp 可用于任何 MCP 后端之前（也已通过官方 mcp-server-git 验证，不仅限于 devmcp），而 devmcp 也可直接与任何 Host 配合使用，无需经过代理。

证据，而非空口声称

两个可运行的基准测试，使用真实的子进程管道，不用模拟对象——下面的数字是它们实际输出的结果，包括差距：

pip install verimcp devmcp-server
python scripts/benchmark_claim_acceptance.py    # does verimcp catch a lying backend?
python scripts/benchmark_retry_duplication.py   # does --idempotent-replay stop a retry from duplicating a side effect?

声明接受率——没有验证层的真实 MCP Host 按设计会接受 100% 的伪造结果；这不是基准测试造成的假象，而是协议本身确实存在的漏洞：

RAW claim-acceptance rate:     14/14  (100%)
verimcp claim-catch rate:      11/14  (79%)

79% 而非 100% 是刻意为之，脚本自身的输出也明确说明了原因：14 个场景中有 3 个利用了特定验证器已记录且合理的局限性（例如，哈希存在性检查无法判断是本次调用创建了该哈希，还是它早已存在）——这些局限都明确列出，而非加以隐瞒，因为工具声称自己在自有基准测试中取得满分，才是真正的危险信号。

重试重复执行——同样的思路应用于 --idempotent-replay，针对 5 种真实的非幂等副作用（计数器递增、发送通知、发票数量增加、写入审计记录、两步流水线）：

RAW duplicate-action rate:      5/5  (100%)
verimcp duplicate-action rate:  0/5  (0%)

scripts/demo.py 是同一验证过程的精简叙述版——捕获一个伪造的提交哈希，确认一次真实写入并原样传递。tests/test_adversarial_corpus.py 和 tests/test_proxy_integration.py 会在每次提交时于 CI 中通过真实的代理管道运行同样的验证，而不只是按需运行。

技术摘要

• 正确性验证器——每个具有可独立检查后置条件的工具／资源各对应一个：write_file（比较磁盘哈希）、git_commit／git_branch（根据实际 Git 状态重新推导）、run_ci_pipeline（自洽性检查＋重新执行标记为可安全重运行的步骤），以及资源读取（repo://status、repo://log、repo://file/{path}）。新验证器采用插件系统（importlib.metadata.entry_points，与 pytest／Black 使用的机制相同）——参见 docs/writing-a-verifier.md。
• GitHub——GitHub 官方 MCP 服务中的 create_pull_request、issue_write（创建）和 create_branch，都会通过 GitHub 自身的 REST API 进行检查：PR／议题／分支必须存在，并且标题必须与请求的一致，这也能发现服务将真实的旧 PR 当作新 PR 返回的情况。只有在确认仓库可见后，404 才会被计为不存在；因此，没有令牌的私有仓库会跳过检查，而不会被错误标记。
• 回执（默认在 wrap 下启用 --receipts）——每项检查都会记录实际观察到的内容（PR 的真实标题和链接、提交的真实消息和作者、文件的真实哈希）、检查位置和时间，无论检查结果是否成立。回执始终写入审计日志并显示在控制台；启用该标记后，还会附加到工具回复中。
• 远程服务（--backend-url）——通过 Streamable HTTP 代理服务（MCP 规范 2025-06-18：JSON 和 SSE 回复、会话 ID、协议版本标头），并支持 --header 'Authorization: Bearer ${TOKEN}'／--header-from-env，因此密钥无需存放在配置文件或命令行中。除测试套件外，也使用托管服务（DeepWiki）进行了验证。
• 来自 Host 的根目录——verimcp 会向支持 roots 的 Host（Claude Code、Cursor）请求其工作区，因此即使服务本身从不请求，文件系统和 Git 验证器也能在其前面工作，例如 mcp-server-git。
• 重试前验证（--idempotent-replay）——只有在上述检查独立验证前一次完全相同的调用成功后，重试的 tools/call 才会从缓存中返回结果；键匹配但之前没有经过验证的成功结果时，会视为缓存未命中，而不是错误地去重。此功能改编自 arXiv:2608.02645，并移至代理层，因此适用于 verimcp 代理的任意 Host／后端组合，而不只是某个 Agent 框架自带的重试包装器。
• 策略门控——在调用到达后端之前评估允许／拒绝／要求审批规则，适用于无法客观判断真伪的调用（采样速率限制、通过 YAML 设置任意工具名称／参数策略、通过真实 MCP elicitation/create 进行人在环审批）。
• 审计＋回放——verimcp 处理的每次调用都会被记录，并作为真实的 verimcp://audit MCP 资源提供；verimcp replay 会依据新策略重新运行已记录的流量，以回测“是否会产生任何变化”。
• 可观测性——每次调用都会生成符合 GenAI 语义约定的 OpenTelemetry span／指标，并可导出到任意 OTLP 收集器。
• 通过真实客户端验证，而不只依赖我们自己的测试——官方 MCP Inspector 和 VS Code 原生 MCP 支持（Copilot Chat）各自发现了一个我们自己的测试套件从未触发的真实缺陷；现已修复，并添加了回归测试。

更深入的设计考量（例如为何原则上不为提示词／roots 设置验证器、为何策略与验证是独立概念等）见 docs/adr/；对于想深入了解的人来说，上述摘要已涵盖使用或评估本项目所需的全部信息。

入门

最快方式：保护已有的 MCP 服务（0.4.0，尚未发布到 PyPI——在此之前请从 GitHub 安装）：

pip install "verimcp[dashboard] @ git+https://github.com/rudranaresh0201/mcp"
verimcp wrap                 # puts verimcp in front of every server in Claude Code, Claude Desktop and Cursor
verimcp-dashboard --audit-log ~/.verimcp/audit.jsonl   # watch every verdict live at http://127.0.0.1:8787

重启 MCP 应用，然后继续用日常语言使用它。wrap 会先备份每个配置文件，跳过无法安全接入的服务（通过应用自身 OAuth 流程登录的服务、旧版 SSE 服务），绝不会将请求头令牌放入命令行参数中，而 verimcp unwrap 会原样恢复原始配置。--dry-run 会显示计划，但不会写入任何内容。

以下是通过官方 mcp-server-git 和一个故意撒谎的文件服务运行后的实际效果：

[verimcp receipt] CONTRADICTED · FilesystemVerifier
todo.txt does not exist on disk

[verimcp receipt] VERIFIED · GitServerCommitVerifier
commit b6fcbbd50b11 exists: 'Add hello file' by Rudra

作为用户——直接从 PyPI 安装：

pip install verimcp devmcp-server
verimcp -- devmcp --repo-path ./some-repo

名称说明：PyPI 上的发行包名是 devmcp-server（由于 PyPI 的拼写相似度检查将 devmcp 与一个无关的现有包判定为易混淆名称，devmcp 无法使用），但 Python 导入名和 CLI 命令仍然都是 devmcp——如果你正在阅读 devmcp 自身的源码，上述内容不会有任何变化。

与 Claude Desktop、Claude Code 或 Cursor 搭配使用——执行 pip install 后，按常规方式将 devmcp 添加为 MCP 服务，只需将其 command 指向 verimcp，而不是直接指向 devmcp：

{
  "mcpServers": {
    "devmcp": {
      "command": "verimcp",
      "args": ["--root", "/path/to/your/repo", "--", "devmcp", "--repo-path", "/path/to/your/repo"]
    }
  }
}

• Claude Desktop：将以下内容粘贴到 claude_desktop_config.json 中（macOS： ~/Library/Application Support/Claude/claude_desktop_config.json，Windows： %APPDATA%\Claude\claude_desktop_config.json）。
• Claude Code：claude mcp add devmcp -- verimcp --root /path/to/your/repo -- devmcp --repo-path /path/to/your/repo
• Cursor：在 Cursor 的 MCP 设置中使用相同的 JSON 格式。

从此以后，你的助手会像使用普通工具一样使用 write_file、git_commit、git_branch、 run_ci_pipeline、sqlite_* 和 docker_*——无需更改提示词——但在告知助手操作成功之前，工具给出的每项声明都会经过独立复核。

在 Docker 中使用——无需本地安装 Python/git：

docker build -t verimcp-devmcp .
docker run -i -v /path/to/your/repo:/repo verimcp-devmcp

作为贡献者——从此仓库进行可编辑安装：

pip install -e ".[dev]"
pip install -e "./devmcp[dev]"

pytest tests devmcp/tests   # 138 tests, real subprocess + real git repo, nothing mocked
ruff check src tests devmcp/src devmcp/tests

python scripts/inspector_smoke_test.py   # verify against the real MCP Inspector client (needs node/npx)

亲自体验可观测性

# spans/metrics print to stderr (verimcp's stdout is the live MCP protocol channel)
verimcp --otel-exporter console -- devmcp --repo-path ./some-repo

# or point a real collector, Jaeger, or Grafana Agent at it
pip install "verimcp[otel]"
verimcp --otel-exporter otlp --otel-endpoint localhost:4317 -- devmcp --repo-path ./some-repo

完全省略 --otel-exporter 表示不会产生任何遥测开销——这是默认设置，与这里其他所有选择启用的标志相同。

观看它识破谎言

控制台会读取 verimcp 已写入的审计日志，并将其流式传输到浏览器——包括判定结果、工具、参数，以及每项判定所依据的证据。

verimcp-console.onrender.com 会重放一段录制的会话。这是一段录制内容，不是实时 Agent，界面也会明确说明这一点：它提供的日志由 scripts/demo_audit_log.py 生成，该脚本驱动真实代理，连接真实的 devmcp 服务和对抗性测试样例，因此屏幕上的每个事件都来自真实运行所使用的代码路径。虚构事件的仪表盘截图，恰恰就是本项目旨在揭穿的那种毫无依据的声明。（免费实例——闲置一段时间后，首次加载需要约 30 秒唤醒。）

查看你自己的会话：

pip install "verimcp[dashboard]"
verimcp --audit-log ./audit.jsonl -- devmcp --repo-path ./some-repo   # terminal 1
verimcp-dashboard --audit-log ./audit.jsonl                           # terminal 2

控制台从不直接与代理通信。verimcp 通过 stdio 与唯一一个 Host 使用 MCP 通信；在该管道上增加第二个读取器会破坏会话，因此审计日志是受支持的带外访问方式（ADR 0004）——读取文件不会干扰它所观察的内容。对于一个核心主张就是不进行干扰的工具而言，这一点至关重要。

亲自体验重试前验证

verimcp --idempotent-replay -- devmcp --repo-path ./some-repo

连续两次发送相同的 tools/call（工具相同、参数相同、请求 ID 不同——这正是客户端超时后重新发送时在线路上的表现）。第一次调用会实际运行；第二次会直接返回已确认的结果，不再触及后端。省略该标志即可使用未更改的默认设置：每次重试都会重新执行，与此功能加入前相同。

参与贡献

参见 CONTRIBUTING.md，了解开发环境设置、如何添加验证器、本项目的 ADR 规范以及提交/PR 约定。有关发布历史，请参见 CHANGELOG.md。

许可证

MIT——详见 LICENSE。