mcp-as-a-judge

MCP を裁定者として使う ⚖️

mcp-name: io.github.OtherVibes/mcp-as-a-judge

MCP as a Judge は、AI コーディングアシスタントと LLM の間に検証レイヤーとして機能し、より安全で高品質なコードの実現を支援します。

MCP as a Judge は、以下の項目について明示的な LLM 評価を必須にする 行動規範を備えた MCP であり、AI コーディングアシスタントの能力を強化します。

• 調査、システム設計、計画
• コード変更、テスト、タスク完了の検証

証拠に基づく調査、再発明よりも再利用を優先すること、そして人間が介在する意思決定を徹底します。

IDE にルールやエージェント（Copilot、Cursor、Claude Code）がある場合は、引き続き使用してください。この Judge は、計画、コード差分、テストに強制力のある承認ゲートを追加します。

AI コーディングアシスタントと LLM が抱える主な問題

• LLM の出力を真実として扱い、調査を省略して古い情報を使ってしまう
• ライブラリや既存コードを再利用せず、同じものを作り直してしまう
• 手を抜き、エンジニアリング基準を満たさないコードや不十分なテストを作成する
• 要件が曖昧だったり計画が変わったりしても、独断で判断する
• セキュリティ上の見落とし：入力検証の欠如、インジェクションのリスクや攻撃経路、最小権限の原則への違反、脆弱な防御的プログラミング

バイブコーディングを苦痛にする必要はありません

徹底すること

• 証拠に基づく調査と再利用（ベストプラクティス、ライブラリ、既存コード）
• ユーザー要件に沿った、計画を優先する進め方
• 曖昧な点や障害について、人間が介在する意思決定
• コードとテストに対する品質ゲート（セキュリティ、パフォーマンス、保守性）

主な機能

• MCP のサンプリングによるインテリジェントなコード評価。ソフトウェアエンジニアリング基準を徹底し、セキュリティ、パフォーマンス、保守性のリスクを検出します
• 包括的な計画・設計レビュー：アーキテクチャ、調査の深さ、要件との適合性、実装アプローチを検証します
• MCP のエリシテーションによるユーザー主導の意思決定：要件を明確にし、障害を解決し、選択内容を透明に保ちます
• システム設計とコード変更におけるセキュリティ検証

ツールとその役割

ツール	解決すること
set_coding_task	タスクのメタデータを作成・更新し、task_size を分類して、次のステップのワークフローガイダンスを返します
get_current_coding_task	最新の task_id とメタデータを取得して、安全に作業を再開します
judge_coding_plan	計画・設計を検証し、ライブラリの選定と内部再利用マップを必須とし、リスクを検出します
judge_code_change	統合 Git 差分について、正確性、再利用、セキュリティ、コード品質をレビューします
judge_testing_implementation	実際のランナー出力と任意のカバレッジ情報を使って、テストを検証します
judge_coding_task_completion	完了前に計画、コード、テストの承認を確認する最終ゲートです
raise_missing_requirements	不足している詳細や判断を引き出し、進行を妨げる要因を解消します
raise_obstacle	トレードオフ、制約、強制される変更についてユーザーと確認します

🚀 クイックスタート

要件と推奨事項

MCP クライアントの前提条件

MCP as a Judge のコア機能は、MCP サンプリングとMCP エリシテーション機能に大きく依存しています。

• MCP サンプリング - AI を活用したコード評価と判定に必要です
• MCP エリシテーション - 対話形式でユーザーに判断を求めるプロンプトに必要です

システムの前提条件

• Docker Desktop / Python 3.13+ - MCP サーバーの実行に必要です

対応 AI アシスタント

AI アシスタント	プラットフォーム	MCP サポート	状態	備考
GitHub Copilot	Visual Studio Code	✅ フル	推奨	サンプリングとエリシテーションを含む完全な MCP 統合
Claude Code	-	⚠️ 部分的	LLM API キーが必要です	サンプリングサポートの機能リクエスト エリシテーションサポートの機能リクエスト
Cursor	-	⚠️ 部分的	LLM API キーが必要です	MCP サポートは利用できますが、サンプリング／エリシテーションには制限があります
Augment	-	⚠️ 部分的	LLM API キーが必要です	MCP サポートは利用できますが、サンプリング／エリシテーションには制限があります
Qodo	-	⚠️ 部分的	LLM API キーが必要です	MCP サポートは利用できますが、サンプリング／エリシテーションには制限があります

✅ 推奨セットアップ： GitHub Copilot + VS Code — MCP サンプリングをフルサポートし、API キーは不要です。

⚠️ 重要： MCP サンプリングをフルサポートしていないアシスタント（Cursor、Claude Code、Augment、Qodo）では、必ず LLM_API_KEY を設定してください。設定しないと、サーバーは計画やコードを評価できません。LLM API の設定を参照してください。

💡 ヒント： より良い分析と判定のため、コンテキスト長の大きいモデル（≥ 1M トークン）を推奨します。

MCP サーバーが自動的に使用されない場合

トラブルシューティングについては、FAQ セクションをご覧ください。

🔧 MCP の設定

MCP 対応クライアントで MCP as a Judge を設定します。

方法 1：Docker を使用する（推奨）

VS Code 向けワンクリックインストール（MCP）

備考：

• VS Code がサンプリングモデルを制御します。「MCP: List Servers → mcp-as-a-judge → Configure Model Access」から選択してください。

1. MCP の設定を行う：

   MCP クライアントの設定ファイルに次の内容を追加します。

   {
     "command": "docker",
     "args": ["run", "--rm", "-i", "--pull=always", "ghcr.io/othervibes/mcp-as-a-judge:latest"],
     "env": {
       "LLM_API_KEY": "your-openai-api-key-here",
       "LLM_MODEL_NAME": "gpt-4o-mini"
     }
   }
   

   📝 設定オプション（すべて任意）：

   • LLM_API_KEY：GitHub Copilot + VS Code では任意です（MCP サンプリングが組み込まれています）
   • LLM_MODEL_NAME：任意のカスタムモデルです（デフォルトについては対応 LLM プロバイダーを参照してください）
   • --pull=always フラグにより、常に最新バージョンを自動的に取得できます

   必要に応じて、次の手順で手動更新してください。

   # Pull the latest version
   docker pull ghcr.io/othervibes/mcp-as-a-judge:latest
   

方法 2：uv を使用する

1. パッケージをインストールする：

   uv tool install mcp-as-a-judge
   

2. MCP の設定を行う：

   MCP サーバーは、MCP 対応クライアントによって自動的に検出される場合があります。

   📝 備考：

   • GitHub Copilot + VS Code では追加の設定は不要です（MCP サンプリングが組み込まれています）
   • LLM_API_KEY は任意で、必要に応じて環境変数で設定できます

3. 最新バージョンに更新する：

   # Update MCP as a Judge to the latest version
   uv tool upgrade mcp-as-a-judge
   

VS Code でサンプリングモデルを選択する

• コマンドパレット（Cmd/Ctrl+Shift+P）を開き、「MCP: List Servers」を選択します
• 設定済みサーバー「mcp-as-a-judge」を選択します
• 「Configure Model Access」を選択します
• サンプリングを有効にするモデルにチェックを入れます

🔑 LLM API の設定（任意）

完全な MCP サンプリングをサポートしていない AI アシスタントでは、フォールバックとして LLM API キーを設定できます。これにより、クライアントが MCP サンプリングをサポートしていない場合でも、MCP as a Judge が動作します。

• LLM_API_KEY（共通キー）を設定します。ベンダーは自動検出されます。必要に応じて、LLM_MODEL_NAME を設定してデフォルトを上書きできます。

対応している LLM プロバイダー

順位	プロバイダー	API キーの形式	デフォルトモデル	備考
1	OpenAI	sk-...	gpt-4.1	速度に最適化された、高速で信頼性の高いモデル
2	Anthropic	sk-ant-...	claude-sonnet-4-20250514	卓越した推論能力を備えた高性能モデル
3	Google	AIza...	gemini-2.5-pro	思考機能を内蔵した、最も高度なモデル
4	Azure OpenAI	[a-f0-9]{32}	gpt-4.1	Azure 経由で利用する OpenAI と同等のモデル
5	AWS Bedrock	AWS 認証情報	anthropic.claude-sonnet-4-20250514-v1:0	Anthropic に準拠
6	Vertex AI	サービスアカウント JSON	gemini-2.5-pro	Google Cloud 経由で利用するエンタープライズ向け Gemini
7	Groq	gsk_...	deepseek-r1	速度面で優れた推論モデル
8	OpenRouter	sk-or-...	deepseek/deepseek-r1	利用可能な最良の推論モデル
9	xAI	xai-...	grok-code-fast-1	最新のコーディング特化モデル（2025年8月）
10	Mistral	[a-f0-9]{64}	pixtral-large	最も高度なモデル（124B パラメーター）

クライアントごとの設定

Cursor

1. Cursor の設定を開きます：

   • File → Preferences → Cursor Settings の順に選択します
   • MCP タブに移動します
   • + Add をクリックして新しい MCP サーバーを追加します

2. MCP サーバーの設定を追加します：

   {
     "command": "uv",
     "args": ["tool", "run", "mcp-as-a-judge"],
     "env": {
       "LLM_API_KEY": "your-openai-api-key-here",
       "LLM_MODEL_NAME": "gpt-4.1"
     }
   }
   

   📝 設定オプション：

   • LLM_API_KEY：Cursor では必須です（MCP サンプリングのサポートが限定的なため）
   • LLM_MODEL_NAME：カスタムモデルを指定できます（デフォルトについては対応している LLM プロバイダーを参照してください）

Claude Code

1. CLI から MCP サーバーを追加します：

   # Set environment variables first (optional model override)
   export LLM_API_KEY="your_api_key_here"
   export LLM_MODEL_NAME="claude-3-5-haiku"  # Optional: faster/cheaper model
   
   # Add MCP server
   claude mcp add mcp-as-a-judge -- uv tool run mcp-as-a-judge
   

2. 別の方法：手動で設定します：

   • ~/.config/claude-code/mcp_servers.json を作成または編集します

   {
     "command": "uv",
     "args": ["tool", "run", "mcp-as-a-judge"],
     "env": {
       "LLM_API_KEY": "your-anthropic-api-key-here",
       "LLM_MODEL_NAME": "claude-3-5-haiku"
     }
   }
   

   📝 設定オプション：

   • LLM_API_KEY：Claude Code では必須です（MCP サンプリングのサポートが限定的なため）
   • LLM_MODEL_NAME：カスタムモデルを指定できます（デフォルトについては対応している LLM プロバイダーを参照してください）

その他の MCP クライアント

その他の MCP 対応クライアントでは、標準の MCP サーバー設定を使用します。

{
  "command": "uv",
  "args": ["tool", "run", "mcp-as-a-judge"],
  "env": {
    "LLM_API_KEY": "your-openai-api-key-here",
    "LLM_MODEL_NAME": "gpt-5"
  }
}

📝 設定オプション：

• LLM_API_KEY：ほとんどの MCP クライアントで必須です（GitHub Copilot + VS Code を除く）
• LLM_MODEL_NAME：カスタムモデルを指定できます（デフォルトについては対応している LLM プロバイダーを参照してください）

🔒 プライバシーと柔軟な AI 統合

🔑 MCP サンプリング（推奨）＋ LLM API キーのフォールバック

プライマリモード：MCP サンプリング

• すべての判定は MCP サンプリング機能を使用して実行されます
• 外部 LLM API サービスの設定や利用料の支払いは不要です
• MCP 対応クライアントが既に使用している AI モデルを直接利用します
• 現在の対応対象： GitHub Copilot + VS Code

フォールバックモード：LLM API キー

• MCP サンプリングを利用できない場合、サーバーは LLM API キーを使用できます
• LiteLLM 経由で複数のプロバイダーに対応しています：OpenAI、Anthropic、Google、Azure、Groq、Mistral、xAI
• API キーのパターンからベンダーを自動検出します
• モデルが指定されていない場合、ベンダーごとにデフォルトモデルが選択されます

🛡️ プライバシーを大切にします

• サーバーはお使いのマシン上でローカルに動作します
• データは収集しません。コードや会話はプライベートに保たれます
• MCP サンプリングの使用時に外部 API は呼び出されません。フォールバック用に LLM_API_KEY を設定した場合、サーバーは提供された評価内容を使って判定（計画／コード／テスト）を行う目的に限り、選択した LLM プロバイダーを呼び出します
• 開発ワークフローと機密情報を完全に管理できます

🤝 貢献

皆さまからの貢献を歓迎します！ガイドラインについては、CONTRIBUTING.mdをご覧ください。

開発環境のセットアップ

# Clone the repository
git clone https://github.com/OtherVibes/mcp-as-a-judge.git
cd mcp-as-a-judge

# Install dependencies with uv
uv sync --all-extras --dev

# Install pre-commit hooks
uv run pre-commit install

# Run tests
uv run pytest

# Run all checks
uv run pytest && uv run ruff check && uv run ruff format --check && uv run mypy src

© コンセプトと方法論

© 2025 OtherVibes and Zvi Fried。「MCP as a Judge」のコンセプト、「behavioral MCP」のアプローチ、段階的なワークフロー（計画 → コード → テスト → 完了）、ツールの分類と説明、およびプロンプトテンプレートは、このリポジトリで開発されたオリジナルの成果です。

先行事例と帰属表示

「LLM-as-a-judge」は広く知られたアイデアですが、このリポジトリでは、OtherVibes and Zvi Friedによる独自の「MCP as a Judge」behavioral MCPパターンを定義しています。このパターンは、タスク中心のワークフローの遵守（計画 → コード → テスト → 完了）、明示的なLLMベースの検証、人間参加型の情報引き出しに、ここで提供するプロンプトテンプレートとツールの分類を組み合わせたものです。帰属表示は「OtherVibes – MCP as a Judge (Zvi Fried)」としてください。

❓ FAQ

「MCP as a Judge」は、IDE アシスタント（GitHub Copilot、Cursor、Claude Code）のルール／サブエージェントとどう違いますか？

機能	IDE ルール	サブエージェント	MCP as a Judge
静的な動作ガイダンス	✓	✓	✗
カスタムシステムプロンプト	✓	✓	✓
プロジェクトコンテキストの統合	✓	✓	✓
専門的なタスクへの対応	✗	✓	✓
アクティブな品質ゲート	✗	✗	✓
証拠に基づく検証	✗	✗	✓
フィードバック付きの承認／却下	✗	✗	✓
ワークフローの遵守	✗	✗	✓
アシスタント間の互換性	✗	✗	✓

• 参考資料：GitHub Copilot カスタム指示、Cursor ルール、Claude Code サブエージェント

Judge ワークフローとタスクリストはどのように関係していますか？両方必要なのはなぜですか？

• タスクリスト＝計画／整理：タスク、優先度、ステータスを追跡します。エンジニアリングの品質や準備状況を保証するものではありません。
• Judge ワークフロー＝品質ゲート：計画／設計、コードの差分、テスト、最終的な完了に対する承認を必須にします。実際の証拠（例：統合 Git 差分や生のテスト出力）を求め、構造化された承認と必要な改善点を返します。
• 両方を併用：タスクリストで作業を整理し、Judge で各段階が実際に次へ進める状態かを判断します。また、サーバーは次のツールに関するガイダンスも出力し、各ゲートを通じて進捗を維持します。

Judge が自動的に使われない場合、どうすれば強制できますか？

• プロンプトに「use mcp-as-a-judge」または「Evaluate plan/code/test using the MCP server mcp-as-a-judge」と入力します。
• VS Code：「コマンドパレット」→「MCP: List Servers」の順に選択し、「mcp-as-a-judge」が一覧にあり、有効になっていることを確認します。
• MCP サーバーが実行中であり、クライアントで Judge ツールが有効化／承認されていることを確認します。

VS Code でサンプリングに使うモデルを選ぶにはどうすればよいですか？

• コマンドパレット（Cmd/Ctrl+Shift+P）を開きます →「MCP: List Servers」を選択します
• 「mcp-as-a-judge」を選択します →「Configure Model Access」を選択します
• 使用するモデルにチェックを入れて、サンプリングを有効にします

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています（LICENSEを参照）。

🙏 謝辞

• AnthropicによるModel Context Protocol
• LLM APIを統合するLiteLLM

---