Nanoleaf MCP Server

🚀 Nanoleaf MCP 服務器

Nanoleaf MCP 服務器是一款基於模型上下文協議（MCP）的服務器，用於控制 Nanoleaf 智能燈。藉助該服務器，你可以通過 Warp 終端或任何支持 MCP 的客戶端來控制 Nanoleaf 設備。

✨ 主要特性

• 🔍 自動發現：可自動發現網絡中的 Nanoleaf 設備。
• 🔗 直接 IP 連接：支持通過指定 IP 地址連接特定設備。
• 🔐 授權支持：提供安全的設備配對授權機制。
• 💡 全面控制：可對燈光的開關、亮度、顏色和特效進行全方位控制。
• 🐳 容器化部署：採用 Docker 容器化技術，方便快捷部署。
• 🖥️ Warp 終端集成：無縫集成 Warp 終端，操作更便捷。

📦 可用工具

• get_nanoleaf_info：獲取設備詳細信息。
• turn_on_nanoleaf / turn_off_nanoleaf：控制設備電源開關。
• set_brightness：調節燈光亮度（範圍：0 - 100）。
• set_color：通過色調（範圍：0 - 360）和飽和度（範圍：0 - 100）設置燈光顏色。
• set_effect：應用燈光特效。
• get_effects：列出所有可用的燈光特效。
• discover_nanoleaf：發現網絡中的 Nanoleaf 設備。
• connect_to_ip：連接到指定 IP 地址的設備。
• authorize_nanoleaf：在設備配對模式下進行授權。

🚀 快速開始

自動化設置（推薦）

為了獲得最便捷的設置體驗，建議使用提供的設置腳本：

./setup.sh

該腳本將完成以下操作：

1. 構建 Docker 鏡像。
2. 掃描網絡中的 Nanoleaf 設備。
3. 幫助你獲取授權令牌。
4. 創建所有配置文件。
5. 測試設置是否成功。
6. 生成 Warp 配置文件。

手動設置

前提條件

• 系統已安裝 Docker。
• 網絡中存在 Nanoleaf 設備。
• 安裝 Warp 終端（可選，用於 MCP 集成）。

步驟 1：克隆並構建

git clone <repository-url>
cd nanoleaf-mcp-server
docker build -t nanoleaf-mcp-server-nanoleaf-mcp-server .

步驟 2：查找 Nanoleaf 設備

選項 A：自動發現

docker run --rm -i --network=host nanoleaf-mcp-server echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "discover_nanoleaf", "arguments": {}}}'

選項 B：手動 IP 掃描

# 掃描網絡中在 Nanoleaf 端口響應的設備
nmap -p 16021 192.168.1.0/24

選項 C：查看路由器管理面板：檢查已連接的設備列表。

步驟 3：獲取授權令牌

1. 將 Nanoleaf 設備置於配對模式：
   • 按住 Nanoleaf 設備的電源按鈕 5 - 7 秒。
   • 觀察配對指示燈（通常為閃爍燈光）。
2. 立即獲取授權令牌（在 30 秒內）：

# 將 192.168.1.100 替換為你的設備 IP 地址
curl -X POST http://192.168.1.100:16021/api/v1/new

你將獲得類似以下的響應：

{"auth_token":"YourAuthTokenHere123456789"}

步驟 4：配置環境變量

在項目目錄下創建一個 .env 文件：

NANOLEAF_IP=192.168.1.100
NANOLEAF_AUTH_TOKEN=YourAuthTokenHere123456789
NANOLEAF_PORT=16021
NANOLEAF_PROTOCOL=http

步驟 5：測試設置

# 使用環境變量進行測試
docker run --rm -i --network=host --env-file .env nanoleaf-mcp-server echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_nanoleaf_info", "arguments": {}}}'

如果測試成功，你將看到 Nanoleaf 設備的詳細信息！

步驟 6：運行示例（可選）

使用示例腳本測試所有功能：

./examples.sh

該腳本將演示所有可用功能，包括開關燈、更改顏色和應用特效。

💻 使用示例

完整示例

以下是一個使用實際值的完整示例（請替換為你自己的值）：

1. 設備發現地址：<DEVICE_IP>:16021
2. 已獲取的授權令牌：<AUTH_TOKEN>
3. Warp 配置：

{
  "mcpServers": {
    "nanoleaf": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "NANOLEAF_IP=<DEVICE_IP>",
        "-e", "NANOLEAF_AUTH_TOKEN=<AUTH_TOKEN>",
        "-e", "NANOLEAF_PORT=16021",
        "-e", "NANOLEAF_PROTOCOL=http",
        "nanoleaf-mcp-server-nanoleaf-mcp-server"
      ],
      "env": {}
    }
  }
}

4. 測試命令：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "set_effect", "arguments": {"effect": "Cyberpunk 2077"}}}' | docker run --rm -i --network=host -e NANOLEAF_IP=<DEVICE_IP> -e NANOLEAF_AUTH_TOKEN=<AUTH_TOKEN> nanoleaf-mcp-server-nanoleaf-mcp-server

Warp 終端集成

添加到 Warp MCP 配置

將以下內容添加到你的 Warp MCP 服務器配置中（請將值替換為你實際的設備 IP 地址和授權令牌）：

{
  "mcpServers": {
    "nanoleaf": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "NANOLEAF_IP=192.168.1.100",
        "-e", "NANOLEAF_AUTH_TOKEN=YourAuthTokenHere123456789",
        "-e", "NANOLEAF_PORT=16021",
        "-e", "NANOLEAF_PROTOCOL=http",
        "nanoleaf-mcp-server-nanoleaf-mcp-server"
      ],
      "env": {}
    }
  }
}

重要提示：

• 將 192.168.1.100 替換為你的 Nanoleaf 設備 IP 地址。
• 將 YourAuthTokenHere123456789 替換為你實際的授權令牌。
• 確保你已使用標籤 nanoleaf-mcp-server-nanoleaf-mcp-server 構建了 Docker 鏡像。

替代配置（如果出現路徑問題）

如果你遇到與路徑相關的問題，可以使用以下替代方法：

{
  "mcpServers": {
    "nanoleaf": {
      "command": "bash",
      "args": ["-c", "cd /path/to/nanoleaf-mcp-server && docker run --rm -i --network=host --env-file .env nanoleaf-mcp-server-nanoleaf-mcp-server"],
      "env": {}
    }
  }
}

在 Warp 中使用

配置完成後，你可以直接在 Warp 中使用 Nanoleaf 工具：

• 控制燈光開關。
• 調節亮度和顏色。
• 應用酷炫特效，如“北極光”或“賽博朋克”。
• 獲取設備信息。

手動使用示例

開關燈

# 開燈
curl -X PUT http://your-ip:16021/api/v1/your-token/state \
  -H "Content-Type: application/json" \
  -d '{"on":{"value":true}}'

# 關燈
curl -X PUT http://your-ip:16021/api/v1/your-token/state \
  -H "Content-Type: application/json" \
  -d '{"on":{"value":false}}'

設置亮度

curl -X PUT http://your-ip:16021/api/v1/your-token/state \
  -H "Content-Type: application/json" \
  -d '{"brightness":{"value":50}}'

應用特效

curl -X PUT http://your-ip:16021/api/v1/your-token/effects \
  -H "Content-Type: application/json" \
  -d '{"select":"Northern Lights"}'

📚 詳細文檔

故障排除

設備未找到

• 確保設備與服務器在同一網絡中。
• 檢查防火牆設置。
• 嘗試手動 IP 掃描：nmap -p 16021 192.168.1.0/24

授權失敗

• 設備必須處於配對模式（按住電源按鈕 5 - 7 秒）。
• 配對模式僅持續約 30 秒。
• 確保沒有其他設備正在控制該設備。

連接問題

• 驗證 IP 地址是否正確。
• 檢查設備是否使用 HTTPS（某些較新的型號）。
• 確保 Docker 具有網絡訪問權限（--network=host）。

環境變量無效

• 檢查 .env 文件是否存在且值正確。
• 驗證 Docker 命令是否包含 --env-file .env。
• 確保 Warp 配置中的文件路徑為絕對路徑。

Warp 終端問題

“系統找不到指定的路徑”錯誤

• 使用直接環境變量配置，而不是 --env-file。
• 確保你的 Docker 鏡像標籤完全匹配：nanoleaf-mcp-server-nanoleaf-mcp-server。
• 如果路徑問題仍然存在，嘗試使用替代的 bash 配置。

Warp 中 MCP 服務器無響應

• 驗證 Docker 鏡像是否使用正確的標籤構建。
• 檢查配置中的 IP 地址和授權令牌是否正確。
• 首先手動測試 Docker 命令：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_nanoleaf_info", "arguments": {}}}' | docker run --rm -i --network=host -e NANOLEAF_IP=your-ip -e NANOLEAF_AUTH_TOKEN=your-token nanoleaf-mcp-server-nanoleaf-mcp-server

日誌中顯示“MCP 服務器已退出”

• 這通常表示配置存在問題。
• 檢查所有環境變量是否正確設置。
• 確保 Docker 鏡像存在：docker images | grep nanoleaf

設備兼容性

本服務器已在以下設備上進行測試：

• Nanoleaf Canvas
• Nanoleaf Light Panels
• Nanoleaf Hexagons

該服務器應適用於大多數支持 v1 API 的 Nanoleaf 設備。

貢獻

歡迎提交問題、功能請求或拉取請求！

📄 許可證

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