LacyLights

Design de iluminação teatral com inteligência artificial para o sistema LacyLights.

Documentação

Servidor MCP LacyLights

Um servidor MCP (Model Context Protocol) que fornece recursos de design de iluminação teatral com inteligência artificial para o sistema LacyLights. Este servidor permite que assistentes de IA criem, gerenciem e controlem designs profissionais de iluminação teatral por meio de interações em linguagem natural.

O que é o LacyLights MCP?

O LacyLights MCP é uma interface inteligente de controle de iluminação que preenche a lacuna entre a visão criativa e a execução técnica. Ele permite que designers de iluminação, diretores e técnicos possam:

Criar looks de iluminação usando descrições em linguagem natural
Analisar roteiros teatrais para gerar automaticamente cues de iluminação
Gerenciar fixtures DMX de diversos fabricantes
Criar e executar sequências de cues para apresentações teatrais
Otimizar designs de iluminação para impacto dramático ou eficiência energética

O sistema usa IA para entender a intenção artística e traduzi-la em valores DMX precisos para fixtures de iluminação do mundo real.

Referência Completa de Funções

Gerenciamento de Projetos

list_projects - Lista todos os projetos de iluminação disponíveis com contagens opcionais de fixtures/looks
create_project - Cria um novo projeto de iluminação para uma produção
get_project_details - Obtém detalhes abrangentes sobre um projeto específico
delete_project - Exclui um projeto e todos os dados associados (requer confirmação)
qlc_import_guidance - Obtém informações sobre importação de arquivos QLC+ (.qxw)

Gerenciamento de Fixtures

get_fixture_inventory - Consulta fixtures disponíveis e suas capacidades (as definições incluem source: BUILTIN, OFL, GDTF, EOS, USER ou SYNTHESIZED, quando o backend as reporta)
import_gdtf_fixtures - Importa tipos de fixtures GDTF de arquivos .gdtf, arquivos .zip contendo-os, ou pastas no host do MCP (veja abaixo)
analyze_fixture_capabilities - Análise aprofundada das capacidades dos fixtures (mistura de cores, posicionamento, efeitos). Os sinalizadores de capacidade incluem hasColorTemperature (canal COLOR_TEMPERATURE), hasHueSaturation (tanto HUE quanto SATURATION, reportado como mistura "Hue/Saturation (HSI)") e hasSpeed (canal SPEED; a análise de posicionamento o reporta como speedControl)
create_fixture_instance - Adiciona um novo fixture a um projeto com detalhes de fabricante/modelo
get_channel_map - Visualiza o mapa de uso de canais DMX de um projeto
suggest_channel_assignment - Obtém atribuições ideais de canais para múltiplos fixtures
update_fixture_instance - Modifica propriedades existentes de fixtures
delete_fixture_instance - Remove um fixture de um projeto (requer confirmação)

Criação e Gerenciamento de Looks

generate_look - Geração de looks com IA baseada em descrições e contexto
analyze_script - Extrai cues de iluminação e sugestões de roteiros teatrais
optimize_look - Otimiza looks para diversos objetivos (energia, impacto, simplicidade)
update_look - Atualiza propriedades de looks e valores de fixtures
activate_look - Ativa um look por nome ou ID
fade_to_black - Apaga todas as luzes gradualmente com temporização personalizável
get_current_active_look - Obtém informações sobre o look atualmente ativo

Operações Avançadas de Looks

add_fixtures_to_look - Adiciona fixtures a looks existentes
remove_fixtures_from_look - Remove fixtures específicos de looks
get_look_fixture_values - Lê valores atuais de fixtures em um look
ensure_fixtures_in_look - Garante que fixtures existam com valores específicos
update_look_partial - Atualizações parciais de looks com mesclagem de fixtures
bulk_update_looks_partial - Atualizações parciais em lote em múltiplos looks com mesclagem de fixtures

Gerenciamento de Sequências de Cues

create_cue_sequence - Constrói sequências de cues a partir de looks existentes
generate_act_cues - Gera listas completas de cues para atos teatrais
optimize_cue_timing - Otimiza a temporização de cues para diversas estratégias
analyze_cue_structure - Analisa listas de cues com recomendações

Operações com Listas de Cues

update_cue_list - Atualiza metadados de listas de cues
add_cue_to_list - Adiciona novos cues a listas existentes
remove_cue_from_list - Remove cues de listas
update_cue - Modifica propriedades individuais de cues
bulk_update_cues - Atualiza múltiplos cues simultaneamente
reorder_cues - Reordena cues com nova numeração
get_cue_list_details - Consulta cues com filtragem e ordenação
delete_cue_list - Exclui listas inteiras de cues (requer confirmação)

Controle de Reprodução de Cues

start_cue_list - Inicia a reprodução de uma lista de cues a partir de qualquer ponto
next_cue - Avança para o próximo cue
previous_cue - Volta para o cue anterior
go_to_cue - Salta para um cue específico por número ou nome
stop_cue_list - Interrompe a lista de cues em reprodução
get_cue_list_status - Obtém o status da reprodução e opções de navegação

Gerenciamento de Look Boards

Os Look Boards fornecem um sistema de layout visual para organizar e acionar looks com posições de botões personalizáveis em uma tela 2D (padrão de 2000x2000 pixels).

CRUD de Look Boards

list_look_boards - Lista todos os look boards em um projeto com contagens de botões
get_look_board - Obtém um look board específico com todos os botões e layout
create_look_board - Cria um novo look board com configurações personalizadas de tela e grade
update_look_board - Atualiza metadados e configurações de look boards
delete_look_board - Exclui um look board e todos os seus botões (requer confirmação)
bulk_create_look_boards - Cria múltiplos look boards em uma única operação
bulk_update_look_boards - Atualiza múltiplos look boards em uma única operação
bulk_delete_look_boards - Exclui múltiplos look boards em uma única operação

Gerenciamento de Botões de Look Boards

add_look_to_board - Adiciona um look como botão em uma posição específica da tela
update_look_board_button - Atualiza propriedades do botão (posição, tamanho, cor, rótulo)
remove_look_from_board - Remove um botão de um look board
update_look_board_button_positions - Atualização em lote de posições de botões (arrastar e soltar)
bulk_create_look_board_buttons - Cria múltiplos botões em uma única operação
bulk_update_look_board_buttons - Atualiza múltiplos botões em uma única operação
bulk_delete_look_board_buttons - Exclui múltiplos botões em uma única operação

Reprodução de Look Boards

activate_look_from_board - Ativa um look de um board (usa o tempo de fade padrão do board)
create_look_board_with_buttons - Cria um look board completo com botões em um único comando

Importação de Fixtures GDTF

import_gdtf_fixtures({ paths, onExisting? }) - Lê cada caminho no computador que executa o servidor MCP: um .gdtf, um .zip de arquivos .gdtf (zips aninhados até 2 níveis), ou uma pasta pesquisada recursivamente (pastas ocultas e arquivos não-GDTF ignorados, symlinks que saem da pasta não são seguidos). Apenas o description.xml de cada fixture é enviado para a mutação importGdtfFixtures do backend, em lotes de até 25 arquivos. onExisting é UPDATE (padrão) ou SKIP para tipos de fixtures importados anteriormente. Retorna contagens de criados/atualizados/inalterados/pulados/falhos e uma lista por arquivo (limitada a 100, falhas primeiro).

Os limites correspondem ao backend: no máximo 2000 entradas por arquivo, description.xml de no máximo 32 MB, entradas __MACOSX/ e ._* puladas. Arquivos ilegíveis são reportados como FAILED e nunca interrompem os demais. Importe apenas arquivos que você fornecer; a ferramenta nunca baixa do GDTF Share.

Exportação de Dados (CSV / Excel)

Requer lacylights-go v0.4.0 ou mais recente; backends mais antigos recebem uma mensagem de "atualize o LacyLights".

list_data_export_tables - Lista tabelas exportáveis com suas colunas e escopo (quais IDs cada exportação precisa)
export_data_table - Exporta uma tabela como CSV (retornado inline, truncado com uma nota quando grande) ou XLSX (gravado em um arquivo; o caminho é retornado)
export_data_workbook - Exporta várias tabelas do projeto como uma pasta de trabalho XLSX de múltiplas planilhas gravada em um arquivo

Os arquivos são gravados no argumento outputDirectory da ferramenta, caso contrário em LACYLIGHTS_EXPORT_DIR, caso contrário em uma pasta privada (0700) lacylights-exports no diretório temporário do sistema. Os arquivos são criados com modo 0600 e nunca sobrescrevem um arquivo existente (um sufixo numérico é adicionado). Observe que outputDirectory é escolhido pelo assistente de IA e pode ser qualquer diretório em que o processo do servidor MCP possa gravar. Defina LACYLIGHTS_EXPORT_DIR para dar às exportações um local previsível e mantenha o assistente nesse padrão.

Instalação

Instale as dependências:

npm install

Configure as variáveis de ambiente:

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

Compile o projeto:

npm run build

Configuração

Variáveis de Ambiente

LACYLIGHTS_GRAPHQL_ENDPOINT - Endpoint GraphQL para seu backend lacylights-go (padrão: http://localhost:4000/graphql)
OPENAI_API_KEY - Chave da API OpenAI, necessária apenas para as ferramentas de geração com IA (ex.: generate_look, analyze_script, generate_act_cues). O servidor inicia sem ela e todas as outras ferramentas funcionam; as ferramentas de IA então retornam um erro pedindo para você configurá-la.

Variáveis de Ambiente Opcionais

CHROMA_HOST - Host do ChromaDB para funcionalidade RAG aprimorada (padrão: localhost)
CHROMA_PORT - Porta do ChromaDB (padrão: 8000)
LACYLIGHTS_EXPORT_DIR - Diretório para arquivos de exportação de dados CSV/XLSX (padrão: lacylights-exports no diretório temporário do sistema)

Executando o Servidor

Certifique-se de que seu backend lacylights-go esteja em execução primeiro, depois:

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

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

Você deve ver:

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

Integração com Claude

Adicione este servidor à sua configuração do 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:

Use o caminho absoluto para run-mcp.js em sua configuração
Se o acima não funcionar, encontre o caminho do seu Node.js com: which node
O script wrapper garante o carregamento adequado do módulo CommonJS

Lançamentos e Versionamento

Canais de Lançamento

O LacyLights MCP suporta dois canais de lançamento:

Lançamentos Estáveis (ex.: 1.4.0, 1.5.0)
- Versões prontas para produção
- Totalmente testadas e validadas
- Listadas como "Latest" no GitHub
- Atualizam latest.json para descoberta automática
Lançamentos Beta (ex.: 1.4.1b1, 1.5.0b2)
- Versões de pré-lançamento para testes
- Novos recursos e mudanças experimentais
- Marcadas como "Pre-release" no GitHub
- Não afetam o latest.json estável

Formato de Versão

Estável: X.Y.Z (versionamento semântico)
- X = Versão principal (mudanças que quebram compatibilidade)
- Y = Versão secundária (novos recursos)
- Z = Versão de correção (correções de bugs)
Beta: X.Y.Zb[N] (beta com iteração)
- b = Identificador beta
- [N] = Número da iteração beta (1, 2, 3, ...)

Instalando Versões Específicas

Instalar a Última Estável (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 Versão 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 Testes

# 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

Distribuição de Lançamentos

Todos os lançamentos são distribuídos por múltiplos canais:

Lançamentos do GitHub: https://github.com/bbernstein/lacylights-mcp/releases
- Código-fonte
- Arquivos pré-compilados
- Notas de lançamento
Distribuição S3: https://dist.lacylights.com/releases/mcp/
- Downloads diretos de arquivos
- Checksums SHA256
- Metadados latest.json
Registro DynamoDB:
- Rastreamento de versões
- Metadados de lançamento
- Sinalizadores de pré-lançamento

Programa de Testes Beta

Quer ajudar a testar novos recursos? Instale lançamentos beta:

Verifique betas: Visite GitHub Releases
- Procure por lançamentos marcados como "Pre-release"
- Formato de versão: X.Y.Zb[N]
Instale o beta:
```
# See "Install Beta for Testing" above
```
Reporte problemas:
- Abra issues no GitHub
- Inclua o número da versão
- Forneça etapas de reprodução

Processo de Lançamento

Para mantenedores: Consulte RELEASE_PROCESS.md para documentação completa de lançamento, incluindo:

Fluxos de trabalho de lançamento beta
Procedimentos de lançamento estável
Gerenciamento de versões
Verificação de distribuição
Solução de problemas e reversão

Exemplo Completo: Design de Iluminação para Macbeth

Aqui está um exemplo abrangente mostrando como um designer de iluminação usaria o LacyLights MCP para criar um design de iluminação completo para a peça Macbeth, de Shakespeare:

Etapa 1: Criar o Projeto

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"

Etapa 2: Configurar Equipamentos

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)

Etapa 3: Analisar o Roteiro

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

Etapa 4: Gerar Looks Principais

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

Etapa 5: Criar Sequências de Cue

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

Etapa 6: Gerar Cues dos Atos com Análise do Roteiro

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

Etapa 7: Otimizar para Performance

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

Etapa 8: Criar Sequências de Efeitos Especiais

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

Etapa 9: Executar o Espetáculo

Durante a apresentação, o gerente de palco pode 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

Etapa 10: Fazer Ajustes ao 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

Exemplos de Uso Avançado

Fluxo de Trabalho de Design Orientado por Roteiro

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"

Configuração Multi-Universe

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

Processo de Design 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

Recursos Impulsionados por IA

Análise Inteligente de Roteiro

Extrai cues de iluminação explícitas das direções de palco
Identifica necessidades implícitas de iluminação a partir de diálogos e ações
Sugere iluminação atmosférica com base no contexto dramático
Reconhece convenções teatrais padrão (nascer do sol, pôr do sol, tempestades)

Geração de Looks Contextual

Compreende princípios de iluminação teatral
Aplica teoria das cores para impacto emocional
Considera capacidades e posições dos equipamentos
Gera valores DMX que respeitam restrições do mundo real

Otimização Adaptativa

Eficiência Energética: Reduz o consumo de energia mantendo a intenção artística
Impacto Dramático: Melhora contraste e foco para efeito máximo
Simplicidade Técnica: Simplifica a programação para operação mais fácil
Precisão de Cores: Otimiza para reprodução fiel de cores

Solução de Problemas

Problemas Comuns

Erros de importação de módulos
- Certifique-se de que a versão do Node.js seja 18+, conforme especificado no package.json
- Use o script wrapper run-mcp.js, não dist/index.js diretamente
Erros de conexão GraphQL
- Verifique se o backend lacylights-go está rodando na porta 4000
- Verifique a variável de ambiente LACYLIGHTS_GRAPHQL_ENDPOINT
Erros da API OpenAI (ex.: "This tool requires OpenAI, but OPENAI_API_KEY is not set")
- Defina OPENAI_API_KEY no bloco env da configuração do seu cliente MCP (ou exporte no shell que inicia o servidor) e reinicie o servidor. O servidor não carrega um arquivo .env por conta própria
- Verifique se a chave da API tem acesso ao GPT-4
Erros de conexão MCP no Claude
- Use o caminho absoluto completo na configuração do Claude
- Reinicie o Claude após atualizar a configuração do MCP
- Verifique os logs do Claude para mensagens de erro detalhadas
Erro "Unexpected token ?"
- Atualize sua configuração para usar o caminho completo para Node.js 14+
- No macOS com Homebrew: "command": "/opt/homebrew/bin/node"
- Em outros sistemas, encontre o caminho do node com: which node

Configuração do ChromaDB (Opcional - Para RAG Aprimorado)

O servidor MCP funciona imediatamente com armazenamento de padrões em memória. Para armazenamento vetorial persistente e correspondência de padrões mais sofisticada:

Opção 1: Docker (Recomendado)

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

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

Opção 2: Instalação Local

# Install ChromaDB
pip install chromadb

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

Em seguida, atualize seu arquivo .env:

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

Integração com o Ecossistema LacyLights

Este servidor MCP faz parte do sistema completo LacyLights:

lacylights-go - API GraphQL backend para gerenciamento de equipamentos e looks
lacylights-fe - Frontend web para controle manual e visualização
lacylights-mcp - Interface de IA para automação inteligente

O servidor MCP aprimora o sistema existente com:

Controle por linguagem natural
Geração inteligente de looks
Capacidades de análise de roteiro
Criação automatizada de cues
Otimização de performance

Desenvolvimento

Estrutura do Projeto

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

Adicionando Novas Ferramentas

Crie a implementação da ferramenta no arquivo apropriado em src/tools/
Adicione a definição da ferramenta a src/index.ts no handler ListToolsRequestSchema
Adicione o handler da ferramenta no handler CallToolRequestSchema
Atualize este README com a documentação da ferramenta

Testes

npm test

Diretório MCP

Licença

MIT