LacyLights MCP Server

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.

What is LacyLights MCP?

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 scenes using natural language descriptions

• Analyze theatrical scripts to automatically generate lighting cues

• Manage DMX fixtures from various manufacturers

• Create and run cue sequences for theatrical performances

• Optimize lighting designs for 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.

Related MCP server: Lightning Tools MCP Server

Complete Function Reference

Project Management

• list_projects - List all available lighting projects with optional fixture/scene 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

Fixture Management

• 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)

Scene Creation & Management

• generate_scene - AI-powered scene generation based on descriptions and context

• analyze_script - Extract lighting cues and suggestions from theatrical scripts

• optimize_scene - Optimize scenes for various goals (energy, impact, simplicity)

• update_scene - Update scene properties and fixture values

• activate_scene - Activate a scene by name or ID

• fade_to_black - Fade all lights to black with customizable timing

• get_current_active_scene - Get information about the currently active scene

Advanced Scene Operations

• add_fixtures_to_scene - Add fixtures to existing scenes

• remove_fixtures_from_scene - Remove specific fixtures from scenes

• get_scene_fixture_values - Read current fixture values in a scene

• ensure_fixtures_in_scene - Ensure fixtures exist with specific values

• update_scene_partial - Partial scene updates with fixture merging

Cue Sequence Management

• create_cue_sequence - Build cue sequences from existing scenes

• 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

Cue List Operations

• 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)

Cue Playback Control

• 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

Scene Board Management

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

Scene Board CRUD

• list_scene_boards - List all scene boards in a project with button counts

• get_scene_board - Get a specific scene board with all buttons and layout

• create_scene_board - Create a new scene board with custom canvas and grid settings

• update_scene_board - Update scene board metadata and settings

• delete_scene_board - Delete a scene board and all its buttons (requires confirmation)

• bulk_create_scene_boards - Create multiple scene boards in a single operation

• bulk_update_scene_boards - Update multiple scene boards in a single operation

• bulk_delete_scene_boards - Delete multiple scene boards in a single operation

Scene Board Button Management

• add_scene_to_board - Add a scene as a button at a specific canvas position

• update_scene_board_button - Update button properties (position, size, color, label)

• remove_scene_from_board - Remove a button from a scene board

• update_scene_board_button_positions - Batch update button positions (drag-and-drop)

• bulk_create_scene_board_buttons - Create multiple buttons in a single operation

• bulk_update_scene_board_buttons - Update multiple buttons in a single operation

• bulk_delete_scene_board_buttons - Delete multiple buttons in a single operation

Scene Board Playback

• activate_scene_from_board - Activate a scene from a board (uses board's default fade time)

• create_scene_board_with_buttons - Create a complete scene board with buttons in one command

Installation

1. Install dependencies:

2. Set up environment variables:

3. Build the project:

Configuration

Required Environment Variables

• 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)

Optional Environment Variables

• CHROMA_HOST - ChromaDB host for enhanced RAG functionality (default: localhost)

• CHROMA_PORT - ChromaDB port (default: 8000)

Running the Server

Make sure your lacylights-go backend is running first, then:

You should see:

Integration with Claude

Add this server to your Claude configuration:

Important:

• Use the absolute path to run-mcp.js in your configuration

• If the above doesn't work, find your Node.js path with: which node

• The wrapper script ensures proper CommonJS module loading

Releases & Versioning

Release Channels

LacyLights MCP supports two release channels:

1. Stable Releases (e.g., 1.4.0, 1.5.0)

   • Production-ready versions

   • Fully tested and validated

   • Listed as "Latest" on GitHub

   • Updates latest.json for automatic discovery

2. 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 stable latest.json

Version Format

• Stable: X.Y.Z (semantic versioning)

  • X = Major version (breaking changes)

  • Y = Minor version (new features)

  • Z = Patch version (bug fixes)

• Beta: X.Y.Zb[N] (beta with iteration)

  • b = Beta identifier

  • [N] = Beta iteration number (1, 2, 3, ...)

Installing Specific Versions

Install Latest Stable (Recommended)

Install Specific Version

Install Beta for Testing

Release Distribution

All releases are distributed through multiple channels:

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

   • Source code

   • Pre-built archives

   • Release notes

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

   • Direct archive downloads

   • SHA256 checksums

   • latest.json metadata

3. DynamoDB Registry:

   • Version tracking

   • Release metadata

   • Prerelease flags

Beta Testing Program

Want to help test new features? Install beta releases:

1. Check for betas: Visit GitHub Releases

   • Look for releases marked "Pre-release"

   • Version format: X.Y.Zb[N]

2. Install beta:

   # See "Install Beta for Testing" above

3. Report issues:

   • Open issues on GitHub

   • Include version number

   • Provide reproduction steps

Release Process

For maintainers: See RELEASE_PROCESS.md for complete release documentation including:

• Beta release workflows

• Stable release procedures

• Version management

• Distribution verification

• Troubleshooting and rollback

Complete Example: Lighting Design for Macbeth

Here's a comprehensive example showing how a lighting designer would use LacyLights MCP to create a complete lighting design for Shakespeare's Macbeth:

Step 1: Create the Project

Step 2: Set Up Fixtures

Step 3: Analyze the Script

Step 4: Generate Key Scenes

Step 5: Create Cue Sequences

Step 6: Generate Act Cues with Script Analysis

Step 7: Optimize for Performance

Step 8: Create Special Effect Sequences

Step 9: Run the Show

During performance, the stage manager can use:

Step 10: Make Live Adjustments

Advanced Usage Examples

Script-Driven Design Workflow

Multi-Universe Setup

Collaborative Design Process

AI-Powered Features

Intelligent Script Analysis

• 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)

Context-Aware Scene Generation

• Understands theatrical lighting principles

• Applies color theory for emotional impact

• Considers fixture capabilities and positions

• Generates DMX values that respect real-world constraints

Adaptive Optimization

• 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

Troubleshooting

Common Issues

1. Module import errors

   • Ensure Node.js version is 18+ as specified in package.json

   • Use the run-mcp.js wrapper script, not dist/index.js directly

2. GraphQL connection errors

   • Verify your lacylights-go backend is running on port 4000

   • Check the LACYLIGHTS_GRAPHQL_ENDPOINT environment variable

3. OpenAI API errors

   • Ensure your OPENAI_API_KEY is set in the .env file

   • Verify the API key has access to GPT-4

4. MCP connection errors in Claude

   • Use the full absolute path in your Claude configuration

   • Restart Claude after updating the MCP configuration

   • Check Claude's logs for detailed error messages

5. "Unexpected token ?" error

   • 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:

Option 1: Docker (Recommended)

Option 2: Local Installation

Then update your .env file:

Integration with LacyLights Ecosystem

This MCP server is part of the complete LacyLights system:

• lacylights-go - Backend GraphQL API for fixture and scene 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 scene generation

• Script analysis capabilities

• Automated cue creation

• Performance optimization

Development

Project Structure

Adding New Tools

1. Create tool implementation in appropriate file under src/tools/

2. Add tool definition to src/index.ts in the ListToolsRequestSchema handler

3. Add tool handler in the CallToolRequestSchema handler

4. Update this README with tool documentation

Testing

MCP Directory

License

MIT