debate-hall-mcp
Enables syncing debate turns to GitHub Discussions, generating Architecture Decision Records (ADRs) from synthesis, and injecting human comments for review.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@debate-hall-mcp Start a debate on remote work policy"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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-mcp2. 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-mcpFrom 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.shOptional: enable repo-local git hooks (prints reminder, or auto-runs bootstrap when DEBATE_HALL_AUTO_BOOTSTRAP=1):
./scripts/install-git-hooks.shMCP Tools
Core Tools
Tool | Purpose |
| Create debate: |
| Record turn: |
| View state: |
| Finalize: |
Mode Tools
Tool | Purpose |
| Set next speaker (mediated mode) |
Admin Tools
Tool | Purpose |
| Emergency shutdown (I5 kill switch) |
| Redact turn (preserves hash chain) |
GitHub Tools
Tool | Purpose |
| Sync turns to GitHub Discussion/Issue |
| Generate ADR from synthesis, create PR |
| Inject human GitHub comment into debate |
Auto-Orchestration Tools
Tool | Purpose |
| Run complete Wind→Wall→Door debate automatically |
| Resume a PAUSED debate after failure |
Configuration
Minimal (No GitHub)
The MCP config above is sufficient for local debates.
With GitHub Integration
Copy
.env.exampleto.envAdd your GitHub token:
GITHUB_TOKEN=ghp_your_token_here
Token scopes needed:
repo,write:discussionGet 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-hereResolution order:
DEBATE_HALL_TIERS_FILEenvironment variable./tiers.yaml(project root)~/.debate-hall/tiers.yaml(user home)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: 5Provider options:
cli: External AI CLIs (requiresclaude,codex, orgeminiCLI installed)openrouter: OpenRouter API (requiresOPENROUTER_API_KEYenv var)
Settings:
consensus_required: If true, Wind and Wall must approve Door's synthesismax_turns: Maximum total turns in debatemax_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 |
Recipes, tuning, agent tiers, cognition prompts | |
Empirical research validating the approach | |
Execution tiers, Wall content contract | |
Real multi-model debate patterns | |
Wind/Wall/Door agent definitions | |
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 |
|
|
OpenRouter API |
| Use secret manager |
GitHub token |
| Use secret manager |
Production Checklist
Before deploying at scale:
Configure
DEBATE_HALL_STATE_DIRto dedicated path outside repositorySet proper file permissions (600 for state files, 700 for directory)
Use explicit secret injection (avoid
.envin 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 testsLicense
Apache-2.0 — Built with HestAI and MCP Python SDK.
Available Tools
17 toolsadd_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:
Generate thread_id if not provided (YYYY-MM-DD-topic-slug format)
Run full Wind/Wall/Door debate via run_debate
Extract DecisionRecord from closed debate
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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
Open governance for AI agents: discover live debates, deliberate, vote, follow, and invite.
Public governance wiki where AI agents propose, debate, amend and vote.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
Git collaboration for AI agents and people: tasks, hand-offs, reviews, teams, shared memory.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables 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.7111 npm73MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm1MIT
- AlicenseAqualityDmaintenanceFacilitates 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.130 npm17MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables multi-agent debate cross-examination and consensus arbitration through a deterministic, zero-dependency MCP server, providing structured outputs and telemetry for autonomous AI workflows.-