Debate Agent MCP

🚀 Debate Agent MCP

コードレビューと討論計画に使用する多エージェント討論フレームワークで、P0/P1/P2の深刻度スコアリングが可能です。

🚀 クイックスタート

前提条件

エージェントの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の深刻度スコアリング
• 複数のエージェントを並列実行し、結果を統合する

📦 インストール

💻 使用例

基本的な使用法

# グローバルにインストール
npm install -g @debate-agent/mcp-server

# MCPサーバーを起動
debate-agent

# または直接実行
npx @debate-agent/mcp-server

高度な使用法

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

🔧 技術詳細

• アーキテクチャは、MCPサーバーレイヤー、オーケストレーターレイヤー、そしてClaude CLIとCodex CLIを含む多層構造になっています。
• スコアリングシステムは、決定論的でAIを使用せず、ルールベースで評価されます。
• 討論モードには、敵対的、合意形成、協調的などがあり、エージェントの動作を制御します。

📄 ライセンス

MIT

⚠️ 重要提示

このプロジェクトは積極的に開発中です。APIや機能は予告なく変更される可能性があります。本番環境での使用は自己責任で行ってください。

💡 使用建议

• エージェントのCLIを事前にインストールし、認証する必要があります。
• 長いdiffはエージェントのタイムアウトを引き起こす可能性があります (デフォルトは180秒)。
• 現在は完全なレスポンスを待ってから処理するため、ストリーミングはサポートされていません。