# Symphony of One MCP - Multi-Agent Orchestration System

A Model Context Protocol (MCP) server that enables multiple Claude instances to collaborate through a centralized hub with shared workspace and real-time communication.

## Architecture

```
User (Orchestrator) ← Central Hub Server → Shared Working Directory
         ↑                    ↓                        ↑
    Hub CLI Interface    Message Router           File Access
         ↑                    ↓                        ↓
Multiple Claude Code Instances via MCP Servers ← → Collaboration
```

## Components

### 1. Central Hub Server (`server.js`)

- Express + Socket.IO server for agent coordination
- Room-based chat system for agent communication
- Task management and delegation system
- File watching with real-time change notifications
- REST API for agent management and orchestration

### 2. User Orchestrator CLI (`cli.js`)

- Command & control interface for the user
- Agent monitoring and task assignment
- Broadcasting messages to agent groups
- Real-time system statistics and room management

### 3. Claude Agent MCP Server (`mcp-server.js`)

- MCP server that Claude Code instances connect to
- Shared file system access with security constraints
- Real-time chat participation with other agents
- Task execution and progress reporting
- File change notifications and collaboration sync

## Quick Start

### 1. Automated Setup

```bash
npm run setup
```

This will:

- Install all dependencies (including sqlite3)
- Create the shared workspace directory
- Test the MCP server
- Show Claude Desktop configuration instructions

> 🆕 **New in v2.0**: Enhanced CLI with role management, task templates, and tab completion!

### 2. Start the Central Hub

```bash
npm run server
```

This starts the hub server on `http://localhost:3000` with a shared directory at `./shared`

### 3. Configure Claude Desktop

#### **🎯 Automatic Configuration (Recommended)**

Generate the correct configuration for your environment:

```bash
npm run config
```

This creates:

- `claude-config-windows.json` - For Claude Desktop (Windows)
- `claude-config-wsl.json` - For Claude Code (WSL)

**Note:** The examples below show placeholder paths. When you run `npm run config`, it will generate the actual paths for your project location.

#### **📋 Manual Configuration**

Add the appropriate configuration to your Claude Desktop configuration file (usually at `%APPDATA%\Claude\claude_desktop_config.json`):

**For Claude Desktop (Windows):**

```json
{
  "mcpServers": {
    "claude-symphony-of-one": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\project\\mcp-server-wrapper.js"],
      "env": {
        "CHAT_SERVER_URL": "http://localhost:3000",
        "SHARED_DIR": "C:\\path\\to\\your\\project\\shared",
        "AGENT_NAME": "Claude-Agent-Windows"
      }
    }
  }
}
```

**For Claude Code (WSL):**

```json
{
  "mcpServers": {
    "claude-symphony-of-one": {
      "command": "node",
      "args": ["/mnt/c/path/to/your/project/mcp-server-wrapper.js"],
      "env": {
        "CHAT_SERVER_URL": "http://localhost:3000",
        "SHARED_DIR": "/mnt/c/path/to/your/project/shared",
        "AGENT_NAME": "Claude-Agent-WSL"
      }
    }
  }
}
```

**🔧 Note:** The configurations use the smart wrapper script (`mcp-server-wrapper.js`) which automatically handles Windows/WSL path differences.

**📖 For detailed Windows/WSL setup instructions, see [`WINDOWS_WSL_SETUP_GUIDE.md`](./WINDOWS_WSL_SETUP_GUIDE.md)**

### 4. Start User Orchestrator CLI (Optional)

```bash
npm run cli
```

This opens the orchestrator interface for managing agents and tasks.

### 5. Restart Claude Desktop

Restart Claude Desktop to load the MCP server. You should now see the Symphony of One tools available in Claude.

## Configuration

### Environment Variables

- `CHAT_SERVER_URL`: Hub server URL (default: `http://localhost:3000`)
- `SHARED_DIR`: Shared workspace directory (default: `./shared`)
- `AGENT_NAME`: Agent display name (default: auto-generated)
- `PORT`: Hub server port (default: `3000`)

### Manual Configuration (Alternative)

If you prefer manual setup, see the `claude-config-example.json` file for the exact configuration format.

### Testing the Setup

```bash
npm test
```

This will test the MCP server functionality and verify all tools are working correctly.

## Available Tools (MCP)

### Room Management

- `room_join` - Join a chat room for collaboration
- `send_message` - Send messages to other agents (supports @mentions)
- `get_messages` - Get conversation history
- `room_leave` - Leave current room

### Task Coordination

- `task_create` - Create tasks for agent coordination
- `task_list` - View all room tasks
- Task assignment and status tracking

### File System (Shared Workspace)

- `file_read` - Read files from shared directory
- `file_write` - Write files to shared directory
- `file_list` - List directory contents
- `file_delete` - Remove files
- Automatic change notifications to all agents

### Agent Memory & Notifications

- `memory_store` - Store persistent information with optional expiration
- `memory_retrieve` - Retrieve stored memories by key or type
- `notifications_get` - Get mentions and alerts for this agent
- `notification_read` - Mark notifications as read

## Orchestrator Commands

### Enhanced Orchestrator Commands (v2.0)

### Role Management 🎭

- `/role assign` - Interactive role assignment with guided menus
- `/role list` - Show current agent role assignments
- `/roles` - List all available predefined roles
- `/role create` - Create custom organizational roles
- `/role prompt <agent>` - Send role-specific instructions

### Task Templates & Quick Assignments 📋

- `/template list` - Show available task templates
- `/template use <name>` - Create tasks from templates with variables
- `/quick bug` - Emergency bug fix assignment
- `/quick security` - Security incident response
- `/quick feature` - New feature development
- `/quick performance` - Performance optimization
- `/quick review` - Code review request

### Room Management

- `/join <room>` - Join/create a room (with TAB completion)
- `/rooms` - List all rooms
- `/agents` - Show agents in current room with role info
- `/history [n]` - Show recent messages

### Agent Orchestration

- `/broadcast <msg>` - Send message to all agents
- `/assign <agent> <task>` - Assign task to specific agent
- `/tag <agent> <msg>` - Send tagged message to specific agent (@mention)
- `/monitor [room]` - Monitor room activity
- `/stats` - Show system statistics

### Task Management

- `/task create` - Create new tasks
- `/task list` - View all tasks
- `/task update <id>` - Update task status

### Enhanced Features

- **TAB key** - Auto-complete commands and parameters
- **UP/DOWN arrows** - Navigate command history
- **Interactive menus** - Use arrow keys for selections
- `/clear` - Clear screen and show quick start guide

### Memory & Notifications

- `/memory list` - View system memory usage
- `/notifications` - View recent notifications and mentions
- `/logs [type]` - View system activity logs

## Use Cases

### Multi-Agent Development

- Multiple Claude instances work on different parts of a codebase
- Real-time file change notifications keep all agents synchronized
- Task delegation and progress tracking
- Shared workspace prevents conflicts

### Collaborative Analysis

- Agents can specialize in different analysis domains
- Chat-based coordination for complex problem solving
- Shared document editing and review
- Task assignment based on agent capabilities

### Orchestrated Workflows

- User defines high-level goals and delegates to agents
- Agents self-coordinate through chat and task system
- File-based deliverable sharing and review
- Progress monitoring and intervention capabilities

## API Endpoints

### Core Operations

- `POST /api/join/:room` - Agent joins room
- `POST /api/send` - Send chat message
- `GET /api/messages/:room` - Get message history
- `GET /api/rooms` - List all rooms

### Task Management

- `POST /api/tasks` - Create task
- `GET /api/tasks/:room` - Get room tasks
- `POST /api/tasks/:id/update` - Update task

### Memory & Notifications

- `POST /api/memory/:agentId` - Store agent memory
- `GET /api/memory/:agentId` - Retrieve agent memory
- `GET /api/notifications/:agentId` - Get agent notifications
- `POST /api/notifications/:id/read` - Mark notification as read

### Orchestration

- `GET /api/stats` - System statistics
- `POST /api/broadcast/:room` - Broadcast message
- `GET /api/agents/:room` - List room agents

## New Features Added

### 🎭 Advanced Role Management System (v2.0)

- **Predefined Agent Roles**: 11 specialized roles across Development, Analysis, Management, Quality, Operations, Documentation, and Research
- **Interactive Role Assignment**: Use `/role assign` to assign roles to agents with guided menus
- **Task Templates**: 7+ predefined templates for common workflows (code review, feature implementation, bug fixes, etc.)
- **Quick Assignments**: Instant task creation with `/quick bug`, `/quick security`, etc. that auto-suggest appropriate agents
- **Tab Completion**: IntelliSense-like command completion with TAB key
- **Custom Roles & Templates**: Create organization-specific roles and task templates

### 🏷️ Agent Tagging & Mentions

- Use `@agentName` in messages to tag specific agents
- Tagged agents receive real-time notifications
- Orchestrator can use `/tag <agent> <message>` for direct communication
- Persistent notification storage and management

### 💾 Persistent Storage & Memory

- SQLite database for all messages, tasks, and agent data
- Agent memory system with optional expiration
- Persistent notification system with read/unread status
- Comprehensive logging with Winston
- Data survives server restarts

### 📊 Enhanced Monitoring & Logging

- Real-time activity monitoring
- Persistent message and event logging
- System statistics and memory usage tracking
- Agent activity and performance metrics

## Security Features

- Path traversal protection for file operations
- Sandboxed shared directory access
- Agent capability declarations and validation
- WebSocket authentication and room isolation
- Secure memory storage with expiration
- Audit trail for all agent actions

## Future Enhancements

- Agent authentication and permissions
- File locking for concurrent access
- Task dependencies and workflows
- Agent discovery and capability matching
- Advanced monitoring and analytics
- Memory cleanup and optimization
- Notification channels and routing