# Agent Coordination MCP Server

多 Agent 会话协调系统 — 让多个 Claude Code 会话通过 MCP 协议实现跨会话通信、状态共享、任务调度。

## 功能

- **会话管理** — 注册/注销会话，心跳检测，状态同步
- **消息传递** — 异步点对点消息和广播，支持 TTL 和 ACK
- **任务调度** — 任务看板，支持创建/认领/更新/完成，依赖关系和自动 unblock
- **三角色协作** — 产品经理、规划师、开发人员分工协作完成需求

## 环境要求

- Node.js 18+
- Claude Code（支持 MCP 的版本）

## 下一步

- 开发前后端
- 优化上下文开销

## 安装

```bash
git clone <repo-url>
cd agent-coordination-mcp
npm install
```

### 一键安装（Windows PowerShell）

```powershell
.\setup.ps1
```

该脚本会自动完成：安装依赖 → 类型检查 → 运行测试 → 安装 Skill 到 `~/.claude/skills/`

### 手动安装 Skill

如果不使用 `setup.ps1`，手动将 Skill 复制到 Claude Code 目录：

```bash
# 将 .claude/skills/coordinator/ 复制到全局 skills 目录
cp -r .claude/skills/coordinator ~/.claude/skills/
```

## 配置

### 方式一：通过 Claude Code CLI 添加（推荐）

```bash
claude mcp add coordinator -- npx tsx /path/to/this/project/src/server.ts
```

将 `/path/to/this/project` 替换为本项目的实际路径。

### 方式二：手动编辑 MCP 配置文件

在 Claude Code 的 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "coordinator": {
      "command": "npx",
      "args": ["tsx", "/path/to/this/project/src/server.ts"]
    }
  }
}
```

配置文件位置：
- **全局配置**：`~/.claude/claude_desktop_config.json`
- **项目配置**：项目根目录下的 `.mcp.json`

### 生产模式配置

构建后使用编译产物运行，无需 `tsx`：

```bash
npm run build
```

```json
{
  "mcpServers": {
    "coordinator": {
      "command": "node",
      "args": ["/path/to/this/project/dist/server.js"]
    }
  }
}
```

## 使用

### 1. 启动协调 Skill

在 Claude Code 中输入：

```
/coordinator product-manager
/coordinator planner
/coordinator developer
```

每个会话选择一个角色，Skill 会自动引导完成注册和初始化。

### 2. 三角色协作流程

```
用户提出需求
    │
    ▼
产品经理接收需求 → 创建规划任务 → 分配给规划师
    │
    ▼
规划师分析需求 → 拆解任务 → 输出 spec → 通知产品经理
    │
    ▼
产品经理审查 spec → 通过后创建开发任务 → 分配给开发人员
    │
    ▼
开发人员认领任务 → 按 spec 实现 → 完成后通知产品经理
    │
    ▼
产品经理验收 → 向用户汇报
```

验收失败时：
- **规划问题**（spec 不符合预期）→ 创建任务给规划师重新规划
- **开发问题**（spec 正确但实现有误）→ 创建任务给开发人员修复

### 3. 角色职责

| 角色 | 职责 | 禁止行为 |
|------|------|----------|
| **product-manager** | 接收需求、分配任务、审查 spec、验收结果 | 写代码、绕过规划师 |
| **planner** | 分析需求、拆解任务、输出 spec | 写代码、直接联系开发人员 |
| **developer** | 接收 spec、开发实现、交付验收 | 创建任务、直接联系规划师 |

## MCP Tools 参考

### 会话管理

| Tool | 参数 | 说明 |
|------|------|------|
| `register_session` | `name: string` | 注册会话，同名幂等 |
| `unregister_session` | `session_id: string` | 注销会话，释放任务 |
| `heartbeat` | `session_id: string` | 心跳，建议每 30 秒一次 |
| `update_status` | `session_id, status` | 更新状态（idle/working/error） |
| `list_sessions` | `status?` | 列出会话，可按状态过滤 |

### 消息传递

| Tool | 参数 | 说明 |
|------|------|------|
| `send_message` | `from, to, content, type?` | 发送消息，`to="*"` 为广播 |
| `get_messages` | `session_id, since?, type?` | 获取待处理消息 |
| `ack_message` | `message_id` | 确认消息已处理 |

### 任务管理

| Tool | 参数 | 说明 |
|------|------|------|
| `create_task` | `title, created_by, assignee?, priority?, depends_on?` | 创建任务 |
| `claim_task` | `task_id, session_id` | 认领任务（原子操作） |
| `update_task` | `task_id, status?, assignee?, metadata?` | 更新任务，完成时自动 unblock 下游 |
| `list_tasks` | `status?, assignee?, created_by?` | 查询任务 |
| `watch_task` | `task_id` | 查看任务状态和变更记录 |

## 开发

### 常用命令

```bash
npm run dev          # 开发模式（tsx 直接运行）
npm run build        # 编译 TypeScript
npm start            # 运行编译产物
npm test             # 运行测试（watch 模式）
npm run test:run     # 运行测试（单次）
npm run typecheck    # 类型检查
npm run lint         # ESLint 检查
```

### 项目结构

```
src/
├── server.ts          # MCP Server 入口，注册所有 tools
├── db.ts              # SQLite 数据库初始化和迁移
├── session.ts         # 会话管理（注册、心跳、状态）
├── message.ts         # 消息传递（发送、获取、确认）
├── task.ts            # 任务管理（创建、认领、更新、查询）
├── config.ts          # 配置管理
├── health.ts          # 健康检查
├── alert.ts           # 告警机制
├── audit.ts           # 审计日志
├── api-version.ts     # API 版本管理
├── circuit-breaker.ts # 熔断器
├── types.ts           # 共享类型定义
└── tools.ts           # 工具函数

.claude/skills/coordinator/
├── SKILL.md           # Skill 入口定义
├── workflows.md       # 三角色工作流
└── examples.md        # 工具调用示例
```

### 设计原则

- **会话身份**：每个 Claude Code 会话通过 `register_session` 获得唯一 ID
- **消息异步**：发送方不阻塞，接收方按需拉取，持久化在 SQLite 中
- **任务即真相**：所有会话共享同一个任务看板，状态变更原子化
- **心跳检测**：超过 1 小时无心跳的会话标记为 stale，任务自动释放
- **级联 unblock**：任务完成时自动解除下游 blocked 任务

## License

MIT