mcp-as-a-judge

MCP as a Judge ⚖️

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

MCP as a Judge 充当 AI 编码助手与大模型之间的验证层，帮助确保代码更安全、质量更高。

MCP as a Judge 是一种行为型 MCP，通过要求大模型明确评估以下内容，增强 AI 编码助手的能力：

• 研究、系统设计和规划
• 代码变更、测试和任务完成情况验证

它要求以证据为依据开展研究、优先复用而非重新发明，并在决策过程中纳入人工参与。

如果你的 IDE 具有规则/Agent（Copilot、Cursor、Claude Code），请继续使用它们——这个 Judge 会在计划、代码差异和测试环节增加可执行的审批关卡。

AI 编码助手和大模型的主要问题

• 将大模型输出视为事实；跳过研究并使用过时信息
• 不复用库和现有代码，反而重复造轮子
• 偷工减料：代码不符合工程标准，测试薄弱
• 需求模糊或计划变更时，擅自做决定
• 安全盲点：缺少输入验证、存在注入风险/攻击向量、违反最小权限原则，以及防御式编程不足

Vibe 编码不必令人沮丧

强制要求

• 基于证据的研究和复用（最佳实践、库、现有代码）
• 以计划为先，确保交付符合用户需求
• 在需求模糊和遇到阻碍时，由人工参与决策
• 对代码和测试设置质量关卡（安全性、性能、可维护性）

主要功能

• 通过 MCP sampling 智能评估代码；强制遵循软件工程标准，并标记安全性、性能和可维护性风险
• 全面审查计划/设计：验证架构、研究深度、需求匹配度和实施方案
• 通过 MCP elicitation 由用户主导决策：澄清需求、解决障碍，并确保选择过程透明
• 验证系统设计和代码变更中的安全性

工具及其作用

工具	解决的问题
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 Sampling 和 MCP Elicitation 功能：

• MCP Sampling - AI 驱动的代码评估和判定所必需
• MCP Elicitation - 交互式用户决策提示所必需

系统前提条件

• Docker Desktop / Python 3.13+ - 运行 MCP 服务所必需

支持的 AI 助手

AI 助手	平台	MCP 支持	状态	备注
GitHub Copilot	Visual Studio Code	✅ 完整	推荐	完整的 MCP 集成，支持 sampling 和 elicitation
Claude Code	-	⚠️ 部分	需要 LLM API 密钥	Sampling 支持功能请求 Elicitation 支持功能请求
Cursor	-	⚠️ 部分	需要 LLM API 密钥	支持 MCP，但 sampling/elicitation 功能有限
Augment	-	⚠️ 部分	需要 LLM API 密钥	支持 MCP，但 sampling/elicitation 功能有限
Qodo	-	⚠️ 部分	需要 LLM API 密钥	支持 MCP，但 sampling/elicitation 功能有限

✅ 推荐配置： GitHub Copilot + VS Code — 完整支持 MCP sampling；无需 API 密钥。

⚠️ 重要： 对于不完整支持 MCP sampling 的助手（Cursor、Claude Code、Augment、Qodo），必须设置 LLM_API_KEY。否则，服务无法评估计划或代码。请参阅 LLM API 配置。

💡 提示： 优先选择上下文窗口较大的模型（≥ 1M tokens），以获得更好的分析和判定效果。

如果 MCP 服务未自动使用

如需排查问题，请访问 常见问题解答。

🔧 MCP 配置

在启用 MCP 的客户端中配置 MCP as a Judge：

方法 1：使用 Docker（推荐）

VS Code 一键安装（MCP）

备注：

• VS Code 控制 sampling 模型；通过“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 sampling）
   • 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 sampling）
   • LLM_API_KEY 为可选项，需要时可通过环境变量设置

3. 更新到最新版本：

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

在 VS Code 中选择 sampling 模型

• 打开命令面板（Cmd/Ctrl+Shift+P）→ “MCP: List Servers”
• 选择已配置的服务“mcp-as-a-judge”
• 选择“Configure Model Access”
• 勾选首选模型以启用 sampling

🔑 LLM API 配置（可选）

对于不完全支持 MCP 采样的 AI 助手，你可以配置 LLM API 密钥作为备用方案。这样即使客户端不支持 MCP 采样，MCP as a Judge 也能正常工作。

• 设置 LLM_API_KEY（统一密钥）。系统会自动检测服务提供商；也可以选择设置 LLM_MODEL_NAME 来覆盖默认值。

支持的 LLM 提供商

Rank	Provider	API Key Format	Default Model	Notes
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	与 OpenAI 相同，但通过 Azure 提供
5	AWS Bedrock	AWS credentials	anthropic.claude-sonnet-4-20250514-v1:0	与 Anthropic 保持一致
6	Vertex AI	Service Account 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 和 Zvi Fried。“MCP as a Judge” 概念、“behavioral MCP” 方法、分阶段工作流（plan → code → test → completion）、工具分类与描述，以及提示词模板，均为在此仓库中开发的原创成果。

既有成果与署名

尽管“LLM‑as‑a‑judge”是一个广为人知的理念，但此仓库定义了由 OtherVibes 和 Zvi Fried 提出的原创“MCP as a Judge” behavioral MCP 模式。它结合了以任务为中心的工作流约束（plan → code → test → completion）、基于 LLM 的显式验证和人在回路中的信息引导，以及此处提供的提示词模板和工具分类。请署名为：“OtherVibes – MCP as a Judge (Zvi Fried)”。

❓ 常见问题

“MCP as a Judge” 与 IDE 助手（GitHub Copilot、Cursor、Claude Code）中的规则/子 Agent 有何不同？

特性	IDE 规则	子 Agent	MCP as a Judge
静态行为指导	✓	✓	✗
自定义系统提示词	✓	✓	✓
项目上下文集成	✓	✓	✓
专项任务处理	✗	✓	✓
主动质量门禁	✗	✗	✓
基于证据的验证	✗	✗	✓
通过反馈批准/拒绝	✗	✗	✓
工作流约束	✗	✗	✓
跨助手兼容性	✗	✗	✓

• 参考资料：GitHub Copilot 自定义说明、Cursor 规则、Claude Code 子 Agent

Judge 工作流与任务列表有什么关系？为什么两者都需要？

• 任务列表 = 规划/组织：跟踪任务、优先级和状态，但不能保证工程质量或就绪状态。
• Judge 工作流 = 质量门禁：对计划/设计、代码差异、测试和最终完成情况实施审批。它要求提供真实证据（例如统一 Git 差异和原始测试输出），并返回结构化审批结果和所需改进。
• 两者结合：使用任务列表组织工作；使用 Judge 判断每个阶段是否真正可以继续。服务端还会发出 next_tool 指引，推动进度通过各道门禁。

如果 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 授权（参见 LICENSE）。

🙏 致谢

• Anthropic 提供的 Model Context Protocol
• LiteLLM，用于统一的 LLM API 集成

---