Hue Mcp

Hue Mcp

管理 TypeScript

🚀 🌈 Hue MCP Server

Hue MCP Server 是一款现代化的模型上下文协议（MCP）服务器，它能够让 AI 助手使用自然语言控制飞利浦 Hue 智能照明系统，为智能家居控制带来了极大的便利。

🚀 快速开始

前提条件

  • Node.js 18 及以上版本
  • 本地网络中的飞利浦 Hue 桥接器（v2）
  • Claude Desktop 或兼容的 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 Desktop 配置

选项 B：CLI 设置

npm run setup

3. 添加到 Claude Desktop

将生成的配置复制到你的 Claude Desktop 配置文件中： 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 Desktop 并尝试以下命令：

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

✨ 主要特性

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

📚 详细文档

  • 安装指南 - 详细的设置说明
  • 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 带有洞察的系统概述 "给我一个灯光摘要"

✨ 增强功能

所有工具现在都包括：

  • 🎯 快速操作 - 为常见任务提供预建建议
  • 💡 智能推荐 - 能源提示和故障排除建议
  • 📊 丰富上下文 - 房间关系和功能信息
  • 🔍 过滤与搜索 - 精确找到你需要的内容
  • 📈 摘要统计 - 概述数据，便于做出更好的决策

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

为了提高持续对话的效率：

  • 📏 智能响应大小 - 支持 紧凑、标准、详细 模式
  • 🧠 上下文管理 - 学习用户偏好，随时间自适应
  • 📊 智能分页 - 不会因过多数据而让用户感到负担
  • 🎛️ 渐进式披露 - 开始时简洁，根据请求展开
  • ⚡ 对话状态跟踪 - 跟踪使用情况，以选择最佳工具

🎨 自然语言示例

🔍 智能搜索查询

  • "查找所有厨房灯光" → 按房间名称搜索
  • "显示所有开启的灯光" → 按当前状态过滤
  • "卧室里的彩色灯泡" → 按功能和房间搜索
  • "所有无法访问的灯光" → 查找连接问题

💬 对话效率示例

  • "快速状态" → 使用最少上下文实现快速响应
  • "我有哪些灯光？"（首次询问）→ 标准详细级别
  • "我有哪些灯光？"（重复询问）→ 紧凑响应
  • "打开卧室灯光" → 建议使用房间控制而非单个灯光控制

🎨 颜色与氛围

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

🌟 氛围场景（自动变化）

这些关键词会触发逼真的单个灯光变化：

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

亮度与设置

  • "缓慢调暗蓝色灯光" → 蓝色灯光缓慢过渡
  • "明亮的红色" → 全亮度的红色
  • "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 地址 必需
HUE_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 通信

📝 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

为智能家居社区用心打造 ❤️

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

默认排序 时间排序

0 个评论

« 上一篇
FREEZONEX_mcp Server Supos
下一篇 »
Hekmon8_Homeassistant Server Mcp
  • 0 关注
  • 0 收藏，37 浏览
  • system 提出于 2025-10-04 11:54

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »