LacyLights

Diseño de iluminación teatral impulsado por IA para el sistema LacyLights.

Documentación

Servidor MCP de LacyLights

Un servidor MCP (Protocolo de Contexto de Modelo) que proporciona capacidades de diseño de iluminación teatral impulsadas por IA para el sistema LacyLights. Este servidor permite a los asistentes de IA crear, gestionar y controlar diseños profesionales de iluminación teatral mediante interacciones en lenguaje natural.

¿Qué es LacyLights MCP?

LacyLights MCP es una interfaz inteligente de control de iluminación que une la brecha entre la visión creativa y la ejecución técnica. Permite a diseñadores de iluminación, directores y técnicos:

Diseñar looks de iluminación usando descripciones en lenguaje natural
Analizar guiones teatrales para generar automáticamente señales de iluminación
Gestionar accesorios DMX de varios fabricantes
Crear y ejecutar secuencias de señales para representaciones teatrales
Optimizar diseños de iluminación para impacto dramático o eficiencia energética

El sistema utiliza IA para comprender la intención artística y traducirla en valores DMX precisos para accesorios de iluminación del mundo real.

Referencia Completa de Funciones

Gestión de Proyectos

list_projects - Listar todos los proyectos de iluminación disponibles con conteos opcionales de accesorios/looks
create_project - Crear un nuevo proyecto de iluminación para una producción
get_project_details - Obtener detalles completos sobre un proyecto específico
delete_project - Eliminar un proyecto y todos los datos asociados (requiere confirmación)
qlc_import_guidance - Obtener información sobre la importación de archivos QLC+ (.qxw)

Gestión de Accesorios

get_fixture_inventory - Consultar accesorios disponibles y sus capacidades
analyze_fixture_capabilities - Análisis profundo de capacidades de accesorios (mezcla de colores, posicionamiento, efectos)
create_fixture_instance - Agregar un nuevo accesorio a un proyecto con detalles de fabricante/modelo
get_channel_map - Ver el mapa de uso de canales DMX para un proyecto
suggest_channel_assignment - Obtener asignaciones óptimas de canales para múltiples accesorios
update_fixture_instance - Modificar propiedades de accesorios existentes
delete_fixture_instance - Eliminar un accesorio de un proyecto (requiere confirmación)

Creación y Gestión de Looks

generate_look - Generación de looks impulsada por IA basada en descripciones y contexto
analyze_script - Extraer señales de iluminación y sugerencias de guiones teatrales
optimize_look - Optimizar looks para varios objetivos (energía, impacto, simplicidad)
update_look - Actualizar propiedades de looks y valores de accesorios
activate_look - Activar un look por nombre o ID
fade_to_black - Desvanecer todas las luces a negro con temporización personalizable
get_current_active_look - Obtener información sobre el look actualmente activo

Operaciones Avanzadas de Looks

add_fixtures_to_look - Agregar accesorios a looks existentes
remove_fixtures_from_look - Eliminar accesorios específicos de looks
get_look_fixture_values - Leer valores actuales de accesorios en un look
ensure_fixtures_in_look - Asegurar que los accesorios existan con valores específicos
update_look_partial - Actualizaciones parciales de looks con fusión de accesorios
bulk_update_looks_partial - Actualizaciones parciales por lotes en múltiples looks con fusión de accesorios

Gestión de Secuencias de Señales

create_cue_sequence - Construir secuencias de señales a partir de looks existentes
generate_act_cues - Generar listas completas de señales para actos teatrales
optimize_cue_timing - Optimizar la temporización de señales para varias estrategias
analyze_cue_structure - Analizar listas de señales con recomendaciones

Operaciones de Listas de Señales

update_cue_list - Actualizar metadatos de listas de señales
add_cue_to_list - Agregar nuevas señales a listas existentes
remove_cue_from_list - Eliminar señales de listas
update_cue - Modificar propiedades individuales de señales
bulk_update_cues - Actualizar múltiples señales simultáneamente
reorder_cues - Reordenar señales con nueva numeración
get_cue_list_details - Consultar señales con filtrado y ordenamiento
delete_cue_list - Eliminar listas completas de señales (requiere confirmación)

Control de Reproducción de Señales

start_cue_list - Comenzar la reproducción de una lista de señales desde cualquier punto
next_cue - Avanzar a la siguiente señal
previous_cue - Retroceder a la señal anterior
go_to_cue - Saltar a una señal específica por número o nombre
stop_cue_list - Detener la lista de señales actualmente en reproducción
get_cue_list_status - Obtener estado de reproducción y opciones de navegación

Gestión del Tablero de Looks

Los Tableros de Looks proporcionan un sistema de diseño visual para organizar y activar looks con posiciones de botones personalizables en un lienzo 2D (predeterminado 2000x2000 píxeles).

CRUD de Tableros de Looks

list_look_boards - Listar todos los tableros de looks en un proyecto con conteos de botones
get_look_board - Obtener un tablero de looks específico con todos los botones y diseño
create_look_board - Crear un nuevo tablero de looks con configuración personalizada de lienzo y cuadrícula
update_look_board - Actualizar metadatos y configuración del tablero de looks
delete_look_board - Eliminar un tablero de looks y todos sus botones (requiere confirmación)
bulk_create_look_boards - Crear múltiples tableros de looks en una sola operación
bulk_update_look_boards - Actualizar múltiples tableros de looks en una sola operación
bulk_delete_look_boards - Eliminar múltiples tableros de looks en una sola operación

Gestión de Botones del Tablero de Looks

add_look_to_board - Agregar un look como botón en una posición específica del lienzo
update_look_board_button - Actualizar propiedades del botón (posición, tamaño, color, etiqueta)
remove_look_from_board - Eliminar un botón de un tablero de looks
update_look_board_button_positions - Actualización por lotes de posiciones de botones (arrastrar y soltar)
bulk_create_look_board_buttons - Crear múltiples botones en una sola operación
bulk_update_look_board_buttons - Actualizar múltiples botones en una sola operación
bulk_delete_look_board_buttons - Eliminar múltiples botones en una sola operación

Reproducción del Tablero de Looks

activate_look_from_board - Activar un look desde un tablero (usa el tiempo de desvanecimiento predeterminado del tablero)
create_look_board_with_buttons - Crear un tablero de looks completo con botones en un solo comando

Instalación

Instalar dependencias:

npm install

Configurar variables de entorno:

cp .env.example .env
# Edit .env with your configuration

Construir el proyecto:

npm run build

Configuración

Variables de Entorno Requeridas

OPENAI_API_KEY - Clave API de OpenAI para la generación de iluminación impulsada por IA
LACYLIGHTS_GRAPHQL_ENDPOINT - Punto final GraphQL para tu backend lacylights-go (predeterminado: http://localhost:4000/graphql)

Variables de Entorno Opcionales

CHROMA_HOST - Host de ChromaDB para funcionalidad RAG mejorada (predeterminado: localhost)
CHROMA_PORT - Puerto de ChromaDB (predeterminado: 8000)

Ejecución del Servidor

Asegúrate de que tu backend lacylights-go esté ejecutándose primero, luego:

# Start in development mode (with auto-reload)
npm run dev

# Or build and run in production mode
npm run build
npm start

Deberías ver:

RAG service initialized with in-memory patterns
LacyLights MCP Server running on stdio

Integración con Claude

Agrega este servidor a tu configuración de Claude:

{
  "mcpServers": {
    "lacylights": {
      "command": "/usr/local/bin/node",
      "args": ["/path/to/lacylights-mcp/run-mcp.js"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here",
        "LACYLIGHTS_GRAPHQL_ENDPOINT": "http://localhost:4000/graphql"
      }
    }
  }
}

Importante:

Usa la ruta absoluta a run-mcp.js en tu configuración
Si lo anterior no funciona, encuentra tu ruta de Node.js con: which node
El script envoltorio asegura la carga adecuada del módulo CommonJS

Lanzamientos y Versionado

Canales de Lanzamiento

LacyLights MCP soporta dos canales de lanzamiento:

Lanzamientos Estables (ej., 1.4.0, 1.5.0)
- Versiones listas para producción
- Completamente probadas y validadas
- Listadas como "Última" en GitHub
- Actualiza latest.json para descubrimiento automático
Lanzamientos Beta (ej., 1.4.1b1, 1.5.0b2)
- Versiones preliminares para pruebas
- Nuevas características y cambios experimentales
- Marcadas como "Pre-lanzamiento" en GitHub
- No afecta el latest.json estable

Formato de Versión

Estable: X.Y.Z (versionado semántico)
- X = Versión principal (cambios disruptivos)
- Y = Versión menor (nuevas características)
- Z = Versión de parche (correcciones de errores)
Beta: X.Y.Zb[N] (beta con iteración)
- b = Identificador beta
- [N] = Número de iteración beta (1, 2, 3, ...)

Instalación de Versiones Específicas

Instalar Última Estable (Recomendado)

# Download latest stable release
curl -s https://dist.lacylights.com/releases/mcp/latest.json | jq -r '.url' | xargs curl -LO

# Extract archive
tar -xzf lacylights-mcp-*.tar.gz
cd lacylights-mcp

# Install and run
npm ci --omit=dev
npm start

Instalar Versión Específica

# Download specific version (replace X.Y.Z with actual version)
VERSION="1.4.0"  # or "1.4.1b1" for beta
curl -LO https://dist.lacylights.com/releases/mcp/lacylights-mcp-${VERSION}.tar.gz

# Verify SHA256 checksum (optional but recommended)
curl -s https://dist.lacylights.com/releases/mcp/latest.json | jq -r '.sha256'
sha256sum lacylights-mcp-${VERSION}.tar.gz

# Extract and run
tar -xzf lacylights-mcp-${VERSION}.tar.gz
cd lacylights-mcp
npm ci --omit=dev
npm start

Instalar Beta para Pruebas

# Download latest beta (check GitHub releases for version)
VERSION="1.5.0b2"
curl -LO https://dist.lacylights.com/releases/mcp/lacylights-mcp-${VERSION}.tar.gz

# Extract and test
tar -xzf lacylights-mcp-${VERSION}.tar.gz
cd lacylights-mcp
npm ci --omit=dev
npm start

Distribución de Lanzamientos

Todos los lanzamientos se distribuyen a través de múltiples canales:

Lanzamientos de GitHub: https://github.com/bbernstein/lacylights-mcp/releases
- Código fuente
- Archivos precompilados
- Notas de lanzamiento
Distribución S3: https://dist.lacylights.com/releases/mcp/
- Descargas directas de archivos
- Sumas de verificación SHA256
- Metadatos latest.json
Registro DynamoDB:
- Seguimiento de versiones
- Metadatos de lanzamiento
- Indicadores de pre-lanzamiento

Programa de Pruebas Beta

¿Quieres ayudar a probar nuevas características? Instala lanzamientos beta:

Buscar betas: Visita Lanzamientos de GitHub
- Busca lanzamientos marcados como "Pre-lanzamiento"
- Formato de versión: X.Y.Zb[N]
Instalar beta:
```
# See "Install Beta for Testing" above
```
Reportar problemas:
- Abre problemas en GitHub
- Incluye el número de versión
- Proporciona pasos de reproducción

Proceso de Lanzamiento

Para mantenedores: Consulta RELEASE_PROCESS.md para documentación completa de lanzamiento que incluye:

Flujos de trabajo de lanzamiento beta
Procedimientos de lanzamiento estable
Gestión de versiones
Verificación de distribución
Solución de problemas y reversión

Ejemplo Completo: Diseño de Iluminación para Macbeth

Aquí hay un ejemplo completo que muestra cómo un diseñador de iluminación usaría LacyLights MCP para crear un diseño de iluminación completo para Macbeth de Shakespeare:

Paso 1: Crear el Proyecto

Use create_project to create a new project called "Macbeth - Main Stage 2024"
with description "Shakespeare's Macbeth, directed by Jane Smith, March 2024 production"

Paso 2: Configurar Accesorios

Use create_fixture_instance to add these fixtures to the project:
- 12x Chauvet SlimPAR Pro RGBA fixtures for front wash (channels 1-48)
- 8x Martin MAC Quantum Profile moving heads for specials (channels 100-163)
- 6x ETC Source Four LED Series 2 for side lighting (channels 200-241)
- 4x Chauvet Strike 4 strobes for storm effects (channels 300-315)
- 2x Rosco Vapour Plus hazers for atmosphere (channels 400-403)

Paso 3: Analizar el Guion

Use analyze_script with the full text of Act 1 to extract:
- All lighting cues mentioned in stage directions
- Scene transitions that need lighting changes
- Mood and atmosphere requirements for each scene

Paso 4: Generar Looks Clave

Use generate_look to create these essential looks:

1. "Opening - Thunder and Lightning"
   - Script context: "Thunder and lightning. Enter three witches."
   - Mood: ominous, supernatural
   - Color palette: ["deep purple", "electric blue", "white strobe"]
   - Intensity: dramatic

2. "Duncan's Arrival at Inverness"
   - Script context: "Hautboys and torches. Enter Duncan, Malcolm, Donalbain, Banquo"
   - Mood: regal, warm
   - Color palette: ["warm amber", "gold", "soft orange"]
   - Intensity: moderate

3. "Lady Macbeth Reads the Letter"
   - Script context: "Enter Lady Macbeth, reading a letter"
   - Mood: intimate, plotting
   - Color palette: ["cool blue", "pale amber", "shadow"]
   - Focus areas: ["center stage", "downstage center"]

4. "The Dagger Soliloquy"
   - Script context: "Is this a dagger which I see before me"
   - Mood: hallucinatory, tense
   - Color palette: ["blood red", "deep shadow", "cold steel blue"]
   - Intensity: subtle
   - Focus areas: ["center stage spot"]

5. "Murder of Duncan"
   - Script context: "Macbeth exits to kill Duncan, bell rings"
   - Mood: dark, suspenseful
   - Color palette: ["deep red", "black", "moonlight blue"]
   - Intensity: dramatic

6. "Banquo's Ghost Appears"
   - Script context: "The Ghost of Banquo enters, and sits in Macbeth's place"
   - Mood: supernatural, terrifying
   - Color palette: ["ghostly green", "cold white", "shadow"]
   - Effects: use moving heads for ghost tracking

7. "Lady Macbeth's Sleepwalking"
   - Script context: "Enter Lady Macbeth with a taper"
   - Mood: haunted, guilty
   - Color palette: ["candlelight amber", "moonlight", "deep shadow"]
   - Focus areas: ["follow spot", "single candle effect"]

8. "Final Battle"
   - Script context: "Alarums. Enter Macbeth and Macduff fighting"
   - Mood: violent, chaotic
   - Color palette: ["fire red", "steel blue", "explosive white"]
   - Intensity: dramatic
   - Effects: strobe for sword clashes

Paso 5: Crear Secuencias de Señales

Use create_cue_sequence to build the Act 1 cue list:
- Name: "Act 1 - Complete"
- Include all Act 1 looks in order
- Set default fade times: 3 seconds in, 3 seconds out
- Add follow cues for quick transitions during soliloquies

Paso 6: Generar Señales de Actos con Análisis del Guion

Use generate_act_cues with the complete text of Act 2:
- This will analyze the script and create a complete cue list
- Automatically times transitions based on dramatic pacing
- Suggests lighting changes for every entrance, exit, and mood shift

Paso 7: Optimizar para el Rendimiento

Use optimize_cue_timing on the Act 1 cue list:
- Strategy: "dramatic_timing"
- This will adjust fade times for maximum dramatic impact
- Smooth transitions for scene changes
- Sharp cuts for supernatural appearances

Paso 8: Crear Secuencias de Efectos Especiales

Use create_cue_sequence for the storm effect:
1. Lightning Strike 1 (strobes at full, 0.1s)
2. Thunder Roll (deep blue wash, 2s fade)
3. Lightning Strike 2 (strobes at 75%, 0.15s)
4. Return to storm base (purple/blue, 3s fade)
- Set follow times for automatic progression

Paso 9: Ejecutar el Espectáculo

Durante la representación, el director de escena puede usar:

start_cue_list "Act 1 - Complete"
next_cue  # Advance through each cue
go_to_cue 15.5  # Jump to specific cue for pickups
fade_to_black 5  # Emergency blackout with 5-second fade

Paso 10: Hacer Ajustes en Vivo

Use update_look to adjust the "Banquo's Ghost" look:
- Increase moving head intensity for better visibility
- Adjust color temperature based on costume reflectance
- Fine-tune positioning for actor's blocking changes

Ejemplos de Uso Avanzado

Flujo de Trabajo de Diseño Impulsado por Guion

1. Analyze the entire script:
   analyze_script with full play text

2. Review extracted cues and looks

3. Generate all suggested looks in batch:
   generate_look for each suggestion

4. Create master cue list:
   create_cue_sequence with all looks

5. Optimize for your venue:
   optimize_look for each look with "technical_simplicity"

Configuración Multi-Universo

For large productions spanning multiple DMX universes:

1. Plan channel allocation:
   suggest_channel_assignment for all fixtures

2. Create fixtures with specific universe assignments:
   create_fixture_instance with universe: 1 for front lights
   create_fixture_instance with universe: 2 for moving heads
   create_fixture_instance with universe: 3 for effects

3. View the complete channel map:
   get_channel_map for the project

Proceso de Diseño Colaborativo

Director requests:
"I want the witches' scenes to feel otherworldly but not cartoonish"

Use generate_look:
- Description: "Witches on the heath"
- Mood: "otherworldly, mysterious"
- Color palette: ["deep violet", "fog grey", "pale green"]
- Intensity: "subtle"

Then iterate with optimize_look using "dramatic_impact" until satisfied

Características Impulsadas por IA

Análisis Inteligente de Guiones

Extrae señales de iluminación explícitas de las acotaciones escénicas
Identifica necesidades de iluminación implícitas del diálogo y la acción
Sugiere iluminación atmosférica basada en el contexto dramático
Reconoce convenciones teatrales estándar (amanecer, atardecer, tormentas)

Generación de Looks Consciente del Contexto

Comprende principios de iluminación teatral
Aplica teoría del color para impacto emocional
Considera capacidades y posiciones de accesorios
Genera valores DMX que respetan restricciones del mundo real

Optimización Adaptativa

Eficiencia Energética: Reduce el consumo de energía manteniendo la intención artística
Impacto Dramático: Mejora el contraste y el enfoque para máximo efecto
Simplicidad Técnica: Simplifica la programación para una operación más fácil
Precisión de Color: Optimiza para una reproducción de color verdadera

Solución de Problemas

Problemas Comunes

Errores de importación de módulos
- Asegúrate de que la versión de Node.js sea 18+ como se especifica en package.json
- Usa el script envoltorio run-mcp.js, no dist/index.js directamente
Errores de conexión GraphQL
- Verifica que tu backend lacylights-go esté ejecutándose en el puerto 4000
- Revisa la variable de entorno LACYLIGHTS_GRAPHQL_ENDPOINT
Errores de API de OpenAI
- Asegúrate de que tu OPENAI_API_KEY esté configurado en el archivo .env
- Verifica que la clave API tenga acceso a GPT-4
Errores de conexión MCP en Claude
- Usa la ruta absoluta completa en tu configuración de Claude
- Reinicia Claude después de actualizar la configuración de MCP
- Revisa los registros de Claude para mensajes de error detallados
Error de "token inesperado ?"
- Actualiza tu configuración para usar la ruta completa a Node.js 14+
- En macOS con Homebrew: "command": "/opt/homebrew/bin/node"
- En otros sistemas, encuentra tu ruta de node con: which node

Configuración de ChromaDB (Opcional - Para RAG Mejorado)

El servidor MCP funciona de inmediato con almacenamiento de patrones en memoria. Para almacenamiento vectorial persistente y coincidencia de patrones más sofisticada:

Opción 1: Docker (Recomendado)

# Start ChromaDB with Docker
docker-compose up -d chromadb

# Verify it's running
curl http://localhost:8000/api/v2/heartbeat

Opción 2: Instalación Local

# Install ChromaDB
pip install chromadb

# Start the server
chroma run --host localhost --port 8000

Luego actualiza tu archivo .env:

# Uncomment these lines in .env
CHROMA_HOST=localhost
CHROMA_PORT=8000

Integración con el Ecosistema LacyLights

Este servidor MCP es parte del sistema completo LacyLights:

lacylights-go - API GraphQL de backend para la gestión de accesorios y looks
lacylights-fe - Frontend web para control manual y visualización
lacylights-mcp - Interfaz de IA para automatización inteligente

El servidor MCP mejora el sistema existente con:

Control mediante lenguaje natural
Generación inteligente de looks
Capacidades de análisis de guiones
Creación automatizada de cues
Optimización de rendimiento

Desarrollo

Estructura del Proyecto

src/
├── tools/           # MCP tool implementations
│   ├── fixture-tools.ts    # Fixture management operations
│   ├── look-tools.ts       # Look creation and control
│   ├── cue-tools.ts        # Cue list management
│   └── project-tools.ts    # Project operations
├── services/        # Core services
│   ├── graphql-client.ts   # GraphQL API client
│   ├── rag-service.ts      # RAG pattern matching
│   └── ai-lighting.ts      # AI look generation
├── types/          # TypeScript type definitions
│   └── lighting.ts         # Core lighting types
└── index.ts        # MCP server entry point

Añadir Nuevas Herramientas

Crea la implementación de la herramienta en el archivo correspondiente bajo src/tools/
Añade la definición de la herramienta a src/index.ts en el manejador ListToolsRequestSchema
Añade el manejador de la herramienta en el manejador CallToolRequestSchema
Actualiza este README con la documentación de la herramienta

Pruebas

npm test

Directorio MCP

Licencia

MIT