debate-hall-mcp 0.4.0

Production-grade MCP server for Wind/Wall/Door multi-perspective debate orchestration

debate-hall-mcp

Production-grade MCP server for Wind/Wall/Door multi-perspective debate orchestration.

Table of Contents

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

---

For AI Agents

===AGENT_BOOTSTRAP===
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 for decision records

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
uv pip install -e ".[dev]"

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?

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

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

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

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 (496 tests, 92%+ coverage)
pytest

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

License

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