ultimate-debate-mcp

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

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

# 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:

{
  "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:

# 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

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