微信扫一扫article
README
🚀 LacyLights MCP 服务器
LacyLights MCP 服务器是一个基于 MCP（模型上下文协议）的服务器，它借助人工智能技术为 LacyLights 系统提供剧场灯光设计能力。
✨ 主要特性
灯具管理
get_fixture_inventory- 查询可用的照明灯具及其功能analyze_fixture_capabilities- 分析特定灯具的颜色混合、定位、效果等功能
场景生成
generate_scene- 根据剧本上下文和设计偏好生成灯光场景analyze_script- 从戏剧剧本中提取与灯光相关的信息optimize_scene- 优化现有场景，以提高能源效率、增强戏剧效果等
灯光提示管理
create_cue_sequence- 根据现有场景创建灯光提示序列generate_act_cues- 为戏剧表演生成完整的灯光提示建议optimize_cue_timing- 优化灯光提示的时间安排，以实现平滑过渡或戏剧效果analyze_cue_structure- 分析并建议改进灯光提示列表
📦 安装指南
- 安装依赖项：
npm install
- 设置环境变量：
cp .env.example .env
# 编辑 .env 文件并进行配置
- 构建项目：
npm run build
📦 ChromaDB 设置（可选）
为了简化操作，MCP 服务器目前使用内存模式存储系统。如果您想使用 ChromaDB 进行持久向量存储和更高级的 RAG 功能，请按以下步骤操作：
选项 1：使用 Docker（推荐）
# 使用 Docker 启动 ChromaDB
docker-compose up -d chromadb
# 验证是否正在运行
curl http://localhost:8000/api/v2/heartbeat
选项 2：本地安装
# 安装 ChromaDB
pip install chromadb
# 启动服务器
chroma run --host localhost --port 8000
然后更新您的 .env 文件：
# 取消 .env 文件中以下行的注释
CHROMA_HOST=localhost
CHROMA_PORT=8000
注意：当前实现无需 ChromaDB 即可使用内置灯光模式运行。ChromaDB 可通过向量相似度搜索增强系统的模式匹配能力。
📚 详细文档
必需的环境变量
OPENAI_API_KEY- 用于人工智能灯光生成的 OpenAI API 密钥LACYLIGHTS_GRAPHQL_ENDPOINT- 您的 lacylights - node 后端的 GraphQL 端点（默认值：http://localhost:4000/graphql）
运行服务器
确保您的 lacylights-node 后端已启动，然后执行以下操作：
# 在开发模式下启动（支持自动重新加载）
npm run dev
# 或者在生产模式下构建并运行
npm run build
npm start
您应该会看到以下输出：
RAG service initialized with in-memory patterns
LacyLights MCP Server running on stdio
可选的环境变量
CHROMA_HOST- 用于 RAG 功能的 ChromaDB 主机（默认值：localhost）CHROMA_PORT- ChromaDB 端口（默认值：8000）
💻 使用示例
运行服务器
# 开发模式
npm run dev
# 生产模式
npm start
与 Claude 集成
将此服务器添加到您的 Claude 配置中：
{
"mcpServers": {
"lacylights": {
"command": "/usr/local/bin/node",
"args": ["/Users/bernard/src/lacylights/lacylights-mcp/run-mcp.js"],
"env": {
"OPENAI_API_KEY": "your_openai_api_key_here",
"LACYLIGHTS_GRAPHQL_ENDPOINT": "http://localhost:4000/graphql"
}
}
}
}
重要提示：如果上述配置不起作用，您可能需要指定 Node.js 14+ 的准确安装路径。您可以使用以下命令查找：
which node
注意：在配置中使用 run-mcp.js 的绝对路径。此包装器可确保正确加载 CommonJS 模块。
生成场景
使用 generate_scene 工具为以下场景创建灯光：
- 场景：“麦克白夫人梦游场景”
- 剧本上下文：“夜晚的黑暗城堡，麦克白夫人手持蜡烛进入，饱受内疚折磨”
- 氛围：“神秘”
- 调色板：["深蓝", "苍白的白色", "冷色"]
分析剧本
使用 analyze_script 工具分析《麦克白》第一幕的全文，以：
- 提取所有灯光提示
- 为每个时刻建议场景
- 识别关键灯光时刻
创建灯光提示序列
使用 create_cue_sequence 工具，根据剧本分析生成的场景为第一幕创建灯光提示列表。
🔧 技术细节
基于人工智能的功能
- 使用 RAG 进行剧本分析：分析戏剧剧本以提取与灯光相关的信息，使用向量嵌入将剧本上下文与灯光模式匹配，并根据戏剧上下文提供智能建议。
- 智能场景生成：根据艺术意图为灯具创建详细的 DMX 值，考虑灯具功能和位置，并应用色彩理论和灯光设计原则。
- 灯光提示时间优化：分析灯光提示序列以优化时间安排，考虑戏剧节奏和技术限制，并提供多种优化策略。
项目结构
src/
├── tools/ # MCP 工具实现
│ ├── fixture-tools.ts
│ ├── scene-tools.ts
│ └── cue-tools.ts
├── services/ # 核心服务
│ ├── graphql-client.ts
│ ├── rag-service.ts
│ └── ai-lighting.ts
├── types/ # TypeScript 类型定义
│ └── lighting.ts
└── index.ts # MCP 服务器入口点
添加新工具
- 在
src/tools/下的适当文件中创建工具实现。 - 在
src/index.ts的ListToolsRequestSchema处理程序中添加工具定义。 - 在
CallToolRequestSchema处理程序中添加工具处理程序。 - 在本 README 中更新工具文档。
测试
npm test
与 LacyLights 集成
此 MCP 服务器旨在与现有的 LacyLights 系统配合使用：
- lacylights-node - 提供用于灯具和场景管理的 GraphQL API。
- lacylights-fe - 用于手动灯光控制和可视化的前端。
MCP 服务器作为人工智能层，通过智能自动化和设计辅助增强现有系统。
故障排除
常见问题
- 模块导入错误：服务器使用 ES 模块和 cross - fetch 进行 GraphQL 请求，请确保 Node.js 版本为 18+（如 package.json 中所指定）。
- GraphQL 连接错误：验证您的
lacylights-node后端是否在端口 4000 上运行，并检查LACYLIGHTS_GRAPHQL_ENDPOINT环境变量。 - OpenAI API 错误：确保您的
OPENAI_API_KEY已在.env文件中设置，并验证 API 密钥是否有权访问 GPT - 4。 - Claude 中的 MCP 连接错误：确保使用
run-mcp.js包装脚本，而不是直接使用dist/index.js，在您的 Claude 配置中使用完整的绝对路径，并在更新 MCP 配置后重启 Claude。 - “Unexpected token ?” 错误：这意味着 Claude 使用的是旧版本的 Node.js（< 14），请更新您的配置以使用 Node.js 安装的完整路径。在使用 Homebrew 的 macOS 上：
"command": "/opt/homebrew/bin/node"；在其他系统上，使用which node查找您的 Node 路径。
依赖项
简化实现使用：
- 直接的 fetch 请求而不是 Apollo Client，以实现更好的 ESM 兼容性。
- 内存模式存储而不是 ChromaDB（可在以后升级）。
- Cross - fetch 填充工具以支持 Node.js 的 fetch 功能。
📄 许可证
本项目采用 MIT 许可证。