# 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)
#### **📋 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:\\Users\\wes\\Desktop\\claude-symphony-of-one-mcp\\mcp-server-wrapper.js"
],
"env": {
"CHAT_SERVER_URL": "http://localhost:3000",
"SHARED_DIR": "C:\\Users\\wes\\Desktop\\claude-symphony-of-one-mcp\\shared",
"AGENT_NAME": "Claude-Agent-Windows"
}
}
}
}
```
**For Claude Code (WSL):**
```json
{
"mcpServers": {
"claude-symphony-of-one": {
"command": "node",
"args": [
"/mnt/c/Users/wes/Desktop/claude-symphony-of-one-mcp/mcp-server-wrapper.js"
],
"env": {
"CHAT_SERVER_URL": "http://localhost:3000",
"SHARED_DIR": "/mnt/c/Users/wes/Desktop/claude-symphony-of-one-mcp/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
