Ledfx MCP

🚀 LedFX MCP 服務器

LedFX MCP 服務器是一個模型上下文協議（MCP）服務器，它使 AI 助手能夠與本地 LedFX 實例進行交互並對其進行控制。該服務器為 AI 助手（如 Claude）和 LedFX 之間搭建了橋樑，讓你可以通過自然語言控制 LED 照明設置。

🚀 快速開始

LedFX MCP 服務器可幫助你通過 AI 助手以自然語言的方式控制 LED 照明。要使用該服務器，你需要滿足以下先決條件：

• 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

安裝

# 克隆倉庫
git clone https://github.com/abossard/ledfx-mcp.git
cd ledfx-mcp

# 安裝依賴
npm install

# 一鍵構建並運行
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"
      }
    }
  }
}

✨ 主要特性

• 🎨 通過自然語言控制 LED 效果
• 🔧 管理多個 LED 設備和虛擬設備
• 🎭 激活預配置場景
• 📊 查詢設備和系統信息
• 🔒 採用類型安全的 TypeScript 實現
• 🏗️ 遵循軟件設計最佳實踐構建
• 🎨 通過 /api/colors 提供 LedFX 顏色和漸變（內置 + 用戶自定義）
• 🗂️ 調色板管理，以用戶漸變的形式存儲在 LedFX 中
• 🤖 基於自然語言描述實現 AI 場景創建
• 📝 支持 播放列表，用於場景序列
• 💡 基於情緒和描述提供 效果推薦
• 📚 提供 LedFX 功能解釋，幫助你瞭解任何 LedFX 概念
• 🔄 正確的 API 實現，使用虛擬設備（而非物理設備）應用效果

📦 安裝指南

# 克隆倉庫
git clone https://github.com/abossard/ledfx-mcp.git
cd ledfx-mcp

# 安裝依賴
npm install

# 一鍵構建並運行
npm run dev

💻 使用示例

基礎用法

配置完成後，你可以通過自然語言與 LedFX 設置進行交互：

• 基本操作：
  • "列出我所有的 LED 虛擬設備"
  • "在我的桌面燈虛擬設備上激活彩虹效果"
  • "顯示所有可用場景"
  • "清除所有虛擬設備上的效果"
• 自然語言場景創建：
  • "創建一個帶有緩慢藍色波浪的平靜海洋場景"
  • "創建一個帶有快速彩虹顏色的活力派對場景"
  • "創建一個帶有淡粉色和紫色漸變的浪漫場景"
  • "創建一個帶有中等亮度穩定白光的專注場景"
• 顏色和調色板管理：
  • "列出所有 LedFX 顏色和漸變"
  • "獲取顏色或漸變 '日落'"
  • "創建用戶顏色 '我的洋紅色' = #FF00FF"
  • "創建一個名為 '日落氛圍' 的新調色板，包含 #FFA500、#FF69B4、#800080"
  • "保存我的派對場景播放列表"
• 效果推薦：
  • "推薦適合放鬆夜晚的效果"
  • "哪些效果與音樂搭配效果好？"
  • "為派對推薦一些活力四射的效果"
• 學習 LedFX：
  • "解釋 LedFX 中的虛擬設備是什麼"
  • "設備和虛擬設備有什麼區別？"
  • "音頻響應效果是如何工作的？"
  • "告訴我關於 WLED 設備的信息"
  • "列出所有可用的效果類型"

📚 詳細文檔

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 行為的上游源文件

🔧 技術細節

設計原則

本項目遵循以下原則：

Grokking Simplicity

• 關注點分離：操作（I/O 操作）與計算（純函數）明確分離
• 分層設計：有清晰的抽象層（工具 → 客戶端 → API）
• 不可變性：數據轉換儘可能使用純函數

A Philosophy of Software Design

• 深度模塊：複雜的 LedFX API 交互隱藏在簡單的接口後面
• 信息隱藏：實現細節對調用者進行抽象
• 最小化複雜性：每個模塊都有單一、專注的職責

實現狀態

當前狀態：已實現並具備全面的測試套件

此 MCP 服務器是針對當前 LedFX API 實現的，並通過自動化測試和持續集成檢查進行了驗證。該實現修復了關鍵的 API 問題（虛擬設備與物理設備），並添加了高級功能，如調色板管理、自然語言場景創建和 AI 推薦。

重要說明

1. 應用了 API 修正：效果正確應用於虛擬設備（而非物理設備），符合當前 LedFX API 行為
2. 全面測試：34 個測試涵蓋單元和端到端場景，全部通過
3. CI/CD 管道：GitHub Actions 工作流，包含 lint、構建、測試和覆蓋率任務
4. 生產就緒：有完整的文檔，包括安裝指南、使用示例和架構文檔

架構

服務器分為三個主要層：

1. MCP 服務器層 (index.ts)：處理 MCP 協議通信
2. 工具層 (tools.ts)：定義可用工具並路由請求
3. 客戶端層 (ledfx-client.ts)：抽象 LedFX HTTP API 交互

這種分層架構確保了：

• 清晰的關注點分離
• 易於測試和維護
• 便於擴展新功能

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

資源

• LedFX 文檔
• 模型上下文協議
• MCP TypeScript SDK

故障排除

服務器無法連接到 LedFX

• 確保 LedFX 正在運行，並且可以通過配置的主機/端口訪問
• 檢查防火牆設置
• 驗證 LEDFX_HOST 和 LEDFX_PORT 環境變量

工具未在 Claude 中顯示

• 配置更改後重啟 Claude Desktop
• 驗證 dist/index.js 的路徑是否為絕對路徑
• 檢查 Claude Desktop 日誌以查找錯誤

支持

如有問題或疑問，請通過以下方式尋求幫助：

• GitHub 問題
• LedFX 社區