# Ultimate Debate MCP Server

A Model Context Protocol (MCP) server that enables **Claude + GPT adversarial collaboration**. GPT-5.2 automatically critiques, debates, and verifies Claude's work for higher-quality outputs.

## Features

- **`gpt_critique`** - Single-pass adversarial critique of code, plans, or text
- **`gpt_verify`** - Verify that fixes actually resolve identified issues
- **`debate`** - Multi-round debate loop between Claude and GPT

## Requirements

- Node.js >= 20.0.0
- OpenAI API key with GPT-5.2 access
- Claude Code CLI

## Installation

### 1. Clone and Build

```bash
git clone https://github.com/YOUR_USERNAME/ultimate-debate-mcp.git
cd ultimate-debate-mcp
npm install
npm run build
```

### 2. Install Globally in Claude Code

```bash
# Add the MCP server globally (works in any folder)
claude mcp add ultimate-debate --scope user -- node /path/to/ultimate-debate-mcp/dist/index.js
```

### 3. Configure Environment Variables

Edit your `~/.claude.json` and find the `mcpServers` section at the root level. Add your OpenAI API key:

```json
{
  "mcpServers": {
    "ultimate-debate": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/ultimate-debate-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key",
        "OPENAI_MODEL": "gpt-5.2",
        "RATE_LIMIT_RPM": "100",
        "RATE_LIMIT_RPH": "1000",
        "CACHE_MAX_SIZE": "100",
        "CACHE_TTL_MS": "3600000"
      }
    }
  }
}
```

### 4. Restart Claude Code

Close and reopen Claude Code. Verify installation:

```
/mcp
```

You should see `ultimate-debate` listed with 3 tools.

## Configuration Options

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENAI_API_KEY` | required | Your OpenAI API key |
| `OPENAI_MODEL` | `gpt-5.2` | Model to use (gpt-5.2, gpt-4o, etc.) |
| `RATE_LIMIT_RPM` | `100` | Max requests per minute |
| `RATE_LIMIT_RPH` | `1000` | Max requests per hour |
| `CACHE_MAX_SIZE` | `100` | Max cached responses |
| `CACHE_TTL_MS` | `3600000` | Cache TTL (1 hour) |

## Auto-Collaboration Setup

To make Claude automatically use GPT review, add these rules to your global `~/.claude/CLAUDE.md`:

```markdown
# Auto-Collaboration Rules

When the `ultimate-debate` MCP server is available, automatically:

1. **Before implementation** (>20 lines): Call `gpt_critique` on the plan
2. **After implementation**: Call `gpt_critique` on the code
3. **After fixing issues**: Call `gpt_verify` to confirm resolution
4. **For architecture decisions**: Call `debate` with 2 rounds

## Decision Criteria

| Change Type | Action |
|-------------|--------|
| New feature | `debate` (2 rounds) |
| Bug fix | `gpt_critique` + `gpt_verify` |
| Refactor | `gpt_critique` |
| Trivial (<10 lines) | Skip review |

## Skip Review

Say "skip review" or "no gpt" to bypass auto-collaboration.
```

## Usage Examples

### Manual Critique

Ask Claude to review code:
```
Critique this authentication code for security issues
```

### Manual Debate

For architecture decisions:
```
Debate whether we should use Redis or PostgreSQL for session storage
```

### Manual Verify

After fixing issues:
```
Verify the SQL injection fix is complete
```

## MCP Tools Reference

### `gpt_critique`

Single-pass adversarial critique.

**Parameters:**
- `content` (required) - The content to critique
- `context` (optional) - Additional context
- `focus_areas` (optional) - Array of: `logic`, `security`, `performance`, `edge_cases`, `assumptions`, `completeness`

**Returns:** Issues with severity (critical/high/medium/low), category, and suggestions.

### `gpt_verify`

Verify fixes are resolved.

**Parameters:**
- `original` (required) - Original content before fix
- `revised` (required) - Revised content after fix
- `issues_to_check` (required) - Array of issues to verify

**Returns:** Lists of verified, unresolved, and new issues.

### `debate`

Multi-round debate loop.

**Parameters:**
- `goal` (required) - The objective to debate
- `context` (optional) - Additional context
- `artifacts` (optional) - Code, diffs, specs, logs
- `rounds` (default: 2) - Number of debate rounds (1-5)
- `confidence_threshold` (default: 0.8) - Stop early if confidence reached
- `budget` (optional) - Token and cost limits

**Returns:** Critical issues, resolved issues, suggested patches, test recommendations.

## Development

```bash
npm install      # Install dependencies
npm run build    # Build for production
npm run dev      # Development mode with hot reload
npm run test     # Run tests
npm run lint     # Run linter
```

## License

MIT