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 許可證。