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

협력적 멀티에이전트 턴 테이킹 허브 (Model Context Protocol 기반)
동기화된 멀티에이전트 대화, 인간-인-더-루프 상호작용 (@user), 멘션 기반 턴 큐, 실시간 디스크 마크다운 기록 추적을 조율합니다.

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

📖 개요

**multiagent-mcp**는 멀티에이전트 LLM 조정을 위해 설계된 특수 Model Context Protocol (MCP) 서버입니다. 여러 AI 에이전트(예: Architect, Reviewer, Optimizer)와 인간 사용자(@user)가 구조화된 비동기 인식 턴 테이킹 토론에 참여할 수 있게 합니다.

혼란스러운 동시 생성이나 복잡한 수동 폴링 대신, multiagent-mcp는 명시적인 @멘션 을 통해 턴을 조정하고, 내부 FIFO 턴 큐를 유지하며, 도착 동기화 장벽을 처리하고, 증분 읽지 않은 메시지 슬라이싱을 제공하며, 실시간으로 원자적 마크다운 기록을 디스크에 기록합니다.

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. 공개 vs. 비공개 메시징 (`is_private=True`)

공개 메시지: 기록에 추가되고 모든 참가자에게 전달되며 대기 중인 모든 리스너를 깨웁니다.
비공개 메시지 (is_private=True) :
- 발신자와 명시적으로 멘션된 수신자에게만 표시되고 전달됩니다.
- @all 금지: is_private=True와 함께 @all을 호출하면 명시적인 ValueError가 발생합니다.
- 인간 사용자를 위해 기록에 전용 🔒 [비공개 메시지] 블록으로 형식화됩니다.
엄격한 기록 금지: 에이전트는 디스크의 마크다운 기록 파일을 직접 읽는 것(view_file 또는 셸 명령을 통해)이 엄격히 금지되어 대역 외 정보 유출이 없도록 보장합니다.

4. 실시간 마크다운 기록 추적

모든 메시지, 참가자 테이블 및 시스템 알림은 지정된 마크다운 파일(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 통합용) 및 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을 편집합니다(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`

대화방을 초기화하거나 재설정하고, 메모리 구조를 지우며, 초기 마크다운 기록 파일을 생성합니다.

매개변수:

매개변수	유형	필수	기본값	설명
`filepath`	`str`	예	—	마크다운 기록 파일의 대상 경로.
`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`

방에 공개 또는 비공개 메시지를 게시합니다. 멘션을 검증하고, 턴 큐를 업데이트하며, 마크다운 파일에 추가하고, 발신자를 다음 턴이 오거나 새 메시지가 도착할 때까지 대기 루프에 넣습니다. 차단 해제 시 새로운 읽지 않은 메시지만 반환합니다.

매개변수:

매개변수	유형	필수	기본값	설명
`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가 생성한 실시간 마크다운 파일의 예입니다:

# 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. 공개 vs. 비공개 메시징 (is_private=True)

4. 실시간 마크다운 기록 추적

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. 공개 vs. 비공개 메시징 (`is_private=True`)

1. `init_conversation`

2. `join_conversation`

3. `list_participants`

4. `send_message`

💡 실제 통합: `multiagent-chat` 스킬