LacyLights MCP服务器

](https://github.com/bbernstein/lacylights-mcp/releases/latest) ](https://github.com/bbernstein/lacylights-mcp/releases) ![License: MIT](https://opensource.org/licenses/MIT)

MCP（模型上下文协议）服务器，为LacyLights系统提供AI驱动的戏剧照明设计功能。该服务器使AI助手能够通过自然语言交互创建、管理和控制专业的戏剧灯光设计。

什么是LacyLights MCP？

LacyLights MCP是一个智能照明控制接口，弥合了创意视觉和技术执行之间的差距。它允许照明设计师、导演和技术人员：

设计照明外观 使用自然语言描述
分析戏剧剧本 自动生成照明提示
管理DMX设备 来自不同的制造商
创建和运行提示序列 用于戏剧表演
优化照明设计 为了产生巨大的影响或提高能源效率

该系统使用人工智能来理解艺术意图，并将其转化为现实世界照明设备的精确DMX值。

完整功能参考

项目管理

list_projects -列出所有可用的照明项目，包括可选的灯具/外观数量
create_project -为制作创建新的照明项目
get_project_details -获取特定项目的全面详细信息
delete_project -删除项目和所有相关数据（需要确认）
qlc_import_guidance -获取有关导入QLC+（.qxw）文件的信息

夹具管理

get_fixture_inventory -查询可用的夹具及其功能
analyze_fixture_capabilities -对夹具功能（色彩混合、定位、效果）进行深入分析
create_fixture_instance -向项目中添加带有制造商/型号详细信息的新夹具
get_channel_map -查看项目的DMX通道使用图
suggest_channel_assignment -为多个灯具获得最佳通道分配
update_fixture_instance -修改现有设备属性
delete_fixture_instance -从项目中删除夹具（需要确认）

外观设计与管理

generate_look -基于描述和上下文的人工智能外观生成
analyze_script -从戏剧剧本中提取灯光提示和建议
optimize_look -优化外观以实现各种目标（能量、影响力、简单性）
update_look -更新外观属性和设备值
activate_look -按名称或ID激活外观
fade_to_black -通过可定制的定时将所有灯光淡化为黑色
get_current_active_look -获取有关当前活动外观的信息

高级外观操作

add_fixtures_to_look -将装置添加到现有外观中
remove_fixtures_from_look -从外观中删除特定的固定装置
get_look_fixture_values -查看当前夹具值
ensure_fixtures_in_look -确保夹具具有特定值
update_look_partial -通过夹具合并进行部分外观更新
bulk_update_looks_partial -通过夹具合并跨多个外观批量进行部分更新

线索序列管理

create_cue_sequence -从现有外观构建线索序列
generate_act_cues -为戏剧表演生成完整的提示列表
optimize_cue_timing -优化各种策略的提示时间
analyze_cue_structure -分析提示列表并给出建议

线索列表操作

update_cue_list -更新提示列表元数据
add_cue_to_list -向现有列表添加新提示
remove_cue_from_list -从列表中删除提示
update_cue -修改单个线索属性
bulk_update_cues -同时更新多个提示
reorder_cues -使用新编号重新排序线索
get_cue_list_details -具有过滤和排序功能的查询线索
delete_cue_list -删除整个提示列表（需要确认）

提示播放控制

start_cue_list -从任何一点开始播放提示列表
next_cue -前进到下一个提示
previous_cue -返回上一个提示
go_to_cue -按数字或名称跳转到特定提示
stop_cue_list -停止当前播放的提示列表
get_cue_list_status -获取播放状态和导航选项

Look Board管理

Look Boards提供了一个可视化布局系统，用于在2D画布上组织和触发具有可定制按钮位置的外观（默认2000x2000像素）。

外观板CRUD

list_look_boards -列出项目中所有带有按钮数量的外观板
get_look_board -获得一个包含所有按钮和布局的特定外观板
create_look_board -使用自定义画布和网格设置创建新的外观板
update_look_board -更新外观板元数据和设置
delete_look_board -删除查看板及其所有按钮（需要确认）
bulk_create_look_boards -在一次操作中创建多个外观板
bulk_update_look_boards -在一次操作中更新多个外观板
bulk_delete_look_boards -在一次操作中删除多个外观板

Look Board按钮管理

add_look_to_board -在特定画布位置添加外观作为按钮
update_look_board_button -更新按钮属性（位置、大小、颜色、标签）
remove_look_from_board -从观察板上取下一个按钮
update_look_board_button_positions -批量更新按钮位置（拖放）
bulk_create_look_board_buttons -在一次操作中创建多个按钮
bulk_update_look_board_buttons -在一次操作中更新多个按钮
bulk_delete_look_board_buttons -在一次操作中删除多个按钮

Look Board回放

activate_look_from_board -从板上激活外观（使用板的默认淡入淡出时间）
create_look_board_with_buttons -在一个命令中创建一个包含按钮的完整外观板

安装

安装依赖项：

npm install

设置环境变量：

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

构建项目：

npm run build

配置

所需的环境变量

OPENAI_API_KEY -用于AI供电照明生成的OpenAI API密钥
LACYLIGHTS_GRAPHQL_ENDPOINT -lacyllights后端的GraphQL端点（默认值：http://localhost:4000/graphql)

可选环境变量

CHROMA_HOST -ChromaDB主机，用于增强RAG功能（默认：localhost）
CHROMA_PORT -ChromaDB端口（默认值：8000）

运行服务器

确保你的 lacylights-go 后端首先运行，然后：

# 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

与Claude整合

将此服务器添加到您的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"
      }
    }
  }
}

重要:

使用绝对路径 run-mcp.js 在您的配置中
如果上述方法不起作用，请使用以下命令查找您的Node.js路径： which node
包装器脚本确保正确加载CommonJS模块

发布和版本控制

释放通道

LacyLights MCP支持两个释放通道：

稳定版发布 （例如。， 1.4.0, 1.5.0)

- 生产就绪版本 - 经过充分测试和验证 - 在GitHub上列为“最新” - 更新 latest.json 用于自动发现

测试版 （例如。， 1.4.1b1, 1.5.0b2)

- 用于测试的预发布版本 - 新功能和实验性更改 - 在GitHub上标记为“预发布” - 不影响稳定 latest.json

版本格式

稳定： X.Y.Z （语义版本控制）

- X =主要版本（重大更改） - Y =次要版本（新功能） - Z =补丁版本（错误修复）

贝塔： X.Y.Zb[N] （贝塔迭代）

- b =Beta标识符 - [N] =贝塔迭代次数（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

发布分发

所有版本都通过多种渠道分发：

GitHub发布： https://github.com/bbernstein/lacylights-mcp/releases

- 源代码 - 预建档案 - 发行说明

S3分布： https://dist.lacylights.com/releases/mcp/

- 直接下载存档 - SHA256校验和 - latest.json 元数据

DynamoDB注册表：

- 版本跟踪 - 发布元数据 - 预发布标志

Beta测试计划

想帮助测试新功能吗？安装测试版：

检查测试版： 访问

- 查找标记为“预发布”的版本 - 版本格式： X.Y.Zb[N]

安装测试版：

   # See "Install Beta for Testing" above

报告问题：

- GitHub上的未决问题 - 包括版本号 - 提供复制步骤

发布过程

对于维护人员：请参阅发布_产品.md 获取完整的发布文档，包括：

Beta版发布工作流程
稳定的发布程序
版本管理
分发验证
故障排除和回滚

完整示例：麦克白的灯光设计

以下是一个全面的例子，展示了照明设计师如何使用LacyLights MCP为莎士比亚的《麦克白》创作完整的照明设计：

第一步：创建项目

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)

步骤3：分析脚本

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

步骤4：生成关键外观

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

步骤5：创建线索序列

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

步骤6：使用脚本分析生成动作提示

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

步骤7：优化性能

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

第8步：创建特效序列

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

第九步：表演

演出期间，舞台监督可以使用：

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

第10步：进行实时调整

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

AI驱动的功能

智能脚本分析

从舞台指示中提取明确的灯光提示
从对话和行动中识别隐含的照明需求
根据戏剧背景建议大气照明
认可标准戏剧惯例（日出、日落、风暴）

上下文感知外观生成

了解戏剧灯光原理
运用色彩理论来影响情绪
考虑夹具的性能和位置
生成符合实际约束的DMX值

自适应优化

能效：在保持艺术意图的同时降低功耗
戏剧性影响：增强对比度和焦点，以获得最佳效果
技术简单：简化编程，便于操作
色彩准确度：针对真彩色渲染进行优化

故障排除

常见问题

模块导入错误

- 确保Node.js版本为package.json中指定的18+ - 使用 run-mcp.js 包装脚本，不是 dist/index.js 直接

GraphQL连接错误

- 验证您的 lacylights-go 后端正在端口4000上运行 - 检查 LACYLIGHTS_GRAPHQL_ENDPOINT 环境变量

OpenAI API错误

- 确保您的 OPENAI_API_KEY 设置在 .env 文件 - 验证API密钥是否有权访问GPT-4

Claude中的MCP连接错误

- 在Claude配置中使用完整的绝对路径 - 更新MCP配置后重新启动Claude - 检查克劳德的日志以获取详细的错误消息

“意外令牌？”错误

- 更新配置以使用Node.js 14的完整路径+ - 在macOS上使用Homebrew： "command": "/opt/homebrew/bin/node" - 在其他系统上，使用以下命令查找节点路径： which node

ChromaDB设置（可选-用于增强RAG）

MCP服务器采用内存模式存储，开箱即用。对于持久矢量存储和更复杂的模式匹配：

选项1:Docker（推荐）

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

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

选项2：本地安装

# Install ChromaDB
pip install chromadb

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

然后更新您的 .env 文件：

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

与LacyLights生态系统整合

此MCP服务器是完整的LacyLights系统的一部分：

蕾丝灯亮了 -用于固定装置和外观管理的后端GraphQL API
蕾丝灯 -用于手动控制和可视化的Web前端
lacyllights mcp -用于智能自动化的AI接口

MCP服务器通过以下方式增强了现有系统：

自然语言控制
智能外观生成
脚本分析功能
自动创建线索
性能优化

发展

项目结构

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

添加新工具

在适当的文件中创建工具实现 src/tools/
将工具定义添加到 src/index.ts 在 ListToolsRequestSchema 处理器
在中添加工具处理程序 CallToolRequestSchema 处理器
使用工具文档更新此README

测试

npm test

MCP目录

许可证

麻省理工学院

LacyLights MCP Server

快速接入

详细介绍

LacyLights MCP服务器

什么是LacyLights MCP？

完整功能参考

项目管理

夹具管理

外观设计与管理

高级外观操作

线索序列管理

线索列表操作

提示播放控制

Look Board管理

外观板CRUD

Look Board按钮管理

Look Board回放

安装

配置

所需的环境变量

可选环境变量

运行服务器

与Claude整合

发布和版本控制

释放通道

版本格式

安装特定版本

安装最新稳定版（推荐）

安装特定版本

安装测试版进行测试

发布分发

Beta测试计划

发布过程

完整示例：麦克白的灯光设计

第一步：创建项目

第二步：设置固定装置

步骤3：分析脚本

步骤4：生成关键外观

步骤5：创建线索序列

步骤6：使用脚本分析生成动作提示

步骤7：优化性能

第8步：创建特效序列

第九步：表演

第10步：进行实时调整

高级使用示例

脚本驱动设计工作流

多宇宙设置

协同设计过程

AI驱动的功能

智能脚本分析

上下文感知外观生成

自适应优化

故障排除

常见问题

ChromaDB设置（可选-用于增强RAG）

选项1:Docker（推荐）

选项2：本地安装

与LacyLights生态系统整合

发展

项目结构

添加新工具

测试

MCP目录

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP