de en es ja ko ru zh

multiagent-mcp

Name: multiagent-mcp
Author: hjamet

by hjamet

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

🌐 multiagent-mcp

基于模型上下文协议（MCP）的协作式多智能体轮流发言中心
编排同步的多智能体对话、人在回路交互（@user）、提及驱动的发言队列，以及实时 Markdown 转录文件追踪。

Python Version MCP License: MIT Code Style: Black / Flake8

📖 概述

multiagent-mcp 是一个专为多智能体 LLM 协调而设计的专用模型上下文协议（MCP）服务器。它使多个 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 已加入对话），自动解除等待参与者的阻塞，并启动对话。

3. 公开消息与私密消息（`is_private=True`）

公开消息：追加到转录文件中，发送给所有参与者，并唤醒所有等待的监听者。
私密消息（is_private=True）：
- 仅对发送者和显式提及的接收者可见和传递。
- 禁止 @all：使用 is_private=True 并包含 @all 会引发显式的 ValueError。
- 在转录文件中以专用的 🔒 [私密消息] 块格式呈现给人类用户。
严格转录文件禁令：严格禁止智能体直接读取磁盘上的 Markdown 转录文件（通过 view_file 或 shell 命令），确保零带外信息泄露。

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 支持标准 I/O（stdio）（用于 Claude Desktop、Antigravity、Cursor 的本地 CLI 集成）和服务器发送事件（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（位于 Windows 上的 %APPDATA%\Claude\claude_desktop_config.json 或 macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "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 转录文件。

参数：

参数	类型	必需	默认值	描述
`filepath`	`str`	是	—	Markdown 转录文件的目标路径。
`participants`	`list[str]`	是	—	预期参与者句柄列表（例如 `["@user", "@Alice", "@Bob"]`）。
`topic`	`str`	否	`""`	对话主题或简报上下文。

返回（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`

在房间中注册一个参与者。处理到达同步屏障并广播到达通知。

参数：

参数	类型	必需	默认值	描述
`handle`	`str`	是	—	参与者句柄（例如 `'@Alice'` 或 `'Alice'`）。
`name`	`str`	否	`""`	可选显示名称（默认为清理后的句柄）。
`timeout_seconds`	`float`	否	`45.0`	阻塞等待发言的超时秒数。

返回（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 文件，并将发送者置于等待循环中，直到轮到其下一次发言或收到新消息，解除阻塞时仅返回新的未读消息。

参数：

参数	类型	必需	默认值	描述
`sender`	`str`	是	—	发送者句柄（例如 `'@Alice'`）。
`content`	`str`	是	—	消息内容。必须包含至少一个有效的 `@接收者` 提及。
`is_private`	`bool`	否	`False`	如果为 `True`，消息仅对发送者和被标记的接收者可见。
`timeout_seconds`	`float`	否	`45.0`	在返回发言状态前等待的最大秒数。

返回（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 技能演示了监督者如何在 Obsidian 中编排子智能体和 @user：

执行序列

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

📜 实时转录格式

以下是 multiagent-mcp 生成的实时 Markdown 文件示例：

# 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 许可证授权。

This server cannot be deployed

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

UproarOAuth
chat.uproar
Chat where AI agents are first-class members, with their own identity and permissions.
Communication Agent Orchestration
1
handoff-mcp-server A
io.github.josephibra
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
Agent Orchestration Autonomous Agents
2
gpu A
ai.joinmultiplayer
Agent-to-agent network for teams: dm, who-knows-X routing, shared rooms. Human-in-the-loop.
Agent Orchestration Communication
2
ParleyOAuth
dev.weldra
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
Autonomous Agents Developer Tools
1

Related MCP Servers

Agent Communication MCP Server
Communication Agent Orchestration Autonomous Agents
mkXultra
A
license
Not graded
quality
A
maintenance
Enables AI agents to communicate with each other through Slack-like room-based channels with messaging, mentions, presence management, and long-polling for real-time collaboration.
Updated 21 days ago (2026-09-19 06:01 UTC)
63 npm
5
MIT
agent-room-mcp
Communication Agent Orchestration
umbecanessa
A
license
Not graded
quality
D
maintenance
Enables Cursor agents to communicate via a shared chat room, allowing them to ask questions, share status, and warn about conflicts while collaborating on the same repo.
Updated 4 months ago (2026-06-12 14:17 UTC)
150 npm
MIT
pairdown
Workplace & Productivity Note Taking
rohanrichards
F
license
Not graded
quality
B
maintenance
Enables agents to join multiplayer markdown rooms, collaborate on documents live with humans, and respond to mentions via comments.
Updated a month ago (2026-08-25 03:40 UTC)
-
ai-collaboration-mcp
Agent Orchestration Autonomous Agents Communication
monthop-gmail
F
license
Not graded
quality
B
maintenance
Enables AI agents from different providers to collaborate in shared discussion threads, posting proposals and reviews while retrieving synchronized context, with human oversight.
Updated 10 days ago (2026-09-29 20:12 UTC)
-

🌐 multiagent-mcp

📖 概述

✨ 核心特性

1. 基于提及的轮流发言（@<名称>）与去重

2. 到达屏障与全局唤醒广播

3. 公开消息与私密消息（is_private=True）

4. 实时 Markdown 转录文件追踪

5. 增量未读消息切片

📦 安装与设置

前提条件

标准安装

🚀 运行服务器

1. Stdio 模式（IDE 和桌面应用的默认模式）

2. SSE 服务器模式（HTTP 和网络子智能体）

⚙️ MCP 客户端配置

1. Google Antigravity 与 Cursor 配置

通过 Stdio：

通过 SSE（远程/本地服务器）：

2. Claude Desktop 配置

🛠️ 工具参考

1. init_conversation

2. join_conversation

3. list_participants

4. send_message

💡 实际集成：multiagent-chat 技能

执行序列

📜 实时转录格式

🧪 测试

📄 许可证

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Agent Communication MCP Server

agent-room-mcp

pairdown

ai-collaboration-mcp

1. 基于提及的轮流发言（`@<名称>`）与去重

3. 公开消息与私密消息（`is_private=True`）

1. `init_conversation`

2. `join_conversation`

3. `list_participants`

4. `send_message`

💡 实际集成：`multiagent-chat` 技能