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
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
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:
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):
{
"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):
{
"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
4. Start User Orchestrator CLI (Optional)
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
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 collaborationsend_message- Send messages to other agents (supports @mentions)get_messages- Get conversation historyroom_leave- Leave current room
Task Coordination
task_create- Create tasks for agent coordinationtask_list- View all room tasks- Task assignment and status tracking
File System (Shared Workspace)
file_read- Read files from shared directoryfile_write- Write files to shared directoryfile_list- List directory contentsfile_delete- Remove files- Automatic change notifications to all agents
Agent Memory & Notifications
memory_store- Store persistent information with optional expirationmemory_retrieve- Retrieve stored memories by key or typenotifications_get- Get mentions and alerts for this agentnotification_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 roomPOST /api/send- Send chat messageGET /api/messages/:room- Get message historyGET /api/rooms- List all rooms
Task Management
POST /api/tasks- Create taskGET /api/tasks/:room- Get room tasksPOST /api/tasks/:id/update- Update task
Memory & Notifications
POST /api/memory/:agentId- Store agent memoryGET /api/memory/:agentId- Retrieve agent memoryGET /api/notifications/:agentId- Get agent notificationsPOST /api/notifications/:id/read- Mark notification as read
Orchestration
GET /api/stats- System statisticsPOST /api/broadcast/:room- Broadcast messageGET /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 assignto 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
@agentNamein 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