Debate Agent MCP

🚀 Debate Agent MCP

Debate Agent MCP 是一个多智能体辩论框架，主要用于代码审查和辩论规划，并具备 P0/P1/P2 严重程度评分功能。

⚠️ 重要提示

本项目正在积极开发中，API 和功能可能会在未事先通知的情况下发生变化。在生产环境中使用时，请自行承担风险。

🚀 快速开始

前提条件

你必须安装并认证智能体 CLI：

# 检查 Claude CLI
claude --version
claude auth status  # 应显示已登录

# 检查 Codex CLI
codex --version
# 应通过 OpenAI 进行认证

# MCP 将调用这些工具，无需额外认证

命令行界面 (CLI) 用户

# 全局安装
npm install -g @debate-agent/mcp-server

# 启动 MCP 服务器
debate-agent

# 或者直接运行
npx @debate-agent/mcp-server

Claude Code 用户

# 将 MCP 添加到 Claude Code
claude mcp add debate-reviewer -- node /path/to/packages/mcp-server/dist/index.js

# 验证连接
claude mcp list
# 应显示：debate-reviewer: ✓ Connected

SDK 用户

npm install @debate-agent/core

import { runDebate, createDebatePlan } from '@debate-agent/core';

// 运行代码审查辩论
const result = await runDebate({
  question: 'Review this code for security issues',
  agents: ['codex', 'claude'],
  platform: 'backend',
});

// 创建辩论计划
const plan = createDebatePlan('Best caching strategy', ['codex', 'claude'], 'collaborative', 2);

✨ 主要特性

• 多智能体辩论框架，可用于代码审查和辩论规划。
• 支持 P0/P1/P2 严重程度评分，能对问题进行细致分级。
• 无需 API 密钥或认证，通过调用本地安装的 CLI 工具实现功能。
• 提供多种工具，如列出智能体、读取未提交的 git diff 等。
• 具备确定性的评分系统，基于规则进行评估。
• 支持多种辩论模式，包括对抗性、共识性和协作性。

📦 安装指南

安装相关包

💻 使用示例

基础用法

import { runDebate, createDebatePlan } from '@debate-agent/core';

// 运行代码审查辩论
const result = await runDebate({
  question: 'Review this code for security issues',
  agents: ['codex', 'claude'],
  platform: 'backend',
});

// 创建辩论计划
const plan = createDebatePlan('Best caching strategy', ['codex', 'claude'], 'collaborative', 2);

📚 详细文档

架构概述

┌─────────────────────────────────────────────────────────────────────────────┐
│                           DEBATE AGENT MCP                                  │
│                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                         MCP SERVER LAYER                              │  │
│  │                    (Model Context Protocol)                           │  │
│  │                                                                       │  │
│  │   Exposes tools via stdio to Claude Code / AI assistants:            │  │
│  │   • list_agents    • read_diff    • run_agent                        │  │
│  │   • debate_review  • debate_plan                                     │  │
│  │                                                                       │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                    │                                        │
│                                    ▼                                        │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                      ORCHESTRATOR LAYER                               │  │
│  │                     (@debate-agent/core)                              │  │
│  │                                                                       │  │
│  │   Pipeline:                                                          │  │
│  │   1. Read git diff ──► 2. Run agents in parallel (Promise.all)       │  │
│  │   3. Critique round ──► 4. Deterministic scoring ──► 5. Merge        │  │
│  │                                                                       │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                    │                                        │
│                    ┌───────────────┴───────────────┐                        │
│                    ▼                               ▼                        │
│  ┌──────────────────────────┐    ┌──────────────────────────┐              │
│  │      Claude CLI          │    │      Codex CLI           │              │
│  │  /opt/homebrew/bin/claude│    │  /opt/homebrew/bin/codex │              │
│  │                          │    │                          │              │
│  │  spawn() as subprocess   │    │  spawn() as subprocess   │              │
│  │  Uses YOUR credentials   │    │  Uses YOUR credentials   │              │
│  └──────────────────────────┘    └──────────────────────────┘              │
│                    │                               │                        │
│                    ▼                               ▼                        │
│              Anthropic API                   OpenAI API                     │
│           (auth via local CLI)            (auth via local CLI)              │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

工作原理

无需认证

MCP 本身不需要 API 密钥或认证，它会协调你本地安装的 CLI 工具：

┌─────────────────────────────────────────────────────────────────┐
│  YOUR MACHINE                                                   │
│                                                                 │
│  ~/.claude/credentials  ──► claude CLI ──► Anthropic API       │
│  ~/.codex/credentials   ──► codex CLI  ──► OpenAI API          │
│                                                                 │
│  The MCP just runs: spawn("claude", ["--print", prompt])        │
│  Same as typing in your terminal!                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

执行流程

Step 1: Build Prompt
├── Combine review question + git diff + platform rules
├── Add P0/P1/P2 severity definitions
└── Request JSON output format

Step 2: Parallel Execution
├── spawn("/opt/homebrew/bin/claude", ["--print", prompt])
├── spawn("/opt/homebrew/bin/codex", ["exec", prompt])
└── Both run simultaneously via Promise.all()

Step 3: Capture Output
├── Read stdout from each CLI process
└── Parse JSON responses

Step 4: Deterministic Scoring (No AI)
├── Count P0/P1/P2 findings
├── Check file accuracy against diff
├── Penalize false positives
└── Score clarity and fix quality

Step 5: Merge & Report
├── Pick winner by highest score
├── Combine unique findings from all agents
└── Generate final recommendation

路线图

当前 (v1.0) - 单轮审查

Claude ──┐
         ├──► Parallel Review ──► Score ──► Merge ──► Final Report
Codex  ──┘

未来目标 - 多轮交叉审查

通过对抗验证消除幻觉问题

Round 1: Initial Review (Parallel)
┌─────────┐     ┌─────────┐
│ Claude  │     │ Codex   │
│ Review  │     │ Review  │
└────┬────┘     └────┬────┘
     │               │
     ▼               ▼
Round 2: Cross-Review (Each agent reviews the other's findings)
┌─────────────────────────────────────────┐
│ Claude reviews Codex's findings         │
│ "Is P0 about null pointer valid?"       │
│ "Did Codex miss the SQL injection?"     │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│ Codex reviews Claude's findings         │
│ "Is the race condition real?"           │
│ "False positive on line 42?"            │
└─────────────────────────────────────────┘
     │               │
     ▼               ▼
Round 3: Consensus Building
┌─────────────────────────────────────────┐
│ Only findings validated by BOTH agents  │
│ Hallucinations eliminated               │
│ Disputed findings flagged for human     │
└─────────────────────────────────────────┘
     │
     ▼
Final: Validated Review
┌─────────────────────────────────────────┐
│ High-confidence findings (both agreed)  │
│ Disputed findings (need human review)   │
│ Eliminated findings (proven false)      │
│ Combined score from validation rounds   │
└─────────────────────────────────────────┘

目标：通过让智能体相互审查工作，我们可以：

• 消除幻觉发现（一个智能体虚构出不存在的问题）。
• 捕捉遗漏的问题（一个智能体发现另一个智能体遗漏的问题）。
• 建立置信度分数（多个智能体验证的发现更可靠）。
• 减少误报（对抗性审查可以发现不正确的评估）。

MCP 工具

配置

在项目根目录创建 debate-agent.config.json：

{
  "agents": {
    "codex": {
      "name": "codex",
      "path": "/opt/homebrew/bin/codex",
      "args": ["exec", "--skip-git-repo-check"],
      "timeout_seconds": 180
    },
    "claude": {
      "name": "claude",
      "path": "/opt/homebrew/bin/claude",
      "args": ["--print", "--dangerously-skip-permissions"],
      "timeout_seconds": 180
    },
    "gemini": {
      "name": "gemini",
      "path": "/opt/homebrew/bin/gemini",
      "args": ["--prompt"],
      "timeout_seconds": 180
    }
  },
  "debate": {
    "default_agents": ["codex", "claude"],
    "include_critique_round": true,
    "default_mode": "adversarial"
  }
}

严重程度级别

定义位置：packages/core/src/prompts/review-template.ts

特定平台规则

定义位置：packages/core/src/prompts/platform-rules.ts

评分系统

评分是确定性的（不使用 AI），基于纯规则进行评估：

最高可能得分：134 最低可能得分：-30

定义位置：packages/core/src/engine/judge.ts

辩论模式

项目结构

debate-agent-mcp/
├── packages/
│   ├── core/                       # @debate-agent/core
│   │   ├── src/
│   │   │   ├── engine/
│   │   │   │   ├── debate.ts       # Orchestration (parallel execution)
│   │   │   │   ├── judge.ts        # Deterministic scoring rules
│   │   │   │   ├── merger.ts       # Combine findings from agents
│   │   │   │   └── planner.ts      # Debate plan generation
│   │   │   ├── prompts/
│   │   │   │   ├── review-template.ts   # P0/P1/P2 definitions
│   │   │   │   └── platform-rules.ts    # Platform-specific scrutiny
│   │   │   ├── tools/
│   │   │   │   ├── read-diff.ts    # Git diff reader
│   │   │   │   └── run-agent.ts    # CLI spawner (spawn())
│   │   │   ├── config.ts           # Config loader
│   │   │   ├── types.ts            # TypeScript types
│   │   │   └── index.ts            # Public exports
│   │   └── package.json
│   │
│   ├── mcp-server/                 # @debate-agent/mcp-server
│   │   ├── src/
│   │   │   ├── index.ts            # MCP server (stdio transport)
│   │   │   └── bin/cli.ts          # CLI entry point
│   │   └── package.json
│   │
│   └── vscode-extension/           # debate-agent-mcp (VS Code)
│       ├── src/
│       │   └── extension.ts
│       └── package.json
│
├── debate-agent.config.json        # Example config
├── package.json                    # Monorepo root
├── pnpm-workspace.yaml
└── README.md

集成

Claude Desktop

{
  "mcpServers": {
    "debate-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"]
    }
  }
}

Claude CLI

claude mcp add debate-agent -- node /path/to/packages/mcp-server/dist/index.js

VS Code / Cursor

安装 VS Code 扩展，它会自动配置 MCP。

开发

# 克隆仓库
git clone https://github.com/ferdiangunawan/debate-agent-mcp
cd debate-agent-mcp

# 安装依赖
npm install

# 构建所有包
npm run build

# 构建特定包
npm run build:core
npm run build:server
npm run build:extension

已知限制

• 实验性：API 可能会在未事先通知的情况下发生变化。
• 需要本地 CLIs：你必须安装并认证 claude 和 codex CLIs。
• 超时风险：长的 diff 可能会导致智能体超时（默认 180 秒）。
• 无流式处理：目前在处理前需要等待完整响应。
• 单轮批判：未来版本将支持多轮验证。

贡献

欢迎贡献代码！请先创建一个 issue 来讨论提议的更改。

📄 许可证

本项目采用 MIT 许可证。