Name: LIFX设备控制服务器
Author: furey

使用说明

LIFX API MCP服务器

LIFX API MCP服务器 是一个本地模型上下文协议（MCP）服务器，通过LLM使用自然语言访问LIFX设备，通过LIFX HTTP API执行列出灯光、设置状态、激活场景和触发效果等操作。包括上下文资源和有用的提示。

快速开始

获取LIFX API代币：
- 去你的 LIFX云设置页面.
- 生成新的个人访问令牌。 请确保此令牌安全！

安装LIFX MCP服务器： （选择一种方法）

NPX（推荐）：
```
npx -y lifx-api-mcp-server@latest
```

Docker：

docker run --rm -i --network=host --pull=always furey/lifx-api-mcp-server

配置API令牌：
- 关键步骤： 通过设置您的令牌一这些方法（优先级顺序）：
  1. 配置文件（推荐）： 编辑 ~/.lifx-api-mcp-server.jsonc （生成 npx -y lifx-api-mcp-server@latest config:create)并将您的令牌添加到 apiToken 现场。
  2. 环境变量： 集 CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN.
  3. 命令行参数（最不推荐）： 在运行服务器时传递令牌（例如。， npx ... YOUR_TOKEN).
设置MCP客户端：
- 配置您的客户端（例如。，克劳德桌面, MCP检查员)启动服务器没有如果使用config/env，则使用token参数。
控制灯光：
- 开始使用自然语言与LIFX设备进行交互（请参阅教程).使用以下资源 @lix-api:lifx://lights 并提示如下 @lix-api:effect-creator.

特性

工具

list-lights：获取属于该帐户的灯，可通过选择器进行筛选。
set-state：设置所选灯光的状态（功率、颜色、亮度等）。
set-states：在一个请求中跨多个选择器设置多个状态。
state-delta：以相对量改变状态属性（亮度、色调、饱和度、开尔文、红外）。
toggle-power：切换选定灯光的电源状态。
breathe-effect：执行呼吸（淡入淡出）效果。
pulse-effect：执行脉冲（闪光）效果。
move-effect：对线性设备（LIFX Z条）执行移动效果。
morph-effect：对磁贴设备执行变形效果。
flame-effect：在Tile设备上执行火焰效果。
clouds-effect：在磁贴设备上执行云效果（FW>=4.8）。
sunrise-effect：在磁贴设备上执行日出效果（FW>=4.8）。
sunset-effect：在磁贴设备上执行日落效果（FW>=4.8）。
effects-off：关闭任何跑步效果。
list-scenes：列出帐户中可用的场景。
activate-scene：通过UUID激活指定场景。
cycle：在预定义状态列表中循环选定的灯光。
validate-color：验证颜色字符串并返回其组件。
clean：控制LIFX清洁设备。

资源

lifx://lights：提供可用灯的摘要列表（ID、标签、电源、已连接）。获取实时数据。
lifx://light/{selector}/state：提供与选择器匹配的灯的详细当前状态。支持选择器的自动补全功能。获取实时数据。
lifx://scenes：提供可用场景的列表（名称、UUID）。获取实时数据。

鼓励

effect-creator：引导用户创建效果参数并生成相应的工具命令。
troubleshooter：通过检查特定灯的状态（获取实时数据），帮助诊断其基本连接问题。
selector-helper：列出实时数据中的可用标识符（标签、组、位置、ID），以帮助用户构建准确的选择器。

其他特征

配置文件： 通过自定义设置 ~/.lifx-api-mcp-server.jsonc.
环境变量： 覆盖配置设置（例如。， CONFIG_API_TOKEN, CONFIG_LOG_LEVEL).
组件禁用： 通过配置有选择地禁用工具、资源或提示。
直接API映射： 工具通常与LIFX API端点1:1对应。
错误处理： 根据LIFX API响应和HTTP状态代码提供反馈。
选择器支持： 使用LIFX选择器(all, id:, label:等等）用于瞄准光。
颜色支持： 接受标准LIFX颜色字符串。
Docker支持： 在Docker容器中轻松运行。

安装

LIFX MCP服务器可以通过多种方式安装和运行：

NPX （最简单）
Docker Hub
Node.js源代码
Docker源代码

安装：NPX

[！注意]
NPX要求 Node.js （v18+）已安装。

# Ensure Node.js v18+ is installed
node --version

# Run the server (token should ideally be set via config/env)
npx -y lifx-api-mcp-server@latest [YOUR_LIFX_API_TOKEN_IF_NEEDED]

安装：Docker Hub

[！注意]
需要码头工人安装。

# Ensure Docker is installed
docker --version

# Run the server (token should ideally be set via config/env)
# Mount config file (recommended):
docker run --rm -i --network=host \
  -v ~/.lifx-api-mcp-server.jsonc:/root/.lifx-api-mcp-server.jsonc:ro \
  --pull=always furey/lifx-api-mcp-server

# OR pass token via environment variable:
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN \
  --pull=always furey/lifx-api-mcp-server

# OR pass token as argument (least recommended):
docker run --rm -i --network=host \
  --pull=always furey/lifx-api-mcp-server YOUR_LIFX_API_TOKEN

（替换 furey/lifx-api-mcp-server 如果不同，请使用实际的Docker Hub映像名称）

安装：Node.js源代码

[！注意]
需要 Node.js 安装了（v18+）和npm/yarn。

克隆存储库（如果已发布，则替换为实际URL）：

git clone https://github.com/furey/lifx-api-mcp-server.git # Placeholder
cd lifx-api-mcp-server

安装依赖项：
```
npm install
```
运行服务器（令牌最好通过config/env设置）：
```
node lifx-api-mcp-server.js [YOUR_LIFX_API_TOKEN_IF_NEEDED]
```

安装：Docker源代码

[！注意]
需要码头工人安装。

克隆存储库：

git clone https://github.com/furey/lifx-api-mcp-server.git # Placeholder
cd lifx-api-mcp-server

构建Docker镜像：
```
docker build -t lifx-mcp-server .
```

运行容器（令牌最好通过config/env设置）：

# Using mounted config file (recommended):
docker run --rm -i --network=host \
  -v ~/.lifx-api-mcp-server.jsonc:/root/.lifx-api-mcp-server.jsonc:ro \
  lifx-mcp-server

# Using environment variable:
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN \
  lifx-mcp-server

# Using argument (least recommended):
docker run --rm -i --network=host \
  lifx-mcp-server YOUR_LIFX_API_TOKEN

安装验证

当服务器成功启动时，您应该看到如下输出：

[LIFX MCP] LIFX API MCP Server vX.Y.Z starting…
[LIFX MCP] Loading config file: /path/to/.lifx-api-mcp-server.jsonc (or 'No config file found')
[LIFX MCP] Initializing MCP server…
[LIFX MCP] Registering MCP resources…
[LIFX MCP] Total MCP resources registered: X
[LIFX MCP] Registering MCP prompts…
[LIFX MCP] Total MCP prompts registered: Y
[LIFX MCP] Registering MCP tools…
[LIFX MCP] Total MCP tools registered: Z
[LIFX MCP] Creating stdio transport…
[LIFX MCP] Connecting MCP server transport…
[LIFX MCP] LIFX API MCP Server running.

配置

通过配置文件或环境变量自定义服务器的行为。API令牌是最关键的设置。

配置：API令牌（优先级顺序）

配置文件(apiToken 按键）： 创建/编辑 ~/.lifx-api-mcp-server.jsonc.（推荐）
环境变量(CONFIG_API_TOKEN): 集 CONFIG_API_TOKEN=YOUR_TOKEN.
命令行参数： 运行脚本时，将令牌作为第一个参数传递。（最不推荐）

配置：配置文件

在以下位置创建配置文件 ~/.lifx-api-mcp-server.jsonc （或 .json).使用 npx -y lifx-api-mcp-server@latest config:create 生成它。

Example configuration file (`~/.lifx-api-mcp-server.jsonc`)

{
  // Your LIFX Personal Access Token (Required if not using ENV or CLI arg)
  // Get from: https://cloud.lifx.com/settings
  "apiToken": "YOUR_LIFX_API_TOKEN_HERE",

  // Log level: "info" (default) or "verbose" for more detailed logs including rate limits
  "logLevel": "info",

  // --- Optional: Disable specific components ---
  // Add component names here to disable them. Examples:
  // "disabled": {
  //   "tools": ["clean", "cycle"], // Disable specific tools
  //   "resources": ["scenes"],     // Disable the scenes resource
  //   "prompts": true              // Disable all prompts
  // },
  "disabled": {
    "tools": [],
    "resources": [],
    "prompts": []
  },

  // --- Optional: Enable only specific components ---
  // If an 'enabled' array is defined, ONLY those components of that type will be enabled,
  // overriding any 'disabled' settings for that type. Examples:
  // "enabled": {
  //    "tools": ["list-lights", "set-state"], // Only enable these two tools
  //    "resources": ["lights"]                // Only enable the lights resource
  // }
  "enabled": {
    "tools": null,
    "resources": null,
    "prompts": null
  }
}

配置：配置文件生成

您可以自动生成默认配置文件：

# NPX Usage (recommended)
npx -y lifx-api-mcp-server@latest config:create

# Node.js Usage (from source directory)
npm run config:create

# Force overwrite existing file
npx -y lifx-api-mcp-server@latest config:create -- --force
npm run config:create -- --force

# Specify custom path/filename (uses CONFIG_PATH env var)
CONFIG_PATH=/path/to/my-lifx-config.jsonc npm run config:create

这将示例配置内容保存到 ~/.lifx-api-mcp-server.jsonc 默认情况下。

配置：环境变量覆盖

可以使用环境变量覆盖设置（优先于配置文件）。

配置设置	环境变量覆盖	示例值
`apiToken`	`CONFIG_API_TOKEN`	`c0ffee...`
`logLevel`	`CONFIG_LOG_LEVEL`	`verbose`
`disabled.tools`	`CONFIG_DISABLED_TOOLS`	`clean,cycle` / `true`
`enabled.tools`	`CONFIG_ENABLED_TOOLS`	`list-lights,set-state`
`disabled.resources`	`CONFIG_DISABLED_RESOURCES`	`scenes` / `true`
`enabled.resources`	`CONFIG_ENABLED_RESOURCES`	`lights,light-state`
`disabled.prompts`	`CONFIG_DISABLED_PROMPTS`	`troubleshooter` / `true`
`enabled.prompts`	`CONFIG_ENABLED_PROMPTS`	`effect-creator`

示例用法：

# Set token and log level via environment variables when using NPX
CONFIG_API_TOKEN=YOUR_TOKEN CONFIG_LOG_LEVEL=verbose npx -y lifx-api-mcp-server@latest

# Same example using Docker
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_TOKEN \
  -e CONFIG_LOG_LEVEL=verbose \
  --pull=always furey/lifx-api-mcp-server

客户端设置

配置您的MCP客户端（例如，Claude Desktop、MCP Inspector）以启动 lifx-api-mcp-server. 重要提示： 如果您已经通过配置文件或环境变量配置了API令牌，不要在客户端设置中将其作为参数传递。

客户端设置：Claude Desktop

安装克劳德桌面.
查找或创建 claude_desktop_config.json:
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- 窗户： %APPDATA%\Claude\claude_desktop_config.json

添加服务器配置（根据需要调整路径）：

{
  "mcpServers": {
    "lix-api": {
      // Use the full path to npx if it's not in your default PATH
      "command": "/path/to/your/npx", // Or node
      "args": [
        // NPX example: (NO TOKEN HERE if set in config/env)
        "-y",
        "lifx-api-mcp-server@latest"

        // Node.js from source example: (NO TOKEN HERE if set in config/env)
        // "/path/to/lifx-api-mcp-server/lifx-api-mcp-server.js"
      ],
      "env": {
         // Optional: Uncomment for verbose logging
         // "CONFIG_LOG_LEVEL": "verbose"
         // Optional: Set token via env if not using config file
         // "CONFIG_API_TOKEN": "YOUR_LIFX_API_TOKEN"
      }
    }
  }
}

重新启动克劳德桌面。
开始聊天并尝试与您的灯进行交互（例如，“@lixapi list my lights”）。

客户端设置：MCP检查器

MCP检查员对调试很有用。

# Run MCP Inspector with the LIFX server (NO TOKEN HERE if set in config/env)
npx -y @modelcontextprotocol/inspector npx -y lifx-api-mcp-server@latest

# Open the inspector in your browser (usually http://localhost:5173)

数据保护

API代币安全： 您的LIFX API代币授予您对灯光的控制权。 保密。 使用配置文件(~/.lifx-api-mcp-server.jsonc 具有适当的文件权限）或环境变量比将令牌作为命令行参数传递更安全，特别是在共享环境或日志中。
数据流： 使用远程LLM（如通过Claude Desktop）时，您的提示向 LLM和结果此MCP服务器返回的（灯光名称、状态、场景名称）将发送给LLM提供程序。如果隐私是一个主要问题，请注意灯光/组/位置/场景标签中的潜在敏感信息。
本地执行： 此服务器在您的计算机上本地运行。它通过HTTPS与LIFX云API直接通信。

教程

确保服务器正在运行并已连接到MCP客户端。替换占位符，如 label:MyLamp 使用您的实际灯光/组/位置标签或ID。

检查可用灯光（资源）：
- @lix-api:lifx://lights
- ^{➥ Uses lights 资源}
获取特定的灯光状态（资源）：
- @lix-api:lifx://light/label:Office Lamp/state
- ^{➥ Uses light-state 资源}
获取可用场景（资源）：
- @lix-api:lifx://scenes
- ^{➥ Uses scenes 资源}
使用选择器帮助程序（提示）：
- @lix-api:selector-helper goal: "the lights in the kitchen"
- ^{➥ Uses selector-helper 提示}
创建效果（提示）：
- @lix-api:effect-creator effect_type:breathe selector:all description:"a very slow fade to warm white"
- ^{➥ Uses effect-creator 提示（按照指示进行响应）}
灯故障排除（提示）：
- @lix-api:troubleshooter selector:"id:d073d5xxxxxx"
- ^{➥ Uses troubleshooter 提示}
列出您的灯光（工具）：
- “列出我的灯” 或 “列表灯选择器：全部”
- ^{➥ Uses list-lights 工具}
打开灯（工具）：
- “打开名为办公灯的灯” 或 “设置状态选择器：标签：办公灯电源：打开”
- ^{➥ Uses set-state 工具}
设置颜色和亮度（工具）：
- “将厨房组灯设置为蓝色，亮度为50%，持续3秒”
- “设置状态选择器：组：厨房颜色：蓝色亮度：0.5持续时间：3”
- ^{➥ Uses set-state 工具}
切换位置（工具）：
- “打开客厅的灯” 或 “切换电源选择器：位置：客厅”
- ^{➥ Uses toggle-power 工具}
增加亮度（工具）：
- “使所有灯亮10%” 或 “状态增量选择器：所有亮度：0.1”
- ^{➥ Uses state-delta 工具}
激活场景（需要资源/工具中的场景UUID）：
- “使用uuid abcdef12-3456-激活场景…”
- “激活场景sceneuuid:abcdef12-3456-…”
- ^{➥ Uses activate-scene 工具}

Docker 文件

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies cleanly
# Using --omit=dev because devDependencies are not needed in production
RUN npm ci --omit=dev --production --no-fund --no-audit

# Copy the rest of the application code
COPY . .

# Set the entrypoint
ENTRYPOINT ["node", "lifx-api-mcp-server.js"]

# Default command (can be overridden, e.g., with API token if not using config/env)
# CMD ["YOUR_DEFAULT_TOKEN_IF_NEEDED"]

免责声明

本软件按“原样”提供，不提供任何形式的保修。使用风险自负。
作者不隶属于LIFX（LiFi Labs股份有限公司）。
确保您了解LIFX API速率限制（每个令牌120次请求/分钟），以避免临时阻塞。如果发生以下情况，则记录速率限制信息 logLevel 是 verbose.
此服务器部分是在人工智能的帮助下生成的，可能包含错误。

支持

如果您发现此工具有用，请考虑支持开发人员（可选）：

给我买杯咖啡 | GitHub赞助