debate-hall-mcp

MCP server for Wind/Wall/Door multi-perspective debate orchestration with production-oriented design patterns.

Production Status: This server implements production-minded patterns (validation, bounded operation, atomic persistence) suitable for development and small-scale deployments. For larger production deployments, see production deployment considerations.

Table of Contents

• What It Does
• Quick Start
• Installation
• MCP Tools
• Configuration
• Example
• Documentation
• Contributing

For AI Agents

===AGENT_BOOTSTRAP===
DEV_BOOTSTRAP::scripts/dev-bootstrap.sh
DEV_HOOKS_OPT_IN::scripts/install-git-hooks.sh[core.hooksPath=.githooks]→DEBATE_HALL_AUTO_BOOTSTRAP=1
SKILL::skills/debate-hall/SKILL.md
WORKFLOW::init→turn→get→close
AGENTS::agents/README.md[Wind/Wall/Door definitions]
COGNITIONS::agents/cognitions/[PATHOS|ETHOS|LOGOS overlays]
RECIPES::[SPEED(3)|STANDARD(12)|DEEP(36)|FORTRESS|LABORATORY]
===END===

What It Does

• Structured debates with Wind (explore) → Wall (constrain) → Door (synthesize)
• Deterministic state with turn limits, hash chain, and verifiable transcripts
• Multiple modes: Fixed sequence or mediated orchestration
• GitHub integration: Sync debates to Discussions, create ADRs from synthesis
• OCTAVE export: Semantic compression format with tamper-proof sealing (v1.0.0)

Quick Start

1. Install

pip install debate-hall-mcp

2. Configure MCP Client

Add to Claude Desktop (claude_desktop_config.json) or Claude Code (~/.claude.json):

{
  "mcpServers": {
    "debate-hall": {
      "command": "debate-hall-mcp"
    }
  }
}

3. Start a Debate

User: Start a debate about whether to rewrite our backend in Rust

Claude: [calls init_debate with thread_id="rust-rewrite",
         topic="Should we rewrite our backend in Rust?"]

4. Run the Dialectic

Wind → "What if we rewrote in Rust? Memory safety, performance..."
Wall → "Yes, but: team expertise, ecosystem maturity, timeline..."
Door → "Therefore: Profile hotspots first, consider Rust for specific components..."

That's it. For GitHub integration, see Configuration.

Installation

PyPI:

pip install debate-hall-mcp
# or
uv pip install debate-hall-mcp

From source:

git clone https://github.com/elevanaltd/debate-hall-mcp
cd debate-hall-mcp
./scripts/dev-bootstrap.sh
uv pip install -e ".[dev]"

Development bootstrap (worktrees/branches)

One-command setup:

./scripts/dev-bootstrap.sh

Optional: enable repo-local git hooks (prints reminder, or auto-runs bootstrap when DEBATE_HALL_AUTO_BOOTSTRAP=1):

./scripts/install-git-hooks.sh

MCP Tools

Core Tools

Mode Tools

Admin Tools

GitHub Tools

Auto-Orchestration Tools

Configuration

Minimal (No GitHub)

The MCP config above is sufficient for local debates.

With GitHub Integration

1. Copy .env.example to .env
2. Add your GitHub token:

   GITHUB_TOKEN=ghp_your_token_here
   

Token scopes needed: repo, write:discussion Get one at: GitHub → Settings → Developer settings → Personal access tokens

Tier Configuration (Auto-Orchestration)

The run_debate tool uses tier configurations to determine which AI providers to use for each role.

Quick Start:

# Copy the template and add your API key
cp tiers.yaml.example tiers.yaml
export OPENROUTER_API_KEY=your-key-here

Resolution order:

1. DEBATE_HALL_TIERS_FILE environment variable
2. ./tiers.yaml (project root)
3. ~/.debate-hall/tiers.yaml (user home)
4. Built-in defaults

See tiers.yaml.example for all configuration options including CLI providers and custom prompts.

Example tier configuration:

# ~/.debate-hall/tiers.yaml
standard:
  wind:
    provider: cli      # Use external CLI (claude, codex, gemini)
    cli: claude
    role: wind-agent   # Optional: role for PAL MCP
  wall:
    provider: cli
    cli: codex
  door:
    provider: cli
    cli: gemini
  settings:
    consensus_required: true   # Wind/Wall must approve synthesis
    max_turns: 12
    max_refinement_loops: 3

premium:
  wind:
    provider: openrouter       # Use OpenRouter API
    model: anthropic/claude-3-opus
  wall:
    provider: openrouter
    model: openai/gpt-4-turbo
  door:
    provider: openrouter
    model: google/gemini-pro
  settings:
    consensus_required: true
    max_turns: 20
    max_refinement_loops: 5

Provider options:

• cli: External AI CLIs (requires claude, codex, or gemini CLI installed)
• openrouter: OpenRouter API (requires OPENROUTER_API_KEY env var)

Settings:

• consensus_required: If true, Wind and Wall must approve Door's synthesis
• max_turns: Maximum total turns in debate
• max_refinement_loops: How many times Door can refine after rejection

See Usage Patterns for detailed configuration options.

Example

Thread: "microservices-vs-monolith"
Topic: "Should we migrate to microservices?"

[WIND] "What if we decomposed into services? Independent scaling,
        technology diversity, team autonomy..."

[WALL] "Yes, but we have 3 developers. Microservices add operational
        complexity, network latency, distributed transactions..."

[DOOR] "Therefore: Start with a modular monolith. Design service
        boundaries now, but keep deployment unified. Extract services
        only when team grows or specific scaling needs emerge."

Documentation

The Pattern

Three cognitive voices in tension:

Architecture Immutables

Production Deployment Considerations

While debate-hall-mcp implements production-minded patterns (validation, bounded operation, atomic persistence), there are considerations for larger-scale production deployments.

For comprehensive deployment guidance, see Production Deployment Guide.

Current Strengths

• Deterministic behavior: Rule-based validation with no LLM dependency
• Resource limits: Hard turn/round limits prevent runaway sessions
• Atomic persistence: File writes use atomic replace with fsync
• Concurrency control: File locking with Compare-and-Swap (CAS) for race prevention
• Content verification: SHA-256 hash chain with optional tamper detection
• GitHub integration: Rate-limit handling and feature toggles

Quick Configuration

Production Checklist

Before deploying at scale:

• Configure DEBATE_HALL_STATE_DIR to dedicated path outside repository
• Set proper file permissions (600 for state files, 700 for directory)
• Use explicit secret injection (avoid .env in production)
• Plan for state backup/retention
• Monitor file lock contention if using multiple workers
• Consider database backend for >10 concurrent instances (#106)

Recommended Use Cases

Well-suited for:

• Development and testing workflows
• Single-instance or low-concurrency deployments
• Scripted automation with sequential debates
• Research and experimentation

Requires additional work for:

• High-concurrency multi-instance production environments
• Large-scale orchestration with 10+ concurrent debates

Contributing

See CONTRIBUTING.md for development setup, testing, and guidelines.

# Quick dev setup
git clone https://github.com/elevanaltd/debate-hall-mcp
cd debate-hall-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests (800+ tests)
pytest

# Quality checks
ruff check src tests && mypy src && black --check src tests

License

Apache-2.0 — Built with HestAI and MCP Python SDK.