Smart Bulb MCP Server

一个基于 Node.js 和 TypeScript 构建的 Model Context Protocol (MCP) 服务器，用于通过 IP 控制智能灯泡。它支持：

• Mock/模拟灯泡：无需物理硬件即可进行本地测试和开发。

• Yeelight/Xiaomi 灯泡：使用标准 TCP 端口 55443（本地控制 JSON-RPC 协议）控制真实的物理智能灯泡。

功能特性

• 通过 IP 连接：动态连接本地网络中的不同灯泡。

• 电源控制：打开或关闭灯泡。

• 亮度与不透明度：将灯泡亮度/强度从 1% 调整到 100%。

• 颜色控制：使用 RGB 坐标或十六进制颜色值设置颜色。

• 状态查询：实时获取灯泡的当前状态。

Related MCP server: Philips Hue MCP Service

快速开始

1. 构建服务器

首先，安装依赖并编译 TypeScript 文件：

# Install dependencies
npm install

# Compile the TypeScript files
npm run build

编译后的文件将输出到 dist/ 目录。

2. 运行 / 开发

您可以直接通过标准 I/O（Stdio）运行服务器：

# Run the built JS
npm start

# Compile and run in development mode
npm run dev

配置 MCP 客户端

要将此服务器与 MCP 客户端（如 Claude Desktop 或 Cursor）配合使用，请将服务器配置添加到您的配置文件中。

适用于 Claude Desktop

编辑 claude_desktop_config.json（在 Windows 上通常位于 %APPDATA%\Claude，在 macOS 上通常位于 ~/Library/Application Support/Claude）：

{
  "mcpServers": {
    "smart-bulb": {
      "command": "node",
      "args": ["D:/Palwinder/mcp-server-bulb/dist/index.js"]
    }
  }
}

注意：请将 D:/Palwinder/mcp-server-bulb/dist/index.js 为您机器上 dist/index.js 的绝对路径。

对外提供的 MCP 工具

服务器连接后，宿主 LLM 将可以访问以下工具：

1. connect_bulb

连接到一个指定 IP 的灯泡。

• 参数：

  • ip（string，必填）：IP 地址（例如 "192.168.1.15" 或 "127.0.0.1"）。

  • type（枚举 ["mock", "yeelight"]，默认值 "mock"）：驱动程序类型。使用 "mock" 可在没有物理硬件的情况下测试服务器功能，使用 "yeelight" 则用于控制真实的 Yeelight 灯泡。

  • port（number，可选）：要使用的端口。Yeelight 默认为 55443，Mock 默认为 9999。

2. disconnect_bulb

断开与当前连接的灯泡的断开连接。

• 参数：无。

3. get_bulb_state

获取连接状态、电源状态、亮度/不透明度和 RGB 颜色。

• 参数：无。

4. set_bulb_power

打开或关闭灯泡。

• 参数：

  • power（boolean，必填）：true 表示打开，false 表示关闭。

5. set_bulb_brightness

设置灯泡的亮度/不透明度。

• 参数：

  • brightness（number，必填）：取值为 1 到 100。

6. set_bulb_color_rgb

使用 RGB 值设置灯泡颜色。

• 参数：

  • r（number，必填）：红色分量 0 - 255。

  • g（number，必填）：绿色分量 0 - 255。

  • b（number，必填）：蓝色分量 0 - 255。

7. set_bulb_color_hex

使用十六进制颜色代码实现设置灯泡颜色。

• 参数：

  • hex（string，必填）：十六进制代码（例如 "#FF0000" 或 "00FF00"）。

OpenAI 集成客户端

我们在 src/openai-client.ts 中构建了一个客户端封装，使您可以直接将提示词发送给 OpenAI。OpenAI 随后会自动调用 MCP 工具来对您的智能灯泡执行操作。

客户端设置与运行

1. 设置您的 OpenAI API 密钥： 在 Windows（PowerShell）上：

   $env:OPENAI_API_KEY="your-actual-api-key"

   在 macOS/Linux（Bash）上：

   export OPENAI_API_KEY="your-actual-api-key"

2. 运行客户端：

   • 交互式 CLI 模式：

     npm run client

     这会打开一个 shell 提示符。尝试输入：

     连接到模拟灯泡，打开它，将其亮度设置为 80%，并将颜色设置为黄色。

   • 一次性命令模式： 将您的提示直接作为参数传入：

     npm run client -- "connect to the mock bulb, turn it on, and set color to blue"

3. 自定义模型（可选）： 默认情况下使用 gpt-4o-mini。您可以通过设置 OPENAI_MODEL 环境变量来更换：

   $env:OPENAI_MODEL="gpt-4o"

开发者详情与架构

该项目采用模块化架构：

• src/bulb/interface.ts：定义通用契约（ISmartBulb）和状态结构（BulbState）。

• src/bulb/mock.ts：模拟灯泡实例，在内存中模拟网络延迟和状态变化。

• src/bulb/yeelight.ts：实现基于原始 TCP 行缓冲区的解析器，直接与物理 Yeelight WiFi 灯泡发送和接收 JSON-RPC 数据包，不依赖任何第三方 SDK。

• src/index.ts：挂载并配置 @modelcontextprotocol/server 工具，处理连接状态和校验模式。

• src/openai-client.ts：以子进程方式启动 MCP 服务器，动态加载其所有工具，将其暴露为 OpenAI Functions，并在多轮对话中执行工具调用循环。

由 Palwinder Singh 构建