Hubitat Local MCP Server

すべての操作は破壊的です。ハブ管理者ツールは、設定でハブ管理者の読み取り/書き込み権限を有効にする必要があります。書き込みツールは3層の安全ゲートを適用します：ハブ管理者の書き込み権限が有効 + 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" }
      ]
    }
  ]
}

MCP設定ファイル（~/.claude.jsonまたはプロジェクトの.mcp.json）に以下を追加します。

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

リモートアクセスの場合は、代わりにHubitat CloudのURLを使用します。

Claude Desktopの設定ファイルに以下を追加します。

• 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はConnectorsを通じてMCPサーバーをサポートしています。

1. claude.aiにアクセスし、Settings > Connectors を選択します。
2. 新しいコネクタを追加し、HubitatのエンドポイントURLを入力します。
3. リモートアクセスの場合はクラウドエンドポイントのURLを使用するか、Cloudflare TunnelのURLを使用します。

Hubitat Cloudを使用すると、どこからでもclaude.aiからスマートホームを制御できます — ローカルのセットアップは必要ありません！

HTTP URLを介してMCPサーバーをサポートする任意のAIサービスは、このサーバーを使用できます。以下のいずれかを使用します。

• Hubitat Cloud URL — Hubitat Cloudのサブスクリプションがあれば、追加のセットアップは必要ありません。
• Cloudflare Tunnel — 無料のセルフホスト型のリモートアクセス用（リモートアクセスオプションを参照）。

Hubitat Cloudのサブスクリプションがある場合：

1. クラウドエンドポイントURLはアプリ内に直接表示されます。
2. そのURLをMCPクライアントの設定に使用します。
3. 追加のセットアップは必要ありません！

Hubitat Cloudのサブスクリプションなしで無料のリモートアクセスを行うには：

1. cloudflaredをインストールします。
2. トンネルを作成します。

   # cloudflared config.yml
   ingress:
     - hostname: hubitat-mcp.yourdomain.com
       service: http://YOUR_HUB_IP:80
     - service: http_status:404
   

3. トンネルのURLを使用します。

   https://hubitat-mcp.yourdomain.com/apps/api/123/mcp?access_token=YOUR_TOKEN
   

1. HubitatのウェブUIでApps > MCP Rule Server を開きます。
2. Hub Admin Accessの下で、以下を切り替えます。
   • Enable Hub Admin Read Tools — 読み取り専用のハブ情報を取得するためのツールを有効にします。
   • Enable Hub Admin Write Tools — バックアップ、再起動、シャットダウン、Z-Wave修復、およびアプリ/ドライバ管理のためのツールを有効にします。
3. ハブにHub Securityが有効になっている場合は、以下も設定します。
   • Hub Security Username と Password をHub Securityセクションで設定します。

すべてのハブ管理者の書き込みツールは、3層の安全ゲートを適用します。

1. ハブ管理者の書き込み権限が設定で有効になっている必要があります。
2. AIは明示的にconfirm=trueを渡す必要があります。
3. 過去24時間以内に完全なハブバックアップが存在する必要があります（自動的に強制されます）。

さらに、既存のアプリ/ドライバを変更または削除するツールは、変更を行う前にアイテムのソースコードを自動的にバックアップします。

update_app_code、update_driver_code、delete_app、またはdelete_driverを使用すると、サーバーは変更を行う前に元のソースコードを自動的に保存します。

• バックアップは.groovyファイルとしてハブのローカルFile Managerに保存されます。
• mcp-backup-app-<id>.groovyまたはmcp-backup-driver-<id>.groovyという名前で保存されます。
• MCPアプリをアンインストールしても保存されます。
• http://<your-hub-ip>/local/<filename>からダウンロードできます。
• 最大20個まで保存され、最も古いものは自動的に削除されます。
• 1時間の保護期間があり、複数回の編集でも編集前の元のコードが保存されます。

MCPを介して復元する方法:

1. list_item_backupsを使用して利用可能なバックアップを確認します。
2. バックアップキーとconfirm=trueを指定してrestore_item_backupを実行します。

手動で復元する方法（MCPを使用しない場合）:

1. HubitatのウェブUIでSettings > File Managerを開きます。
2. バックアップファイル（例：mcp-backup-app-123.groovy）をダウンロードします。
3. Apps Code（またはDrivers Code）を開き、アプリを選択し、ソースコードを貼り付けてSaveをクリックします。

ハブにHub Securityが有効になっている場合（ウェブUIにログインが必要）、MCPサーバーは自動的に認証を処理します。

• アプリの設定でHub Securityのユーザー名とパスワードを設定します。
• サーバーはセッションクッキーを30分間キャッシュします。
• 古いクッキーは自動的に削除され、再認証されます。
• Hub Securityが有効になっていない場合は、資格情報は必要ありません。

• list_devicesでdetailed=trueを指定する場合 — 50以上のデバイスでは遅くなる可能性があります。ページネーションを使用してください：list_devices(detailed=true, limit=25, offset=0)
• 期間トリガー — 最大2時間（7200秒）までです。
• 捕捉された状態 — デフォルトの制限は20個です（設定で1 - 100に設定可能）。
• Hubitat Cloudのレスポンス — 最大128KBです（AWS MQTTの制限）。大規模なデバイスリストではページネーションを使用してください。
• リアルタイムイベントストリーミングはサポートされていません（MCPのレスポンスのみ）。
• 日の出/日没の時間は毎日再計算されます。

アプリの「Select Devices for MCP Access」設定でデバイスが選択されていることを確認してください。

1. Apps Code > MCP Rule Serverを開きます。
2. OAuth > Enable OAuth in Appをクリックします。
3. Saveをクリックします。
4. Appsでアプリを再開いて、新しいトークンを取得します。

• アプリの設定で「Enable Rule Engine」がオンになっていることを確認してください。
• 「Debug Logging」を有効にし、Hubitatのログを確認してください。
• トリガーデバイスがMCPアクセス用に選択されていることを確認してください。
• 期間ベースのトリガーの場合、条件が全期間にわたって真であることを確認してください。

• button_eventトリガータイプを使用していることを確認してください（device_eventではなく）。
• ボタンのアクションタイプ（pushed、held、doubleTapped、またはreleased）を確認してください。

Hubitat Cloudには128KBのレスポンスサイズ制限があります（AWS MQTTの制限）。ページネーションを使用してください。

list_devices(detailed=true, limit=25, offset=0)   // 最初の25個のデバイス
list_devices(detailed=true, limit=25, offset=25)  // 次の25個のデバイス

レスポンスにはtotal、hasMore、およびnextOffsetが含まれており、ページネーションに役立ちます。

バージョン0.1.0では新しい親/子アーキテクチャが使用されています。state.rulesに保存されている古いルールは自動的に移行されません。UIまたはMCPを介してルールを再作成する必要があります。

バグ報告を容易にするには、以下の手順を実行してください。

1. デバッグログレベルを設定します：Settings > MCP Debug Log Level > "Debug"、またはAIにset_log_levelを使用して"debug"に設定させます。
2. 問題を再現します。
3. AIにgenerate_bug_reportツールを使用させます — 診断情報を収集し、提出可能なレポートを作成します。
4. GitHub Issuesで報告を提出します。

将来のアイデア — 以下のすべては予測的なものであり、実現可能性を判断するためにさらなる調査が必要です。これらの機能のいずれも保証されているわけではありません。

ステータスキー: [ ] = 未着手 | [~] = 進行中 / 部分的に完了 | [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式を受け付けます。ユーザーが提供した文字列は検証が必要です。

• [ ] エンドポイント/ウェブフックトリガー — 難易度: 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()を公開していません。2つのアプローチがあります。(A) ポーリング — schedule()を5–10秒ごとに使用して、atomicState内の最後に知られている値と現在の値を比較します。これには遅延とハブの負荷が増えます。(B) 変数コネクタの回避策 — HubitatのVariable Connector機能（ファームウェア ≥ 2.3.4）はハブ変数をデバイス属性として公開し、既存のdevice_eventトリガーを介してサブスクライブできます。オプションBの方がクリーンですが、ユーザーがVariable Connectorデバイスを作成する必要があります。

  実装計画:

  1. 構成可能なポーリング間隔を持つvariable_changeトリガータイプを追加します。
  2. 最後に知られている値をatomicState.variableSnapshotsに保存します。
  3. 各ポーリングサイクルで比較し、変更があればルールを実行します。
  4. Variable Connectorアプローチを推奨する代替案としてドキュメント化します。

• [ ] システム起動トリガー — 難易度: 2 | 作業量: S

  実現可能です。 Hubitatはsubscribe(location, "systemStart", handler)をサポートしています。system_startトリガータイプを追加します。ハブの再起動後、アプリが復元され、initialize() → subscribeToTriggers()が実行され、systemStartイベントがルールをトリガーします。わずかなエッジケース：すべてのアプリが復元される前にイベントが発生する可能性があります — ハードウェアでのテストが必要です。

  実装計画:

  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. ルール構造にconditionsと並行してrequiredExpressions配列を追加します。
  2. ゲートに関連するデバイスイベントを別々にサブスクライブします。
  3. ゲートハンドラーが条件を評価し、偽の場合はすべてのアクティブな遅延をキャンセルします。
  4. 各ルールのすべてのアクティブな遅延IDをatomicState.activeDelayIdsに追跡します。
  5. ルール実行が正常に完了したときにクリーンアップロジックを追加します。

• [ ] 完全なブール式ビルダー（AND/OR/XOR/NOTとネスト） — 難易度: 4 | 作業量: L

  実現可能です。 フラットな条件配列 + conditionLogicトグルを再帰的なツリー構造：{operator: "AND", operands: [...]}に置き換えます。evaluateConditions()をツリーウォーカーとして書き直します。NOTは単一のオペランドをラップし、XORは正確に1つが真であることをチェックします。既存のevaluateCondition()は葉ノードに対してすでにモジュール化されています。主な課題はMCPツールの使いやすさと下位互換性です — フラットな配列形式には移行ロジックが必要です。

  実装計画:

  1. operatorとoperandsフィールドを持つツリーデータ構造を定義します。
  2. 再