Lacylights MCP

🚀 LacyLights MCP Server

LacyLightsシステムに対し、AIを搭載した演劇照明設計機能を提供するMCP（Model Context Protocol）サーバーです。本サーバーは、照明器具の管理、シーン生成、キュー管理などの機能を備え、演劇照明の設計と制御を効率化します。

✨ 主な機能

照明器具管理

• 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サーバーは、簡単のために現在はメモリ内のパターンストレージシステムを使用しています。永続的なベクトルストレージとより高度なRAG機能を使用する場合は、ChromaDBを利用できます。

オプション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 - AIによる照明生成に必要な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ツールを使用して、マクベスの第1幕の全文を分析します。
- すべての照明キューを抽出する
- 各瞬間のシーンを提案する
- 重要な照明の瞬間を特定する

キューシーケンスの作成

create_cue_sequenceツールを使用して、脚本分析から生成されたシーンを使用して第1幕のキューリストを作成します。

🔧 技術詳細

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サーバーは、既存のシステムにインテリジェントな自動化と設計支援を提供するAIレイヤーとして機能します。

トラブルシューティング

一般的な問題

1. モジュールインポートエラー

   • サーバーは、GraphQLリクエストにcross-fetchを使用したESモジュールを使用しています。
   • package.jsonで指定されているように、Node.jsのバージョンが18以上であることを確認してください。

2. GraphQL接続エラー

   • lacylights-nodeバックエンドがポート4000で稼働していることを確認してください。
   • LACYLIGHTS_GRAPHQL_ENDPOINT環境変数を確認してください。

3. OpenAI APIエラー

   • .envファイルにOPENAI_API_KEYが設定されていることを確認してください。
   • 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でノードのパスを見つけてください。

依存関係

簡略化された実装では、以下のものを使用しています。

• Apollo Clientではなく直接のfetchリクエストを使用して、より良いESM互換性を実現します。
• ChromaDBではなくメモリ内のパターンストレージを使用しています（後でアップグレード可能）。
• Node.jsのfetchサポートのためのcross-fetchポリフィルを使用しています。

📄 ライセンス

MIT