forge-test-mcp

forge-test-mcp

一个 MCP 服务，可运行 Foundry 的 forge test 和 forge build，并返回 AI 编码 Agent 可据此采取行动的精简结构化结果：对于每个失败的测试，提供测试类型、解码后的原因、模糊测试反例或不变量调用序列、控制台日志和简短的解码跟踪。它通过标准 MCP over stdio 通信，适用于任何 MCP 客户端（Claude Code、 Codex、Cursor、Claude Desktop、Windsurf，等等）。目前已使用 MCP 测试客户端进行测试，尚未在这些客户端中逐一验证。

当 forge 未运行测试时（例如发生编译错误、没有匹配的测试、超时、缺少或不受支持的 forge 等），工具会将其报告为错误。对于未运行的测试，它绝不会报告“0 个失败”。

状态： 0.1.0，首个版本。请参阅 CHANGELOG.md，了解此版本包含的内容以及尚未验证的部分。

使用前须知

• 运行测试会执行代码。 forge test 会以你的用户权限执行项目中的 Solidity 代码。仅在你愿意亲自在终端中测试的项目上使用此服务。
• FFI 默认关闭，除非你使用 --allow-ffi 启动服务，即使 foundry.toml 中启用了它也是如此。forge 会使用 --offline 运行，但测试本身仍可能访问网络，例如通过分叉作弊码。
• 不会发送交易。 任何工具都不会发送交易、部署、签名或获取密钥。
• 测试通过并不能证明合约安全。

详情请参阅安全与信任。

要求

• Node.js 22 或更高版本。
• Foundry，其中的 forge 版本必须是 1.8.5 或更高的 1.8.x 版本。需要自行安装；此服务不会安装或更新任何内容。更新的版本也能运行，但会标记为未经测试。
• 项目使用的编译器版本需提前安装一次：先在终端中运行 forge build。服务使用 --offline 运行 forge，因此无法自行下载 solc。

配置 MCP 客户端

在你的 Foundry 项目中启动服务（即包含 foundry.toml 的目录或其子目录）。大多数客户端都接受以下 mcpServers 配置：

{
  "mcpServers": {
    "forge-test": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

请像上面一样固定到确切版本。各客户端的快捷配置方法摘自各厂商文档（于 2026-10-23 检查，尚未通过逐一运行各客户端进行验证）：

• Claude Code： 将上面的 JSON 放入项目根目录中的 .mcp.json。在交互式会话中，Claude Code 首次会要求你批准项目服务。

• Cursor： 将其放入 .cursor/mcp.json，并在服务条目中添加 "type": "stdio"。

• Codex： 放入 .codex/config.toml（仅对受信任的项目加载）或 ~/.codex/config.toml：

  [mcp_servers.forge-test]
  command = "npx"
  args = ["-y", "[email protected]"]
  

Docker

该镜像包含服务和 forge 1.8.6，即官方 Alpine 静态构建版本。构建过程会使用固定的 SHA-256 摘要校验下载内容；这些摘要取自该版本的来源证明 attestations，并在固定时完成验证。将项目挂载到 /project，并将缓存卷挂载到 /cache，forge 会在其中存放编译器：

docker build -t forge-test-mcp .
docker run --rm -v "$PWD":/project -v forge-test-mcp-cache:/cache --entrypoint forge forge-test-mcp build

第二条命令会联网安装一次项目所需的 solc。然后，将客户端配置为使用 docker 运行 ["run", "-i", "--rm", "-v", "<project>:/project", "-v", "forge-test-mcp-cache:/cache", "forge-test-mcp"]。forge 会将 out/ 和 cache/ 写入项目，因此在 Linux 上，请在两条命令中都添加 --user "$(id -u):$(id -g)"。

选项

选项放在 args 中的包名后面。只有用户可以设置这些选项；任何工具参数都无法设置。

选项	含义
--root <dir>	项目目录（默认值：客户端启动服务的位置）。
--forge <path>	forge 可执行文件（默认值：PATH 中的 forge）。
--timeout <seconds>	达到此时长后停止一次 forge 运行（默认值为 300）。
--allow-ffi	当 foundry.toml 启用 FFI 时，允许测试使用 FFI cheatcode。默认关闭；详见下文。
--strict-version	遇到高于已测试范围的 forge 版本时拒绝运行，而不是发出标记。

工具

工具	功能
run_tests	运行 forge test。筛选项：match_test、match_contract、match_path；fuzz_runs；traces（默认值为 true）；max_bytes（默认值为 8192）。
explain_failure	以高详细度重新运行一个测试，并仅返回该测试的信息：原因、反例、日志、回溯和解码后的跟踪信息。传入 run_tests 输出的测试名称，例如 "BankTest.test_transfer()"。
build	运行 forge build，并返回包含文件、行号、列号和代码的编译器错误与警告。force: true 会重新编译所有内容。

这些工具都不会发送交易、部署、签名或接受密钥。

run_tests 失败时的结果如下：

{
  "status": "failed",
  "forge": "1.8.6",
  "summary": { "suites": 1, "passed": 1, "failed": 1, "skipped": 0 },
  "ffi": "disabled",
  "fuzzRuns": { "configured": 256, "used": 256 },
  "notRun": [],
  "failures": [
    {
      "test": "SupplyInvariantTest.invariant_supplyMatches()",
      "file": "test/Supply.t.sol",
      "kind": "invariant",
      "reason": "supply mismatch: 6683 != 6355",
      "sequence": {
        "calls": [
          { "call": "Handler.mint(uint256)", "args": "6683", "sender": "0x…022f" },
          { "call": "Handler.burnFrom(uint256)", "args": "328", "sender": "0x…054e" }
        ],
        "shrunkFrom": 4
      },
      "trace": [
        "[21670] SupplyInvariantTest::invariant_supplyMatches()",
        "  ├─ [0] VM::assertEq(6683, 6355, \"supply mismatch\") [staticcall]",
        "  │   └─ ← [Revert] supply mismatch: 6683 != 6355",
        "  └─ ← [Revert] supply mismatch: 6683 != 6355"
      ],
      "traceLinesOmitted": 16
    }
  ],
  "truncated": null
}

响应不会超出大小上限。内容超出上限时，会优先省略跟踪信息和日志，其次省略完整的失败信息；truncated 会准确说明省略了多少项。

测试未运行时

结果是一个 MCP 错误（isError: true），包含代码、消息和提示：

代码	原因
COMPILE_FAILED	项目无法编译（其中包含最先出现的编译器错误）。
NO_TESTS_RAN	没有测试匹配筛选条件，或所有匹配的测试均已跳过。
NOT_A_FOUNDRY_PROJECT	此处或仓库中的上级目录都没有 foundry.toml。
FORGE_NOT_FOUND、UNSUPPORTED_FORGE_VERSION	找不到 forge，或其版本低于 1.8.5。
SOLC_MISSING	在终端中运行一次 forge build，以便 forge 安装编译器。
TIMEOUT	运行时间超过了 --timeout；forge 会在运行完成前不报告任何内容。
CONFIG_ERROR、INVALID_ARGUMENTS、FORGE_CRASHED、FORGE_FAILED、UNPARSEABLE_OUTPUT、INCONSISTENT_RESULT、OUTPUT_TOO_LARGE、FFI_OVERRIDE_FAILED	forge 无法生成可信的报告；原因见消息和 stderr。

安全与信任

运行测试就会执行代码。 forge test 会以当前用户的权限执行项目的 Solidity 代码和作弊码，就像在终端中运行一样。仅在你愿意亲自在终端中测试的项目上使用此服务。它无法让不可信的代码库变得安全。

此服务采取以下措施来降低风险：

• 默认关闭 FFI，除非你主动启用。 FFI 作弊码会运行任意 shell 命令。forge 会忽略环境中的 FOUNDRY_FFI，因此当 foundry.toml 设置 ffi = true 时，此服务会使用一份已解析配置的副本运行 forge，并将其中的 ffi 设为 false，还会通过 forge 检查该设置是否生效，然后才运行任何内容。如果你想使用 FFI，请使用 --allow-ffi 启动服务。
• 不下载内容。 forge 始终通过 --offline 运行，因此 forge 本身不会进行网络查询。测试仍可自行访问网络，例如通过 vm.createSelectFork 和 RPC 端点运行分叉测试。
• 不使用 shell。 forge 会通过参数列表启动。工具参数会经过验证，并作为单个 --flag=value 参数传入。
• 机密信息。 forge 会自行加载项目的 .env，因此测试可以读取并打印其中的值。此服务会将其环境变量和 .env 中名称类似 *PRIVATE_KEY*、*MNEMONIC*、*SECRET*、*TOKEN*、*API_KEY* 和 *RPC_URL* 的变量的精确值（RPC URL 通常包含 API 密钥）替换为 [redacted:NAME]。十六进制值（例如私钥）即使没有 0x 前缀、字母大小写不同、没有前导零，或以十进制表示（如 vm.envUint 和 console.log 打印的形式），也会被捕获。以其他形式打印的机密信息则无法捕获。请勿将可用于转账的密钥放入你要用 Agent 测试的项目中。
• 不进行交易。 任何工具都不会广播交易、部署、签名或使用密钥。

如需报告漏洞，请参阅 SECURITY.md。

测试通过并不能证明合约安全。 这只能说明你编写的测试通过了。持有资产的合约需要接受独立审计。

Foundry 兼容性

在 Linux、macOS 和 Windows 上，通过 CI 使用 forge 1.8.5 和 1.8.6 进行测试。支持范围：>=1.8.5 <1.9.0。不支持更早的版本。更新的版本会附带 forgeUntested 说明运行（或在使用 --strict-version 时被拒绝）。

开发

npm test 会运行单元测试。设置 FORGE_BIN=/path/to/forge 后，还会使用真实的 forge 运行集成测试。npm run lint 会检查代码风格。代码和测试中的需求 ID（FR-、NFR-、D-）指的是项目的内部规范。

许可证

MIT © Vitaliy Chernov。依赖项的许可证请参阅 NOTICE。