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. Install Dependencies

npm install

2. Start the Central Hub

npm run server

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

3. Start User Orchestrator CLI

npm run cli

This opens the orchestrator interface for managing agents and tasks.

4. Connect Claude Agents

Each Claude Code instance connects via the MCP server:

node mcp-server.js

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`)

Claude Code Integration

Add to your MCP configuration:

{
  "mcpServers": {
    "claude-gateway": {
      "command": "node",
      "args": ["path/to/Symphony-of-One-MCP/mcp-server.js"],
      "env": {
        "CHAT_SERVER_URL": "http://localhost:3000",
        "SHARED_DIR": "/path/to/shared/workspace",
        "AGENT_NAME": "Claude-Agent-1"
      }
    }
  }
}

Available Tools (MCP)

Room Management

• `room_join` - Join a chat room for collaboration
• `room_send` - Send messages to other agents (supports @mentions)
• `room_history` - Get conversation history
• `room_list` - List all active rooms
• `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

Room Management

• `/join ` - Join/create a room
• `/rooms` - List all rooms
• `/agents` - Show agents in current room
• `/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

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

🏷️ 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