forge-test-mcp

forge-test-mcp

Foundry の forge test と forge build を実行し、AI コーディングエージェントが利用できる簡潔で構造化された結果を返す MCP サーバーです。各失敗テストについて、種類、デコードされた理由、ファズテストの反例または不変条件テストの呼び出しシーケンス、コンソールログ、簡潔にデコードされたトレースを返します。標準の 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 を実行します。サーバーは forge を --offline で実行するため、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

イメージにはサーバーと、公式の静的 Alpine ビルドである forge 1.8.6 が含まれます。ビルド時に、固定された SHA-256 ダイジェストとダウンロード内容を照合します。これらのダイジェストはリリースのプロベナンス証明から取得し、固定時に検証されています。プロジェクトを /project に、forge がコンパイラを保存するキャッシュボリュームを /cache にマウントしてください。

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

2 つ目のコマンドは、プロジェクトの 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チートコードの使用を許可します。デフォルトでは無効です。下記を参照してください。
--strict-version	テスト済みの範囲より新しいforgeのバージョンを警告する代わりに拒否します。

ツール

ツール	内容
run_tests	forge testを実行します。フィルター：match_test、match_contract、match_path。fuzz_runs、traces（デフォルトはtrue）、max_bytes（デフォルトは8192）。
explain_failure	詳細度を上げて1つのテストを再実行し、そのテストのみを返します：理由、反例、ログ、バックトレース、デコードされたトレース。テスト名は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 チートコードは任意のシェルコマンドを実行します。forge は環境変数の FOUNDRY_FFI を無視するため、foundry.toml で ffi = true が設定されている場合、サーバーは解決済みの設定をコピーして ffi = false にしたうえで forge を実行し、実行前に forge を通じてその設定が反映されたことを確認します。FFI を使う場合は、サーバーを --allow-ffi 付きで起動してください。
• ダウンロードはありません。 forge は常に --offline 付きで実行されるため、forge 自体がネットワークを検索することはありません。ただし、たとえば vm.createSelectFork や RPC エンドポイントを使うフォークテストなど、テストが独自にネットワークへアクセスする可能性はあります。
• シェルは使いません。 forge は引数リストを使って起動します。ツールの引数は検証され、単一の --flag=value 引数として渡されます。
• シークレット。 forge はプロジェクトの .env を自ら読み込むため、テストからその値を読み取って出力できます。サーバーは、環境変数および .env にある *PRIVATE_KEY*、*MNEMONIC*、*SECRET*、*TOKEN*、*API_KEY*、*RPC_URL* のような名前の変数の値と完全に一致するものを [redacted:NAME] に置き換えます（RPC URL には API キーが埋め込まれていることがよくあります）。秘密鍵などの 16 進数の値についても、0x の有無、大文字小文字、先頭のゼロの有無にかかわらず、また 10 進数表記でも検出します（vm.envUint や console.log が出力する形式です）。それ以外の形式で出力されたシークレットは検出できません。エージェントを使ってテストするプロジェクトには、資金を使える鍵を置かないでください。
• トランザクションはありません。 どのツールもブロードキャスト、デプロイ、署名、鍵の取得を行いません。

脆弱性を報告するには、SECURITY.md をご覧ください。

テストに合格しても、コントラクトの安全性が証明されるわけではありません。 作成したテストに合格したことを示すだけです。価値を保持するコントラクトには、独立した監査が必要です。

Foundry の互換性

Linux、macOS、Windows で、forge 1.8.5 および 1.8.6 に対して CI でテスト済みです。サポート対象の範囲： >=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 をご覧ください。