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 capacidades de design de iluminação teatral com IA 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 marcações de iluminação
Gerenciar equipamentos DMX de diversos fabricantes
Criar e executar sequências de marcações 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 equipamentos de iluminação reais.

Referência Completa de Funções

Gerenciamento de Projetos

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

Gerenciamento de Equipamentos

get_fixture_inventory - Consultar equipamentos disponíveis e suas capacidades
analyze_fixture_capabilities - Análise aprofundada das capacidades dos equipamentos (mistura de cores, posicionamento, efeitos)
create_fixture_instance - Adicionar um novo equipamento a um projeto com detalhes de fabricante/modelo
get_channel_map - Visualizar mapa de uso de canais DMX para um projeto
suggest_channel_assignment - Obter atribuições ideais de canais para múltiplos equipamentos
update_fixture_instance - Modificar propriedades de equipamentos existentes
delete_fixture_instance - Remover um equipamento 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 - Extrair marcações de iluminação e sugestões de roteiros teatrais
optimize_look - Otimizar looks para diversos objetivos (energia, impacto, simplicidade)
update_look - Atualizar propriedades de looks e valores de equipamentos
activate_look - Ativar um look por nome ou ID
fade_to_black - Esmaecer todas as luzes para preto com temporização personalizável
get_current_active_look - Obter informações sobre o look atualmente ativo

Operações Avançadas de Looks

add_fixtures_to_look - Adicionar equipamentos a looks existentes
remove_fixtures_from_look - Remover equipamentos específicos de looks
get_look_fixture_values - Ler valores atuais de equipamentos em um look
ensure_fixtures_in_look - Garantir que equipamentos existam com valores específicos
update_look_partial - Atualizações parciais de looks com mesclagem de equipamentos
bulk_update_looks_partial - Atualizações parciais em lote em múltiplos looks com mesclagem de equipamentos

Gerenciamento de Sequências de Marcações

create_cue_sequence - Construir sequências de marcações a partir de looks existentes
generate_act_cues - Gerar listas completas de marcações para atos teatrais
optimize_cue_timing - Otimizar temporização de marcações para diversas estratégias
analyze_cue_structure - Analisar listas de marcações com recomendações

Operações com Listas de Marcações

update_cue_list - Atualizar metadados de listas de marcações
add_cue_to_list - Adicionar novas marcações a listas existentes
remove_cue_from_list - Remover marcações de listas
update_cue - Modificar propriedades individuais de marcações
bulk_update_cues - Atualizar múltiplas marcações simultaneamente
reorder_cues - Reordenar marcações com nova numeração
get_cue_list_details - Consultar marcações com filtragem e ordenação
delete_cue_list - Excluir listas inteiras de marcações (requer confirmação)

Controle de Reprodução de Marcações

start_cue_list - Iniciar a reprodução de uma lista de marcações de qualquer ponto
next_cue - Avançar para a próxima marcação
previous_cue - Voltar para a marcação anterior
go_to_cue - Pular para uma marcação específica por número ou nome
stop_cue_list - Parar a lista de marcações em reprodução
get_cue_list_status - Obter status de reprodução e opções de navegação

Gerenciamento de Painéis de Looks

Os Painéis de Looks 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 2000x2000 pixels).

CRUD de Painéis de Looks

list_look_boards - Listar todos os painéis de looks em um projeto com contagens de botões
get_look_board - Obter um painel de looks específico com todos os botões e layout
create_look_board - Criar um novo painel de looks com configurações personalizadas de tela e grade
update_look_board - Atualizar metadados e configurações do painel de looks
delete_look_board - Excluir um painel de looks e todos os seus botões (requer confirmação)
bulk_create_look_boards - Criar múltiplos painéis de looks em uma única operação
bulk_update_look_boards - Atualizar múltiplos painéis de looks em uma única operação
bulk_delete_look_boards - Excluir múltiplos painéis de looks em uma única operação

Gerenciamento de Botões do Painel de Looks

add_look_to_board - Adicionar um look como botão em uma posição específica da tela
update_look_board_button - Atualizar propriedades do botão (posição, tamanho, cor, rótulo)
remove_look_from_board - Remover um botão de um painel de looks
update_look_board_button_positions - Atualização em lote de posições de botões (arrastar e soltar)
bulk_create_look_board_buttons - Criar múltiplos botões em uma única operação
bulk_update_look_board_buttons - Atualizar múltiplos botões em uma única operação
bulk_delete_look_board_buttons - Excluir múltiplos botões em uma única operação

Reprodução do Painel de Looks

activate_look_from_board - Ativar um look de um painel (usa o tempo de esmaecimento padrão do painel)
create_look_board_with_buttons - Criar um painel de looks completo com botões em um único comando

Instalação

Instalar dependências:

npm install

Configurar variáveis de ambiente:

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

Compilar o projeto:

npm run build

Configuração

Variáveis de Ambiente Obrigatórias

OPENAI_API_KEY - Chave da API OpenAI para geração de iluminação com IA
LACYLIGHTS_GRAPHQL_ENDPOINT - Endpoint GraphQL para seu backend lacylights-go (padrão: http://localhost:4000/graphql)

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)

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 seu caminho do 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 "Mais recente" no GitHub
- Atualiza latest.json para descoberta automática
Lançamentos Beta (ex.: 1.4.1b1, 1.5.0b2)
- Versões pré-lançamento para testes
- Novos recursos e mudanças experimentais
- Marcadas como "Pré-lançamento" no GitHub
- Não afeta 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 no 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 por betas: Visite Lançamentos no GitHub
- Procure por lançamentos marcados como "Pré-lançamento"
- 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 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 Marcações

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 Marcações 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-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

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 com IA

Análise Inteligente de Roteiros

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

Geração de Looks Sensível ao Contexto

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 renderizaçã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 seu backend lacylights-go está em execução na porta 4000
- Verifique a variável de ambiente LACYLIGHTS_GRAPHQL_ENDPOINT
Erros da API OpenAI
- Certifique-se de que sua OPENAI_API_KEY esteja definida no arquivo .env
- Verifique se a chave da API tem acesso ao GPT-4
Erros de conexão MCP no Claude
- Use o caminho absoluto completo em sua 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 seu 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 de backend para gerenciamento de fixtures 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 scripts
Criação automatizada de cues
Otimização de desempenho

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 em src/index.ts no manipulador ListToolsRequestSchema
Adicione o manipulador da ferramenta no manipulador CallToolRequestSchema
Atualize este README com a documentação da ferramenta

Testes

npm test

Diretório MCP

Licença

MIT