内容
# 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
