# Debate Agent MCP

> **EXPERIMENTAL**: This project is in active development. APIs and features may change without notice. Use at your own risk in production environments.

A multi-agent debate framework for **code review** and **debate planning** with P0/P1/P2 severity scoring.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           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)              │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## How It Works

### No Authentication Required

The MCP itself requires **no API keys or authentication**. It orchestrates your locally installed CLI tools:

```
┌─────────────────────────────────────────────────────────────────┐
│  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!                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Execution Flow

```
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
```

## 360 Debate Feature (v2.0)

The 360 Debate feature provides **multi-turn cross-review** with confidence scoring. It supports two modes:

| Mode | Description | Output |
|------|-------------|--------|
| **review** | P0/P1/P2 code review findings | `.debate/review-TIMESTAMP.md` |
| **plan** | Implementation planning with consensus | `.debate/plan-TIMESTAMP.md` |

### 360 Debate Pipeline

```
Round 1: Initial Review (Parallel)
┌─────────┐     ┌─────────┐
│ Claude  │     │ Codex   │
│ Review  │     │ Review  │
└────┬────┘     └────┬────┘
     │               │
     ▼               ▼
Round 2: 360 Cross-Review (Each agent reviews ALL others)
┌─────────────────────────────────────────┐
│ Claude reviews Codex's findings         │
│ Codex reviews Claude's findings         │
│ "Is P0 about null pointer valid?"       │
│ "Did Codex miss the SQL injection?"     │
└─────────────────────────────────────────┘
     │
     ▼
Confidence Check: >= 80%?
     │
     ├── No ──► Repeat (max 3 rounds)
     │
     ▼ Yes
Winner Composition
┌─────────────────────────────────────────┐
│ Highest scoring agent composes final    │
│ Merge valid findings, eliminate dupes   │
│ Document elimination reasons            │
└─────────────────────────────────────────┘
     │
     ▼
Validation Phase
┌─────────────────────────────────────────┐
│ Other agents vote: approve/reject       │
│ Majority approval required              │
│ Winner breaks ties                      │
└─────────────────────────────────────────┘
     │
     ▼
Final Report: .debate/review-*.md or .debate/plan-*.md
```

### Review Mode Example

```typescript
// Run 360 code review
const result = await runDebate360({
  question: 'Review this code for security issues',
  mode: 'review',  // P0/P1/P2 severity scoring
  agents: ['claude', 'codex'],
  platform: 'backend',
  maxRounds: 3,
  confidenceThreshold: 80,
});

// Output: .debate/review-2025-01-20T10-30-00.md
console.log(result.finalFindings);  // Validated P0/P1/P2 findings
```

### Plan Mode Example

```typescript
// Run 360 implementation planning
const result = await runDebate360({
  question: 'Plan how to add user authentication',
  mode: 'plan',  // Consensus-based, no severity
  agents: ['claude', 'codex'],
  maxRounds: 3,
  confidenceThreshold: 80,
});

// Output: .debate/plan-2025-01-20T10-30-00.md
console.log(result.finalPlan);  // Validated implementation steps
```

### Mode Comparison

| Aspect | Review Mode | Plan Mode |
|--------|-------------|-----------|
| **Purpose** | Find bugs, security issues | Plan implementation approach |
| **Scoring** | P0/P1/P2 severity (max 134 pts) | Clarity + Consensus (0-100) |
| **Output** | Findings with fix suggestions | Implementation steps with phases |
| **Winner** | Highest severity score | Highest consensus + clarity |
| **Final Result** | Merged P0/P1/P2 findings | Merged implementation plan |
| **MD File** | `review-TIMESTAMP.md` | `plan-TIMESTAMP.md` |

**Benefits of 360 Debate**:
- Eliminate hallucinated findings (validated by multiple agents)
- Catch missed issues (one agent finds what another missed)
- Build confidence scores (80% threshold ensures agreement)
- Reduce false positives (adversarial review catches incorrect assessments)
- Comprehensive report in `.debate/` directory

---

## Packages

| Package | Description | Install |
|---------|-------------|---------|
| [`@debate-agent/core`](./packages/core) | Core logic (framework-agnostic) | `npm i @debate-agent/core` |
| [`@debate-agent/mcp-server`](./packages/mcp-server) | MCP server for CLI users | `npm i -g @debate-agent/mcp-server` |
| [`debate-agent-mcp`](./packages/vscode-extension) | VS Code extension | Install from marketplace |

## Quick Start

### Prerequisites

You must have the agent CLIs installed and authenticated:

```bash
# Check Claude CLI
claude --version
claude auth status  # Should show logged in

# Check Codex CLI
codex --version
# Should be authenticated via OpenAI

# The MCP will spawn these - no additional auth needed
```

### For CLI Users

```bash
# Install globally
npm install -g @debate-agent/mcp-server

# Start MCP server
debate-agent

# Or run directly
npx @debate-agent/mcp-server
```

### For Claude Code

```bash
# Add MCP to Claude Code
claude mcp add debate-reviewer -- node /path/to/packages/mcp-server/dist/index.js

# Verify connection
claude mcp list
# Should show: debate-reviewer: ✓ Connected
```

### For SDK Users

```bash
npm install @debate-agent/core
```

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

// Run code review debate
const result = await runDebate({
  question: 'Review this code for security issues',
  agents: ['codex', 'claude'],
  platform: 'backend',
});

// Create debate plan
const plan = createDebatePlan('Best caching strategy', ['codex', 'claude'], 'collaborative', 2);
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `list_agents` | List all configured agents |
| `read_diff` | Read uncommitted git diff |
| `run_agent` | Run a single agent with prompt |
| `debate_review` | Multi-agent P0/P1/P2 code review (single round) |
| `debate_plan` | Create structured debate plan |
| `debate_360` | **360 multi-round debate with modes: `review` (P0/P1/P2) or `plan` (consensus)** |

## Configuration

Create `debate-agent.config.json` in your project root:

```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"
  }
}
```

## Severity Levels

| Level | Criteria |
|-------|----------|
| **P0** | Breaking defects, crashes, data loss, security/privacy problems, build blockers |
| **P1** | Likely bugs/regressions, incorrect logic, missing error-handling, missing tests |
| **P2** | Minor correctness issues, small logic gaps, non-blocking test gaps |

Defined in: `packages/core/src/prompts/review-template.ts`

## Platform-Specific Rules

| Platform | Focus Areas |
|----------|-------------|
| **flutter** | Async misuse, setState, dispose(), BuildContext in async, Riverpod leaks |
| **android** | Manifest, permissions, ProGuard, lifecycle violations, context leaks |
| **ios** | plist, ATS, keychain, signing, main thread UI, retain cycles |
| **backend** | DTO mismatch, HTTP codes, SQL injection, auth flaws, rate limiting |
| **general** | Null pointers, resource leaks, race conditions, XSS, input validation |

Defined in: `packages/core/src/prompts/platform-rules.ts`

## Scoring System

The scoring is **deterministic** (no AI) - pure rule-based evaluation:

| Criteria | Points | Max |
|----------|--------|-----|
| P0 Finding | +15 | 45 |
| P1 Finding | +8 | 32 |
| P2 Finding | +3 | 12 |
| False Positive | -10 | -30 |
| Concrete Fix | +5 | 25 |
| File Accuracy | +2 | 10 |
| Clarity | 0-10 | 10 |

**Maximum possible score**: 134
**Minimum possible score**: -30

Defined in: `packages/core/src/engine/judge.ts`

## Debate Modes

| Mode | Description |
|------|-------------|
| **adversarial** | Agents challenge each other's positions |
| **consensus** | Agents work to find common ground |
| **collaborative** | Agents build on each other's ideas |

## Project Structure

```
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
```

## Integration

### Claude Desktop

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

### Claude CLI

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

### VS Code / Cursor

Install the VS Code extension - it auto-configures MCP.

## Development

```bash
# Clone repo
git clone https://github.com/ferdiangunawan/debate-agent-mcp
cd debate-agent-mcp

# Install dependencies
npm install

# Build all packages
npm run build

# Build specific package
npm run build:core
npm run build:server
npm run build:extension
```

## Known Limitations

- **Experimental**: APIs may change without notice
- **Local CLIs required**: You must have `claude` and `codex` CLIs installed and authenticated
- **Timeout risks**: Long diffs may cause agent timeouts (default 180s)
- **No streaming**: Currently waits for full response before processing
- **Minimum 2 agents**: 360 debate requires at least 2 agents for cross-review

## Contributing

Contributions welcome! Please open an issue first to discuss proposed changes.

## License

MIT