Skip to main content
Glama
debate-hall-mcp

debate-hall-mcp

by elevanaltd

debate-hall-mcp

License CI PyPI version Python 3.11+

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


Related MCP server: DebateTalk MCP

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

Tool

Purpose

init_debate

Create debate: thread_id, topic, mode?, max_turns?

add_turn

Record turn: thread_id, role, content

get_debate

View state: thread_id, include_transcript?

close_debate

Finalize: thread_id, synthesis, output_format?, seal?

Mode Tools

Tool

Purpose

pick_next_speaker

Set next speaker (mediated mode)

Admin Tools

Tool

Purpose

force_close_debate

Emergency shutdown (I5 kill switch)

tombstone_turn

Redact turn (preserves hash chain)

GitHub Tools

Tool

Purpose

github_sync_debate

Sync turns to GitHub Discussion/Issue

ratify_rfc

Generate ADR from synthesis, create PR

human_interject

Inject human GitHub comment into debate

Auto-Orchestration Tools

Tool

Purpose

run_debate

Run complete Wind→Wall→Door debate automatically

resume_debate

Resume a PAUSED debate after failure

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

Doc

Content

Usage Patterns

Recipes, tuning, agent tiers, cognition prompts

Evidence

Empirical research validating the approach

Architecture

Execution tiers, Wall content contract

Examples

Real multi-model debate patterns

Agents

Wind/Wall/Door agent definitions

Skills

AI agent skill installation

The Pattern

Three cognitive voices in tension:

Role

Cognition

Voice

Wind

PATHOS

"What if..." — expansive, visionary

Wall

ETHOS

"Yes, but..." — grounding, critical

Door

LOGOS

"Therefore..." — synthesizing, decisive

Architecture Immutables

ID

Principle

I1

Cognitive State Isolation — server manages state

I2

OCTAVE Binding — exportable semantic transcripts

I3

Finite Closure — hard turn/round limits

I4

Verifiable Ledger — SHA-256 hash chain

I5

Safety Override — admin kill switch

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

Setting

Environment Variable

Recommended Value

State directory

DEBATE_HALL_STATE_DIR

/var/lib/debate-hall/

OpenRouter API

OPENROUTER_API_KEY

Use secret manager

GitHub token

GITHUB_TOKEN

Use secret manager

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)

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.

Available Tools

17 tools
add_turnC

Record turn. role:Wind|Wall|Door. cognition:PATHOS|ETHOS|LOGOS→validates content.

Inputs: role (required), content (required), thread_id (required), model, +5 more. Returns: object

close_debateC

Finalize debate. synthesis:Door's final resolution->closes room.

Args: output_format: 'json' (default), 'octave', or 'both' seal: Add cryptographic seal to OCTAVE output for tamper detection (v1.0.0) export_decision: Export DecisionRecord to context directory for search indexing (Issue #138). Creates an OCTAVE file in .hestai/state/context/decisions/ that search_decisions can find.

Inputs: synthesis (required), thread_id (required), seal, output_format, +1 more. Returns: result

consultA

Create advisory consultation session. advisor answers questioner's question.

Creates a two-party mediated session where a questioner asks an advisor for guidance. The question is recorded as the first turn.

Args: topic: What the consultation is about advisor_role: Who to consult (e.g. "TMG", "CE") question: The specific question being asked questioner_role: Who is asking (default: "Questioner") thread_id: Custom thread ID (auto-generated if omitted) context: Additional context for the advisor max_turns: Consultation turn limit (default: 6)

Returns: Dictionary with thread_id, status, session_type, question, advisor_role, questioner_role, awaiting, turn_count

Inputs: topic (required), question (required), advisor_role (required), context, +3 more. Returns: object

conveneA

Assemble committee for group decision. members respond, chair manages order.

Creates a mediated committee session where multiple agents deliberate. Supports go_nogo (GO/NO-GO extraction), vote, and review decision types.

Args: topic: What the committee is deciding members: Committee member roles (e.g. ["CRS", "CE"]) brief: The brief/description for the committee chair_role: Who chairs the committee (default: "Chair") decision_type: "go_nogo" | "vote" | "review" (default: "review") thread_id: Custom thread ID (auto-generated if omitted) context: Additional context for the committee max_turns: Committee turn limit (default: 12)

Returns: Dictionary with thread_id, status, session_type, decision_type, chair_role, members, awaiting, turn_count

Inputs: brief (required), topic (required), members (required), context, +4 more. Returns: object

extract_decision_recordA

Extract a DecisionRecord from a closed debate.

The "Cognitive Notary" product - a verified record that can be indexed, searched, and cited by future decision-making agents.

Args: thread_id: Thread identifier of closed debate

Returns: Dictionary with DecisionRecord fields: - thread_id, topic, decided_at (identity) - synthesis, decision_hash, status (outcome) - wind_perspectives, wall_constraints, door_refinements (rationale) - consensus_reached, consensus_votes, refinement_count (validation) - extracted_at, source_hash, turn_count (provenance)

Raises: FileNotFoundError: If thread doesn't exist ValueError: If debate is not closed (ACTIVE or PAUSED status)

Inputs: thread_id (required). Returns: object

force_close_debateC

I5:safety override. reason:logged→force closes any state.

Inputs: reason (required), thread_id (required). Returns: object

get_debateB

State+optional transcript. include_transcript→adds turn history. context_turns:limit depth.

Inputs: thread_id (required), context_turns, include_metadata, include_transcript. Returns: object

github_sync_debateA

Sync debate turns to GitHub Discussion/Issue comments.

Posts new turns as formatted comments with cognition headers. Idempotent: tracks synced turns to avoid duplicates.

Args: thread_id: The debate thread to sync repo: Repository in owner/repo format target_id: GitHub node ID (discussions) or issue number (issues) target_type: 'discussion' (GraphQL) or 'issue' (REST)

Note: Can be disabled by setting GITHUB_TOOLS_ENABLED=false

Inputs: repo (required), target_id (required), thread_id (required), target_type. Returns: object

human_interjectB

Inject human GitHub comment into active debate as context.

Fetches comment from GitHub and adds to debate context. Detects which role was replied to for injection typing.

Args: thread_id: The debate thread to inject into repo: Repository in owner/repo format target_id: GitHub node ID (discussions) or issue number (issues) comment_id: Comment node ID (DC_...) or issue comment ID (numeric)

Note: Can be disabled by setting GITHUB_TOOLS_ENABLED=false

Inputs: repo (required), target_id (required), thread_id (required), comment_id (required). Returns: object

init_debateC

Create room. mode:fixed|mediated. strict_cognition->validate turns.

Inputs: topic (required), thread_id (required), mode, max_turns, +3 more. Returns: object

pick_next_speakerB

Mediated mode only. role:Wind|Wall|Door→sets next expected speaker.

Inputs: role (required), thread_id (required). Returns: object

ratify_rfcA

Generate ADR from Door synthesis and create PR.

Requires: Debate must be closed with synthesis.

Args: thread_id: The debate thread to ratify repo: Repository in owner/repo format adr_number: Explicit ADR number (required to prevent collisions) target_id: Optional reference ID for linking (e.g., discussion node ID) adr_path: Path for ADR file in repo (default: docs/adr/)

Returns: Dictionary with pr_url, pr_number, adr_path, branch_name

Note: Can be disabled by setting GITHUB_TOOLS_ENABLED=false

Inputs: repo (required), thread_id (required), adr_number (required), adr_path, +1 more. Returns: object

resolve_questionA

Resolve a question through structured debate and return decision record.

High-level Layer 3 API that combines run_debate + extract_decision_record into a single operation. Agents call this for quick, verified decisions.

Process:

  1. Generate thread_id if not provided (YYYY-MM-DD-topic-slug format)

  2. Run full Wind/Wall/Door debate via run_debate

  3. Extract DecisionRecord from closed debate

  4. Return verified decision ready for use

Args: topic: The question or topic to resolve tier: Tier configuration name (default: "standard") thread_id: Optional custom thread ID (auto-generated if None)

Returns: Dictionary with DecisionRecord fields plus debate metadata: - All DecisionRecord fields (identity, outcome, rationale, validation, provenance) - debate_result: The raw run_debate result for reference

Raises: RuntimeError: If debate fails or cannot be closed ValueError: If tier configuration is invalid

Inputs: topic (required), tier, thread_id. Returns: object

resume_debateA

Resume a PAUSED debate from where it left off (Phase 4).

Allows resuming debates that were paused due to failures (provider timeouts, errors, etc.) during auto-orchestration.

Args: thread_id: The thread ID of the paused debate tier: Configuration tier (default: "standard") compression_tier: Override compression tier (None = use tier default) primer_tier: Override primer tier (None = use tier default)

Returns: Dictionary with thread_id, topic, status, turn_count, and synthesis

Inputs: thread_id (required), tier, primer_tier, compression_tier. Returns: object

run_debateA

Auto-orchestrate a Wind/Wall/Door debate (ADR-0002).

Runs a complete automated debate with three agents:

  • Wind (PATHOS): Expands possibilities and explores alternatives

  • Wall (ETHOS): Validates against constraints and evidence

  • Door (LOGOS): Synthesizes a third-way resolution

Args: topic: The debate topic to explore tier: Configuration tier (default: "standard") thread_id: Optional custom thread ID (auto-generated if not provided) compression_tier: Override compression tier (None = use tier default) primer_tier: Override primer tier (None = use tier default) context_files: Optional list of absolute file paths to inject as codebase context. Agents will see file contents in their prompts. mode: Debate mode - "standard" for full Wind/Wall/Door debate, "speed" for lightweight Speed Dialogue Mode (Issue #139), "raci" for RACI governance mode (Turn Manifest Compiler). raci_config: Required when mode="raci". Dictionary with RACI roles: - responsible: Proposer role name (required) - accountable: Decision maker role name (required) - consulted: List of advisor role names (optional, max 5) - informed: List of observer role names (optional, max 3, post-verdict OBSERVATION turns)

Returns: Dictionary with thread_id, topic, status, turn_count, and synthesis

Inputs: topic (required), mode, tier, thread_id, +4 more. Returns: object

search_decisionsA

Search for past decisions matching a query.

Uses field-weighted BM25 to find relevant decisions from the decisions directory. Returns ranked results with relevance scores.

Field weights (ADR-0004):

  • SEARCH_ANCHORS: 15.0 (pre-computed Q&A)

  • TOPIC: 10.0 (what it is)

  • TAGS: 8.0 (classification)

  • SYNTHESIS: 5.0 (the decision)

  • RATIONALE: 2.0 (wind/wall perspectives)

Args: query: Search query string limit: Maximum number of results (default 10) min_score: Minimum score threshold 0-1 (default 0.0)

Returns: Dictionary with: - query: The search query - count: Number of results - results: List of matching decisions with thread_id, topic, synthesis, score, decided_at, file_path

Inputs: query (required), limit, min_score. Returns: object

tombstone_turnD

I4:redact content→hash chain preserved. turn_index:0-based.

Inputs: reason (required), thread_id (required), turn_index (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 17 tools

    Disambiguation3/5

    Most tools are distinct, but init_debate, run_debate, resolve_question, consult, and convene all create or orchestrate sessions, so an agent could easily pick the wrong one. Descriptions separate manual vs auto vs committee/consultation modes, yet the overlapping names and session-creating behavior leave some ambiguity.

    Naming Consistency4/5

    Tool names are predominantly snake_case with a verb-first pattern (init_debate, add_turn, get_debate, close_debate, run_debate). A few names deviate, such as github_sync_debate (noun-led), human_interject (no direct object), and bare consult/convene, but the pattern is still readable and mostly predictable.

    Tool Count3/5

    The 17 tools exceed the typical 3-15 well-scoped range, and several utilities (force_close_debate, tombstone_turn, human_interject) are niche. The set still covers multiple subdomains, but the count feels heavy and includes some redundant high-level conveniences like resolve_question on top of run_debate+extract_decision_record.

    Completeness2/5

    The core debate lifecycle has init, add, get, close, force close, speaker picking, and tombstoning, but there is no way to list active debates or delete/archive a thread. More critically, consult and convene create sessions that return awaiting states, yet no tool exists to add advisor/committee turns, leaving those workflows half-built.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables multi-round brainstorming debates between multiple AI models like GPT, DeepSeek, and Ollama to produce synthesized final outputs. Users can orchestrate parallel model interactions where AI agents critique and refine each other's ideas to reach a consolidated conclusion.
      7
      111 npm
      73
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to facilitate structured multi-model debates that synthesize multiple perspectives into clear categories like ground truths and blind spots. It provides tools for running real-time debates, checking model health, and managing history via the Model Context Protocol.
      42 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Facilitates structured multi-agent debates with arguments, rebuttals, and judgments across multiple rounds, enabling diverse AI personas to engage in formal debate and collaborative problem-solving.
      1
      30 npm
      17
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables multi-agent debate cross-examination and consensus arbitration through a deterministic, zero-dependency MCP server, providing structured outputs and telemetry for autonomous AI workflows.
      -