🌈 Hue MCP Server

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

✨ 特性

• 🎨 自然语言控制 - "将客厅灯光调至暴风雨黄昏"
• 🔍 智能灯泡搜索 - "查找卧室中的所有彩色灯泡"
• 🏠 智能房间与区域管理 - 使用单个命令控制整个房间和区域
• 🌟 氛围变化 - 为真实场景提供独立灯光变化
• 🎭 场景激活 - 浏览并激活预定义的照明场景
• 🧠 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%"
• "激活精力充沛的场景"
• "显示所有可用的灯光"
• "关闭所有灯光"

📚 文档

• 安装指南 - 详细的设置说明
• MCP工具参考 - 完整的工具文档
• 自然语言示例 - 命令示例和模式
• 故障排除 - 常见问题及解决方案
• 开发指南 - 贡献和扩展
• API参考 - 技术API文档

💡 最佳使用模式

对于聊天机器人的效率

🔍 发现查询

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

🏠 房间控制

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

📊 状态检查

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

响应大小指导原则

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

🛠️ 可用命令

命令	描述
npm run setup:web	启动交互式Web设置向导
npm run setup	CLI设置工具
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_KEY	API认证密钥	必填
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文件。

🙏 致谢

• Philips Hue 提供了出色的智能照明平台
• node-hue-api 提供了优秀的SDK
• Model Context Protocol 提供了AI集成框架
• Anthropic 提供了Claude和MCP开发

---

为智能家居社区制作 ❤️

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