Ledfx MCP

🚀 LedFX MCPサーバー

AIアシスタントがローカルのLedFXインスタンスとやり取りし、制御できるようにするモデルコンテキストプロトコル（MCP）サーバーです。

🚀 クイックスタート

このMCPサーバーはAIアシスタント（Claudeなど）とLedFXの間の橋渡しを行い、自然言語でLED照明セットアップを制御できます。サーバーはLedFXの機能をMCPツールとして公開し、AIアシスタントが以下のことを行えるようにします。

• デバイスと仮想情報を照会する
• LEDデバイスと仮想デバイスをリストし、管理する
• 仮想デバイス（仮想LEDストリップ）にエフェクトを適用する
• シーンを管理し、アクティブにする
• カスタムパレットとプレイリストを作成する
• AIによるエフェクト推薦を取得する
• システム情報を取得する

✨ 主な機能

• 🎨 自然言語でLEDエフェクトを制御する
• 🔧 複数のLEDデバイスと仮想デバイスを管理する
• 🎭 事前に設定されたシーンをアクティブにする
• 📊 デバイスとシステム情報を照会する
• 🔒 型安全なTypeScript実装
• 🏗️ ソフトウェア設計のベストプラクティスに従って構築されている
• 🎨 /api/colorsを通じたLedFXの色とグラデーション（組み込み + ユーザー定義）
• 🗂️ LedFXにユーザーグラデーションとして保存されるパレット管理
• 🤖 自然言語の説明からのAIによるシーン作成
• 📝 シーンシーケンスのプレイリストサポート
• 💡 ムードと説明に基づくエフェクト推薦
• 📚 LedFXの機能説明 - 任意のLedFXの概念について学ぶ
• 🔄 正しいAPI実装 - エフェクトに仮想デバイス（デバイスではない）を使用する

🔧 技術詳細

設計原則

このプロジェクトは以下の原則に従っています。

Grokking Simplicity

• 関心事の分離：アクション（入出力操作）は計算（純粋関数）から明確に分離されています。
• 階層化設計：明確な抽象化レイヤー（ツール → クライアント → API）
• 不変性：可能な限り純粋関数を使用したデータ変換

A Philosophy of Software Design

• 深いモジュール：複雑なLedFX APIのやり取りはシンプルなインターフェースの背後に隠されています。
• 情報隠蔽：実装の詳細は呼び出し元から抽象化されています。
• 複雑さの最小化：各モジュールは単一の焦点を持った責任を持っています。

実装状況

現在の状況：包括的なテストスイートを備えた実装済み

このMCPサーバーは現在のLedFX APIに対して実装され、自動テストと継続的インテグレーションチェックによって検証されています。実装では重要なAPIの問題（仮想デバイスとデバイスの違い）を修正し、パレット管理、自然言語によるシーン作成、AIによる推薦などの高度な機能を追加しています。

重要な注意事項

1. API修正適用：エフェクトは正しく仮想デバイス（デバイスではない）に適用され、現在のLedFX APIの動作に一致しています。
2. 包括的なテスト：ユニットテストとE2Eシナリオをカバーする34のテスト - すべて合格
3. CI/CDパイプライン：リント、ビルド、テスト、カバレッジジョブを含むGitHub Actionsワークフロー
4. 本番環境対応：インストールガイド、使用例、アーキテクチャドキュメントで完全にドキュメント化されています。

ドキュメント

• API仕様 - 完全なLedFX APIリファレンス
• テスト仕様 - 包括的なテスト計画
• 実装ノート - 設計決定と技術的なノート
• 参考文献 - LedFXのリソースとリンク
• インストールガイド - ステップバイステップのセットアップ手順
• 使用ガイド - すべての機能の使用方法

状況：LedFX 2.1.4以降で本番環境での使用が可能です。

📦 インストール

前提条件

• Node.js 24または25
• 実行中のLedFXインスタンス（デフォルト: localhost:8888）
• MCP互換のAIアシスタント（例: Claude Desktop）

テスト用のLedFXの実行

Dockerを使用する（推奨）

# docker-composeを使用する（このリポジトリに含まれています）
docker-compose up -d

# またはdocker runを使用する
docker run -d --name ledfx -p 8888:8888 ledfxorg/ledfx:latest

pipを使用する

pip install ledfx
ledfx --host 0.0.0.0 --port 8888

現在のインストールドキュメントについては、REFERENCES.mdの公式LedFXのリンクを参照してください。

インストール手順

# リポジトリをクローンする
git clone https://github.com/abossard/ledfx-mcp.git
cd ledfx-mcp

# 依存関係をインストールする
npm install

# ビルドと実行を1つのコマンドで行う
npm run dev

設定

サーバーは以下の環境変数を使用してLedFXに接続します。

• LEDFX_HOST: LedFXサーバーのホスト（デフォルト: localhost）
• LEDFX_PORT: LedFXサーバーのポート（デフォルト: 8888）

これらはMCPクライアントの設定で、または環境変数として設定できます。

💻 使用例

Claude Desktopの設定

Claude Desktopの設定ファイルに以下を追加してください。

• Claude DesktopはこのMCPサーバーを標準入出力経由で起動します。
• Node.js 24または25を使用してください。
• nodeとdist/index.jsを使用する場合は、パスは絶対パスである必要があります。

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ledfx": {
      "command": "node",
      "args": ["/absolute/path/to/ledfx-mcp/dist/index.js"],
      "env": {
        "LEDFX_HOST": "localhost",
        "LEDFX_PORT": "8888"
      }
    }
  }
}

ローカルビルドなしでGitから実行する場合は、npxをコマンドとして使用します。

{
  "mcpServers": {
    "ledfx": {
      "command": "npx",
      "args": ["github:abossard/ledfx-mcp"],
      "env": {
        "LEDFX_HOST": "localhost",
        "LEDFX_PORT": "8888"
      }
    }
  }
}

サンプルインタラクション

設定後、自然言語でLedFXのセットアップとやり取りできます。

基本操作

• "すべてのLED仮想デバイスをリストする"
• "机のライトの仮想デバイスに虹色のエフェクトを適用する"
• "利用可能なすべてのシーンを表示する"
• "すべての仮想デバイスからエフェクトをクリアする"

自然言語によるシーン作成

• "ゆっくりした青い波を持つ穏やかな海のシーンを作成する"
• "高速な虹色でエネルギッシュなパーティーシーンを作成する"
• "薄いピンクと紫のグラデーションを持つロマンチックなシーンを作成する"
• "中程度の明るさで安定した白色光の集中シーンを作成する"

色とパレット管理

• "すべてのLedFXの色とグラデーションをリストする"
• "色またはグラデーション 'sunset' を取得する"
• "ユーザー色 'my-magenta' = #FF00FF を作成する"
• "#FFA500, #FF69B4, #800080 を持つ 'Sunset Vibes' という名前の新しいパレットを作成する"
• "パーティーシーンのプレイリストを保存する"

エフェクト推薦

• "くつろぐ夕方に適したエフェクトを推薦する"
• "音楽と相性の良いエフェクトは何ですか？"
• "パーティーにエネルギッシュなものを提案してください"

LedFXの学習

• "LedFXの仮想デバイスとは何かを説明する"
• "デバイスと仮想デバイスの違いは何ですか？"
• "音声反応型エフェクトはどのように機能しますか？"
• "WLEDデバイスについて教えてください"
• "利用可能なすべてのエフェクトタイプをリストする"

利用可能なツール

サーバーは40以上のMCPツールをカテゴリに分けて公開しています。

コア管理

エフェクト制御（修正済み - 仮想デバイスを使用）

シーン管理

パレット管理（LedFX /api/colors）

プレイリスト管理

色管理（LedFX /api/colors）

AI機能

プリセット管理

オーディオ管理

開発

# 依存関係をインストールする
npm install

# プロジェクトをビルドする
npm run build

# ビルドと実行を1つのコマンドで行う
npm run dev

# 開発用のウォッチモード
npm run watch

# ビルドと実行を1つのコマンドで行う
npm run dev

# コードをリントする
npm run lint

# リントの問題を修正する
npm run lint:fix

プロジェクト構造

ledfx-mcp/
├── src/
│   ├── index.ts         # メインサーバーのエントリーポイント
│   ├── ledfx-client.ts  # LedFX APIクライアント
│   └── tools.ts         # MCPツールの定義とハンドラー
├── docs/                # 包括的なドキュメント
│   ├── API_SPECIFICATION.md      # LedFX APIリファレンス
│   ├── TEST_SPECIFICATION.md     # テスト計画と要件
│   ├── IMPLEMENTATION_NOTES.md   # 既知の問題と必要な修正
│   └── REFERENCES.md             # LedFXのリソースとリンク
├── dist/                # コンパイルされたJavaScript（生成される）
├── docker-compose.yml   # テスト用のDockerセットアップ
├── package.json         # プロジェクトの設定
├── tsconfig.json        # TypeScriptの設定
└── README.md           # このファイル

ドキュメント

docs/ディレクトリに包括的なドキュメントがあります。

API仕様

docs/API_SPECIFICATION.md

LedFX REST APIエンドポイントの完全なリファレンス（LedFX 2.1.4と上流ソースに対して検証済み）：

• すべてのエンドポイントのパス、メソッド、パラメーター
• データモデルとオーケストレーションの注意事項（仮想デバイス、プリセット、シーン、プレイリスト、ブレンダー）
• APIの動作の癖と互換性に関する注意事項

テスト仕様

docs/TEST_SPECIFICATION.md

包括的なテスト要件とテストケース：

• すべてのコンポーネントのユニットテストケース
• 統合テストシナリオ
• エンドツーエンドのワークフロー
• パフォーマンステスト基準
• 互換性テストマトリックス
• モック戦略とテストフィクスチャ
• Dockerベースのテスト環境のセットアップ

実装ノート

docs/IMPLEMENTATION_NOTES.md

現在の実装と実際のAPIの批判的な分析：

• 既知の問題とバグ（デバイスと仮想デバイスの混同）
• 本番環境での使用前に必要な修正
• 欠落している機能と機能のギャップ
• 推奨される実装フェーズ
• 将来のバージョンへの移行パス

参考文献

docs/REFERENCES.md

API検証のための簡潔なソースインデックス：

• 公式LedFXのドキュメントのリンク
• リリース/バージョンのリンク
• APIの動作を検証するために使用される上流のソースファイル

アーキテクチャ

サーバーは3つの主要なレイヤーに組織されています。

1. MCPサーバーレイヤー (index.ts)：MCPプロトコルの通信を処理する
2. ツールレイヤー (tools.ts)：利用可能なツールを定義し、リクエストをルーティングする
3. クライアントレイヤー (ledfx-client.ts)：LedFX HTTP APIのやり取りを抽象化する

このレイヤードアーキテクチャにより、以下が保証されます。

• 関心事の明確な分離
• 簡単なテストとメンテナンス
• 新しい機能の拡張性

コントリビュート

コントリビューションは歓迎されます！コードが以下のことを確認してください。

• 既存のコードスタイルに従っている
• 適切なコメントを含んでいる
• リントを通過する (npm run lint)
• 正常にビルドされる (npm run build)

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

リソース

• LedFXドキュメント
• モデルコンテキストプロトコル
• MCP TypeScript SDK

トラブルシューティング

サーバーがLedFXに接続できない

• LedFXが実行中で、設定されたホスト/ポートでアクセス可能であることを確認する
• ファイアウォールの設定を確認する
• LEDFX_HOSTとLEDFX_PORTの環境変数を確認する

ツールがClaudeに表示されない

• 設定変更後にClaude Desktopを再起動する
• dist/index.jsのパスが絶対パスであることを確認する
• Claude Desktopのログを確認してエラーをチェックする

サポート

問題や質問については、以下を参照してください。

• GitHubの問題
• LedFXコミュニティ