# Roundtable MCP

**Role-Based Multi-Model Orchestration Server** — Turn multiple AI models into a coordinated expert council.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Standard](https://img.shields.io/badge/MCP-1.0.0-blue.svg)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org/)

---

## 🏛️ What is Roundtable?

**Roundtable MCP** is a Model Context Protocol (MCP) server designed for role-based multi-model council orchestration.

Instead of asking several models the same question and voting on their answers, Roundtable assigns each model a specialized role, equips them with custom skill guidelines, runs them across a **3-tier priority execution pipeline** (Antigravity CLI, Local Ollama, Cloud APIs), and synthesizes their findings into unified reports automatically persisted to your Obsidian Vault.

```
                 ┌── Architect (Gemini 3.7 Flash) ────┐
                 ├── Developer (Gemma 4 Local GPU) ───┤
Prompt ──────────┼── QA Tester (Claude Sonnet 4.6) ───┼──> Synthesis Report
                 └── DevOps (GPT-OSS 120B) ───────────┘
                       PARALLEL ROUNDTABLE
```

---

## 💡 Key Capabilities

- **👥 Parallel Expert Panels (`roundtable_start`)**: Execute multiple specialized LLMs (Gemini, Claude, Gemma, GPT-OSS) simultaneously for multi-dimensional problem solving.
- **⚡ Host Delegation & Exclusion**: Automatically skips spawning redundant background CLI/API subprocesses for the active host model, delegating lead synthesis directly to the live session.
- **🌊 Sequential Cascade Relays (`roundtable_cascade`)**: Pipeline tasks across multi-stage handoffs (`Architect` $\rightarrow$ `Developer` $\rightarrow$ `QA` $\rightarrow$ `DevOps`).
- **🛡️ 3-Tier Execution Pipeline**: Prioritizes zero-config Antigravity CLI (leveraging your subscription Google OAuth), falls back to Local Ollama GPU, and routes to direct Cloud APIs when needed.
- **🎯 Dynamic Roles & Skills Engine (`roundtable_roles`, `roundtable_assign_role`)**: Assign models distinct roles (`ROLES.md`) with dynamic `.skill` and `SKILL.md` rules.
- **📓 Persistent Obsidian Memory & Graph Hubs (`roundtable_save`, `roundtable_search`)**: Automatically log sessions, search past memories, and ingest documents/folders with 30-minute auto-save throttling and automatic Graph View clustering.
- **🔍 Honest Execution (Zero Faked Personas)**: No single-model roleplay simulations. If a model is offline or out of quota, Roundtable honestly reports the connectivity diagnostic.

---

## 🛠️ Official Tools Catalog

| Official Tool Name | Mode / Category | Description |
|:---|:---|:---|
| **`roundtable_start`** | 👥 **Parallel Council** | Starts a multi-model council advisory discussion across registered expert models. |
| **`roundtable_cascade`** | 🌊 **Sequential Relay** | Runs multi-stage sequential relay (`Architect ➔ Dev ➔ QA ➔ DevOps`). |
| **`roundtable_route`** | 🎯 **Single Router** | Routes a specialized prompt to a single target model or role. |
| **`roundtable_roles`** | 📋 **Project Roles** | Displays active project model roles, aliases, and `ROLES.md` priority sources. |
| **`roundtable_assign_role`** | ✍️ **Assign Role** | Dynamically assigns a custom role to a model & persists in `ROLES.md`. |
| **`roundtable_assign_skill`** | 🧠 **Assign Skill** | Associates a `.skill` file or skill guideline to a specific model. |
| **`roundtable_models`** | 🏛️ **List Experts** | Lists all registered expert models, their roles, and provider status. |
| **`roundtable_presets`** | 📋 **Preset Catalog** | Lists all built-in expert roles (`qa_tester`, `cicd_engineer`, `security_auditor`, etc.). |
| **`roundtable_search`** | 📓 **Vault Search** | Searches past session notes in Obsidian memory. |
| **`roundtable_save`** | ✍️ **Save Vault Note** | Saves custom notes or ingests files/folders into your Obsidian Vault. |
| **`roundtable_read`** | 📖 **Read Vault Note** | Reads full markdown content of an Obsidian note. |
| **`roundtable_help`** | ❓ **Help & Cheatsheet** | Displays the complete quickstart cheatsheet directly in chat. |

---

## 🚀 Quick Start

### 1. Clone & Build

```bash
git clone https://github.com/hardc0l2e/roundtable-mcp.git
cd roundtable-mcp
npm install
npm run build
```

### 2. Configure Models (`config.json`)

```json
{
  "models": [
    {
      "id": "gemini-flash",
      "name": "Gemini 3.7 Flash (Antigravity)",
      "role_preset": "architect",
      "aliases": ["gemini", "flash", "lead", "architect"],
      "provider": "antigravity-cli",
      "model": "gemini-3.7-flash-medium",
      "enabled": true
    },
    {
      "id": "claude-sonnet",
      "name": "Claude Sonnet 4.6 (Antigravity)",
      "role_preset": "qa_tester",
      "aliases": ["claude", "sonnet", "qa"],
      "provider": "antigravity-cli",
      "model": "claude-sonnet-4-6",
      "enabled": true
    },
    {
      "id": "gpt-oss",
      "name": "GPT-OSS 120B (Antigravity)",
      "role_preset": "cicd_engineer",
      "aliases": ["gpt", "gpt-oss", "devops"],
      "provider": "antigravity-cli",
      "model": "gpt-oss-120b-medium",
      "enabled": true
    },
    {
      "id": "gemma-local",
      "name": "Gemma4 26B 128k (Local GPU)",
      "role": "Primary Implementation Engineer",
      "aliases": ["gemma", "gemma4", "local", "coder"],
      "provider": "ollama",
      "endpoint": "http://localhost:11434/api/generate",
      "model": "gemma4-26b-128k:latest",
      "enabled": true
    }
  ],
  "obsidian": {
    "enabled": true,
    "vault_path": "C:/Users/username/Documents/Obsidian Vault",
    "folder": "roundtable-mcp/Sessions",
    "auto_save": true
  }
}
```

*For detailed provider settings and environment variables, see [docs/configuration.md](docs/configuration.md).*

---

## 🏗️ Architecture & Execution Pipeline

Roundtable MCP resolves every model query through a resilient 3-tier priority execution pipeline:

```mermaid
flowchart TD
    Client["MCP Client Host (OpenCode / Antigravity / Codex)"] -->|"JSON-RPC (STDIO)"| Server["Roundtable Server (dist/index.js)"]
    
    subgraph CoreManagers["Core Managers"]
        Server --> Roles["RolesManager (ROLES.md Override)"]
        Server --> Skills["SkillResolver (.skill / SKILL.md)"]
        Server --> Obsidian["ObsidianManager (Vault Search & Ingestion)"]
    end
    
    Roles --> Pipeline["Provider Routing Engine"]
    Skills --> Pipeline
    Obsidian --> Pipeline
    
    subgraph ExecutionPipeline["Execution Pipeline"]
        Pipeline --> Tier1["Tier 1: agy.exe (Google OAuth)"]
        Tier1 -.-> Gemini["Gemini / Claude / GPT-OSS"]
        
        Pipeline --> Tier2["Tier 2: Local GPU (llama.cpp / Ollama)"]
        Tier2 -.-> Gemma["Qwen / Gemma 4 / GPT-OSS"]
        
        Pipeline --> Tier3["Tier 3: Cloud APIs (OpenCode Zen / OpenRouter / Direct)"]
        Tier3 -.-> OpenRouter["Direct REST API Providers"]
    end
    
    Tier1 --> ErrorCheck["Fault Isolation & Root Cause Extraction"]
    Tier2 --> ErrorCheck
    Tier3 --> ErrorCheck
    
    ErrorCheck --> Output["Council Synthesis & Obsidian Vault Auto-Save"]
```

---

## 🔌 Client Integration Setup

### OpenCode (`~/.config/opencode/opencode.jsonc`)
```jsonc
{
  "mcp": {
    "roundtable": {
      "type": "local",
      "command": [
        "node",
        "C:\\projects\\roundtable-mcp\\dist\\index.js",
        "--config",
        "C:\\projects\\roundtable-mcp\\config.json"
      ]
    }
  }
}
```

### Google Antigravity (`~/.gemini/config/mcp_config.json`)
```json
{
  "mcpServers": {
    "roundtable-mcp": {
      "command": "node",
      "args": ["c:/projects/roundtable-mcp/dist/index.js"],
      "env": {
        "ROUNDTABLE_CONFIG_PATH": "c:/projects/roundtable-mcp/config.json"
      }
    }
  }
}
```

---

## 💡 Practical Examples

1. **Run a Parallel Council Discussion**:
   ```json
   roundtable_start(prompt: "Design high-concurrency authentication microservice for 1M DAU")
   ```

2. **Run a Multi-Stage Feature Cascade**:
   ```json
   roundtable_cascade(prompt: "Build JWT Authentication Endpoint", pipeline: ["architect", "coder", "qa_tester", "cicd_engineer"])
   ```

3. **Ingest Documentation to Obsidian Graph Hub**:
   ```json
   roundtable_save(source_path: "docs/architecture.md", target_folder: "roundtable-mcp", target_base: "ROUNDTABLE MCP", tags: ["architecture", "roundtable"])
   ```

4. **Search Past Decision Memory**:
   ```json
   roundtable_search(query: "circuit breakers")
   ```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).