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 許可證。