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 立即可見，反之亦然。為了正式化：文檔中說明共享變量應使用集線器連接器變量。