Hubitat Local MCP Server

添加到你的 MCP 设置文件（~/.claude.json 或项目 .mcp.json）：

{
  "mcpServers": {
    "hubitat": {
      "type": "url",
      "url": "http://192.168.1.100/apps/api/123/mcp?access_token=YOUR_TOKEN"
    }
  }
}

如需远程访问，请使用 Hubitat 云 URL。

添加到你的 Claude 桌面版配置文件：

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

{
  "mcpServers": {
    "hubitat": {
      "type": "url",
      "url": "http://YOUR_HUB_IP/apps/api/123/mcp?access_token=YOUR_TOKEN"
    }
  }
}

Claude.ai 通过 连接器 支持 MCP 服务器：

1. 访问 claude.ai > 设置 > 连接器。
2. 使用你的 Hubitat 端点 URL 添加新连接器。
3. 如需远程访问，请使用 云端点 URL，或使用 Cloudflare 隧道 URL。

借助 Hubitat 云，你可以在任何地方通过 claude.ai 控制你的智能家居 — 无需本地设置！

任何支持通过 HTTP URL 连接 MCP 服务器的 AI 服务都可以使用此服务器。可使用以下任意一种：

• Hubitat 云 URL — 拥有 Hubitat 云订阅无需额外设置。
• Cloudflare 隧道 — 用于免费的自托管远程访问（请参阅 远程访问选项）。

所有操作都会造成干扰。集线器管理员工具需要在设置中启用集线器管理员读取/写入权限。写入工具实施 三层安全网关：启用集线器管理员写入权限 + 24 小时内有完整的集线器备份 + 明确的 confirm=true。

在进行任何修改/删除操作之前，源代码会自动备份。

监控工具需要启用集线器管理员读取权限。

写入/删除操作需要集线器管理员写入权限并确认。

运动激活灯光：

{
  "name": "Motion Light",
  "triggers": [
    { "type": "device_event", "deviceId": "123", "attribute": "motion", "value": "active" }
  ],
  "conditions": [
    { "type": "time_range", "startTime": "sunset", "endTime": "sunrise" }
  ],
  "actions": [
    { "type": "device_command", "deviceId": "456", "command": "on" },
    { "type": "delay", "seconds": 300, "delayId": "motion-off" },
    { "type": "device_command", "deviceId": "456", "command": "off" }
  ]
}

带去抖动的温度控制：

{
  "name": "AC On When Hot",
  "triggers": [
    { "type": "device_event", "deviceId": "1", "attribute": "temperature",
      "operator": ">", "value": "78", "duration": 300 }
  ],
  "actions": [
    { "type": "device_command", "deviceId": "8", "command": "on" }
  ]
}

带局部变量的按钮状态机：

{
  "name": "Smart Button Toggle",
  "localVariables": { "lastScene": "natural" },
  "triggers": [
    { "type": "button_event", "deviceId": "80", "action": "pushed" }
  ],
  "actions": [
    {
      "type": "if_then_else",
      "condition": { "type": "variable", "variableName": "lastScene",
                     "operator": "equals", "value": "natural" },
      "thenActions": [
        { "type": "activate_scene", "sceneDeviceId": "nightlight-scene" },
        { "type": "set_local_variable", "variableName": "lastScene", "value": "nightlight" }
      ],
      "elseActions": [
        { "type": "activate_scene", "sceneDeviceId": "natural-scene" },
        { "type": "set_local_variable", "variableName": "lastScene", "value": "natural" }
      ]
    }
  ]
}

此外，修改或删除现有应用/驱动程序的工具会在进行更改之前自动备份项目的源代码。

展望性想法 — 以下所有内容均为推测，需要进一步研究以确定可行性。这些功能均不保证或承诺实现。

状态标识：[ ] = 未开始 | [~] = 进行中 / 部分完成 | [x] = 已完成 | [?] = 需要研究 / 可行性未知

2025 年 2 月进行了可行性研究。每个项目现在都包含难度评级（1 - 5）、工作量估计和基于全面代码库分析的实施说明。

难度标识：1 = 简单 | 2 = 直接 | 3 = 中等 | 4 = 复杂 | 5 = 极其复杂

工作量标识：S = 小（小时） | M = 中（1 - 3 天） | L = 大（4 天以上）

规则引擎增强

触发器增强

• [x] 条件触发器（在触发时评估） — 难度：1 | 工作量：S

  已实现。evaluateTriggerCondition() 方法使用完整的条件系统评估每个触发器的 condition 字段。每个触发器处理程序已经调用此方法。可能需要更好的文档和 MCP 工具模式更新，以使该功能更易于发现。

• [x] Cron/周期性触发器 — 难度：1 | 工作量：S

  已实现。periodic 触发器类型通过 schedule() 内部生成 cron 表达式。要暴露原始 cron 支持，添加一个 cron 子类型，直接传递用户提供的 cron 表达式。Hubitat 接受标准的 7 字段 cron 表达式。用户提供的字符串需要验证。

• [ ] 端点/Webhook 触发器 — 难度：3 | 工作量：M

  可行。在父应用的 mappings 块中添加一个单一的调度端点（例如，/mcp/webhook?ruleKey=<key>）。父应用通过键查找子规则，并使用请求体/参数作为事件数据调用 executeRule("webhook", webhookEvt)。由于 mappings 是编译时的，因此无法实现每个规则的动态路径，但带有查询参数的共享端点可以工作。OAuth 访问令牌已经保护了路径。

  实施计划：

  1. 在父应用中添加 GET/POST /webhook 映射。
  2. 在子应用的 subscribeToTriggers() 中添加 webhook 触发器类型。
  3. 父应用通过键查找将请求调度到匹配的子规则。
  4. 将请求体、头和查询参数打包成伪事件，用于变量替换。

• [ ] 集线器变量更改触发器 — 难度：3 | 工作量：M

  部分可行。Hubitat 没有为集线器变量更改提供原生的 subscribe() 方法。有两种方法：(A) 轮询 — 使用 schedule() 每 5 - 10 秒比较当前值与 atomicState 中的最后已知值。这会增加延迟和集线器负载。(B) 变量连接器解决方法 — Hubitat 的变量连接器功能（固件 ≥ 2.3.4）将集线器变量暴露为设备属性，可以通过现有的 device_event 触发器进行订阅。选项 B 更简洁，但需要用户创建变量连接器设备。

  实施计划：

  1. 添加 variable_change 触发器类型，可配置轮询间隔。
  2. 在 atomicState.variableSnapshots 中存储最后已知值。
  3. 在每个轮询周期中，比较并在值更改时触发规则。
  4. 将变量连接器方法记录为首选替代方案。

• [ ] 系统启动触发器 — 难度：2 | 工作量：S

  可行。Hubitat 支持 subscribe(location, "systemStart", handler)。添加一个 system_start 触发器类型。集线器重启后，应用恢复，initialize() → subscribeToTriggers() 运行，系统启动事件触发规则。小边缘情况：事件可能在所有应用完成恢复之前触发 — 需要在硬件上进行测试。

  实施计划：

  1. 在子应用中添加 system_start 触发器类型。
  2. 在 subscribeToTriggers() 中订阅 location "systemStart" 事件。
  3. 处理程序调用 executeRule("system_start")。

• [ ] 日期范围触发器 — 难度：2 | 工作量：S

  可行。作为条件实现比作为触发器更好。date_range 条件类型使用 new Date() 检查开始/结束日期，遵循与 time_range 和 days_of_week 相同的模式。如果作为触发器实现，使用 schedule() 在范围开始时触发。java.util.Calendar 在沙箱中可用。

  实施计划：

  1. 在 evaluateCondition() 中添加 date_range 条件类型。
  2. 接受 startDate 和 endDate（ISO 格式）。
  3. 可选地添加一个 date_range 触发器，在范围开始时调度一次性事件。

条件增强

• [ ] 必需表达式（规则门）与飞行中动作取消 — 难度：4 | 工作量：L

  可行但复杂。“门”是在动作执行期间持续监控的条件。如果条件变为假，则取消飞行中的延迟动作。现有的 cancelledDelayIds 机制为取消提供了基础。门需要为相关设备单独进行 subscribe() 调用，处理程序检查门条件并将所有待处理的延迟 ID 标记为取消。这是最具架构复杂性的增强 — 它需要在延迟动作链期间进行异步监控和仔细的状态管理。

  实施计划：

  1. 在规则结构中添加 requiredExpressions 数组，与 conditions 并列。
  2. 单独订阅与门相关的设备事件。
  3. 门处理程序评估条件，如果为假则取消所有活动延迟。
  4. 在 atomicState.activeDelayIds 中跟踪每个规则的所有活动延迟 ID。
  5. 在规则正常执行完成时添加清理逻辑。

• [ ] 完整布尔表达式构建器（AND/OR/XOR/NOT 嵌套） — 难度：4 | 工作量：L

  可行。用递归树结构替换扁平的条件数组 + conditionLogic 切换：{operator: "AND", operands: [...]}。将 evaluateConditions() 重写为树遍历器。NOT 包装单个操作数；XOR 检查恰好一个为真。现有的 evaluateCondition() 用于叶节点已经模块化。主要挑战是 MCP 工具的易用性和向后兼容性 — 扁平数组格式需要迁移逻辑。

  实施计划：

  1. 定义具有 operator 和 operands 字段的树数据结构。
  2. 实现递归的 evaluateConditionTree() 方法。
  3. 支持旧的扁平格式和新的树格式（迁移路径）。
  4. 更新 create_rule/update_rule 工具模式。
  5. 更新 describeCondition() 以进行递归格式化。

• [ ] 每个规则的私有布尔值 — 难度：2 | 工作量：S

  可行。已经可以通过 atomicState.localVariables 实现。添加一个专用的 set_rule_boolean 动作类型，调用 parent.setRuleBooleanOnChild(targetRuleId, boolName, value)，该方法更新目标子规则的局部变量。添加一个 rule_boolean 条件类型，读取特定规则的局部变量。父应用通过 getChildAppById() 调解跨规则访问。

  实施计划：

  1. 在子应用中添加 set_rule_boolean 动作类型。
  2. 在 evaluateCondition() 中添加 rule_boolean 条件类型。
  3. 在父应用中添加 setRuleBooleanOnChild() 方法。
  4. 更新 MCP 工具模式。

动作增强

• [ ] 随时间渐变调光器 — 难度：3 | 工作量：M

  可行。许多调光器原生支持 setLevel(level, duration)，代码库已经使用了该功能。对于软件渐变：计算步长和间隔，然后使用 runIn() 进行增量步骤。示例：在 60 秒内从 0 到 100 = 每 3 秒 5%（20 步）。将步数限制在 ~20 - 30，以避免过度占用集线器的调度器。与色温渐变和斜坡动作共享步进实用程序。

  实施计划：

  1. 添加 fade_dimmer 动作类型，包含 startLevel、endLevel、durationSeconds。
  2. 实现 rampValue() 实用程序，用于步进 runIn() 调度。
  3. 在 runIn() 上使用 [overwrite: false] 以避免冲突回调。
  4. 当设备支持时，回退到原生 setLevel(level, duration)。

• [ ] 随时间改变色温 — 难度：3 | 工作量：M

  可行。与渐变调光器模式相同。使用共享的 rampValue() 实用程序，在每个步骤调用 setColorTemperature()。一些设备原生支持 setColorTemperature(temp, level, duration)。温度范围因设备而异（通常为 2000K - 6500K）。

  实施计划：

  1. 添加 fade_color_temperature 动作类型，包含 startTemp、endTemp、durationSeconds。
  2. 重用渐变调光器的 rampValue() 实用程序。
  3. 处理温度步骤的整数舍入。

• [ ] 按模式执行动作 — 难度：2 | 工作量：S

  可行。添加一个 per_mode 动作类型，包含一个模式名称到动作列表的映射。在执行时，检查 location.mode 并执行匹配的动作列表。结构上类似于 if_then_else，但有多个分支。现有的 if_then_else 与 mode 条件已经提供了此功能，但不够方便。

  实施计划：

  1. 添加 per_mode 动作类型，包含 modeActions 映射。
  2. 在执行时查找 location.mode。
  3. 使用现有的 executeAction() 基础设施执行匹配的动作列表。

• [ ] 等待事件 / 等待表达式 — 难度：5 | 工作量：L

  部分可行。需要在执行流中暂停，直到外部事件发生。在 Hubitat 的单线程模型中，没有阻塞等待。实现方法：将当前执行状态（动作索引、上下文）保存到 atomicState，订阅目标事件，从执行中返回，然后在事件触发时恢复 — 类似于 delay 模式，但由事件触发。必须设置超时。等待订阅和其他触发器之间可能存在竞争条件。

  实施计划：

  1. 添加 wait_for_event 动作类型，包含目标设备/属性和强制超时。
  2. 将执行状态保存到 atomicState（与 delay 模式相同）。
  3. 为目标事件创建临时订阅。
  4. 在事件触发或超时后，从保存的状态恢复执行。
  5. 恢复后清理订阅。

• [ ] 重复直到 / 重复当 — 难度：4 | 工作量：L

  部分可行。扩展现有的 repeat 动作，在每次迭代之前/之后评估条件。关键安全措施：硬限制为 100 次迭代（与现有 repeat 限制匹配），强制最大迭代参数，以及循环保护。如果循环体包含延迟，每次迭代都需要保存状态/恢复模式，这使得实现极其复杂。建议最初仅支持同步循环（循环体中无延迟）。

  实施计划：

  1. 添加 repeat_while 和 repeat_until 动作类型。
  2. 每次迭代通过 evaluateCondition() 评估条件。
  3. 强制 maxIterations 上限（≤100）。
  4. 阶段 1：仅支持同步循环（循环体中无延迟动作）。
  5. 阶段 2（未来）：支持包含延迟的循环，具有状态持久化。

• [ ] 规则间控制 — 难度：2 | 工作量：M

  可行。添加 enable_rule、disable_rule 和 trigger_rule 动作类型。子应用调用父应用，父应用查找目标子规则并调用现有的 enableRule()/disableRule()/executeRule()。为防止规则间的乒乓循环，传递一个“触发链深度”计数器，并拒绝深度超过 5 的执行。

  实施计划：

  1. 添加 enable_rule、disable_rule、trigger_rule 动作类型。
  2. 在父应用中实现 triggerChildRule(targetRuleId, depth)。
  3. 在 executeRule() 中添加深度计数器，以防止级联循环。
  4. 通过 getChildAppById() 验证目标规则是否存在。

• [ ] 文件写入/追加/删除 — 难度：2 | 工作量：S

  可行。父应用已经有 uploadHubFile()/downloadHubFile() 包装器。新的动作类型 file_write、file_append、file_delete 调用父应用方法。追加操作进行读-修改-写循环（非原子操作）。需要集线器管理员写入权限。内容中的变量替换支持动态日志文件。

  实施计划：

  1. 添加 file_write、file_append、file_delete 动作类型。
  2. 子应用调用 parent.writeFileFromRule(fileName, content, mode)。
  3. 根据 [A-Za-z0-9._-] 模式验证文件名。
  4. 应用集线器管理员写入权限以确保安全。

• [ ] 音乐/警报控制 — 难度：2 | 工作量：S

  可行。围绕现有的 device_command 提供便利包装。Hubitat 有 capability.musicPlayer（播放、暂停、停止、设置音量、播放曲目）和 capability.alarm（两者、警报器、频闪灯、关闭）。现有的 speak 动作展示了带有音量的文本转语音模式。这些将是具有内置功能验证的便捷动作类型。

  实施计划：

  1. 添加 play_music 动作类型，包含设备、命令、音量、曲目参数。
  2. 添加 activate_siren 动作类型，包含设备、模式（警报器/频闪灯/两者/关闭）。
  3. 在执行前验证设备是否具有所需功能。

• [x] 自定义动作（任何功能 + 命令） — 难度：1 | 工作量：S

  已实现。现有的 device_command 动作类型通过动态调用（device."${command}"(*params)）接受任何设备 ID、命令和参数。这就是“任何功能 + 命令”功能。

• [ ] 禁用/启用设备 — 难度：1 | 工作量：S

  可行（部分完成）。update_device MCP 工具已经通过内部 /device/disable 端点支持 enabled 属性。一个新的 set_device_enabled 规则动作类型包装相同的调用。需要集线器管理员写入权限。如果目标设备用于活动规则触发器，应发出警告。

  实施计划：

  1. 添加 set_device_enabled 动作类型，包含 deviceId 和 enabled 布尔值。
  2. 调用 parent.setDeviceEnabled(deviceId, enabled)。
  3. 检查设备是否用于任何规则触发器并发出警告。

• [ ] 斜坡动作（连续升高/降低） — 难度：3 | 工作量：M

  部分可行。与渐变调光器/色温模式相同的软件步进模式。通用的 ramp 动作针对任何数字属性。真正的连续升高/降低（如按住物理调光器按钮）使用 startLevelChange(direction) / stopLevelChange()，但无法从软件进行时间限制。与渐变动作共享 rampValue() 实用程序。

  实施计划：

  1. 添加 ramp 动作类型，包含设备、属性、起始值、结束值、持续时间、步数。
  2. 重用渐变动作的 rampValue() 实用程序。
  3. 对于具有 startLevelChange/stopLevelChange 的设备，提供硬件斜坡选项。

• [ ] Ping IP 地址 — 难度：3 | 工作量：M

  不可行。Hubitat 的沙箱 Groovy 环境不提供 ICMP、HubAction、原始套接字或 Runtime.exec()。只有驱动程序代码可以使用 HubAction 进行某些协议。

  替代方案：HTTP 可达性检查 (下面添加为替代项)

• [ ] HTTP 可达性检查 (替代 Ping) — 难度：2 | 工作量：S

  可行。使用 httpGet() 向目标 IP 发送 HTTP 请求，并将成功/失败解释为可达/不可达。这不是真正的 ICMP ping，但可以实现对具有 Web 服务器的设备的网络可达性测试。另一个选项：控制一个社区驱动程序，通过现有的 device_command 动作暴露 ping 功能。

  实施计划：

  1. 添加 http_check 动作类型，包含目标 URL 和超时。
  2. 在 try-catch 块中使用 httpGet()。
  3. 将结果设置在一个变量中（可达/不可达），用于条件判断。
  4. 文档中说明为“HTTP 可达性检查”而非“ping”。

变量系统

• [ ] 集线器变量连接器（作为设备属性暴露） — 难度：4 | 工作量：L

  部分可行。Hubitat 的内置变量连接器功能（固件 ≥ 2.3.4）已经处理集线器变量。对于 MCP 规则引擎变量，将它们作为设备属性暴露需要：(1) 一个自定义虚拟设备驱动程序，(2) 父应用通过 addChildDevice() 创建一个实例，(3) 父应用在变量写入时通过 sendEvent() 更新属性。自定义驱动程序会为项目增加第三个文件和安装复杂性。

  实施计划：

  1. 创建 MCP 变量连接器 驱动程序（新的 Groovy 文件）。
  2. 父应用在首次写入变量时（或按需）自动创建一个子设备。
  3. 扩展 setRuleVariable() 以在连接器设备上也调用 sendEvent()。
  4. 将驱动程序添加到 HPM 包清单中。
  5. 文档中说明集线器变量应使用 Hubitat 的内置连接器。

• [ ] 变量更改事件 — 难度：3 | 工作量：M

  可行。对于 MCP 规则引擎变量：扩展 setRuleVariable() 以触发 sendLocationEvent(name: "ruleVariableChanged", value: varName, data: newValue)。带有 variable_change 触发器的子规则订阅此事件。对于集线器变量：使用上述“集线器变量更改触发器”中的轮询方法或利用变量连接器。

  实施计划：

  1. 在父应用的 setRuleVariable() 中添加 sendLocationEvent() 调用。
  2. 在子应用中添加 variable_change 触发器类型。
  3. 子应用订阅 location "ruleVariableChanged" 事件。
  4. 在处理程序中按变量名称过滤。

• [ ] 局部变量触发器 — 难度：2 | 工作量：S

  可行。在 set_local_variable 或 variable_math 修改局部变量后，检查匹配的 local_variable_change 触发器，并通过 runIn(0, handler) 异步重新触发。如果规则触发自身，存在无限循环的高风险 — 建议仅在外部更改（另一个规则通过规则间控制设置此规则的局部变量）时触发。循环保护提供安全网。

  实施计划：

  1. 添加 local_variable_change 触发器类型。
  2. 在局部变量修改后，调度异步重新评估。
  3. 添加 triggerSource 跟踪，以防止自触发循环。
  4. 依赖循环保护作为安全网。

内置自动化等效功能

理念：优先使用原生 Hubitat 应用。MCP 服务器旨在补充 Hubitat，而非替代它。这些原生应用（房间照明、模式管理器、按钮控制器等）维护良好，有合适的用户界面，并且经过了实战检验。MCP 已经可以与这些应用的 效果 进行交互 — 它可以读取/设置模式、控制设备、对设备事件进行触发，并查看它们创建的虚拟设备。

AI 助手是魔法师。与其构建专门的向导工具来生成 MCP 规则以复制原生应用已经实现的功能，AI 可以使用现有的 create_rule 和完整的规则引擎即时编写规则。针对这些模式的专用 MCP 工具 优先级较低，只有在 MCP 确实无法以某种方式与原生应用的功能进行交互时才会实现。每个项目将根据具体情况进行评估。

• [ ] 房间照明（以房间为中心的照明，带有空位模式） — 低优先级

  首选原生应用。Hubitat 的内置房间照明应用可以很好地处理此功能。MCP 已经可以控制相同的设备，对运动事件进行触发，并使用 if_then_else / delay / cancel_delayed 通过 create_rule 构建等效逻辑（如果需要）。除非发现 MCP 无法与房间照明的行为进行交互的差距，否则不需要专用的 MCP 工具。

• [ ] 区域运动控制器（多传感器区域） — 低优先级

  首选原生应用。Hubitat 的内置区域运动控制器创建一个虚拟运动设备，聚合多个传感器。如果用户将此虚拟设备添加到 MCP 的选定设备中，MCP 已经可以看到并对其进行触发。AI 也可以使用 create_virtual_device + create_rule 结合多设备触发器复制此逻辑（如果需要）。只有在 MCP 无法与原生应用的输出设备进行充分交互时才进行实现。

• [ ] 模式管理器（自动化模式更改） — 低优先级

  首选原生应用。Hubitat 的内置模式管理器处理基于时间和存在的模式更改。MCP 已经可以通过 get_modes/set_mode 读取/设置模式，对 mode_change 进行触发，并构建基于时间/存在触发的规则来调用 set_mode。除非发现特定的交互差距，否则不需要专用工具。

• [ ] 按钮控制器（简化的按钮到动作映射） — 低优先级

  首选原生应用。Hubitat 的内置按钮控制器原生处理此功能。MCP 规则引擎已经有 button_event 触发器，完全支持按钮编号（1 - 20）和动作类型（按下/按住/双击/释放）。AI 可以通过 create_rule 直接创建这些规则。不需要专用工具。

• [ ] 恒温器调度器（基于时间表的设定点） — 低优先级

  首选原生应用。Hubitat 的内置恒温器调度器处理基于时间表的设定点。MCP 规则引擎已经有 time 触发器、set_thermostat 动作、mode 和 days_of_week 条件 — AI 可以直接编写时间表规则。除非 MCP 无法与原生调度器的效果进行交互，否则不需要专用工具。

• [ ] 锁码管理器 — 低优先级 — 需要评估

  可能需要专用工具。Hubitat 的内置锁码管理器通过用户界面处理代码管理。MCP 已经可以通过 send_command（setCode，deleteCode）发送锁码命令，并读取 lockCodes/lastCodeName 属性，因此目前可以进行基本交互。然而，原生应用的内部代码库存和临时代码调度无法直接访问。如果原生应用的输出证明不足，专用工具可能为程序化代码管理增加价值。需要具体情况具体评估。

• [ ] 组和场景（Zigbee 组消息） — 不可行

  不可行。zigbee 对象和 sendHubCommand() 与 Protocol.ZIGBEE 仅在驱动程序中可用，不在应用中。MCP 服务器是一个应用，无法发送原始 Zigbee 命令或管理 Zigbee 组 ID。Zigbee 组管理由闭源平台内部处理，没有文档化的 HTTP API 端点。

  已有替代方案：

  • 利用内置的组和场景应用：指导用户通过内置应用创建 Zigbee 组，然后通过 MCP 的 send_command 控制生成的组激活器设备（组激活器设备是 MCP 已经可以控制的常规开关/调光器设备）
  • 软件级组控制：创建规则，依次向多个设备发送命令 — 已经可以通过多设备规则或 device_command 动作实现
  • 场景捕获/恢复：现有的 capture_state/restore_state 动作提供了跨多个设备的类似场景功能

HPM 与应用/集成管理

• [ ] 按关键字搜索 HPM 存储库 — 难度：2 | 工作量：S

  可行。HPM 使用公共 GraphQL API https://hubitatpackagemanager.azurewebsites.net/graphql。search_hpm_packages 工具通过 httpPost() 发送 GraphQL 查询，并返回匹配的包，包含名称、描述、作者和清单 URL。主存储库列表 https://raw.githubusercontent.com/HubitatCommunity/hubitat-packagerepositories/master/repositories.json 提供离线浏览。

  实施计划：

  1. 创建 search_hpm_packages MCP 工具。
  2. 向 Azure 端点发送 GraphQL Search 查询。
  3. 解析并返回结果，对大型结果集进行分页。
  4. 在 state 中缓存结果，以减少 API 调用。

• [ ] 通过 HPM 安装/卸载包 — 难度：4 | 工作量：L

  部分可行。HPM 没有程序化 API — 它纯粹是基于用户界面的。绕过方法：获取包清单 JSON，下载每个应用/驱动程序源，并通过现有的 install_app/install_driver 工具进行安装。然而，以这种方式安装的包不会出现在 HPM 的“已安装”列表中，会造成碎片化体验。卸载需要通过文档不完善的 /installedapp/ 端点移除运行中的应用实例（不仅仅是代码）。

  实施计划：

  1. 使用绕过方法创建 install_package MCP 工具。
  2. 获取清单 → 下载源 → 通过现有工具安装。
  3. 在文件管理器中跟踪已安装的包，以便进行更新检查。
  4. 文档中说明限制：HPM 不会知道这些安装。
  5. 对于卸载：使用 delete_app/delete_driver 删除代码，研究 /installedapp/disable 用于实例。

• [ ] 检查已安装包的更新 — 难度：3 | 工作量：M

  部分可行。对于 MCP 跟踪的包（来自上述安装工具）：获取每个清单 URL 并比较版本 — 与现有的 MCP 服务器 checkForUpdate() 模式相同。对于 HPM 管理的包：HPM 的内部状态无法从另一个应用访问。需要一个并行跟踪数据库。

  实施计划：

  1. 创建 check_package_updates MCP 工具。
  2. 从文件管理器读取 MCP 跟踪的包列表。
  3. 获取每个清单 URL 并比较版本字段。
  4. 返回有可用更新的包列表。
  5. 优雅地处理获取失败（GitHub 速率限制、网络问题）。

• [ ] 搜索尚未启用的官方集成 — 难度：3 | 工作量：M

  部分可行。没有文档化的端点用于枚举可用的内置应用。list_hub_apps 工具返回用户安装的应用类型，而不是内置应用。实用方法：维护一个硬编码的已知官方集成目录（Hue Bridge、Sonos、Alexa、Google Home、HomeKit 等），并检查哪些有运行实例。列表仅在固件更新时更改。

  实施计划：

  1. 创建 list_available_integrations MCP 工具。
  2. 维护硬编码的官方集成目录及其描述。
  3. 检查已安装的应用实例，以确定哪些已经启用。
  4. 返回可用但未启用的集成，并提供设置指南。
  5. 每次 MCP 服务器发布时更新目录。

• [ ] 从 GitHub、论坛等发现社区应用/驱动程序 — 难度：3 | 工作量：M

  部分可行。主要机制：上述的 HPM 存储库搜索。GitHub API 搜索 (https://api.github.com/search/repositories?q=hubitat+driver) 可以工作，但未经身份验证的速率限制为每分钟 10 次请求。Hubitat 社区论坛没有搜索 API。文件管理器中的精选列表是一个实用的备用方案。

  实施计划：

  1. 创建 search_community_packages MCP 工具。
  2. 主要：通过 GraphQL 搜索 HPM 存储库。
  3. 次要：可选的 GitHub API 搜索，处理速率限制。
  4. 返回合并结果，并注明来源。
  5. 可选地在文件管理器中维护一个精选的热门包列表。

仪表盘管理

• [ ] 以编程方式创建、修改、删除仪表盘 — 难度：4 | 工作量：L

  通过内部 HTTP 端点可行（需要实证测试）。Hubitat 的仪表盘系统使用父 - 子应用模式：“Hubitat 仪表盘”是父应用，每个单独的仪表盘是子应用。深入研究发现了网页界面使用的 /installedapp/createchild/ 内部端点。

  关键发现：

  • 仪表盘列表：GET /dashboard/all?pinToken=<token> 或通过 GET /hub2/appsList 过滤仪表盘子应用。
  • 仪表盘创建：GET /installedapp/createchild/hubitat/Dashboard/parent/{dashboardParentAppId} — 在父应用下创建一个新的子仪表盘。返回重定向到 /installedapp/configure/{newChildId}。
  • 仪表盘布局读取：GET /apps/api/<parentAppId>/dashboard/<childAppId>/layout?access_token=<token>。
  • 仪表盘布局写入：POST /apps/api/<parentAppId>/dashboard/<childAppId>/layout，使用 Bearer 令牌身份验证。
  • 仪表盘删除：可能是 POST /installedapp/configure/{childId} 并执行删除操作，或 GET /installedapp/remove/{childId}（确切端点需要测试）。
  • 子应用类型：命名空间 hubitat，名称 Dashboard（从社区论坛的错误消息中确认）。

  重要注意事项：

  • Groovy 中的 addChildApp() 无法 从 MCP 应用创建仪表盘子应用（父应用不匹配），因此需要使用 HTTP 端点方法。
  • createchild 端点返回 HTTP 重定向（302），而不是 JSON — 需要从 Location 头中提取新的子应用 ID。
  • 创建后的配置（仪表盘名称、授权设备）需要单独的 POST 请求到 /installedapp/configure/{id}，使用表单编码数据。
  • 仪表盘父应用必须已经安装在集线器上。
  • /dashboard/all 的 pinToken 需要从仪表盘父应用获取，或者本地 API 调用可能不需要。
  • 固件 ≥ 2.3.9 引入了“简易仪表盘”作为替代方案 — 其内部结构可能不同。
  • 所有端点均未文档化，可能会随固件版本变化。

  实施计划：

  1. 通过 GET /hub2/appsList（按应用名称过滤）发现仪表盘父应用 ID。
  2. 创建 create_dashboard 工具：调用 GET /installedapp/createchild/hubitat/Dashboard/parent/{parentId}，从重定向中提取新的子应用 ID。
  3. 配置新仪表盘：POST /installedapp/configure/{newId}，包含名称和授权设备。
  4. 创建 list_dashboards 工具，通过 /dashboard/all 或 /hub2/appsList。
  5. 创建 get_dashboard_layout / update_dashboard_layout 工具，用于布局 JSON 的读取/写入。
  6. 创建 delete_dashboard 工具：测试 /installedapp/remove/{childId} 端点。
  7. 将仪表盘父应用 ID 和访问令牌添加到 MCP 应用偏好设置中。
  8. 需要集线器管理员写入权限以确保安全。
  9. 阶段 1：实现列表 + 读取/修改布局（已知可用的端点）。
  10. 阶段 2：实现创建/删除（需要在集线器硬件上进行实证测试）。

规则机器互操作性

可行性已确认 — 创建/修改 RM 规则不可行（闭源、未文档化格式）。然而，通过 hubitat.helper.RMUtils 类控制现有 RM 规则是可行的，该类在 Hubitat 应用沙箱中可用。

• [ ] 通过 RMUtils.getRuleList() 列出所有 RM 规则 — 难度：1 | 工作量：S

  可行。已确认可行。RMUtils.getRuleList("5.0") 返回 RM 5.x 规则；getRuleList() 返回旧版规则。返回适合枚举选项的列表，包含规则 ID 和名称。

  实施计划：

  1. 在父应用中添加 import hubitat.helper.RMUtils。
  2. 创建 list_rm_rules MCP 工具。
  3. 同时调用 getRuleList("5.0") 和 getRuleList() 以覆盖所有规则。
  4. 处理规则机器未安装的情况。

• [ ] 启用/禁用 RM 规则 — 难度：2 | 工作量：S

  可行。使用 RMUtils.sendAction(ruleIds, "pauseRule"/"resumeRule", app.label, "5.0")。“暂停”在 RM 术语中相当于“禁用”。

  实施计划：

  1. 创建 control_rm_rule MCP 工具，包含 action 参数。
  2. 支持动作：pause（禁用），resume（启用）。
  3. 首先通过 getRuleList() 验证规则 ID 是否存在。

• [ ] 通过 RMUtils.sendAction() 触发 RM 规则动作 — 难度：2 | 工作量：S

  可行。支持的动作："runRuleAct"（执行动作，跳过条件），"runRule"（评估条件后运行），"stopRuleAct"（取消延迟/重复动作）。注意："runRule" 不适用于规则 4.x+。

  实施计划：

  1. 在 control_rm_rule 工具中添加 run_actions、evaluate、stop_actions。
  2. 内部映射到 RM 动作字符串。
  3. 文档中说明哪些动作适用于哪些 RM 版本。

• [ ] 暂停/恢复 RM 规则 — 难度：2 | 工作量：S

  可行。与启用/禁用机制相同。可以合并到统一的 control_rm_rule 工具中。

• [ ] 设置 RM 私有布尔值 — 难度：2 | 工作量：S

  可行。使用 RMUtils.sendAction(ruleIds, "setRuleBooleanTrue"/"setRuleBooleanFalse", app.label, "5.0")。简单的 API。

  实施计划：

  1. 在 control_rm_rule 工具中添加 set_boolean_true 和 set_boolean_false。
  2. 接受规则 ID 和布尔值，映射到适当的 sendAction 调用。

• [x] 集线器变量桥接，用于跨引擎协调 — 难度：2 | 工作量：S

  已约 90% 实现。现有的 set_variable/get_variable 工具通过 getGlobalConnectorVariable()/setGlobalConnectorVariable() 与 Hubitat 的全局连接器变量一起工作。这些是规则机器读取/写入的相同变量。通过 MCP 设置的变量对 RM 立即可见，反之亦然。为了正式化：文档中说明共享变量应使用集线器连接器变量。