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 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 ` - Send role-specific instructions

Task Templates & Quick Assignments 📋

• `/template list` - Show available task templates
• `/template use ` - 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 ` - 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 ` - Send message to all agents
• `/assign ` - Assign task to specific agent
• `/tag ` - 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 ` - 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 ` 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