# Claude Orchestrator MCP

An MCP server for coordinating multiple Claude Code sessions across related projects. When you're working on a multi-service system with separate repos (e.g., auth service, API gateway, frontend), this orchestrator enables sessions to communicate changes, request sync points, and stay aware of what's happening in related services.

## The Problem

You have 6 repos for a platform, each with its own Claude Code session. When the auth service session modifies the User schema:

- The API gateway session has no idea
- The frontend session keeps using old types
- Someone has to manually copy/paste context between terminals
- Changes get out of sync, causing integration issues

## The Solution

Claude Orchestrator acts as a coordination layer:

```
┌─────────────────────────────────────────────────────────────┐
│                 claude-orchestrator-mcp                      │
│                                                             │
│  Sessions register → Changes detected → Updates routed      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
         │           │           │           │
    ┌────┴───┐  ┌────┴───┐  ┌────┴───┐  ┌────┴───┐
    │ Auth   │  │ API    │  │ Catalog│  │Frontend│
    │Session │  │Session │  │Session │  │Session │
    └────────┘  └────────┘  └────────┘  └────────┘
```

## Installation

```bash
# Clone and build
git clone <repo>
cd claude-orchestrator-mcp
npm install
npm run build

# Or install globally
npm install -g claude-orchestrator-mcp
```

## Quick Start

### 1. Initialize configuration

```bash
# Create example topology
npx claude-orchestrator init

# Or manually create your topology
npx claude-orchestrator group create my-platform
npx claude-orchestrator member add my-platform ~/repos/auth-service --role auth
npx claude-orchestrator member add my-platform ~/repos/api-gateway --role gateway --depends-on auth
npx claude-orchestrator member add my-platform ~/repos/frontend --role frontend --depends-on gateway
```

### 2. Add to Claude Code MCP configuration

Add to your `~/.claude.json`:

```json
{
  "mcpServers": {
    "claude-orchestrator": {
      "command": "node",
      "args": ["/path/to/claude-orchestrator-mcp/dist/index.js"]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "claude-orchestrator": {
      "command": "npx",
      "args": ["-y", "claude-orchestrator-mcp"]
    }
  }
}
```

### 3. Use in your Claude Code sessions

When starting work in a repo:

```
> Use the register_session tool with repoPath="/Users/me/repos/auth-service",
  projectGroup="my-platform", role="auth"
```

Check for updates from other sessions:

```
> Use get_cross_project_updates with my session ID
```

Notify others about a change:

```
> Use notify_related_sessions to broadcast that I modified the User schema
```

## Configuration

The topology configuration lives at `~/.config/claude-orchestrator/topology.yml`:

```yaml
version: "1.0"

groups:
  my-platform:
    name: my-platform
    description: "My multi-service platform"

    members:
      - path: ~/repos/auth-service
        role: auth
        exports: [UserToken, AuthContext]

      - path: ~/repos/api-gateway
        role: gateway
        dependsOn: [auth]

      - path: ~/repos/frontend
        role: frontend
        dependsOn: [gateway]

    communicationRules:
      - when: schema_change
        from: "*"
        notify: dependents
        priority: high

      - when: breaking_change
        from: "*"
        notify: all
        priority: critical
```

### Change Types

- `schema_change` - Database/GraphQL/Protobuf schema changes
- `api_endpoint_change` - Route/controller/API changes
- `type_definition_change` - TypeScript/interface changes
- `config_change` - Configuration file changes
- `dependency_update` - package.json/requirements.txt changes
- `breaking_change` - Detected via commit message patterns
- `any_change` - Catch-all for any file change

### Notification Targets

- `"all"` - Notify all members in the group
- `"dependents"` - Notify only members that depend on the source
- `["role1", "role2"]` - Notify specific roles

## MCP Tools

### Session Management

| Tool | Description |
|------|-------------|
| `register_session` | Register this session with the orchestrator |
| `unregister_session` | Unregister when done |
| `heartbeat` | Keep session active, update current task |

### Cross-Project Updates

| Tool | Description |
|------|-------------|
| `get_cross_project_updates` | Check for updates from related sessions |
| `notify_related_sessions` | Broadcast a change to related sessions |

### State Queries

| Tool | Description |
|------|-------------|
| `query_project_state` | Query another project's status/changes |
| `list_group_sessions` | List all sessions in a project group |

### Sync Points

| Tool | Description |
|------|-------------|
| `request_sync_point` | Request coordination barrier |
| `acknowledge_sync_point` | Acknowledge a sync request |
| `get_pending_sync_points` | Get pending sync requests |

### Topology

| Tool | Description |
|------|-------------|
| `get_topology` | Get project topology configuration |

## CLI Commands

```bash
# Group management
claude-orchestrator group create <name>
claude-orchestrator group list
claude-orchestrator group show <name>
claude-orchestrator group delete <name>

# Member management
claude-orchestrator member add <group> <path> --role <role> --depends-on <roles>
claude-orchestrator member remove <group> <path>

# Rule management
claude-orchestrator rule add <group> --when <type> --from <roles> --notify <targets>

# Utilities
claude-orchestrator validate
claude-orchestrator init
claude-orchestrator config-path
```

## How It Works

1. **Session Registration**: Each Claude Code session registers with the orchestrator, providing its repo path, project group, and role.

2. **Change Detection**: The orchestrator watches registered repos for file changes (via chokidar) and git commits (via polling). Changes are classified by type based on file patterns.

3. **Event Routing**: When changes are detected, the topology manager determines which sessions should be notified based on communication rules and dependency relationships.

4. **Update Queuing**: Updates are queued for target sessions. When a session calls `get_cross_project_updates`, it receives all pending notifications.

5. **Sync Points**: Sessions can request sync points for coordinated changes. Other sessions are notified and can acknowledge before the requester proceeds.

## Example Workflow

```
Terminal 1 (auth-service):
> Register session for auth-service in my-platform group
> [Working on User schema changes...]
> Notify related sessions: "Modified User schema, added refreshToken field"

Terminal 2 (api-gateway):
> Register session for api-gateway in my-platform group
> Check for cross-project updates
> [Receives notification about User schema change]
> "Update UserToken type to include refreshToken"

Terminal 3 (frontend):
> Register session for frontend in my-platform group
> Check for cross-project updates
> [Receives notification via gateway dependency chain]
> "Update auth context to handle new token field"
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run CLI
npm run cli -- group list

# Type check
npm run typecheck

# Run tests
npm test
```

## License

MIT