LacyLights

An MCP (Model Context Protocol) server that provides AI-powered theatrical lighting design capabilities for the LacyLights system. This server enables AI assistants to create, manage, and control professional theatrical lighting designs through natural language interactions.

LacyLights MCP is an intelligent lighting control interface that bridges the gap between creative vision and technical execution. It allows lighting designers, directors, and technicians to:

- Design lighting looksusing natural language descriptions
- Analyze theatrical scriptsto automatically generate lighting cues
- Manage DMX fixturesfrom various manufacturers
- Create and run cue sequencesfor theatrical performances
- Optimize lighting designsfor dramatic impact or energy efficiency

The system uses AI to understand artistic intent and translate it into precise DMX values for real-world lighting fixtures.

- list_projects- List all available lighting projects with optional fixture/look counts
- create_project- Create a new lighting project for a production
- get_project_details- Get comprehensive details about a specific project
- delete_project- Delete a project and all associated data (requires confirmation)
- qlc_import_guidance- Get information about importing QLC+ (.qxw) files

- get_fixture_inventory- Query available fixtures and their capabilities
- analyze_fixture_capabilities- Deep analysis of fixture capabilities (color mixing, positioning, effects)
- create_fixture_instance- Add a new fixture to a project with manufacturer/model details
- get_channel_map- View DMX channel usage map for a project
- suggest_channel_assignment- Get optimal channel assignments for multiple fixtures
- update_fixture_instance- Modify existing fixture properties
- delete_fixture_instance- Remove a fixture from a project (requires confirmation)

- generate_look- AI-powered look generation based on descriptions and context
- analyze_script- Extract lighting cues and suggestions from theatrical scripts
- optimize_look- Optimize looks for various goals (energy, impact, simplicity)
- update_look- Update look properties and fixture values
- activate_look- Activate a look by name or ID
- fade_to_black- Fade all lights to black with customizable timing
- get_current_active_look- Get information about the currently active look

- add_fixtures_to_look- Add fixtures to existing looks
- remove_fixtures_from_look- Remove specific fixtures from looks
- get_look_fixture_values- Read current fixture values in a look
- ensure_fixtures_in_look- Ensure fixtures exist with specific values
- update_look_partial- Partial look updates with fixture merging
- bulk_update_looks_partial- Batch partial updates across multiple looks with fixture merging

- create_cue_sequence- Build cue sequences from existing looks
- generate_act_cues- Generate complete cue lists for theatrical acts
- optimize_cue_timing- Optimize cue timing for various strategies
- analyze_cue_structure- Analyze cue lists with recommendations

- update_cue_list- Update cue list metadata
- add_cue_to_list- Add new cues to existing lists
- remove_cue_from_list- Remove cues from lists
- update_cue- Modify individual cue properties
- bulk_update_cues- Update multiple cues simultaneously
- reorder_cues- Reorder cues with new numbering
- get_cue_list_details- Query cues with filtering and sorting
- delete_cue_list- Delete entire cue lists (requires confirmation)

- start_cue_list- Begin playing a cue list from any point
- next_cue- Advance to the next cue
- previous_cue- Go back to the previous cue
- go_to_cue- Jump to a specific cue by number or name
- stop_cue_list- Stop the currently playing cue list
- get_cue_list_status- Get playback status and navigation options

Look Boards provide a visual layout system for organizing and triggering looks with customizable button positions on a 2D canvas (default 2000x2000 pixels).

- list_look_boards- List all look boards in a project with button counts
- get_look_board- Get a specific look board with all buttons and layout
- create_look_board- Create a new look board with custom canvas and grid settings
- update_look_board- Update look board metadata and settings
- delete_look_board- Delete a look board and all its buttons (requires confirmation)
- bulk_create_look_boards- Create multiple look boards in a single operation
- bulk_update_look_boards- Update multiple look boards in a single operation
- bulk_delete_look_boards- Delete multiple look boards in a single operation

- add_look_to_board- Add a look as a button at a specific canvas position
- update_look_board_button- Update button properties (position, size, color, label)
- remove_look_from_board- Remove a button from a look board
- update_look_board_button_positions- Batch update button positions (drag-and-drop)
- bulk_create_look_board_buttons- Create multiple buttons in a single operation
- bulk_update_look_board_buttons- Update multiple buttons in a single operation
- bulk_delete_look_board_buttons- Delete multiple buttons in a single operation

- activate_look_from_board- Activate a look from a board (uses board's default fade time)
- create_look_board_with_buttons- Create a complete look board with buttons in one command

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

- OPENAI_API_KEY- OpenAI API key for AI-powered lighting generation
- LACYLIGHTS_GRAPHQL_ENDPOINT- GraphQL endpoint for your lacylights-go backend (default:http://localhost:4000/graphql)

# Start in development mode (with auto-reload) npm run dev # Or build and run in production mode npm run build npm start

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

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

- Use the absolute path torun-mcp.jsin your configuration
- If the above doesn't work, find your Node.js path with:which node
- The wrapper script ensures proper CommonJS module loading

LacyLights MCP supports two release channels:

- Production-ready versions
- Fully tested and validated
- Listed as "Latest" on GitHub
- Updateslatest.jsonfor automatic discovery

Beta Releases(e.g.,1.4.1b1,1.5.0b2)

- Pre-release versions for testing
- New features and experimental changes
- Marked as "Pre-release" on GitHub
- Does not affect stablelatest.json

- X= Major version (breaking changes)
- Y= Minor version (new features)
- Z= Patch version (bug fixes)

- b= Beta identifier
- [N]= Beta iteration number (1, 2, 3, ...)

# 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

# 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

# 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

All releases are distributed through multiple channels:
-

GitHub Releases:https://github.com/bbernstein/lacylights-mcp/releases

S3 Distribution:https://dist.lacylights.com/releases/mcp/

- Look for releases marked "Pre-release"
- Version format:X.Y.Zb[N]

# See "Install Beta for Testing" above

- Open issues on GitHub
- Include version number
- Provide reproduction steps

For maintainers: SeeRELEASE_PROCESS.mdfor complete release documentation including:

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"

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)

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

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

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

Step 6: Generate Act Cues with Script Analysis

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

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

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

During performance, the stage manager can use:

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

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

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"

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

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

- Extracts explicit lighting cues from stage directions
- Identifies implicit lighting needs from dialogue and action
- Suggests atmospheric lighting based on dramatic context
- Recognizes standard theatrical conventions (sunrise, sunset, storms)

- Understands theatrical lighting principles
- Applies color theory for emotional impact
- Considers fixture capabilities and positions
- Generates DMX values that respect real-world constraints

- Energy Efficiency: Reduces power consumption while maintaining artistic intent
- Dramatic Impact: Enhances contrast and focus for maximum effect
- Technical Simplicity: Simplifies programming for easier operation
- Color Accuracy: Optimizes for true color rendering

- Ensure Node.js version is 18+ as specified in package.json
- Use therun-mcp.jswrapper script, notdist/index.jsdirectly

- Verify yourlacylights-gobackend is running on port 4000
- Check theLACYLIGHTS_GRAPHQL_ENDPOINTenvironment variable

- Ensure yourOPENAI_API_KEYis set in the.envfile
- Verify the API key has access to GPT-4

- Use the full absolute path in your Claude configuration
- Restart Claude after updating the MCP configuration
- Check Claude's logs for detailed error messages

- Update your config to use the full path to Node.js 14+
- On macOS with Homebrew:"command": "/opt/homebrew/bin/node"
- On other systems, find your node path with:which node

ChromaDB Setup (Optional - For Enhanced RAG)

The MCP server works out of the box with in-memory pattern storage. For persistent vector storage and more sophisticated pattern matching:

# Start ChromaDB with Docker docker-compose up -d chromadb # Verify it's running curl http://localhost:8000/api/v2/heartbeat

# Install ChromaDB pip install chromadb # Start the server chroma run --host localhost --port 8000

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

This MCP server is part of the complete LacyLights system:

- lacylights-go- Backend GraphQL API for fixture and look management
- lacylights-fe- Web frontend for manual control and visualization
- lacylights-mcp- AI interface for intelligent automation

The MCP server enhances the existing system with:

- Natural language control
- Intelligent look generation
- Script analysis capabilities
- Automated cue creation
- Performance optimization