Lacylights MCP

🚀 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 - 分析并建议改进灯光提示列表

📦 安装指南

1. 安装依赖项：

npm install

2. 设置环境变量：

cp .env.example .env
# 编辑 .env 文件并进行配置

3. 构建项目：

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 服务器入口点

添加新工具

1. 在 src/tools/ 下的适当文件中创建工具实现。
2. 在 src/index.ts 的 ListToolsRequestSchema 处理程序中添加工具定义。
3. 在 CallToolRequestSchema 处理程序中添加工具处理程序。
4. 在本 README 中更新工具文档。

测试

npm test

与 LacyLights 集成

此 MCP 服务器旨在与现有的 LacyLights 系统配合使用：

• lacylights-node - 提供用于灯具和场景管理的 GraphQL API。
• lacylights-fe - 用于手动灯光控制和可视化的前端。

MCP 服务器作为人工智能层，通过智能自动化和设计辅助增强现有系统。

故障排除

常见问题

1. 模块导入错误：服务器使用 ES 模块和 cross - fetch 进行 GraphQL 请求，请确保 Node.js 版本为 18+（如 package.json 中所指定）。
2. GraphQL 连接错误：验证您的 lacylights-node 后端是否在端口 4000 上运行，并检查 LACYLIGHTS_GRAPHQL_ENDPOINT 环境变量。
3. OpenAI API 错误：确保您的 OPENAI_API_KEY 已在 .env 文件中设置，并验证 API 密钥是否有权访问 GPT - 4。
4. Claude 中的 MCP 连接错误：确保使用 run-mcp.js 包装脚本，而不是直接使用 dist/index.js，在您的 Claude 配置中使用完整的绝对路径，并在更新 MCP 配置后重启 Claude。
5. “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 许可证。