Content
# Agent Coordination MCP Server
Multi-Agent Session Coordination System — Enables multiple Claude Code sessions to communicate across sessions, share state, and schedule tasks via the MCP protocol.
## Features
- **Session Management** — Register/unregister sessions, heartbeat detection, state synchronization
- **Message Passing** — Asynchronous point-to-point messages and broadcasts, supporting TTL and ACK
- **Task Scheduling** — Task board, supporting creation/claiming/updating/completion, dependency relationships, and automatic unblocking
- **Three-Role Collaboration** — Product manager, planner, and developer collaborate to complete requirements
## Environment Requirements
- Node.js 18+
- Claude Code (version supporting MCP)
## Next Steps
- Develop front-end and back-end
- Optimize context overhead
## Installation
```bash
git clone <repo-url>
cd agent-coordination-mcp
npm install
```
### One-Click Installation (Windows PowerShell)
```powershell
.\setup.ps1
```
This script will automatically complete: dependency installation → type checking → running tests → installing Skill to `~/.claude/skills/`
### Manual Skill Installation
If not using `setup.ps1`, manually copy the Skill to the Claude Code directory:
```bash
# Copy .claude/skills/coordinator/ to the global skills directory
cp -r .claude/skills/coordinator ~/.claude/skills/
```
## Configuration
### Method 1: Add via Claude Code CLI (Recommended)
```bash
claude mcp add coordinator -- npx tsx /path/to/this/project/src/server.ts
```
Replace `/path/to/this/project` with the actual path to this project.
### Method 2: Manually Edit MCP Configuration File
Add to the MCP configuration file in Claude Code:
```json
{
"mcpServers": {
"coordinator": {
"command": "npx",
"args": ["tsx", "/path/to/this/project/src/server.ts"]
}
}
}
```
Configuration file locations:
- **Global Configuration**: `~/.claude/claude_desktop_config.json`
- **Project Configuration**: `.mcp.json` in the project root directory
### Production Mode Configuration
Use compiled output to run after building, without `tsx`:
```bash
npm run build
```
```json
{
"mcpServers": {
"coordinator": {
"command": "node",
"args": ["/path/to/this/project/dist/server.js"]
}
}
}
```
## Usage
### 1. Start Coordination Skill
Enter in Claude Code:
```
/coordinator product-manager
/coordinator planner
/coordinator developer
```
Each session selects a role, and the Skill will automatically guide completion of registration and initialization.
### 2. Three-Role Collaboration Process
```
User proposes requirement
│
▼
Product manager receives requirement → creates planning task → assigns to planner
│
▼
Planner analyzes requirement → breaks down task → outputs spec → notifies product manager
│
▼
Product manager reviews spec → creates development task after approval → assigns to developer
│
▼
Developer claims task → implements according to spec → notifies product manager upon completion
│
▼
Product manager verifies → reports to user
```
Upon failed verification:
- **Planning issues** (spec does not meet expectations) → create task for planner to re-plan
- **Development issues** (spec correct but implementation incorrect) → create task for developer to fix
### 3. Role Responsibilities
| Role | Responsibilities | Prohibited Actions |
|------|---------------|--------------------|
| **product-manager** | Receive requirements, assign tasks, review spec, verify results | Write code, bypass planner |
| **planner** | Analyze requirements, break down tasks, output spec | Write code, directly contact developer |
| **developer** | Receive spec, develop implementation, deliver verification | Create tasks, directly contact planner |
## MCP Tools Reference
### Session Management
| Tool | Parameters | Description |
|------|------------|-------------|
| `register_session` | `name: string` | Register session, idempotent with same name |
| `unregister_session` | `session_id: string` | Unregister session, release tasks |
| `heartbeat` | `session_id: string` | Heartbeat, recommended every 30 seconds |
| `update_status` | `session_id, status` | Update status (idle/working/error) |
| `list_sessions` | `status?` | List sessions, filter by status |
### Message Passing
| Tool | Parameters | Description |
|------|------------|-------------|
| `send_message` | `from, to, content, type?` | Send message, `to="*"` for broadcast |
| `get_messages` | `session_id, since?, type?` | Get pending messages |
| `ack_message` | `message_id` | Confirm message processed |
### Task Management
| Tool | Parameters | Description |
|------|------------|-------------|
| `create_task` | `title, created_by, assignee?, priority?, depends_on?` | Create task |
| `claim_task` | `task_id, session_id` | Claim task (atomic operation) |
| `update_task` | `task_id, status?, assignee?, metadata?` | Update task, automatically unblock downstream upon completion |
| `list_tasks` | `status?, assignee?, created_by?` | Query tasks |
| `watch_task` | `task_id` | View task status and change records |
## Development
### Common Commands
```bash
npm run dev # Development mode (tsx runs directly)
npm run build # Compile TypeScript
npm start # Run compiled output
npm test # Run tests (watch mode)
npm run test:run # Run tests (single run)
npm run typecheck # Type checking
npm run lint # ESLint checking
```
### Project Structure
```
src/
├── server.ts # MCP Server entry, registers all tools
├── db.ts # SQLite database initialization and migration
├── session.ts # Session management (registration, heartbeat, status)
├── message.ts # Message passing (send, get, confirm)
├── task.ts # Task management (create, claim, update, query)
├── config.ts # Configuration management
├── health.ts # Health check
├── alert.ts # Alert mechanism
├── audit.ts # Audit log
├── api-version.ts # API version management
├── circuit-breaker.ts # Circuit breaker
├── types.ts # Shared type definitions
└── tools.ts # Utility functions
.claude/skills/coordinator/
├── SKILL.md # Skill entry definition
├── workflows.md # Three-role workflow
└── examples.md # Tool invocation examples
```
### Design Principles
- **Session Identity**: Each Claude Code session obtains a unique ID via `register_session`
- **Asynchronous Messaging**: Sender does not block, receiver pulls as needed, persisted in SQLite
- **Task as Truth**: All sessions share the same task board, state changes are atomic
- **Heartbeat Detection**: Sessions without heartbeats for over 1 hour marked as stale, tasks automatically released
- **Cascading Unblock**: Tasks automatically unblock downstream blocked tasks upon completion
## License
MIT
