# agent-discussion-mcp

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

Supports **Solo** execution with tag routing and bounded **Discussion** mode: independent proposals, parallel critique, an independent judge, bounded revision rounds, and SQLite event logs with WAL mode.

See [dsaa.md](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 Execution (`run_solo`)**: Run single-agent tasks directly by agent name or automatically route by tag matching without guessing on ambiguity.
- **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, 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.
- **Client Progress Reporting**: Native MCP progress notifications (`ctx.report_progress`) during multi-round debates.

---

## 🚀 Quick Start

### Installation & Running

```bash
# 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 a named agent or tag-routed agent.
- **`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

| Variable | Fallback (Legacy) | Default | Description |
|---|---|---|---|
| `AGENT_DISCUSSION_API_KEY` | `API_AGENT_API_KEY` | `""` | API key for OpenAI-compatible endpoint |
| `AGENT_DISCUSSION_BASE_URL` | `API_AGENT_BASE_URL` | `https://api.openai.com/v1` | Base URL for `/chat/completions` |
| `AGENT_DISCUSSION_MODEL` | `API_AGENT_MODEL` | `gpt-4o-mini` | Default model for agents without custom override |
| `AGENT_DISCUSSION_DB` | `API_AGENT_DB` | `~/.agent_discussion_mcp/data.db` | SQLite database path for profiles and session audit events |
| `AGENT_DISCUSSION_TIMEOUT` | `API_AGENT_TIMEOUT` | `120` | HTTP request timeout in seconds |

---

## 🧪 Testing & Development

Run the test suite with `pytest`:

```bash
uv run pytest
```

---

## 🗺️ Roadmap

1. ✅ Solo mode and profile registry
2. ✅ Bounded Discussion with independent proposals, critics, judge, blackboard, and output-token budget
3. ⏳ Subagent verification and resumable background execution for long-running discussions

---

## 📄 License

MIT