verdict-mcp

verdict

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

コーディングエージェント向けの、構造化されたサンドボックス内検証フィードバックです。

エージェントの pytest のシェル呼び出しを、エージェントの内部ループ向けに構築された仕組みに置き換えるMCPサーバーです。影響を受けるテストを選択し、分離された環境で実行して、生のランナー出力を40,000トークン分返す代わりに、コンパクトで型付きの判定結果を返します。さらに、失敗がエージェント自身の回帰なのか、以前から存在する問題なのかを知らせる失敗フィンガープリントも提供します。

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

その理由

エージェントによるコーディングで最も頻繁に呼び出されるツールは検証ですが、最も構造化されていないものでもあります。エージェントは1つのモジュールを変更しただけでもテストスイート全体を再実行し、ANSIコード付きのトレースバックの解析にコンテキストを消費し、任意のコードをマシン上で直接実行し、既存の不具合を自分の回帰と誤診することも頻繁にあります（その結果、壊れていなかったコードを「修正」します）。verdictはこの4つすべてを解決します。

ツール

ツール	機能
verify(scope?, base?)	作業ツリーの差分によって影響を受けるテストを選択し（grimpによる静的インポートグラフ）、作業ツリーを読み取り専用でマウントしたpodman/docker上で実行します。フィンガープリントとpreexistingフラグを含む、型付きの失敗結果を返します
explain_failure(check_id)	必要に応じて1件の失敗の完全なトレースバックを返します。大量の情報が要約に含まれることはありません
history(fingerprint)	初回確認時／最終確認時／確認回数を返し、回帰か長期にわたる不具合かを判別します
run_checks(["ruff","mypy"])	リントと型チェックを実行し、同じ判定スキーマに正規化します

各失敗にはフィンガープリントが付与されます。これは、正規化された失敗シグネチャの安定したハッシュです（アドレス、一時パス、ID、所要時間などの変動するトークンはまとめられます）。論理的に同じ失敗であれば、実行やリファクタリングを経ても同じフィンガープリントになります。verdictのメモリを実現するのが、このフィンガープリントです。

クイックスタート

インストール手順は不要です。初回使用時にuvxが取得します。（または、永続的に使えるverdict-mcpコマンドを使う場合は、uv tool install verdict-mcp / pip install 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

エージェントを使わずに試すには：

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で知られている落とし穴の1つは、~/.docker/config.jsonに"credsStore": "gcloud"の行があると、podmanがdocker.ioを含むすべてのレジストリに対してgcloud認証情報ヘルパーを呼び出すことです。gcloudへのログイン期限が切れると、すべてのイメージ取得が失敗します。gcloud auth loginを実行するか、その行を削除して解決してください。

正直な制限事項

• 影響範囲の選定には静的インポートグラフを使用します。そのため、設計上、近似的な結果となります。動的インポート、名前によるフィクスチャの解決、データ駆動型テストは見落とされる可能性があります。verify(scope="all") はいつでも利用でき、フォールバックが発生した場合は selection_note にその旨が記載されます。
• 現時点では Python/pytest のみが対象で、ruff/mypy にも対応しています。アダプターのインターフェースは小規模で、ドキュメントも整備されています。最も求められている貢献は vitest および go test -json アダプターです（CONTRIBUTING.md）。
• フレーク検出とカバレッジマップに基づく選定は v0.2 の予定です（ロードマップ）。

ロードマップ

v0.2： カバレッジに基づく影響範囲マップ（正確な選定）、フィンガープリントの交互変化によるフレーク検出、devcontainer.json のサポート、（ツリーハッシュ、チェック、イメージダイジェスト）をキーとした結果キャッシュ。今後： vitest/jest、go test、cargo test のアダプター、リポジトリごとの判定デーモンモード。

ライセンス

Apache-2.0