Symphony of One

Un servidor MCP para orquestar múltiples instancias de Claude que colaboran en un espacio de trabajo compartido con comunicación en tiempo real.

GitHub
4
Prueba este MCPPatrocinado

Documentación

Symphony of One MCP - Sistema de Orquestación Multi-Agente

Un servidor de Model Context Protocol (MCP) que permite que múltiples instancias de Claude colaboren a través de un hub centralizado con espacio de trabajo compartido y comunicación en tiempo real.

Arquitectura

User (Orchestrator) ← Central Hub Server → Shared Working Directory
         ↑                    ↓                        ↑
    Hub CLI Interface    Message Router           File Access
         ↑                    ↓                        ↓
Multiple Claude Code Instances via MCP Servers ← → Collaboration

Componentes

1. Servidor Hub Central (server.js)

  • Servidor Express + Socket.IO para coordinación de agentes
  • Sistema de chat basado en salas para comunicación de agentes
  • Sistema de gestión y delegación de tareas
  • Monitoreo de archivos con notificaciones de cambios en tiempo real
  • API REST para gestión y orquestación de agentes

2. CLI de Orquestador de Usuario (cli.js)

  • Interfaz de comando y control para el usuario
  • Monitoreo de agentes y asignación de tareas
  • Difusión de mensajes a grupos de agentes
  • Estadísticas del sistema en tiempo real y gestión de salas

3. Servidor MCP de Agente Claude (mcp-server.js)

  • Servidor MCP al que se conectan las instancias de Claude Code
  • Acceso al sistema de archivos compartido con restricciones de seguridad
  • Participación en chat en tiempo real con otros agentes
  • Ejecución de tareas e informes de progreso
  • Notificaciones de cambios de archivos y sincronización de colaboración

Inicio Rápido

1. Configuración Automatizada

npm run setup

Esto hará lo siguiente:

  • Instalar todas las dependencias (incluyendo sqlite3)
  • Crear el directorio del espacio de trabajo compartido
  • Probar el servidor MCP
  • Mostrar instrucciones de configuración de Claude Desktop

🆕 Nuevo en v2.0: CLI mejorado con gestión de roles, plantillas de tareas y autocompletado con TAB.

2. Iniciar el Hub Central

npm run server

Esto inicia el servidor hub en http://localhost:3000 con un directorio compartido en ./shared

3. Configurar Claude Desktop

🎯 Configuración Automática (Recomendada)

Genera la configuración correcta para tu entorno:

npm run config

Esto crea:

  • claude-config-windows.json - Para Claude Desktop (Windows)
  • claude-config-wsl.json - Para Claude Code (WSL)

Nota: Los ejemplos a continuación muestran rutas de marcador de posición. Cuando ejecutes npm run config, generará las rutas reales para la ubicación de tu proyecto.

📋 Configuración Manual

Añade la configuración apropiada a tu archivo de configuración de Claude Desktop (generalmente en %APPDATA%\Claude\claude_desktop_config.json):

Para 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"
      }
    }
  }
}

Para 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"
      }
    }
  }
}

🔧 Nota: Las configuraciones utilizan el script wrapper inteligente (mcp-server-wrapper.js) que maneja automáticamente las diferencias de rutas entre Windows/WSL.

📖 Para instrucciones detalladas de configuración de Windows/WSL, consulta WINDOWS_WSL_SETUP_GUIDE.md

4. Iniciar CLI de Orquestador de Usuario (Opcional)

npm run cli

Esto abre la interfaz del orquestador para gestionar agentes y tareas.

5. Reiniciar Claude Desktop

Reinicia Claude Desktop para cargar el servidor MCP. Ahora deberías ver las herramientas de Symphony of One disponibles en Claude.

Configuración

Variables de Entorno

  • CHAT_SERVER_URL: URL del servidor hub (predeterminado: http://localhost:3000)
  • SHARED_DIR: Directorio del espacio de trabajo compartido (predeterminado: ./shared)
  • AGENT_NAME: Nombre de visualización del agente (predeterminado: generado automáticamente)
  • PORT: Puerto del servidor hub (predeterminado: 3000)

Configuración Manual (Alternativa)

Si prefieres la configuración manual, consulta el archivo claude-config-example.json para conocer el formato exacto de configuración.

Prueba de la Configuración

npm test

Esto probará la funcionalidad del servidor MCP y verificará que todas las herramientas funcionen correctamente.

Herramientas Disponibles (MCP)

Gestión de Salas

  • room_join - Unirse a una sala de chat para colaboración
  • send_message - Enviar mensajes a otros agentes (admite @menciones)
  • get_messages - Obtener historial de conversación
  • room_leave - Salir de la sala actual

Coordinación de Tareas

  • task_create - Crear tareas para coordinación de agentes
  • task_list - Ver todas las tareas de la sala
  • Asignación de tareas y seguimiento de estado

Sistema de Archivos (Espacio de Trabajo Compartido)

  • file_read - Leer archivos del directorio compartido
  • file_write - Escribir archivos en el directorio compartido
  • file_list - Listar contenido del directorio
  • file_delete - Eliminar archivos
  • Notificaciones automáticas de cambios a todos los agentes

Memoria y Notificaciones del Agente

  • memory_store - Almacenar información persistente con expiración opcional
  • memory_retrieve - Recuperar memorias almacenadas por clave o tipo
  • notifications_get - Obtener menciones y alertas para este agente
  • notification_read - Marcar notificaciones como leídas

Comandos del Orquestador

Comandos Mejorados del Orquestador (v2.0)

Gestión de Roles 🎭

  • /role assign - Asignación interactiva de roles con menús guiados
  • /role list - Mostrar asignaciones de roles actuales de los agentes
  • /roles - Listar todos los roles predefinidos disponibles
  • /role create - Crear roles organizacionales personalizados
  • /role prompt <agent> - Enviar instrucciones específicas de rol

Plantillas de Tareas y Asignaciones Rápidas 📋

  • /template list - Mostrar plantillas de tareas disponibles
  • /template use <name> - Crear tareas a partir de plantillas con variables
  • /quick bug - Asignación de corrección de errores de emergencia
  • /quick security - Respuesta a incidentes de seguridad
  • /quick feature - Desarrollo de nuevas funciones
  • /quick performance - Optimización de rendimiento
  • /quick review - Solicitud de revisión de código

Gestión de Salas

  • /join <room> - Unirse/crear una sala (con autocompletado con TAB)
  • /rooms - Listar todas las salas
  • /agents - Mostrar agentes en la sala actual con información de rol
  • /history [n] - Mostrar mensajes recientes

Orquestación de Agentes

  • /broadcast <msg> - Enviar mensaje a todos los agentes
  • /assign <agent> <task> - Asignar tarea a un agente específico
  • /tag <agent> <msg> - Enviar mensaje etiquetado a un agente específico (@mención)
  • /monitor [room] - Monitorear actividad de la sala
  • /stats - Mostrar estadísticas del sistema

Gestión de Tareas

  • /task create - Crear nuevas tareas
  • /task list - Ver todas las tareas
  • /task update <id> - Actualizar estado de la tarea

Funciones Mejoradas

  • Tecla TAB - Autocompletar comandos y parámetros
  • Flechas ARRIBA/ABAJO - Navegar por el historial de comandos
  • Menús interactivos - Usar teclas de flecha para selecciones
  • /clear - Limpiar pantalla y mostrar guía de inicio rápido

Memoria y Notificaciones

  • /memory list - Ver uso de memoria del sistema
  • /notifications - Ver notificaciones y menciones recientes
  • /logs [type] - Ver registros de actividad del sistema

Casos de Uso

Desarrollo Multi-Agente

  • Múltiples instancias de Claude trabajan en diferentes partes de un código base
  • Las notificaciones de cambios de archivos en tiempo real mantienen sincronizados a todos los agentes
  • Delegación de tareas y seguimiento de progreso
  • El espacio de trabajo compartido previene conflictos

Análisis Colaborativo

  • Los agentes pueden especializarse en diferentes dominios de análisis
  • Coordinación basada en chat para resolución de problemas complejos
  • Edición y revisión de documentos compartidos
  • Asignación de tareas basada en capacidades del agente

Flujos de Trabajo Orquestados

  • El usuario define objetivos de alto nivel y delega en los agentes
  • Los agentes se autocoordinan a través del sistema de chat y tareas
  • Compartir y revisar entregables basados en archivos
  • Capacidades de monitoreo de progreso e intervención

Endpoints de API

Operaciones Principales

  • POST /api/join/:room - El agente se une a la sala
  • POST /api/send - Enviar mensaje de chat
  • GET /api/messages/:room - Obtener historial de mensajes
  • GET /api/rooms - Listar todas las salas

Gestión de Tareas

  • POST /api/tasks - Crear tarea
  • GET /api/tasks/:room - Obtener tareas de la sala
  • POST /api/tasks/:id/update - Actualizar tarea

Memoria y Notificaciones

  • POST /api/memory/:agentId - Almacenar memoria del agente
  • GET /api/memory/:agentId - Recuperar memoria del agente
  • GET /api/notifications/:agentId - Obtener notificaciones del agente
  • POST /api/notifications/:id/read - Marcar notificación como leída

Orquestación

  • GET /api/stats - Estadísticas del sistema
  • POST /api/broadcast/:room - Mensaje de difusión
  • GET /api/agents/:room - Listar agentes de la sala

Nuevas Funciones Añadidas

🎭 Sistema Avanzado de Gestión de Roles (v2.0)

  • Roles de Agente Predefinidos: 11 roles especializados en Desarrollo, Análisis, Gestión, Calidad, Operaciones, Documentación e Investigación
  • Asignación Interactiva de Roles: Usa /role assign para asignar roles a los agentes con menús guiados
  • Plantillas de Tareas: 7+ plantillas predefinidas para flujos de trabajo comunes (revisión de código, implementación de funciones, corrección de errores, etc.)
  • Asignaciones Rápidas: Creación instantánea de tareas con /quick bug, /quick security, etc. que sugieren automáticamente agentes apropiados
  • Autocompletado con TAB: Completado de comandos tipo IntelliSense con la tecla TAB
  • Roles y Plantillas Personalizados: Crear roles y plantillas de tareas específicos de la organización

🏷️ Etiquetado y Menciones de Agentes

  • Usa @agentName en los mensajes para etiquetar agentes específicos
  • Los agentes etiquetados reciben notificaciones en tiempo real
  • El orquestador puede usar /tag <agent> <message> para comunicación directa
  • Almacenamiento y gestión persistente de notificaciones

💾 Almacenamiento Persistente y Memoria

  • Base de datos SQLite para todos los mensajes, tareas y datos de agentes
  • Sistema de memoria del agente con expiración opcional
  • Sistema de notificaciones persistente con estado leído/no leído
  • Registro integral con Winston
  • Los datos sobreviven a los reinicios del servidor

📊 Monitoreo y Registro Mejorados

  • Monitoreo de actividad en tiempo real
  • Registro persistente de mensajes y eventos
  • Estadísticas del sistema y seguimiento del uso de memoria
  • Métricas de actividad y rendimiento de agentes

Funciones de Seguridad

  • Protección contra traversal de rutas para operaciones de archivos
  • Acceso a directorio compartido en sandbox
  • Declaraciones y validación de capacidades de agentes
  • Autenticación WebSocket y aislamiento de salas
  • Almacenamiento seguro de memoria con expiración
  • Registro de auditoría para todas las acciones de agentes

Mejoras Futuras

  • Autenticación y permisos de agentes
  • Bloqueo de archivos para acceso concurrente
  • Dependencias de tareas y flujos de trabajo
  • Descubrimiento de agentes y coincidencia de capacidades
  • Monitoreo y análisis avanzados
  • Limpieza y optimización de memoria
  • Canales de notificación y enrutamiento