# mcp-agent-hub

让**多个 Agent 客户端**（Claude Code、Cursor、MiMo、Aider 等，可 2 个以上）在**本机或局域网**互通协作的 MCP 服务。

## 协作模型：手动设主 + 其余全是子代理

- **手动指定一个主理人（master）**：在某个客户端启动时 `--role-type master`，或调用 `set_master`
- **其余全部是子代理（subagent）**：数量不限；入网时自动挂靠到当前主理人
- 支持**本地**（多个 stdio 进程共享一个 SQLite）和**局域网**（Streamable HTTP，多客户端接入同一 Hub）

```text
                ┌─────────────────────┐
                │  主理人 master       │  ← 手动指定（--role-type master / set_master）
                │  拆解 · 派单 · 盯进度 │
                └──────────┬──────────┘
           dispatch_task   │   report / escalate
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
 ┌────────────┐     ┌────────────┐     ┌────────────┐
 │ 子代理 A    │     │ 子代理 B    │     │ 子代理 C    │  ← 可任意多个
 │ coder      │     │ reviewer   │     │ tester     │
 └────────────┘     └────────────┘     └────────────┘
        │                  │                  │
        └──────────────────┼──────────────────┘
                           ▼
              共享黑板 remember/recall
              任务看板 · 消息收件箱 (SQLite)
```

## 安装

依赖：Python 3.12+，推荐 [uv](https://docs.astral.sh/uv/)。

```bash
git clone <repo-url> mcp-agent-hub
cd mcp-agent-hub
uv sync
# 或仅运行时
uv pip install -e .
```

## 快速开始（Linux 示例）

### 场景 1：本机多客户端（stdio + 共享 DB）

所有客户端指向**同一个** `AGENT_HUB_DB` 即可互通。主理人手动设在其中一个客户端上。

```bash
export AGENT_HUB_DB=/tmp/agent-hub.db

# ① 手动设主：这一端是主理人
mcp-agent-hub stdio --name boss --role-type master --role orchestrator

# ② 其余全是子代理（可开任意多个）
mcp-agent-hub stdio --name coder-1    --role-type subagent --role implementer --capabilities code,test
mcp-agent-hub stdio --name reviewer-1 --role-type subagent --role reviewer    --capabilities review,docs
mcp-agent-hub stdio --name tester-1   --role-type subagent --role tester      --capabilities test
```

**主理人**客户端配置（`examples/01-master.json`）：

```json
{
  "mcpServers": {
    "agent-hub": {
      "command": "mcp-agent-hub",
      "args": ["stdio", "--name", "boss", "--role-type", "master", "--role", "orchestrator"],
      "env": { "AGENT_HUB_DB": "/tmp/agent-hub.db" }
    }
  }
}
```

**子代理**客户端配置（换 `--name` / `--role` 即可再开 N 个，见 `examples/02-04`）：

```json
{
  "mcpServers": {
    "agent-hub": {
      "command": "mcp-agent-hub",
      "args": ["stdio", "--name", "coder-1", "--role-type", "subagent", "--role", "implementer", "--capabilities", "code,test"],
      "env": { "AGENT_HUB_DB": "/tmp/agent-hub.db" }
    }
  }
}
```

### 场景 2：局域网 / 跨机器（Streamable HTTP）

一台机器起 Hub，其他机器的 Agent 客户端都连上来：

```bash
mcp-agent-hub serve --host 0.0.0.0 --port 8765 --db /var/lib/agent-hub/hub.db
# 或
./scripts/run-serve.sh 0.0.0.0 8765
```

客户端配置：

```json
{
  "mcpServers": {
    "agent-hub": {
      "url": "http://192.168.1.10:8765/mcp"
    }
  }
}
```

HTTP 模式下多个客户端共享一个服务进程。各方先 `join_hub` 登记身份（主理人可 `set_master`），工具也可带 `agent` 参数指定身份。

### 手动设主的两种方式

1. **启动时指定**：`mcp-agent-hub stdio --name boss --role-type master`
2. **运行时指定**：任意 Agent 调用 `set_master(name="boss")`（`exclusive=true` 会把其他人降为子代理，并改挂汇报线）

之后 `join_hub(role_type="subagent")` 的新 Agent 会**自动挂靠**到当前主理人。

### 协作流程（1 主 + N 子）

| 步骤 | 主理人 | 子代理（×N） |
|------|--------|--------------|
| 1. 设主 | `--role-type master` 或 `set_master` | `join_hub(role_type=subagent)` 自动挂靠 |
| 2. 派单 | `dispatch_task(title, assignee=coder-1)` | 收到 order 消息 |
| 3. 领会 | — | `my_assignments` / `read_inbox` |
| 4. 执行 | `team_status` 看全员负载 | `report_progress(task_id, 50, note)` |
| 5. 同步 | `broadcast` / `send_message` | `send_message` / `escalate` |
| 6. 沉淀 | `remember` / `recall` | `remember` / `recall` |
| 7. 交付 | 收到 report | `complete_task(task_id, result)` |

多个子代理可同时干活；任务池模式用 `claim_task` 抢占，避免重复劳动。

## MCP 工具一览

| 分组 | 工具 | 说明 |
|------|------|------|
| 身份 | `whoami` / `join_hub` / `list_agents` / `set_status` | 登记与在场 |
| 设主 | `set_master` | **手动指定**谁是主理人 |
| 主理人 | `dispatch_task` / `team_status` | 派单、盯全员负载 |
| 子代理 | `my_assignments` / `claim_task` / `report_progress` / `complete_task` / `escalate` | 领活、认领、汇报、交付、上报 |
| 任务 | `create_task` / `list_tasks` / `update_task` | 看板与改派（支持 `parent_id` 子任务树） |
| 消息 | `send_message` / `broadcast` / `read_inbox` / `mark_read` | 点对点、全员广播、房间 |
| 房间 | `create_room` / `join_room` / `list_rooms` | 频道协作 |
| 黑板 | `remember` / `recall` / `forget` | 跨 Agent 共享记忆（带版本） |
| 诊断 | `hub_stats` / `activity_log` | 总览与事件流 |

## 环境变量

| 变量 | 默认 | 说明 |
|------|------|------|
| `AGENT_HUB_DB` | `./agent-hub.db` | SQLite 路径（多客户端务必同一文件） |
| `AGENT_NAME` | — | 默认 Agent 名（也可用 `--name`） |
| `AGENT_ROLE_TYPE` | `subagent` | `master` 或 `subagent`（主理人请设为 `master`） |
| `AGENT_ROLE` | — | 职责描述 |
| `AGENT_CAPABILITIES` | — | 能力标签，逗号分隔 |
| `AGENT_REPORTED_TO` | — | 子代理汇报的主理人名字（不填则自动挂靠） |

## 开发

```bash
uv sync
uv run ruff check src tests
uv run ruff format src tests
uv run pyright src
uv run pytest
uv run python tests/e2e_mcp_handshake.py
```

## 设计说明

- **手动设主**：`--role-type master` / `set_master` / `join_hub(role_type=master)` 三种入口。
- **自动挂靠**：子代理入网时若未指定 `reported_to`，自动指向当前主理人。
- **派单**：`dispatch_task` 建任务并给子代理发 `order` 消息；可派给任意多个子代理。
- **回报**：`report_progress` / `complete_task` 自动给主理人发 `report`；`escalate` 标 `blocked` 并发 `escalation`。
- **抢占**：`claim_task` 事务内抢占，失败会提示当前持有者。
- **存储**：SQLite + WAL，多进程/多客户端并发安全。
- **传输**：`stdio`（本机多客户端共享 DB）；`serve`（局域网 Streamable HTTP）。

## License

MIT