星战科技xingzhan.cloud
返回市场
hue-mcp

hue-mcp

作者：rmrfslashbin2 星标更新：2025-11-20
安装使用来源：spider==github.com

项目介绍

🌈 Hue MCP Server

一个现代的模型上下文协议（MCP）服务器，使AI助手能够通过自然语言控制飞利浦Hue智能照明系统。

TypeScript Node.js License: MIT

✨ 特性

  • 🎨 自然语言控制 - "将客厅灯光调至暴风雨黄昏"
  • 🔍 智能灯泡搜索 - "查找卧室中的所有彩色灯泡"
  • 🏠 智能房间与区域管理 - 使用单个命令控制整个房间和区域
  • 🌟 氛围变化 - 为真实场景提供独立灯光变化
  • 🎭 场景激活 - 浏览并激活预定义的照明场景
  • 🧠 AI优化工具 - 增强响应，快速操作和建议
  • 💬 聊天机器人用户体验优化 - 智能响应大小和上下文管理
  • ⚡ 智能缓存 - 减少95%的API调用，并具有优雅的回退机制
  • 🔧 现代化设置向导 - 基于React的美丽配置体验
  • 🔒 安全且本地化 - 所有通信都保留在您的本地网络上
  • 🛠️ 开发者友好 - 首选TypeScript并进行全面测试

🚀 快速开始

先决条件

  • Node.js 1 以上版本
  • 飞利浦Hue桥接器（v2）在您的本地网络上
  • Claude桌面或兼容的MCP客户端

1. 安装

git clone https://github.com/your-username/hue-mcp.git
cd hue-mcp
npm install

2. 设置您的Hue桥接器

选项A：Web设置（推荐）

npm run setup:web

这将在http://localhost:3000启动一个美丽的设置向导，它将：

  • 自动发现您的Hue桥接器
  • 引导您完成身份验证
  • 测试您的连接
  • 生成Claude桌面配置

选项B：CLI设置

npm run setup

3. 添加到Claude桌面

将生成的配置复制到您的Claude桌面配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hue-lights": {
      "command": "node",
      "args": ["/path/to/hue-mcp/dist/index.js"],
      "env": {
        "HUE_BRIDGE_IP": "192.168.1.100",
        "HUE_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. 开始使用

重启Claude桌面并尝试以下命令：

  • "打开客厅的灯光"
  • "将卧室设置为暖白色30%"
  • "激活精力充沛的场景"
  • "显示所有可用的灯光"
  • "关闭所有灯光"

📚 文档

💡 最佳使用模式

对于聊天机器人的效率

🔍 发现查询

❌ 避免："列出所有灯光"（可能产生大量响应）
✅ 更好："查找已开启的灯光"（过滤后相关）
✅ 最佳："快速状态"（最小上下文摘要）

🏠 房间控制

❌ 避免：多个单独的灯光命令
✅ 更好："关闭所有卧室灯光"（单个房间命令）
✅ 最佳："将卧室设置为放松心情"（场景激活）

📊 状态检查

❌ 避免：每次详细系统概览
✅ 更好："最小状态"（紧凑摘要）
✅ 最佳：根据上下文感知——首次详细，之后最小

响应大小指导原则

  • 首次交互：使用“标准”详细程度进行定向
  • 持续对话：使用“紧凑”以保存上下文窗口
  • 故障排除：使用“详细”获取全面信息
  • 快速检查：使用“最小”进行状态更新

🛠️ 可用命令

命令描述
npm run setup:web启动交互式Web设置向导
npm run setupCLI设置工具
npm run dev在开发模式下运行，带热重载
npm run build构建生产环境
npm run start运行生产构建
npm run test运行单元测试
npm run test:connection测试与您的Hue桥接器的连接
npm run typecheck检查TypeScript类型
npm run lint代码检查
npm run format使用Prettier格式化代码

🔧 MCP工具

服务器提供了这些AI优化工具：

🔍 发现与搜索工具

工具描述示例
find_lights智能搜索带有过滤器"查找所有未开启的灯光"，"卧室中的彩色灯泡"
list_lights带有房间上下文的增强列表"我有哪些灯光？"
get_light详细信息与快速操作"显示厨房灯光的状态"

🏠 房间与区域管理

工具描述示例
list_rooms列出所有房间及其状态"有哪些可用的房间？"
control_room_lights控制整个房间"关闭卧室"
list_zones列出所有区域及其状态"我有哪些区域？"
control_zone_lights控制整个区域"将主区域设置为放松"

🎭 场景管理

工具描述示例
list_scenes按类别浏览场景"我可以激活哪些场景？"
activate_scene激活预定义场景"激活放松场景"

🎛️ 单独控制与概述

工具描述示例
set_light_state通过自然语言控制"打开书桌灯并设置为暖白色"
get_summary带有见解的系统概述"给我一个照明总结"

🔧 桥接器与系统管理

工具描述示例
get_bridge_config桥接器配置和系统信息"显示桥接器设置"
get_info服务器版本和系统信息"我在运行哪个版本？"

👥 用户管理

工具描述示例
list_users列出所有白名单用户"谁有权访问桥接器？"
get_user详细用户信息"显示用户abc123的详细信息"

✨ 增强功能

所有工具现在包括：

  • 🎯 快速操作 - 为常见任务预构建的建议
  • 💡 智能推荐 - 节能提示和故障排除
  • 📊 丰富上下文 - 房间关系和能力信息
  • 🔍 过滤与搜索 - 查找所需内容
  • 📈 概要统计 - 用于更好决策的概述数据

💬 聊天机器人用户体验优化

为了持续对话效率：

  • 📏 智能响应大小 - “紧凑”，“标准”，“详细”模式
  • 🧠 上下文管理 - 学习偏好，随时间适应
  • 📊 智能分页 - 从不过多数据而感到不知所措
  • 🎛️ 渐进披露 - 从最小开始，按需扩展
  • ⚡ 对话状态 - 跟踪使用情况以选择最佳工具

🎨 自然语言示例

🔍 智能搜索查询

  • "查找所有厨房灯光" → 按房间名称搜索
  • "显示已开启的灯光" → 根据当前状态筛选
  • "卧室中的彩色灯泡" → 按照能力和房间搜索
  • "所有无法到达的灯光" → 查找连接问题

💬 对话效率示例

  • "快速状态" → 使用最小上下文进行快速响应
  • "我有哪些灯光？"（首次）→ 标准详细程度
  • "我有哪些灯光？"（重复）→ 紧凑响应
  • "打开卧室灯光" → 建议房间控制而非单独灯光

🎨 颜色与心情

  • "暴风雨黄昏" → 深蓝色紫色，低亮度
  • "暖白色" → 舒适的暖色调
  • "日出" → 橙黄色，中等亮度
  • "海洋" → 蓝色青色
  • "火焰" → 红橙色，高饱和度

🌟 大气场景（自动变化）

这些关键词触发真实的独立灯光变化：

  • "雷暴"，"暴风雨" → 不同强度的蓝光变化
  • "日落"，"日出" → 灯光上的温暖颜色渐变
  • "壁炉"，"蜡烛光" → 暖色闪烁变化
  • "森林"，"海洋" → 自然颜色变化
  • "舒适"，"浪漫" → 微妙的暖色变化

亮度与设置

  • "缓慢变暗蓝色" → 蓝色，慢过渡
  • "全亮红色" → 红色，全亮度
  • "50%暖白色" → 暖色调，半亮度

房间与区域控制

  • "将客厅设置为充满活力模式"
  • "将卧室灯光设置为蜡烛光"
  • "让办公室明亮且凉爽"
  • "将主区域设置为周日晚上的放松模式"
  • "关闭楼下区域的所有灯光"

🏗️ 架构

使用现代技术构建：

  • TypeScript - 类型安全开发
  • node-hue-api v5 - 官方Hue SDK集成
  • React + Vite - 现代设置向导
  • Express - 设置服务器后端
  • Vitest - 快速单元测试
  • ESLint + Prettier - 代码质量

关键设计原则

  • 双模式操作 - 缓存响应与直接API回退
  • 优雅降级 - 尽力满足请求
  • 速率限制保护 - 防止API滥用
  • 全面错误处理 - 清晰、可操作的错误消息

🚀 性能优化

API效率

  • 通过乐观缓存减少60-70%的API调用
  • 智能失效情况下缓存寿命延长5倍（1分钟 → 5分钟）
  • 批量操作优先于单独灯光控制
  • 速率限制保护，2分钟发现缓存
  • 并行执行用于大气变化（所有灯光同时更新）

聊天机器人上下文管理

  • 紧凑模式下响应减少75%
  • 智能分页 - 根据详细程度最大5-20结果
  • 渐进披露 - 最小 → 标准 → 详细
  • 对话状态跟踪 - 学习并随时间适应
  • 查询优化 - 建议更高效的替代方案

内存与上下文窗口

  • 基于对话阶段自适应响应大小
  • 上下文感知参数自动优化
  • 智能截断，带有明确的继续提示
  • 工具选择指导以实现最佳效率

🔍 故障排除

常见问题

"未找到桥接器"

  • 确保您的Hue桥接器已通电并连接到同一网络
  • 尝试在设置向导中手动输入IP地址

"身份验证失败"

  • 确保按下Hue桥接器上的物理按钮
  • 按钮必须在开始身份验证后的30秒内按下

"连接测试失败"

  • 验证您的桥接器IP地址是否正确
  • 检查您的API密钥是否有效
  • 确保您的防火墙允许与桥接器的连接

更多帮助，请参阅我们的故障排除指南。

🧪 测试您的设置

测试您的配置：

# 测试与您的桥接器的连接
npm run test:connection

# 运行单元测试
npm test

# 检查TypeScript类型
npm run typecheck

📄 配置

服务器支持多种配置方法：

  1. 环境变量（最高优先级）
  2. hue-config.json 文件
  3. .env 文件（最低优先级）

配置选项

变量描述默认值
HUE_BRIDGE_IP桥接器IP地址必填
H_UE_API_KEYAPI认证密钥必填
HUE_SYNC_INTERVAL_MS缓存刷新间隔300000（5分钟）
HUE_ENABLE_EVENTS实时事件更新false
LOG_LEVEL日志详细程度info

🤝 贡献

我们欢迎贡献！请参阅我们的开发指南了解详情。

开发设置

# 克隆并安装
git clone https://github.com/your-username/hue-mcp.git
cd hue-mcp
npm install

# 运行测试
npm test

# 启动开发服务器
npm run dev

📈 性能

  • 通过智能缓存减少95%的API调用
  • 缓存数据的亚秒级响应时间
  • 当缓存不可用时优雅回退
  • 速率限制保护防止桥接器过载

🔒 安全

  • 仅限本地网络 - 除桥接器发现外无外部API调用
  • 不收集数据 - 所有照明数据保留在本地
  • 安全认证 - API密钥存储在本地
  • 与Hue桥接器的HTTPS通信

🛡️ 用户管理安全

服务器包括内置安全保护的用户管理工具：

  • 👀 只读访问 - 用户工具提供对桥接器访问的可见性而不进行修改
  • 📝 审计轨迹 - 所有用户操作都被记录并带有元数据
  • 🔒 仅限本地网络 - 所有用户数据都保留在您的本地网络上

注意：由于Philips Hue在其本地API中废弃了此功能，因此不支持删除用户。要移除用户，请使用官方的Philips Hue账户管理网页界面。

📝 许可

MIT许可 - 详情请参阅LICENSE文件。

🙏 致谢

为智能家居社区制作 ❤️

需要帮助？查阅我们的文档或提交问题！