devmcp

MCP 向けの信頼できるエージェントスタック

公式 MCP レジストリに、io.github.rudranaresh0201/verimcp と io.github.rudranaresh0201/devmcp として掲載されています。

コンソールを見る → — ブラウザーで再生される録画セッションです。3 件の検証済み呼び出し、検出された 5 件の虚偽、1 件の正直なバックエンドエラーを確認できます。

問題

MCP のツール呼び出しは、次の 2 つの異なる形でデフォルトで信頼されており、どちらも本番環境のエージェントワークフローで問題になります。

1. 主張が検証されません。 サーバーがコミットに成功した、ファイルを書き込んだ、CI チェックに合格したと言っても、それが本当かどうかをホストが知る方法はありません。isError: false が示すのはツールがクラッシュしなかったことだけであり、主張どおりに動作したことではありません。MCP 経由で git、CI、インフラストラクチャに接続されたエージェントは、自信満々に誤ったツール応答を 1 回受け取るだけで、虚偽に基づいて行動する可能性があります。
2. 再試行は安全ではありません。 あいまいな応答（タイムアウトや接続切断など）の後にホストが tools/call を再送しても、MCP にはバックエンドの再実行を阻止する仕組みがありません。コミットがもう 1 回、CI 実行がもう 1 回、請求がもう 1 回発生する可能性があります。このプロトコルには「これをすでに実行したのでは？」という概念がありません。

解決策

verimcp は、MCP ホストとバックエンドサーバーの間に置かれる透過プロキシです。2 つの独立したチェックを各呼び出しの前後に行う以外は、すべてのメッセージを変更せずに転送します。

• 転送前（事前チェック）— このセッション中に同一の呼び出しがすでに送信され、独立して成功を検証済みの場合、バックエンドに再度アクセスせず、確認済みの結果を使って再試行に応答します。--idempotent-replay については、以下の証明を参照してください。
• バックエンドの応答後（事後チェック）— 検証可能な呼び出しについて、実際の結果を独立して再導出し（ファイルの再読み込み、git ログの再確認、CI ステップの安全な部分の再実行など）、バックエンドの主張と照合します。虚偽があれば、ホストが成功として受け取る前に、実際のエラーに書き換えます。

devmcp は、実証に使用されたバックエンドです。プロトコルの全機能（ツール、リソース、プロンプト、ルート、サンプリング）を備えた、実際の git／CI MCP サーバーとして意図的に構築されています。プロキシの説得力は、何を検出して見せられるかに左右されるためです。

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

どちらも個別にインストールでき、互いにインポート依存関係はありません。verimcp はあらゆる MCP バックエンドの前段で動作し（devmcp だけでなく、公式の mcp-server-git に対しても実証済みです）、devmcp はプロキシを介さず、どのホストからも直接利用できます。

主張だけでなく、証拠も提示

実際のサブプロセスパイプを使い、モックなしで実行できるベンチマークを2つ用意しました。以下の数値は、ギャップも含めて実際に出力されるものです。

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 ホストは、仕組み上、捏造された結果を100％受け入れます。これはベンチマーク上の問題ではなく、プロトコルに実在するギャップです。

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

100％ではなく79％としているのは、意図的であり、スクリプト自体の出力にも明記されています。14件のシナリオのうち3件は、特定の検証機能における、文書化された原則的なギャップを突いています（たとえば、ハッシュの存在確認だけでは、今回の呼び出しでハッシュが作成されたのか、以前から存在していたのかを判別できません）。自らのベンチマークで完璧なスコアを主張するツールこそ、本当に警戒すべきものだからこそ、こうしたギャップを隠さず明示しています。

リトライによる重複実行 — 同じ考え方を--idempotent-replayに適用し、現実的な、べき等ではない副作用5件（カウンターの加算、通知の送信、請求書のインクリメント、監査ログの記録、2段階のパイプライン）で検証します。

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

scripts/demo.pyは、同じ証明をより短く、説明的に示すものです。捏造されたコミットハッシュを1件検出し、実際の書き込み1件は確認したうえで、変更せずに通過させます。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／issue／ブランチが存在するだけでなく、依頼したタイトルが付いている必要があり、サーバーが実在する古い PR を新規として返すケースも検出します。リポジトリが公開状態にあると確認された場合にのみ 404 を判定対象とするため、トークンがないプライベートリポジトリが誤って問題として報告されることはありません。
• レシート（--receipts。wrap ではデフォルトで有効）— 各チェックでは、実際に確認した内容（PR の実際のタイトルとリンク、コミットの実際のメッセージと作成者、ファイルの実際のハッシュ）、確認場所、確認時刻を、主張が正しかった場合も正しくなかった場合も記録します。常に監査ログとコンソールに出力され、このフラグを指定するとツールの返信にも追加されます。
• リモートサーバー（--backend-url）— Streamable HTTP（MCP 仕様 2025-06-18：JSON および SSE の返信、セッション ID、プロトコルバージョンヘッダー）経由でサーバーの前段として動作します。--header 'Authorization: Bearer ${TOKEN}'／--header-from-env を使えば、シークレットを設定ファイルやコマンドラインに保存する必要はありません。テストスイートに加え、ホスト型サーバー（DeepWiki）でも検証済みです。
• ホストからのルート — verimcp は、ルート対応のホスト（Claude Code、Cursor）にワークスペース自体を問い合わせるため、mcp-server-git のようにルートを要求しないサーバーの前段でも、ファイルシステムと Git の検証器が機能します。
• 検証してから再試行（--idempotent-replay）— 再試行された tools/call がキャッシュから応答されるのは、前回の同一の呼び出しが、上記のチェックによって独立して成功と検証された場合に限られます。キーが一致しても以前に検証済みの成功がなければ、誤った重複排除ではなくキャッシュミスになります。arXiv:2608.02645 を参考にし、プロキシ層に実装することで、特定のエージェントフレームワーク独自の再試行ラッパーだけでなく、verimcp が前段として動作するあらゆるホスト／バックエンドの組み合わせで機能します。
• ポリシーゲート — 客観的に正誤を確認できない呼び出し（サンプリング頻度の制限、YAML による任意のツール名／引数ポリシー、実際の MCP elicitation/create を介した人間参加型の承認）について、バックエンドに呼び出しが届く前に、許可／拒否／承認必須のルールを評価します。
• 監査と再生 — verimcp が処理するすべての呼び出しがログに記録され、実際の verimcp://audit MCP リソースとして提供されます。verimcp replay は記録済みのトラフィックを新しいポリシーに対して再実行し、「これによって何かが変わったか」をバックテストします。
• オブザーバビリティ — すべての呼び出しについて、GenAI のセマンティック規約を用いた OpenTelemetry スパン／メトリクスが生成され、任意の OTLP コレクターにエクスポートできます。
• 自作テストだけでなく実際のクライアントで検証済み — 公式 MCP Inspector と VS Code のネイティブ MCP サポート（Copilot Chat）で、自作テストスイートでは発生しなかった実際のバグがそれぞれ検出され、現在は回帰テストを追加して修正済みです。

より詳しい設計上の考え方（プロンプト／ルートに原則として検証器を設けない理由、ポリシーが検証とは別の概念である理由など）は、詳しく知りたい方のために 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 です（devmcp は無関係な既存パッケージとの類似性により、PyPI のタイポスクワッティング検出でブロックされました）。ただし、Python のインポート名と CLI コマンドはどちらも引き続き devmcp です。devmcp 自身のソースを読んでいる場合も、上記の内容に変更はありません。

Claude Desktop、Claude Code、Cursor で使う場合 — pip install の後、通常の方法で devmcp を MCP サーバーとして追加し、command の指定先を devmcp ではなく verimcp にします。

{
  "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：同じ JSON 形式を Cursor の MCP 設定に入力します。

これ以降、アシスタントには 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 では、記録済みのセッションを再生できます。これはライブのエージェントではなく録画であり、そのことは UI にも明記されています。配信されるログは、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 経由で、ちょうど 1 つの Host と MCP 通信を行います。そのパイプ上に 2 つ目の読み取り側を設けるとセッションが破損するため、監査ログがサポートされている帯域外のインターフェイスです（ADR 0004）。ファイルを読み取っても観測対象に影響しないことは、干渉しないという主張がプロジェクトの根幹であるツールにとって重要です。

検証してから再試行する動作を試す

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

同じ tools/call を連続して 2 回送信します（同じツール、同じ引数、新しいリクエスト ID。タイムアウト後にクライアントが再送信する場合と、ワイヤー上ではまったく同じです）。最初の呼び出しは実際に実行され、2 回目はバックエンドに再度アクセスせず、確認済みの結果を使って応答します。このフラグを省略すると、従来どおりデフォルトは変更されず、再試行のたびに再実行されます。

コントリビュート

開発環境のセットアップ、検証器の追加方法、このプロジェクトの ADR に関する方針、コミットや PR の規約については CONTRIBUTING.md をご覧ください。リリース履歴については CHANGELOG.md をご覧ください。

ライセンス

MIT — LICENSE をご覧ください。