MCP As A Judge

🚀 MCP 作為評審員 ⚖️

MCP 作為評審員 在 AI 編碼助手和大語言模型（LLM）之間充當驗證層，有助於確保生成的代碼更安全、質量更高。

✨ 主要特性

MCP 作為評審員 是一種 行為式 MCP，它通過要求對以下方面進行明確的大語言模型評估，來增強 AI 編碼助手的能力：

• 研究、系統設計和規劃
• 代碼更改、測試以及任務完成驗證

它強制進行基於證據的研究，優先複用而非重新發明，並要求人工參與決策。

如果你的集成開發環境（IDE）已有規則或智能代理（如 Copilot、Cursor、Claude Code），可以繼續使用它們 —— 這個評審員會在計劃、代碼差異和測試方面添加可強制執行的審批環節。

關鍵問題

當前 AI 編碼助手和大語言模型存在以下關鍵問題：

• 將大語言模型的輸出視為絕對正確，跳過研究環節，使用過時信息。
• 不重用現有庫和代碼，而是重複造輪子。
• 偷工減料，代碼達不到工程標準，測試力度薄弱。
• 當需求不明確或計劃變更時，擅自做出決策。
• 存在安全盲點，如缺少輸入驗證、存在注入風險/攻擊向量、違反最小權限原則以及防禦性編程不足。

強制執行的內容

• 基於證據的研究和複用（最佳實踐、庫、現有代碼）
• 以用戶需求為導向的先規劃後交付
• 人工參與決策，以應對模糊情況和阻礙
• 代碼和測試的質量關卡（安全性、性能、可維護性）

關鍵能力

• 通過 MCP 採樣 進行智能代碼評估，強制執行軟件工程標準，並標記安全、性能和可維護性風險。
• 全面的計劃/設計審查，驗證架構、研究深度、需求匹配度和實現方法。
• 通過 MCP 啟發式方法 實現用戶驅動的決策，明確需求、解決障礙並保持選擇透明。
• 在系統設計和代碼更改中進行安全驗證。

工具及其作用

🚀 快速開始

要求與建議

MCP 客戶端先決條件

MCP 作為評審員的核心功能嚴重依賴於 MCP 採樣 和 MCP 啟發式方法 特性：

• MCP 採樣：AI 驅動的代碼評估和判斷所必需。
• MCP 啟發式方法：交互式用戶決策提示所必需。

系統先決條件

• Docker Desktop / Python 3.13+：運行 MCP 服務器所必需。

支持的 AI 助手

✅ 推薦設置：GitHub Copilot + VS Code —— 完整的 MCP 採樣，無需 API 密鑰。

⚠️ 重要提示：對於沒有完整 MCP 採樣支持的助手（Cursor、Claude Code、Augment、Qodo），你必須設置 LLM_API_KEY。否則，服務器無法評估計劃或代碼。請參閱 LLM API 配置（可選）。

💡 使用建議：優先選擇大上下文模型（≥ 100 萬個令牌），以獲得更好的分析和判斷結果。

如果 MCP 服務器未自動使用

如需故障排除，請訪問 常見問題解答部分。

🔧 MCP 配置

在支持 MCP 的客戶端中配置 MCP 作為評審員：

方法 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：可選的自定義模型（默認值請參閱 支持的大語言模型提供商）。
• --pull=always 標誌確保你始終自動獲取最新版本。

然後在需要時手動更新：

# 拉取最新版本
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. 更新到最新版本：

# 將 MCP as a Judge 更新到最新版本
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 助手，你可以配置大語言模型 API 密鑰作為備用方案。這樣即使客戶端不支持 MCP 採樣，MCP 作為評審員也能正常工作。

• 設置 LLM_API_KEY（統一密鑰）。系統會自動檢測供應商；可選擇設置 LLM_MODEL_NAME 來覆蓋默認模型。

支持的大語言模型提供商

特定客戶端設置

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：可選的自定義模型（默認值請參閱 支持的大語言模型提供商）。

Claude Code

1. 通過命令行界面添加 MCP 服務器：

# 先設置環境變量（可選的模型覆蓋）
export LLM_API_KEY="your_api_key_here"
export LLM_MODEL_NAME="claude-3-5-haiku"  # 可選：更快/更便宜的模型

# 添加 MCP 服務器
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：可選的自定義模型（默認值請參閱 支持的大語言模型提供商）。

其他 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：可選的自定義模型（默認值請參閱 支持的大語言模型提供商）。

🔒 隱私與靈活的 AI 集成

MCP 採樣（首選）+ LLM API 密鑰備用方案

主要模式：MCP 採樣

• 所有判斷均使用 MCP 採樣 功能進行。
• 無需配置或支付外部大語言模型 API 服務費用。
• 直接與支持 MCP 的客戶端現有的 AI 模型配合使用。
• 目前支持的組合：GitHub Copilot + VS Code。

備用模式：LLM API 密鑰

• 當 MCP 採樣不可用時，服務器可以使用大語言模型 API 密鑰。
• 通過 LiteLLM 支持多個提供商：OpenAI、Anthropic、Google、Azure、Groq、Mistral、xAI。
• 從 API 密鑰模式自動檢測供應商。
• 未指定模型時，按供應商選擇默認模型。

隱私保護

• 服務器在本地機器上運行。
• 不收集數據，你的代碼和對話保持私密。
• 使用 MCP 採樣時不進行外部 API 調用。如果你設置了 LLM_API_KEY 作為備用方案，服務器只會調用你選擇的大語言模型提供商，根據你提供的評估內容進行判斷（計劃/代碼/測試）。
• 完全控制你的開發工作流程和敏感信息。

🤝 貢獻

我們歡迎貢獻！請參閱 CONTRIBUTING.md 瞭解貢獻指南。

開發設置

# 克隆倉庫
git clone https://github.com/OtherVibes/mcp-as-a-judge.git
cd mcp-as-a-judge

# 使用 uv 安裝依賴項
uv sync --all-extras --dev

# 安裝預提交鉤子
uv run pre-commit install

# 運行測試
uv run pytest

# 運行所有檢查
uv run pytest && uv run ruff check && uv run ruff format --check && uv run mypy src

© 概念與方法

© 2025 OtherVibes 和 Zvi Fried。“MCP 作為評審員” 概念、“行為式 MCP” 方法、分階段工作流（計劃 → 代碼 → 測試 → 完成）、工具分類/描述以及提示模板均為本倉庫的原創作品。

已有成果與引用說明

儘管 “大語言模型作為評審員” 是一個廣為人知的概念，但本倉庫定義了由 OtherVibes 和 Zvi Fried 提出的原創 “MCP 作為評審員” 行為式 MCP 模式。它結合了以任務為中心的工作流強制執行（計劃 → 代碼 → 測試 → 完成）、基於大語言模型的明確驗證以及人工參與的啟發式方法，同時提供了此處的提示模板和工具分類。請引用為：“OtherVibes – MCP 作為評審員（Zvi Fried）”。

❓ 常見問題解答

“MCP 作為評審員” 與 IDE 助手（GitHub Copilot、Cursor、Claude Code）中的規則/子代理有何不同？

• 參考資料：GitHub Copilot 自定義說明、Cursor 規則、Claude Code 子代理

評審員工作流與任務列表有何關係？為什麼兩者都需要？

• 任務列表：用於規劃/組織，跟蹤任務、優先級和狀態，但不能保證工程質量或就緒性。
• 評審員工作流：作為質量關卡，對計劃/設計、代碼差異、測試和最終完成進行審批。它需要真實的證據（如統一的 Git 差異和原始測試輸出），並返回結構化的批准和所需的改進建議。
• 結合使用：使用任務列表來組織工作，使用評審員來決定每個階段是否真正準備好繼續進行。服務器還會發出下一步工具指導，以推動工作通過各個關卡。

如果評審員未自動使用，如何強制使用？

• 在你的提示中輸入："use mcp-as-a-judge" 或 "Evaluate plan/code/test using the MCP server mcp-as-a-judge"。
• 在 VS Code 中，打開命令面板（Cmd/Ctrl + Shift + P）→ “MCP: List Servers”，確保 “mcp-as-a-judge” 已列出並啟用。
• 確保 MCP 服務器正在運行，並且在你的客戶端中，評審員工具已啟用/批准。

如何在 VS Code 中選擇採樣模型？

• 打開命令面板（Cmd/Ctrl + Shift + P）→ “MCP: List Servers”。
• 選擇 “mcp-as-a-judge” → “Configure Model Access”。
• 勾選你首選的模型以啟用採樣。

📄 許可證

本項目採用 MIT 許可證（詳見 LICENSE）。

🙏 致謝

• 模型上下文協議，由 Anthropic 提供。
• LiteLLM，用於統一的大語言模型 API 集成。