agent-discussion-mcp

Model Context Protocol (MCP) server for reusable role-based agents, autonomous task execution in workspaces, structured multi-agent debates, peer critiques, and independent judge consensus.

Supports Solo autonomous execution with workspace tools (file editing, shell execution, heartbeat, watchdog protection) and bounded Discussion mode: independent proposals, parallel critique, an independent judge, bounded revision rounds, and SQLite event logs with WAL mode.

See dsaa.md for the original project vision and architectural notes (Russian).

✨ Features

• Role Profiles ("Gems"): Reusable agent profiles with custom roles, system prompts, model overrides, routing tags, temperature, and output token limits.

• Solo Autonomous Execution (run_solo):

  • Run single-agent tasks directly by agent name, or route by tags.

  • Pass working_dir (or workspace_path) to grant the agent full autonomous workspace execution capabilities:

    • list_files: Find files matching glob patterns.

    • read_file: Inspect file contents.

    • write_file: Create or overwrite files.

    • replace_in_file: Targeted surgical text replacement.

    • run_command: Execute bash shell commands directly inside the workspace directory (e.g. running tests, linters, or build commands).

  • Pass custom prompt to override or augment the profile's instructions for a specific task.

• Heartbeat & Inactivity Watchdog Protection:

  • Heartbeat reporting: Emits periodic MCP progress notifications (ctx.report_progress) every 15s (heartbeat_interval_seconds) so the calling agent or client knows the agent is alive and progressing.

  • Inactivity Watchdog: Automatically detects hung or frozen processes (inactivity_timeout_seconds, default 300s) and aborts stuck tasks.

  • Step Limit: Prevents runaway execution loops (max_steps, default 25).

  • Repetition Detector: Detects and breaks out of repetitive identical tool failure loops.

• Structured Discussion Mode (run_discussion):

  1. Independent Proposals: Participating agents draft proposals in parallel without seeing other agents' work.

  2. Peer Critique: Agents review all proposals and produce structured critiques (strengths, concerns, questions).

  3. Independent Judge: A designated judge evaluates the blackboard and decides consensus vs. no-consensus with a defensible final answer and confidence score.

  4. Bounded Revision: If no consensus is reached, agents revise their proposals addressing critiques for up to max_rounds.

• Shared Token Budget: Dynamic token reservation and settlement preventing token overrun in concurrent calls.

• Event Sourcing & Audit Log: Monotonic append-only SQLite log (session_events) recording all proposals, critiques, tool calls, verdicts, and errors in WAL mode.

• Transient Error Resilience: Exponential backoff with jitter on network/HTTP status errors (408, 409, 429, 5xx) and fallback verdict if a judge fails.

Related MCP server: AgentPrism Workflows

🚀 Quick Start

Installation & Running

# Clone the repository
git clone https://github.com/ewanni/agent-discussion-mcp.git
cd agent-discussion-mcp

# Install dependencies with uv
uv sync --extra test

# Configure provider settings
export AGENT_DISCUSSION_API_KEY="your-openai-or-compatible-key"
export AGENT_DISCUSSION_BASE_URL="https://api.openai.com/v1"
export AGENT_DISCUSSION_MODEL="gpt-4o-mini"

# Run the MCP server over stdio
uv run agent-discussion-mcp

(Note: legacy API_AGENT_* environment variables and api-agent-mcp CLI binary are also supported for backwards compatibility).

🛠️ MCP Tools & Resources

Tools

• create_agent: Register a new agent profile (name, role, system_prompt, model, tags, temperature, max_output_tokens).

• update_agent: Modify fields of an existing profile.

• list_agents: Inspect all registered profiles (omits private system prompts / credentials).

• run_solo: Execute a task with an agent.

  • task (required): Task description.

  • working_dir (optional): Path to working directory. When provided, the agent receives workspace tools (read_file, write_file, replace_in_file, list_files, run_command).

  • prompt (optional): Custom system prompt or additional instructions.

  • agent (optional): Name of the agent profile (or routed by task tags).

  • max_steps (optional, default 25): Maximum ReAct tool steps before terminating.

  • inactivity_timeout_seconds (optional, default 300): Watchdog threshold to prevent hanging.

  • heartbeat_interval_seconds (optional, default 15): Interval for MCP progress heartbeat notifications.

• run_discussion: Run a bounded debate with 2–5 participant agents, a separate judge, round limit (1–5), and a shared completion token budget.

Resources

• agent://profiles/{name}: Read a specific agent profile configuration as JSON.

⚙️ Configuration & Environment Variables

🧪 Testing & Development

Run the test suite with pytest:

uv run pytest

🗺️ Roadmap

1. ✅ Solo mode and profile registry

2. ✅ Bounded Discussion with independent proposals, critics, judge, blackboard, and output-token budget

3. ✅ Solo autonomous workspace execution (file tools, bash commands, heartbeat, and watchdog)

4. ⏳ Subagent verification during discussions and resumable background sessions

📄 License

MIT