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 文件。