🌐 multiagent-mcp

Centro de Toma de Turnos Colaborativo Multiagente sobre el Protocolo de Contexto de Modelo (MCP)
Orquesta diálogos multiagente sincronizados, interacciones humano-en-el-bucle (@user), colas de turnos impulsadas por menciones y seguimiento de transcripciones Markdown en vivo en disco.

📖 Descripción General

multiagent-mcp es un servidor especializado del Protocolo de Contexto de Modelo (MCP) diseñado para la coordinación multiagente de LLM. Permite que múltiples agentes de IA (por ejemplo, Arquitecto, Revisor, Optimizador) y un usuario humano (@user) participen en discusiones estructuradas de toma de turnos con conciencia asíncrona.

En lugar de generaciones concurrentes caóticas o sondeos manuales complicados, multiagent-mcp coordina los turnos a través de @menciones explícitas, mantiene una cola de turnos FIFO interna, maneja barreras de sincronización de llegada, proporciona segmentación incremental de mensajes no leídos y escribe una transcripción Markdown atómica y en vivo en el disco en tiempo real.

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

✨ Características Principales

1. Toma de Turnos Basada en Menciones (@<Nombre>) y Desduplicación

• Los turnos se pasan naturalmente entre agentes y el usuario etiquetando identificadores en el contenido del mensaje (por ejemplo, "@Bob ¿qué opinas?").

• Menciones Dirigidas: Los agentes solo deben mencionar a los participantes que son directamente interpelados o que se espera que respondan, en lugar de etiquetar a todos ciegamente.

• Etiqueta de Transmisión Global (@all): En un mensaje público (is_private=False), etiquetar @all se dirige a todos los participantes activos y encola a cada uno de ellos para +1 punto de turno.

• Aislamiento de Bloques de Código: Las menciones dentro de bloques de código delimitados (```) o en línea (`) se eliminan automáticamente antes del análisis para evitar activaciones falsas de turnos.

• Desduplicación: Etiquetar @Bob varias veces dentro del mismo mensaje encola a @Bob exactamente una vez (+1 punto máximo por participante distinto por mensaje).

• Validación: Si un mensaje no contiene menciones válidas de participantes activos, el servidor lo rechaza con un error de validación descriptivo que especifica los identificadores disponibles o @all.

2. Barrera de Llegada y Transmisión de Activación Global

• Cuando los agentes se unen secuencialmente a través de join_conversation, el primer participante queda bloqueado en una barrera de sincronización.

• Una vez que se han unido $ ge 2$ participantes, el servidor transmite un aviso de llegada (@Bob ha llegado a la conversación), desbloquea automáticamente a los participantes en espera e inicia el diálogo.

3. Mensajería Pública vs. Privada (is_private=True)

• Mensajes Públicos: Se añaden a la transcripción, se entregan a todos los participantes y activan a todos los oyentes en espera.

• Mensajes Privados (is_private=True) :

  • Visibles y entregados solo al remitente y a los destinatarios mencionados explícitamente.

  • @all Prohibido: Llamar is_private=True con @all genera un ValueError explícito.

  • Formateados con bloques dedicados 🔒 [Mensaje Privado] en la transcripción para el usuario humano.

• Prohibición Estricta de Transcripción: Se prohíbe estrictamente a los agentes leer el archivo de transcripción Markdown en disco directamente (a través de view_file o comandos de shell), garantizando cero fugas de información fuera de banda.

4. Seguimiento de Transcripción Markdown en Vivo

• Todos los mensajes, tablas de participantes y avisos del sistema se escriben atómicamente en un archivo Markdown especificado (filepath).

• Permite la inspección visual en tiempo real en editores como Obsidian, Cursor o VS Code (ideal para monitoreo en pantalla secundaria).

5. Segmentación Incremental de Mensajes No Leídos

• Cada participante mantiene un last_read_seq_id.

• Las llamadas a wait_for_turn o send_message bloqueante devuelven solo los mensajes no leídos recién llegados (seq_id > last_read_seq_id), ahorrando contexto del LLM y evitando procesamiento repetitivo.

📦 Instalación y Configuración

Requisitos Previos

• Python $ ge 3.10$

• Gestor de paquetes pip o uv

Instalación Estándar

Clona el repositorio e instala en modo editable:

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

Para instalar dependencias de desarrollo (pruebas con pytest):

pip install -e ".[dev]"

🚀 Ejecución del Servidor

multiagent-mcp soporta tanto Entrada/Salida Estándar (stdio) (para integración local con CLI en Claude Desktop, Antigravity, Cursor) como Eventos Enviados por el Servidor (sse) (para microservicios HTTP/en red).

1. Modo Stdio (Predeterminado para IDEs y Aplicaciones de Escritorio)

multiagent-mcp stdio

2. Modo Servidor SSE (Subagentes HTTP y en Red)

# Default binding: 127.0.0.1:8000
multiagent-mcp serve

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

Cuando se ejecuta en modo SSE, el endpoint MCP está disponible en http://127.0.0.1:8000/sse.

⚙️ Configuración del Cliente MCP

1. Configuración de Google Antigravity y Cursor

Añade multiagent-mcp a tu mcp_servers.json (o .cursor/mcp.json / .gemini/antigravity/mcp_servers.json):

A través de Stdio:

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

A través de SSE (Servidor Remoto/Local):

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

2. Configuración de Claude Desktop

Edita tu claude_desktop_config.json (ubicado en %APPDATA%\Claude\claude_desktop_config.json en Windows o ~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

🛠️ Referencia de Herramientas

El servidor expone 4 herramientas FastMCP:

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

Inicializa o reinicia una sala de conversación, limpia las estructuras de memoria y genera el archivo de transcripción Markdown inicial.

Parámetros:

Devuelve (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

Registra a un participante en la sala. Maneja las barreras de sincronización de llegada y transmite avisos de llegada.

Parámetros:

Devuelve (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

Consulta los participantes actuales de la sala, el orador del turno activo, la cola de turnos y el recuento total de mensajes.

Parámetros: Ninguno.

Devuelve (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

Publica un mensaje público o privado en la sala. Valida las menciones, actualiza la cola de turnos, añade al archivo Markdown y pone al remitente en un bucle de espera hasta que sea su próximo turno o hasta que llegue un nuevo mensaje, devolviendo solo mensajes nuevos no leídos al desbloquearse.

Parámetros:

Devuelve (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."
}

💡 Integración en el Mundo Real: Habilidad multiagent-chat

La habilidad multiagent-chat demuestra cómo un supervisor orquesta subagentes y @user en Obsidian:

Secuencia de Ejecución

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

📜 Formato de Transcripción en Vivo

A continuación se muestra un ejemplo del archivo Markdown en vivo generado por multiagent-mcp:

# 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.

---

🧪 Pruebas

El conjunto de pruebas cubre:

• Normalización de participantes y limpieza de identificadores (@Alice, Alice $\to$ @Alice).

• Extracción de menciones y eliminación de bloques de código (``` / `).

• Sincronización de barrera de llegada y transmisión de activación.

• Control de acceso a mensajes privados.

• Segmentación incremental de mensajes no leídos.

• Registro de herramientas FastMCP y comandos CLI (serve / stdio).

Ejecuta las pruebas usando pytest:

pytest

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.