🌐 multiagent-mcp

Совместный многопользовательский хаб с поочередным взаимодействием на основе протокола Model Context Protocol (MCP)
Оркестрируйте синхронизированные многопользовательские диалоги, взаимодействие с человеком (@user), очереди ходов на основе упоминаний и отслеживание живого Markdown-транскрипта на диске.

📖 Обзор

multiagent-mcp — это специализированный сервер Model Context Protocol (MCP), разработанный для координации многопользовательских LLM. Он позволяет нескольким AI-агентам (например, Архитектор, Рецензент, Оптимизатор) и человеку (@user) участвовать в структурированных, асинхронно-осознанных диалогах с поочередным взаимодействием.

Вместо хаотичных одновременных генераций или сложного ручного опроса multiagent-mcp координирует ходы через явные @упоминания, поддерживает внутреннюю FIFO-очередь ходов, обрабатывает барьеры синхронизации прибытия, предоставляет инкрементальную выборку непрочитанных сообщений и записывает атомарный живой Markdown-транскрипт на диск в реальном времени.

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

✨ Основные возможности

1. Поочередное взаимодействие на основе упоминаний (@<Имя>) и дедупликация

• Ходы естественным образом передаются между агентами и пользователем путем упоминания тегов в содержимом сообщения (например, "@Bob что ты думаешь?").

• Целевые упоминания: Агенты должны упоминать только тех участников, к которым непосредственно обращаются или от которых ожидают ответа, а не слепо отмечать всех.

• Глобальный тег трансляции (@all): В публичном сообщении (is_private=False) упоминание @all адресует всех активных участников и ставит каждого из них в очередь на +1 очко хода.

• Изоляция блоков кода: Упоминания внутри обрамленных (```) или встроенных (`) блоков кода автоматически удаляются перед разбором, чтобы предотвратить ложные срабатывания ходов.

• Дедупликация: Многократное упоминание @Bob в одном сообщении ставит @Bob в очередь ровно один раз (макс. +1 очко на каждого уникального участника за сообщение).

• Валидация: Если сообщение не содержит ни одного действительного упоминания активного участника, сервер отклоняет его с описательной ошибкой валидации, указывающей доступные теги или @all.

2. Барьер прибытия и глобальная трансляция пробуждения

• Когда агенты присоединяются последовательно через join_conversation, первый участник блокируется в барьере синхронизации.

• Как только $ ge 2$ участников присоединились, сервер транслирует уведомление о прибытии (@Bob est arrivé dans la conversation), автоматически разблокирует ожидающих участников и запускает диалог.

3. Публичные и приватные сообщения (is_private=True)

• Публичные сообщения: Добавляются в транскрипт, доставляются всем участникам и пробуждают всех ожидающих слушателей.

• Приватные сообщения (is_private=True):

  • Видны и доставляются только отправителю и явно упомянутым получателям.

  • @all запрещено: Вызов is_private=True с @all вызывает явное ValueError.

  • Форматируются с помощью специальных блоков 🔒 [Message Privé] в транскрипте для пользователя-человека.

• Строгий запрет на чтение транскрипта: Агентам строго запрещено напрямую читать файл Markdown-транскрипта на диске (через view_file или команды оболочки), что гарантирует отсутствие утечек информации вне канала.

4. Отслеживание живого Markdown-транскрипта

• Все сообщения, таблицы участников и системные уведомления атомарно записываются в указанный Markdown-файл (filepath).

• Позволяет визуально отслеживать в реальном времени в редакторах типа Obsidian, Cursor или VS Code (идеально для мониторинга на втором дисплее).

5. Инкрементальная выборка непрочитанных сообщений

• Каждый участник поддерживает last_read_seq_id.

• Вызовы wait_for_turn или блокирующий send_message возвращают только новые непрочитанные сообщения (seq_id > last_read_seq_id), экономя контекст LLM и предотвращая повторную обработку.

📦 Установка и настройка

Предварительные требования

• Python $ ge 3.10$

• Менеджер пакетов pip или uv

Стандартная установка

Клонируйте репозиторий и установите в редактируемом режиме:

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

Чтобы установить зависимости для разработки (тестирование с pytest):

pip install -e ".[dev]"

🚀 Запуск сервера

multiagent-mcp поддерживает как стандартный ввод-вывод (stdio) (для локальной интеграции с CLI в Claude Desktop, Antigravity, Cursor), так и Server-Sent Events (sse) (для HTTP/сетевых микросервисов).

1. Режим Stdio (по умолчанию для IDE и настольных приложений)

multiagent-mcp stdio

2. Режим SSE-сервера (HTTP и сетевые подагенты)

# Default binding: 127.0.0.1:8000
multiagent-mcp serve

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

При работе в режиме SSE конечная точка MCP доступна по адресу http://127.0.0.1:8000/sse.

⚙️ Конфигурация MCP-клиента

1. Конфигурация Google Antigravity и Cursor

Добавьте multiagent-mcp в ваш mcp_servers.json (или .cursor/mcp.json / .gemini/antigravity/mcp_servers.json):

Через Stdio:

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

Через SSE (удаленный / локальный сервер):

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

2. Конфигурация Claude Desktop

Отредактируйте ваш claude_desktop_config.json (находится в %APPDATA%\Claude\claude_desktop_config.json на Windows или ~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

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

🛠️ Справочник инструментов

Сервер предоставляет 4 инструмента 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

Инициализирует или сбрасывает комнату разговора, очищает структуры памяти и создает начальный файл Markdown-транскрипта.

Параметры:

Возвращает (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

Регистрирует участника в комнате. Обрабатывает барьеры синхронизации прибытия и транслирует уведомления о прибытии.

Параметры:

Возвращает (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

Запрашивает текущих участников комнаты, активного говорящего, очередь ходов и общее количество сообщений.

Параметры: Нет.

Возвращает (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

Отправляет публичное или приватное сообщение в комнату. Проверяет упоминания, обновляет очередь ходов, добавляет запись в Markdown-файл и помещает отправителя в цикл ожидания до его следующего хода или до появления нового сообщения, возвращая только новые непрочитанные сообщения после разблокировки.

Параметры:

Возвращает (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."
}

💡 Интеграция в реальном мире: навык multiagent-chat

Навык multiagent-chat демонстрирует, как супервизор оркестрирует подагентов и @user в Obsidian:

Последовательность выполнения

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

📜 Формат живого транскрипта

Ниже приведен пример живого Markdown-файла, создаваемого 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.

---

🧪 Тестирование

Набор тестов охватывает:

• Нормализацию участников и очистку тегов (@Alice, Alice $\to$ @Alice).

• Извлечение упоминаний и удаление блоков кода (``` / `).

• Синхронизацию барьера прибытия и трансляцию пробуждения.

• Контроль доступа к приватным сообщениям.

• Инкрементальную выборку непрочитанных сообщений.

• Регистрацию инструментов FastMCP и команды CLI (serve / stdio).

Запустите тесты с помощью pytest:

pytest

📄 Лицензия

Этот проект лицензирован по лицензии MIT.