Nanoleaf MCP Server

🚀 Nanoleaf MCP 服务器

这是一个用于控制 Nanoleaf 智能灯的模型上下文协议（MCP）服务器。该服务器提供了通过 Warp 终端或任何兼容 MCP 的客户端来控制 Nanoleaf 设备的工具。

✨ 主要特性

• 🔍 自动发现：可自动发现网络中的 Nanoleaf 设备。
• 🔗 直接 IP 连接：支持通过特定 IP 地址连接目标设备。
• 🔐 授权支持：确保设备配对的安全性。
• 💡 全面控制：可对灯光、亮度、颜色和特效进行全面控制。
• 🐳 容器化部署：基于 Docker 实现轻松部署。
• 🖥️ Warp 终端集成：支持与 Warp 终端集成使用。

📦 安装指南

自动化安装（推荐）

为了获得最简单的安装体验，可使用提供的安装脚本：

./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

这将展示所有可用功能，包括开关灯、更改颜色和应用特效。

💻 使用示例

基础用法

开关灯

# 开灯
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"}'

高级用法

完整工作示例

以下是一个使用实际值的完整工作示例（请替换为你自己的值）：

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 工具：

• 控制灯光开关。
• 更改亮度和颜色。
• 应用如“北极光”或“赛博朋克”等酷炫特效。
• 获取设备信息。

📚 详细文档

可用工具

• 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 - 发现网络中的设备。
• connect_to_ip - 连接到特定的 IP 地址。
• authorize_nanoleaf - 在设备配对模式下进行授权。

🔧 技术细节

故障排除

设备未找到

• 确保设备在同一网络中。
• 检查防火墙设置。
• 尝试手动 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 文件。

贡献说明

欢迎提交问题、功能请求或拉取请求！