🌐 multiagent-mcp

Gemeinsamer Multi-Agent-Turn-Taking-Hub über das Model Context Protocol (MCP)
Orchestrieren Sie synchronisierte Multi-Agent-Dialoge, Human-in-the-Loop-Interaktionen (@user), erwähnungsgesteuerte Zugreihenfolgen und Live-Markdown-Transkriptverfolgung auf der Festplatte.

📖 Übersicht

multiagent-mcp ist ein spezialisierter Model Context Protocol (MCP)-Server, der für die Koordination mehrerer KI-Agenten entwickelt wurde. Er ermöglicht mehreren KI-Agenten (z. B. Architekt, Reviewer, Optimierer) und einem menschlichen Benutzer (@user), an strukturierten, asynchronitätsbewussten, abwechselnden Diskussionen teilzunehmen.

Statt chaotischer gleichzeitiger Generierungen oder komplizierter manueller Abfragen koordiniert multiagent-mcp die Züge über explizite @Erwähnungen, verwaltet eine interne FIFO-Warteschlange, behandelt Synchronisationsbarrieren beim Eintreffen, bietet inkrementelles Abrufen ungelesener Nachrichten und schreibt ein atomares, Live-Markdown-Transkript in Echtzeit auf die Festplatte.

flowchart TD
    subgraph Clients["Agents & User"]
        A["🤖 Agent @Alice\n(Architect)"]
        B["🤖 Agent @Bob\n(Reviewer)"]
        U["👤 User @user\n(Decider)"]
    end

    subgraph Hub["multiagent-mcp Server (FastMCP)"]
        RM["RoomManager Engine"]
        TQ["FIFO Turn Queue\n(+1 per @mention)"]
        AB["Arrival Barrier &\nWakeup Broadcast"]
        UMS["Incremental Unread Slicing\n(last_read_seq_id)"]
    end

    subgraph Storage["On-Disk Live Transcript"]
        MD["📜 Obsidian / Markdown Note\n(Live File Tracking)"]
    end

    A -->|"1. join_conversation()"| AB
    B -->|"2. join_conversation()"| AB
    AB -->|"3. Global Wakeup & Welcome"| Clients
    A -->|"4. send_message(@Bob, ...)"| RM
    RM -->|"Update Turn Queue"| TQ
    RM -->|"Append Message"| MD
    RM -->|"Wakeup Target"| B
    B -->|"5. wait_for_turn() / send_message(@user)"| RM
    RM -->|"Signal @user Turn"| U
    U -->|"6. send_message(@Alice, ...)"| RM

Related MCP server: agent-room-mcp

✨ Kernfunktionen

1. Erwähnungsbasierte Zugreihenfolge (@<Name>) & Deduplizierung

• Züge werden auf natürliche Weise zwischen Agenten und dem Benutzer weitergegeben, indem Handles im Nachrichteninhalt getaggt werden (z. B. "@Bob, was denkst du?").

• Gezielte Erwähnungen: Agenten sollten nur Teilnehmer erwähnen, die direkt angesprochen werden oder von denen eine Antwort erwartet wird, anstatt blind alle zu taggen.

• Globaler Rundfunk-Tag (@all): In einer öffentlichen Nachricht (is_private=False) adressiert das Taggen von @all alle aktiven Teilnehmer und reiht jeden von ihnen für +1 Zugpunkt ein.

• Code-Block-Isolierung: Erwähnungen innerhalb von umschlossenen (```) oder Inline- (`) Code-Blöcken werden vor dem Parsen automatisch entfernt, um falsche Zugauslöser zu verhindern.

• Deduplizierung: Das mehrfache Taggen von @Bob innerhalb derselben Nachricht stellt @Bob genau einmal in die Warteschlange (+1 max. Punkt pro eindeutigem Teilnehmer pro Nachricht).

• Validierung: Wenn eine Nachricht keine gültigen Erwähnungen aktiver Teilnehmer enthält, lehnt der Server sie mit einem beschreibenden Validierungsfehler ab, der die verfügbaren Handles oder @all angibt.

2. Ankunftsbarriere & Globaler Aufwach-Rundfunk

• Wenn Agenten nacheinander über join_conversation beitreten, wird der erste Teilnehmer in einer Synchronisationsbarriere blockiert.

• Sobald $\ge 2$ Teilnehmer beigetreten sind, sendet der Server eine Ankunftsbenachrichtigung (@Bob est arrivé dans la conversation), entsperrt automatisch wartende Teilnehmer und startet den Dialog.

3. Öffentliche vs. Private Nachrichten (is_private=True)

• Öffentliche Nachrichten: Werden an das Transkript angehängt, an alle Teilnehmer zugestellt und wecken alle wartenden Zuhörer.

• Private Nachrichten (is_private=True):

  • Sichtbar und zugestellt nur an den Absender und explizit erwähnte Empfänger.

  • @all verboten: Der Aufruf von is_private=True mit @all löst einen expliziten ValueError aus.

  • Im Transkript für den menschlichen Benutzer mit dedizierten 🔒 [Message Privé]-Blöcken formatiert.

• Strenges Transkriptverbot: Agenten ist es strengstens untersagt, die auf der Festplatte gespeicherte Markdown-Transkriptdatei direkt zu lesen (über view_file oder Shell-Befehle), um Null-Informationslecks außerhalb der Bandbreite zu gewährleisten.

4. Live-Markdown-Transkriptverfolgung

• Alle Nachrichten, Teilnehmertabellen und Systemhinweise werden atomar in eine angegebene Markdown-Datei (filepath) geschrieben.

• Ermöglicht die Echtzeit-Inspektion in Editoren wie Obsidian, Cursor oder VS Code (ideal für die Überwachung auf einem zweiten Bildschirm).

5. Inkrementelles Abrufen ungelesener Nachrichten

• Jeder Teilnehmer führt eine last_read_seq_id.

• Aufrufe von wait_for_turn oder blockierendes send_message geben nur neu eingetroffene ungelesene Nachrichten zurück (seq_id > last_read_seq_id), was den LLM-Kontext spart und wiederholte Verarbeitung verhindert.

📦 Installation & Einrichtung

Voraussetzungen

• Python $\ge$ 3.10

• pip oder uv Paketmanager

Standardinstallation

Klonen Sie das Repository und installieren Sie es im bearbeitbaren Modus:

git clone https://github.com/hjamet/multiagent-mcp.git
cd multiagent-mcp
pip install -e .

Um Entwicklungsabhängigkeiten zu installieren (Testen mit pytest):

pip install -e ".[dev]"

🚀 Server ausführen

multiagent-mcp unterstützt sowohl Standard I/O (stdio) (für lokale CLI-Integration in Claude Desktop, Antigravity, Cursor) als auch Server-Sent Events (sse) (für HTTP/Netzwerk-Mikrodienste).

1. Stdio-Modus (Standard für IDEs & Desktop-Apps)

multiagent-mcp stdio

2. SSE-Server-Modus (HTTP & Netzwerk-Subagenten)

# Default binding: 127.0.0.1:8000
multiagent-mcp serve

# Custom host and port
multiagent-mcp serve --host 0.0.0.0 --port 8000

Wenn im SSE-Modus ausgeführt, ist der MCP-Endpunkt unter http://127.0.0.1:8000/sse verfügbar.

⚙️ MCP-Client-Konfiguration

1. Google Antigravity & Cursor-Konfiguration

Fügen Sie multiagent-mcp zu Ihrer mcp_servers.json (oder .cursor/mcp.json / .gemini/antigravity/mcp_servers.json) hinzu:

Über Stdio:

{
  "mcpServers": {
    "multiagent-mcp": {
      "command": "multiagent-mcp",
      "args": ["stdio"]
    }
  }
}

Über SSE (Remote / Lokaler Server):

{
  "mcpServers": {
    "multiagent-mcp": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

2. Claude Desktop-Konfiguration

Bearbeiten Sie Ihre claude_desktop_config.json (befindet sich unter %APPDATA%\Claude\claude_desktop_config.json unter Windows oder ~/Library/Application Support/Claude/claude_desktop_config.json unter macOS):

{
  "mcpServers": {
    "multiagent-mcp": {
      "command": "multiagent-mcp",
      "args": ["stdio"]
    }
  }
}

🛠️ Tool-Referenz

Der Server stellt 4 FastMCP-Tools bereit:

classDiagram
    class MultiAgentHub {
        +init_conversation(filepath, participants, topic) dict
        +join_conversation(handle, name, timeout_seconds) TurnResult
        +list_participants() dict
        +send_message(sender, content, is_private, timeout_seconds) TurnResult
    }

1. init_conversation

Initialisiert oder setzt einen Konversationsraum zurück, löscht Speicherstrukturen und erstellt die anfängliche Markdown-Transkriptdatei.

Parameter:

Rückgabe (dict):

{
  "status": "initialized",
  "filepath": "notes/Discussions/Architecture.md",
  "topic": "Multi-Agent Hub Protocol",
  "participants": ["@user", "@Alice", "@Bob"],
  "message": "Room initialized with 3 participants."
}

2. join_conversation

Registriert einen Teilnehmer im Raum. Behandelt Ankunftssynchronisationsbarrieren und sendet Ankunftsbenachrichtigungen.

Parameter:

Rückgabe (TurnResult):

{
  "status": "joined",
  "active_turn": "@Alice",
  "new_messages": [],
  "current_queue": [],
  "active_participants": ["@user", "@Alice", "@Bob"],
  "system_notice": "Joined room. Active participants: 3"
}

3. list_participants

Fragt aktuelle Raumteilnehmer, aktiven Zugsprecher, Zugwarteschlange und Gesamtnachrichtenzahl ab.

Parameter: Keine.

Rückgabe (dict):

{
  "participants": [
    {
      "handle": "@Alice",
      "name": "Alice Architect",
      "status": "active",
      "joined_at": "2026-08-18T10:20:00+00:00",
      "last_read_seq_id": 4
    }
  ],
  "active_participants": ["@Alice", "@Bob", "@user"],
  "active_turn": "@Bob",
  "turn_queue": ["@user"],
  "message_count": 5,
  "topic": "Architecture Review",
  "filepath": "notes/Discussions/Architecture.md"
}

4. send_message

Sendet eine öffentliche oder private Nachricht an den Raum. Validiert Erwähnungen, aktualisiert die Zugwarteschlange, hängt an die Markdown-Datei an und versetzt den Absender in eine Warteschleife, bis er wieder an der Reihe ist oder eine neue Nachricht eintrifft. Bei Entsperrung werden nur neue ungelesene Nachrichten zurückgegeben.

Parameter:

Rückgabe (TurnResult):

{
  "status": "your_turn",
  "active_turn": "@Alice",
  "new_messages": [
    {
      "id": 4,
      "seq_id": 4,
      "sender": "@Bob",
      "recipients": ["@Alice"],
      "content": "I agree with your proposal @Alice.",
      "is_private": false,
      "timestamp": "2026-08-18T10:21:00+00:00"
    }
  ],
  "current_queue": ["@user"],
  "active_participants": ["@Alice", "@Bob", "@user"],
  "system_notice": "Woken up by incoming message/mention for @Alice."
}

💡 Praxisintegration: multiagent-chat-Skill

Der multiagent-chat-Skill demonstriert, wie ein Supervisor Subagenten und @user in Obsidian orchestriert:

Ausführungssequenz

sequenceDiagram
    autonumber
    actor Henri as 👤 Henri (@user)
    participant AGY as 👑 Antigravity (Supervisor)
    participant Hub as ⚡ multiagent-mcp
    participant Alice as 🤖 @Alice (Architect)
    participant Bob as 🤖 @Bob (Reviewer)
    participant MD as 📜 Live Transcript Note

    Henri->>AGY: "Launch debate on AIVC memory protocol"
    AGY->>Hub: init_conversation("notes/Debat.md", ["@user", "@Alice", "@Bob"], "AIVC Memory")
    Hub->>MD: Creates header and participant table

    par Spawn Subagents
        AGY->>Alice: invoke_subagent(Role="@Alice", Prompt="...")
        AGY->>Bob: invoke_subagent(Role="@Bob", Prompt="...")
    end

    Alice->>Hub: join_conversation("@Alice")
    Note over Alice,Hub: Alice waits at arrival barrier
    Bob->>Hub: join_conversation("@Bob")
    Hub->>MD: Append "🔔 @Bob est arrivé dans la conversation"
    Hub-->>Alice: Wakeup broadcast

    Alice->>Hub: send_message("@Alice", "We should use SQLite vector cache. What do you think @Bob?", block=True)
    Hub->>MD: Append Alice's message
    Hub-->>Bob: Wakeup & Assign Turn

    Bob->>Hub: send_message("@Bob", "Good idea, but let's check latency. @user do you approve?", block=True)
    Hub->>MD: Append Bob's message
    Hub-->>AGY: @user mentioned -> Signal turn to Supervisor

    AGY-->>Henri: "C'est à vous de parler : Bob demande votre arbitrage sur la latence."
    Henri->>AGY: "Je valide SQLite, la latence est négligeable."
    AGY->>Hub: send_message("@user", "Je valide SQLite, la latence est négligeable @Alice.", block=False)
    Hub->>MD: Append user message
    Hub-->>Alice: Unblock Alice

📜 Live-Transkript-Format

Nachfolgend ein Beispiel der von multiagent-mcp generierten Live-Markdown-Datei:

# Multi-Agent Room

- **Fichier :** `notes/Discussions/Architecture_Review.md`
- **Sujet :** Multi-Agent Hub Protocol & AIVC Memory
- **Initialisé le :** 2026-08-18 10:20:00

## Participants
| Handle | Nom | Statut | Rejoint le |
|---|---|---|---|
| @user | Henri Jamet | active | 2026-08-18 10:20:00 |
| @Alice | Alice Architect | active | 2026-08-18 10:20:02 |
| @Bob | Bob Reviewer | active | 2026-08-18 10:20:04 |

---

## Fil de discussion

> 🔔 **Système :** @Bob est arrivé dans la conversation

### @Alice ➔ @Bob (2026-08-18 10:20:10 UTC)

Nous devons privilégier un protocole à mémoire partagée pour réduire la latence inter-processus. Qu'en penses-tu @Bob ?

---

### 🔒 [Message Privé] @Bob ➔ @Alice (2026-08-18 10:20:30 UTC)

Vérifions d'abord la compatibilité Windows avant d'interpeller l'utilisateur.

---

### @Bob ➔ @user (2026-08-18 10:21:00 UTC)

D'accord sur le principe. @user, validez-vous cette approche pour le déploiement local ?

---

### @user ➔ @Alice, @Bob (2026-08-18 10:21:45 UTC)

Approche validée, privilégiez la simplicité d'implémentation @Alice.

---

🧪 Testen

Die Testsuite umfasst:

• Teilnehmernormalisierung und Handle-Bereinigung (@Alice, Alice $\to$ @Alice).

• Extraktion von Erwähnungen und Entfernung von Code-Blöcken (``` / `).

• Synchronisation der Ankunftsbarriere und Aufwach-Rundfunk.

• Zugriffskontrolle für private Nachrichten.

• Inkrementelles Abrufen ungelesener Nachrichten.

• FastMCP-Tool-Registrierung und CLI-Befehle (serve / stdio).

Führen Sie Tests mit pytest aus:

pytest

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.