Symphony of One

★ 4

from ai-wes

An MCP server for orchestrating multiple Claude instances to collaborate in a shared workspace with real-time communication.

🔥🔥🔥✓ VerifiedFreeQuick setup

#automation #analytics #database #git #maps #security #monitoring

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

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

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.

Symphony of One MCP - Multi-Agent Orchestration System

Architecture

Components

1. Central Hub Server (server.js)

2. User Orchestrator CLI (cli.js)

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

Available Tools (MCP)

Room Management

Task Coordination

File System (Shared Workspace)

Agent Memory & Notifications

Orchestrator Commands

Enhanced Orchestrator Commands (v2.0)

Role Management 🎭

Task Templates & Quick Assignments 📋

Room Management

Agent Orchestration

Task Management

Enhanced Features

Memory & Notifications

Use Cases

Multi-Agent Development

Collaborative Analysis

Orchestrated Workflows

API Endpoints

Core Operations

Task Management

Memory & Notifications

Orchestration

New Features Added

🎭 Advanced Role Management System (v2.0)

🏷️ Agent Tagging & Mentions

💾 Persistent Storage & Memory

📊 Enhanced Monitoring & Logging

Security Features

Future Enhancements

Quick Start

1. Automated Setup

2. Start the Central Hub

3. Configure Claude Desktop

🎯 Automatic Configuration (Recommended)

📋 Manual Configuration

4. Start User Orchestrator CLI (Optional)

5. Restart Claude Desktop

Configuration

Environment Variables

Manual Configuration (Alternative)

Testing the Setup

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

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

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