Homebridge

@mp-consulting/homebridge-ai-kit

Homebridge 用の AI ツールキットを 1 つのパッケージにまとめています。

• MCP サーバー：AI アシスタント（Claude Desktop、Claude Code、Cursor）から、stdio または Streamable HTTP を介してアクセサリーの操作、プラグインの管理、設定の編集、ログの読み取りができます。
• アシスタント：プロバイダーアダプター（Claude、OpenAI、Gemini、および OpenAI 互換サーバー）、MCP ツールと連携するエージェントループ、すぐに使える機能（ログ診断、設定コパイロット、デバイスエラーの解説、アップデートリスクの概要、整理機能、日次ダイジェスト）を備えています。Homebridge Glass UI と MP Consulting のプラグインで使用されます。
• Homebridge プラグイン（HomebridgeAiKit プラットフォーム）：プロバイダーとモデルの選択、接続テスト、HTTP 経由の MCP 配信、クライアント設定の生成ができる設定ページを備えています。

MCP を必要としない AI の構成要素は、@mp-consulting/homebridge-ai-core として単独でも提供されています。詳細はパッケージをご覧ください。

@mp-consulting/homebridge-mcp-server から名称が変更されました。 以前の homebridge-mcp-server コマンドも引き続き動作するため、既存の MCP クライアント設定を変更する必要はありません。homebridge-mcp-server からの移行をご覧ください。

目次

• パッケージ
• 機能
• プロバイダー
• Homebridge プラグイン · MCP トークン
• MCP サーバー
• ライブラリー API
• セキュリティ
• homebridge-mcp-server からの移行
• 開発

パッケージ

このリポジトリは npm ワークスペースであり、バージョン 2.0.0 の 2 つのパッケージを公開しています。

パッケージ	用途	実行時の依存関係
@mp-consulting/homebridge-ai-core	Homebridge プラグイン向け。 プラグイン UI のアシスタントルート（./plugin の registerAiRoutes）、プロバイダー、秘匿化、プロンプト、設定、アシスタント機能（runAgent を除くすべて）。	ajv のみ
@mp-consulting/homebridge-ai-kit（このパッケージ）	Homebridge Glass UI と MCP 向け。 ai-core のすべて（再エクスポート）に加え、MCP サーバー、runAgent、HomebridgeAiKit Homebridge プラグイン、mcpClientSnippets を含みます。	ai-core、@modelcontextprotocol/sdk、socket.io-client、zod、undici、@homebridge/plugin-ui-utils

プラグインでは ai-core に依存するようにしてください。そうすることで、インストール時に MCP SDK、socket.io、zod が追加で取り込まれることはありません。ai-kit は後方互換性を維持しています。. と ./plugin のエクスポートは ai-core のすべてを同じ名前で再エクスポートするため、ai-kit からインポートするコードは引き続き動作します。

機能

MCP ツール（43 個）：アクセサリ（一覧表示、取得、値を検証して制御、dryRun による一括制御、確認が必要なロック／ガレージドア／アラーム、部屋のレイアウト、センサー履歴）、シーン（一覧表示、実行、保存）、サーバー（状態、再起動、ペアリング、キャッシュされたアクセサリ）、子ブリッジ（一覧表示、ヘルスチェック、再起動、停止、起動）、設定（シークレットを伏せて読み取り、全体書き込み、部分的な patch_config、dryRun 差分、バックアップと復元）、インスタンスのバックアップ、テスト通知、プラグイン（一覧表示、検索、バージョン、スキーマ、変更履歴、インストール、更新、アンインストール）、システム情報とログ（直近の行、フィルター付き正規表現検索）。

購読できるMCP リソース：homebridge://accessories、homebridge://logs/recent、homebridge://status。変更は Homebridge UI の socket.io 名前空間経由で通知されます。ソケットを使用できない場合はポーリングされます。

補完機能付きで resources/list に掲載されるMCP リソーステンプレート：homebridge://accessory/{uniqueId}（特性をすべて含む 1 つのアクセサリ）、homebridge://plugin/{name}（インストール済みプラグイン 1 つとその子ブリッジ。スコープ付きの名前は URL エンコードしてください）、homebridge://child-bridge/{id}（ユーザー名で指定する 1 つの子ブリッジと、Glass UI 上のヘルス情報）。

MCP プロンプト：diagnose-logs、plan-upgrade、audit-config、troubleshoot-device（device、symptom?）、nightly-health-check（hours?）、scene-builder（description、room?）。

アシスタント機能（ライブラリ）：diagnoseLogs、generatePluginConfig、explainDeviceError、assessPluginUpdate、suggestOrganization、dailyDigest、ask、およびツールが必要なあらゆる処理に対応する runAgent。入力はすべてプロバイダーに送信される前に秘匿化され、コンテキストウィンドウに収まるよう短縮されます。JSON 出力はスキーマに照らして検証され、自動修復を 1 回試みます。トークン使用量と Claude の料金も追跡されます。

プロバイダー

すべてのプロバイダーはプレーンな fetch を使用します（SDK は使用しません）。それぞれが対応機能を宣言し、ツール呼び出しに対応しない機能はプロンプトのみの回答にフォールバックします。

provider	デフォルトモデル	API キー	ツール	ストリーミング	コンテキスト
anthropic	claude-sonnet-5-5	必須	対応	対応	1M（Haiku は 200K）
openai	gpt-6.1-sol	必須	対応	対応	128K（増やすには contextTokens を設定）
gemini	gemini-3.8-flash	必須	対応	対応	1M
openai-compatible	llama3.1	任意	対応	対応	8K（contextTokens を設定）

• Claude モデル：claude-sonnet-5-5（デフォルト）、claude-haiku-4-5-20251001（最も安価）、claude-opus-5-5（最も高性能）。
• OpenAI モデル：gpt-6.1-sol（デフォルト）、gpt-6-luna（最も安価）、gpt-6-astra（最も高性能）。リクエストには Responses API を使用し、store: false を指定します（OpenAI 側には何も保存されません）。新しいモデルはこの API 経由でのみツールを呼び出します。代わりに Chat Completions を使うには、たとえばその API のみに対応するプロキシを使用する場合に、"openaiApi": "chat" を設定してください。
• openai-compatible は Ollama（デフォルトの http://127.0.0.1:11434/v1）、LM Studio（http://127.0.0.1:1234/v1）、vLLM などに対応します。入力が正しく短縮されるように、モデルのコンテキストウィンドウに合わせて contextTokens を設定してください。
• デバイス上で動作する Apple Foundation Models プロバイダーを予定しています。

Homebridge プラグイン

他のプラグインと同様にインストールしてください（Homebridge 1.8+ または 2.x）：

npm install -g @mp-consulting/homebridge-ai-kit

次に、Homebridge UI で設定を開きます。設定ページでは HomebridgeAiKit プラットフォームブロックを編集し、フォームに入力した値で接続をテストし、Claude Desktop、Claude Code、Cursor にそのまま貼り付けられる設定を表示します。

{
  "platform": "HomebridgeAiKit",
  "name": "AI Kit",
  "enabled": true,
  "provider": "anthropic",            // anthropic | openai | gemini | openai-compatible
  "model": "claude-sonnet-5-5",       // optional, defaults per provider
  "apiKey": "sk-ant-…",               // secret, redacted wherever config is shown to a model
  "baseUrl": "http://127.0.0.1:11434/v1", // openai-compatible only (or a proxy)
  "contextTokens": 32768,             // optional override, mainly for local models
  "maxOutputTokens": 2048,
  "effort": "medium",                 // Claude and OpenAI: low | medium | high | xhigh | max (unset = model default)
  "openaiApi": "responses",           // openai / openai-compatible: responses | chat (default responses for OpenAI, chat for local servers)
  "maxRetries": 2,                    // retries on 408/429/5xx/529 and network errors (backoff, honours retry-after); 0 = off
  "mcp": {
    "http": {
      "enabled": false,
      "host": "127.0.0.1",
      "port": 8582,
      "token": "…",                   // bearer token MCP clients must send
      "homebridgeUrl": "http://127.0.0.1:8581",
      "homebridgeToken": "hbg_…",     // Glass UI API token the tools act with
      "homebridgeTokenId": "…",       // written by Glass UI so it can revoke that token; leave as is
      "homebridgeCertFingerprint": "AB:CD:…", // https UI with a self-signed certificate: its SHA-256 fingerprint
      "homebridgeCertPath": "/path/to/certificate.pem", // or a PEM with the UI's certificate or its CA
      "readOnly": false,              // true caps every client token at read-only
      "clients": [                    // more client tokens, each with a scope: read | control | admin
        { "name": "Dashboard", "token": "…", "scope": "read" }
      ],
      "allowedOrigins": ["https://my-dashboard.local"], // browser pages allowed besides localhost / this server's IP
      "auditLog": true,               // log every write tool call (JSONL)
      "auditLogPath": "/var/lib/homebridge/homebridge-ai-kit-audit.jsonl" // default: Homebridge storage path
    }
  }
}

mcp.http.enabled を有効にすると、Homebridge の実行中にプラグインが http://<host>:<port>/mcp で MCP を提供します。クライアントトークン（mcp.http.token、HOMEBRIDGE_AI_MCP_TOKEN、または mcp.http.clients に少なくとも 1 つのスコープ付きトークン）と、Homebridge の認証情報が必要です。認証情報には homebridgeToken の Glass UI API トークン、または HOMEBRIDGE_* 環境変数を使用できます。読み取り専用の API トークンを使うと、クライアントは読み取り専用でアクセスできます。

MCP トークン

MCP サーバーは、2 種類のトークンを使用します。

トークン	用途	保存先
クライアントトークン	HTTP MCP サーバーに接続するため、Claude、Cursor などの MCP クライアントが送信する必要のあるトークンです（Authorization: Bearer …）。フルアクセス（admin）または mcp.http.readOnly による読み取り専用アクセス	mcp.http.token（CLI の場合は HOMEBRIDGE_AI_MCP_TOKEN）
スコープ付きクライアントトークン	アクセス権を絞った追加のクライアントトークンです。たとえば、ダッシュボード用の読み取り専用トークンなどです（任意）	mcp.http.clients（CLI の場合は HOMEBRIDGE_AI_MCP_TOKENS）
Homebridge API トークン	MCP サーバーが Homebridge UI に送信して、ツールを実行するためのトークンです。スコープによってクライアントに許可される操作が決まります。read では読み取り専用ツール、admin ではすべてのツールを使用できます	mcp.http.homebridgeToken（CLI の場合は HOMEBRIDGE_TOKEN）

設定または生成する場所：

• Homebridge Glass UI 2.0.0-beta.6 以降： Settings → Assistant → MCP server でクライアントトークンを生成し、Homebridge API トークンをワンクリックで作成できます（読み取り専用または admin。置き換えまたは削除すると再び取り消されます）。また、クライアント設定も表示されます。各シークレットが表示されるのは一度だけです。その後、このページには設定済みかどうかのみが表示されます。
• このプラグインの設定ページ： Generate でクライアントトークンを生成します。Glass UI の Users → API Tokens で作成した Homebridge API トークンを貼り付けてください。
• CLI： HOMEBRIDGE_AI_MCP_TOKEN と HOMEBRIDGE_TOKEN を設定します（MCP サーバーを参照）。例：HOMEBRIDGE_AI_MCP_TOKEN=$(openssl rand -base64 24)。

クライアントトークンのスコープ（それぞれ、前のスコープに含まれる権限も含みます）：

スコープ	ツール
read	すべての読み取り専用ツール
control	さらに、デバイス制御：set_accessory、set_security_accessory（ロックには引き続きユーザーの確認が必要です）、set_accessories、run_scene
admin	さらに、その他すべて：設定の書き込みと復元、バックアップ、save_scene、テスト通知、プラグインのインストールと更新、再起動、キャッシュされたアクセサリ、子ブリッジ

メインのクライアントトークンは admin（従来どおり）です。readOnly が有効な場合は read になります。readOnly はスコープ付きトークンにも上限を設けます。セッションは、そのセッションを開始したトークンに属します。クライアントトークンによってクライアントに表示されるツールが決まりますが、Homebridge API トークンによってサーバー自体が実行できる操作も制限されます。そのため、read API トークンを使うと、すべてが読み取り専用になります。

すべての書き込みツール呼び出しは監査ログに追記されます（デフォルトでは <Homebridge storage>/homebridge-ai-kit-audit.jsonl。mcp.http.auditLog / auditLogPath、または CLI の場合は HOMEBRIDGE_AI_AUDIT_LOG）：1 行につき 1 つの JSON オブジェクトが記録され、ts、tool、args（シークレットはマスキングされます）、ok、error、session、client、principal（トークン名。メイントークンは default、runAgent は agent）、scope が含まれます。notConfirmed: true は、ユーザーが拒否した破壊的な呼び出し（MCP のエリシテーション、または runAgent の confirm）を示します。この場合、呼び出しは実行されません。ドライランも記録され、その場合は args に dryRun: true が含まれます。runAgent では同じ audit オプションを指定できます。ログは 5 MB でローテーションし、古いファイルを 3 つ保持します。

Glass UI は、作成した API トークンの ID である homebridgeTokenId も保存します。これにより、トークンを置き換えたり削除したりしたときに取り消せます。設定ページは保存時に、このフィールド（および表示されないその他のフィールド）を保持します。

自己署名証明書を使った HTTPS の Homebridge UI

Node は自己署名証明書を拒否するため、信頼する証明書を指定するまで、その方法で提供されている Homebridge UI に MCP サーバーが接続できません。証明書の検証が無効になることはありません。この設定は、Homebridge UI へのサーバーのリクエストにのみ適用されます。

設定	CLI	信頼する対象
mcp.http.homebridgeCertFingerprint	HOMEBRIDGE_CERT_FINGERPRINT	この SHA-256 フィンガープリントと完全に一致する証明書のみ（ピン留め）。フィンガープリントが異なる証明書は、有効な証明書であっても拒否され、両方のフィンガープリントを示すエラーが表示されます。
mcp.http.homebridgeCertPath	HOMEBRIDGE_CERT_PATH	この PEM ファイル内の証明書を、パブリック CA に加えて信頼します。UI 自身の自己署名証明書（127.0.0.1 など、任意のホスト名で受け入れられます）、または証明書を発行した CA（通常のホスト名チェックが行われます）を指定できます。

Homebridge マシンで openssl x509 -noout -fingerprint -sha256 -in <certificate.pem> を実行するとフィンガープリントを確認できます（Glass UI の自己署名証明書は <storage>/ssl-certs/certificate.pem にあります）。コロンの有無と大文字・小文字は区別されません。両方を設定した場合、チェーンが PEM に対して検証され、証明書がフィンガープリントと一致する必要があります。証明書を更新したら、フィンガープリントも更新してください。どちらの設定も https URL にのみ適用されます。socket.io 接続では Node のデフォルトの検証が維持されるため、リソースのサブスクリプションはポーリングによって変更を追跡します。

mcp.http の変更を適用するには、Homebridge を再起動してください。プラグインの読み込み時に HTTP サーバーが起動するためです。両方のトークンはパスワードと同様に扱ってください。クライアントトークンを持つ人は誰でも、Homebridge API トークンで許可されているすべてのツールを使用できます。

他のプラグイン向けアシスタントルート

プラグインのカスタム UI サーバーでは、1 回の呼び出しでアシスタントを利用できます。@mp-consulting/homebridge-ai-core/plugin からルートをインポートしてください（ai-kit の ./plugin からも再エクスポートされますが、プラグインはより軽量な ai-core に依存するようにしてください）。ブラウザー側では @mp-consulting/homebridge-ui-kit の MpKit.ai を使用します。

// homebridge-ui/server.js
import { HomebridgePluginUiServer } from '@homebridge/plugin-ui-utils';
import { registerAiRoutes } from '@mp-consulting/homebridge-ai-core/plugin';

class UiServer extends HomebridgePluginUiServer {
  constructor() {
    super();
    registerAiRoutes(this, { pluginName: '@mp-consulting/homebridge-ewelink' });
    this.ready();
  }
}
new UiServer();

ルート	本文	結果
/ai/status	なし	{ enabled, provider, model, capabilities }（キーは含まれません）
/ai/explain	{ error, context?, device?, requestId? }	{ text, usage }
/ai/ask	{ prompt, context?, requestId? }	{ text, usage }
/ai/config	{ schema, request, current?, requestId? }	{ config, explanation, usage }

requestId が指定されている場合、サーバーは ai:chunk { requestId, delta } イベントをストリーミングし、その後 ai:done { requestId } または ai:error { requestId, message } を送信します。ルートはリクエストごとに config.json から HomebridgeAiKit ブロックを読み込むため、設定の変更はすぐに反映されます。

MCP サーバー

インストール

方法	対象
最新リリースの homebridge-ai-kit-x.y.z.mcpb	Claude アプリ：ダブルクリックして拡張機能としてインストールし、Homebridge UI の URL とトークン（またはユーザー名とパスワード）を入力します。Node も設定ファイルも必要ありません。
brew install mp-consulting/tap/homebridge-ai-kit	macOS / Linux で homebridge-ai-kit コマンドを使えます。Homebrew によって最新の状態に保たれます。
npx -y @mp-consulting/homebridge-ai-kit mcp	インストール不要で、あらゆる MCP クライアントから利用できます（以下の設定を参照してください）。

このサーバーは、MCP レジストリ（https://registry.modelcontextprotocol.io）にも io.github.mp-consulting/homebridge-ai-kit として登録されています。

環境

変数	説明
HOMEBRIDGE_URL	Homebridge UI の URL。例：http://192.168.1.100:8581（必須）
HOMEBRIDGE_TOKEN	Homebridge UI API トークン（Glass UI hbg_…）。ユーザー名とパスワードの代わりに使用します
HOMEBRIDGE_USERNAME / HOMEBRIDGE_PASSWORD	トークンが設定されていない場合に使用する UI ログイン情報
HOMEBRIDGE_READ_ONLY	true にすると、変更を行うすべてのツールが削除されます
HOMEBRIDGE_ELICITATION	false にすると、破壊的なツールの実行前にユーザーへ確認を求める（MCP elicitation）機能を停止します。デフォルトでは有効です。elicitation に対応していないクライアントには影響しません
HOMEBRIDGE_ALLOW_SECRETS	true にすると、要求時（includeSecrets）に get_config が実際のパスワードとトークンを返します。デフォルトでは無効です。読み取り専用モードでは無視されます
HOMEBRIDGE_TIMEOUT_MS	リクエストのタイムアウト（デフォルトは 30000）
HOMEBRIDGE_CERT_FINGERPRINT	信頼する（ピン留めする）https Homebridge UI の自己署名証明書の SHA-256 フィンガープリント。自己署名証明書を参照してください
HOMEBRIDGE_CERT_PATH	信頼する https Homebridge UI の証明書または CA を含む PEM ファイル
HOMEBRIDGE_AI_MCP_TOKEN	--http で必要なベアラートークン（フルアクセス、または HOMEBRIDGE_READ_ONLY による読み取り専用）
HOMEBRIDGE_AI_MCP_TOKENS	--http：スコープ付きの追加トークン。scope:token のペアをカンマ区切りで指定します。例：read:abc,control:def
HOMEBRIDGE_AI_AUDIT_LOG	書き込みツール呼び出しの JSONL 監査ログのパス（CLI ではデフォルトで無効）
HOMEBRIDGE_AI_MCP_ALLOWED_ORIGINS	--http：ループバックとサーバー自身の IP に加えて許可するブラウザーのオリジンをカンマ区切りで指定します（すべて許可する場合は *）
HOMEBRIDGE_AI_MCP_MAX_SESSIONS	--http：同時セッションの最大数（デフォルトは 32。空きを作るため、最も長く使用されていないアイドル状態のセッションが閉じられます）
HOMEBRIDGE_AI_MCP_SESSION_IDLE_MINUTES	--http：リクエストがない状態がこの時間続くとセッションを閉じます（デフォルトは 30）

stdio（Claude Desktop、Claude Code、Cursor）

{
  "mcpServers": {
    "homebridge": {
      "command": "npx",
      "args": ["-y", "@mp-consulting/homebridge-ai-kit", "mcp"],
      "env": {
        "HOMEBRIDGE_URL": "http://192.168.1.100:8581",
        "HOMEBRIDGE_TOKEN": "hbg_…"
      }
    }
  }
}

claude mcp add homebridge -e HOMEBRIDGE_URL=http://192.168.1.100:8581 -e HOMEBRIDGE_TOKEN=hbg_… -- npx -y @mp-consulting/homebridge-ai-kit mcp

Streamable HTTP

HOMEBRIDGE_AI_MCP_TOKEN=$(openssl rand -base64 24) \
HOMEBRIDGE_URL=http://127.0.0.1:8581 HOMEBRIDGE_TOKEN=hbg_… \
homebridge-ai-kit mcp --http --port 8582 --host 127.0.0.1

エンドポイントは http://127.0.0.1:8582/mcp です。すべてのリクエストに Authorization: Bearer <HOMEBRIDGE_AI_MCP_TOKEN> が必要です。デフォルトでは 127.0.0.1 にバインドされます。信頼できるネットワーク上でのみ --host 0.0.0.0 を使用し、できれば HTTPS の背後に配置してください。

• オリジンチェック。 MCP 仕様の要件に従い、Origin ヘッダー（つまり Web ページからのリクエスト）があるリクエストは、オリジンがループバック（http://localhost:…、127.0.0.1、[::1]）、サーバー自身の IP アドレス、または HOMEBRIDGE_AI_MCP_ALLOWED_ORIGINS（プラグイン：mcp.http.allowedOrigins）に含まれていない限り、403 で拒否されます。これにより、悪意のあるページが DNS リバインディングを通じてサーバーにアクセスするのを防ぎます。デスクトップクライアントは Origin を送信しないため、影響を受けません。
• セッションは 30 分間アイドル状態が続くと閉じられ、開いたままにできるのは最大 32 件です。ストリームが開いているセッションはアイドル状態になりません。resources/subscribe 用の Homebridge 変更フィードは、すべてのセッションで共有されます。
• 無効なトークン。 1 つのアドレスから誤ったトークンが 5 回送信されると、再試行まで待機する必要があります（Retry-After を伴う 429 が返され、待機時間は最大 5 分まで倍増します）。正しいトークンを使用するとカウントはリセットされます。

claude mcp add --transport http homebridge http://127.0.0.1:8582/mcp --header "Authorization: Bearer <token>"

ツール

グループ	ツール
アクセサリ	list_accessories（room、type、name、manufacturer、excludeManufacturer で絞り込み）、get_accessory、set_accessory、set_security_accessory（ロック、ガレージドア、アラーム。破壊的な操作のため、確認が必要です）、set_accessories（ID またはフィルターで複数の対象を指定し、dryRun に対応。ロック、ドア、アラームは対象外です）、get_accessory_layout、get_accessory_history
サーバー	get_homebridge_status、get_server_status、restart_homebridge、get_pairing_info、get_cached_accessories、remove_cached_accessory、reset_cached_accessories
子ブリッジ	list_child_bridges、get_child_bridge_health*、restart_child_bridge、stop_child_bridge、start_child_bridge
シーン*	list_scenes、run_scene（ID または名前で指定。ロック、ガレージドア、アラームに影響するシーンは実行されません）、save_scene（選択したアクセサリの現在の状態を保存。ロック、ドア、アラームは保存対象外です）
通知*	send_test_notification
設定	get_config、update_config、patch_config（どちらも編集内容を伏せ字にした差分を表示する dryRun に対応。各書き込みでは、その操作を取り消すバックアップ名が示されます）、list_config_backups、restore_config
バックアップ	create_backup、list_backups（UI のバックアップディレクトリに保存されたインスタンス全体のバックアップ）
プラグイン	list_plugins、search_plugins、lookup_plugin、get_plugin_versions、get_plugin_config_schema、get_plugin_changelog、install_plugin、update_plugin、uninstall_plugin、get_plugin_job
システム	get_system_info（CPU 負荷と温度、メモリ、ネットワークスループット、稼働時間）
ログ	get_recent_logs、search_logs（since／until、最低 level、plugin のプレフィックスで絞り込み。一致箇所の前後の context 行を表示）

* Homebridge Glass UI が必要です。別の Homebridge UI を使用している場合、これらのツールはその旨を示すエラーを返します。

• リスト／取得ツール（list_accessories、get_accessory、list_plugins、list_child_bridges、get_child_bridge_health、get_homebridge_status、get_server_status、search_logs、list_scenes）も、outputSchema に一致する structuredContent を返します。
• set_accessory は値を特性に照らして検証してから設定します（形式、最小値／最大値、ステップ、有効な値、書き込み権限）。"50" を 50 に、1 を true に変換し、不正な値を送信する代わりに問題点を説明します。
• ロック、ガレージドア、防犯システム（LockTargetState、TargetDoorState、SecuritySystemTargetState、または LockMechanism、GarageDoorOpener、SecuritySystem サービスの任意の特性）は、set_accessory では拒否されます。これらの操作には set_security_accessory を使用します。このツールには destructiveHint: true の注釈が付いているため、MCP クライアントと runAgent は、ロック解除、開扉、警戒解除の前にユーザーへ確認を求めます。ライトやスイッチは、確認なしで引き続き操作できます。
• get_accessory_history は、過去 hours 時間（デフォルトは24時間、最大8760時間）のアクセサリに記録されたセンサー値（温度、湿度、照度、バッテリー、空気質、電力、エネルギー）を返します。オプションで、特性の type を1つ指定できます。系列ごとに count、min／max（値とその時刻）、時間加重 avg、last、および maxPoints（デフォルト48、2～500）に平均化された points が返されます。時刻はUTCで、分単位です。Homebridge Glass UI（GET /api/accessories/:uniqueId/history）が必要です。この機能は、Homebridge が非セキュアモードで実行されている間に値を記録します。
• patch_config は、platform／accessory と name を基準に特定したプラットフォームまたはアクセサリのブロックを1つ変更します。オブジェクトはマージされ、null はキーを削除し、__REDACTED__ は現在のシークレットを維持します。
• install_plugin、update_plugin、uninstall_plugin は Homebridge UI でジョブを開始し、最大2分間完了を待ちます。さらに時間がかかる場合は get_plugin_job で追跡できます。Homebridge Glass UI（POST /api/plugins/install|update|uninstall、GET /api/plugins/jobs/:id）が必要です。
• ログツールを使用するには、hb-service で管理されている Homebridge のインストールが必要です。

ライブラリ API

import {
  createProvider, readAiConfig, runAgent, diagnoseLogs, generatePluginConfig, UsageTracker,
} from '@mp-consulting/homebridge-ai-kit';
import { HomebridgeClient } from '@mp-consulting/homebridge-ai-kit/mcp';

const config = await readAiConfig();            // HomebridgeAiKit block of ~/.homebridge/config.json
const provider = createProvider(config);

// One-shot feature, streamed
const { text } = await diagnoseLogs({ provider, logs, onChunk: (d) => process.stdout.write(d) });

// Agent with the MCP tools, acting as the current user
const client = new HomebridgeClient({ url: 'http://127.0.0.1:8581', getToken: () => mintShortLivedToken(user) });
const result = await runAgent({
  provider,
  client,
  messages: [{ role: 'user', content: 'Turn off every light downstairs' }],
  confirm: async (call) => askUser(`Allow ${call.name}?`), // destructive tools are refused without it
  onEvent: (e) => console.log(e),
});

エクスポート	用途
createProvider(config) → AiProvider	ChatRequest { system?, messages, tools?, maxOutputTokens?, signal? } を受け取る chat(req) と stream(req)
runAgent(opts) → AgentResult	モデルと MCP ツール間をループします（インメモリトランスポート）。maxSteps のデフォルトは 8 です。破壊的なツールには readOnly と confirm を使用します
diagnoseLogs, generatePluginConfig, explainDeviceError, assessPluginUpdate, suggestOrganization, dailyDigest, ask	すぐに使える機能です。すべて onChunk、signal、systemContext を受け取ります
generateJson({ provider, schema, prompt })	スキーマ検証済みの JSON（ajv）を生成し、修復を 1 回再試行します
trimToContext, estimateTokens	入力をコンテキストウィンドウ内に収めます（ログは末尾を残します）
UsageTracker, costOf	トークン数とコストを計算します（Claude の料金を使用。不明なモデルのコストは null です）
PROMPTS	MCP のプロンプトと共有するプロンプトテンプレート
readAiConfig, resolveAiConfig	HomebridgeAiKit ブロックを読み取り、デフォルト値を設定します
redactSecrets, restoreSecrets, redactText, redactPairing	認証情報とペアリングコードがモデルのコンテキストに含まれないようにします
SlidingWindowRateLimiter, TtlCache, withConfirmTimeout, ConfirmationBroker, readLogTail, stripAnsi	サーバーヘルパー：ユーザーごとのレート制限、有効期限付きキャッシュ、タイムアウト付き確認、ログの末尾

この表の runAgent 以外のすべては @mp-consulting/homebridge-ai-core から提供され、変更せずに再エクスポートされます。

./mcp は createServer、HomebridgeClient、runStdioServer、runHttpServer、createLiveSource、shareLiveSource、createAuditLog、トークン SCOPES、および TLS ピンニングヘルパー createTrustedFetch、normalizeFingerprint、pemFingerprints をエクスポートします。./plugin は registerAiRoutes と testAiConnection（ai-core の ./plugin から）、mcpClientSnippets、AiKitPlatform をエクスポートします。

セキュリティ

• シークレットはモデルのコンテキストに含まれません。 get_config、patch_config、アシスタント機能では、パスワード、トークン、API キー（AI Kit の apiKey と MCP トークンを含む）、ブリッジの PIN が __REDACTED__ に置き換えられます。書き込み時には、プレースホルダーが実際の値に戻されます。get_config の includeSecrets は、サーバーが HOMEBRIDGE_ALLOW_SECRETS=true（createServer／runHttpServer の場合は allowSecrets）で明示的に許可した場合にのみ使用でき、読み取り専用モードでは利用できません。プロバイダーに送信されるフリーテキスト（ログ、エラー）内の認証情報らしき値もマスキングされます。
• 破壊的な操作には同意が必要です。 すべてのツールで MCP の readOnlyHint／destructiveHint が宣言されており、runAgent は confirm コールバックが許可しない限り、破壊的なツールの実行を拒否します。MCP クライアントがエリシテーションに対応している場合、サーバー自体が破壊的なツール呼び出しごとにユーザーへ確認を求めます（引数はシークレットをマスキングして表示されます。ドライランでは確認を省略します。確認が拒否された場合、または確認に失敗した場合、ツールは実行されません）。HOMEBRIDGE_ELICITATION=false を設定すると、これを無効にできます。ドアの解錠、ガレージドアの開放、アラームの解除は、破壊的な set_security_accessory を通じてのみ実行できるため、これらも確認が必要です。set_accessories とシーンでは、これらの対象への操作が拒否されます。設定の書き込みは dryRun で事前確認でき、restore_config でロールバックできます。HOMEBRIDGE_READ_ONLY=true を設定すると、書き込みツールがすべて無効になります。
• ツールの出力はデータとして扱われます。 ログ（ツールおよび homebridge://logs/recent リソース）、変更履歴、その他 Homebridge 由来のフリーテキストは、<untrusted-data source="…"> タグで囲んで返されます（runAgent はモデルに送信するすべてのツール結果をタグで囲みます）。データ内に含まれるタグは無害化されます（JSON の結果と structuredContent は解析できるよう、通常のデータのままです）。また、基本システムプロンプトでは、ツールの出力に含まれる指示には従わず、ユーザーから依頼された場合にのみ変更を行うようモデルに指示します。破壊的なツールに確認を求める仕組みと組み合わせることで、「玄関のドアを解錠して」というログの行がドアを開けることはありません。
• HTTP は保護されています。 HTTP トランスポートではベアラートークンが必須で、トークンは定時間比較で照合され、デフォルトでは 127.0.0.1 にバインドされます。Origin を確認し、アイドル状態のセッションを期限切れにし、無効なトークンが繰り返し送信された場合は応答を遅らせます。
• 最小権限と監査証跡。 追加のクライアントトークンには read または control の権限を設定できます。また、すべての書き込みツール呼び出しは、引数をマスキングして記録されます（MCP トークンを参照）。
• update_config は不完全な設定を拒否します。また、正規表現によるログ検索はワーカースレッドで実行され、5 秒後に終了します。
• HOMEBRIDGE_URL が認証情報を平文の http で非ローカルホストに送信する場合、サーバーは警告を表示します。
• TLS 検証は常に有効です。 自己署名の Homebridge UI 証明書は、HOMEBRIDGE_CERT_FINGERPRINT／HOMEBRIDGE_CERT_PATH（または対応する mcp.http 設定）を通じてのみ信頼され、Homebridge UI へのリクエストに対してのみ適用されます。一致しない証明書は拒否されます。

homebridge-mcp-server からの移行

npm uninstall -g @mp-consulting/homebridge-mcp-server
npm install -g @mp-consulting/homebridge-ai-kit

このパッケージは homebridge-ai-kit と homebridge-mcp-server のエイリアスの両方をインストールします。また、環境変数も変更されないため、既存の設定はそのまま機能します。新しい設定では homebridge-ai-kit mcp を使用してください。MCP サーバーは名前を homebridge-ai-kit として報告するようになりました。また、ライブラリのユーザーは @mp-consulting/homebridge-ai-kit/mcp から createServer と HomebridgeClient をインポートします。

開発

git clone https://github.com/mp-consulting/homebridge-ai-kit.git
cd homebridge-ai-kit
npm install
npm run build          # builds packages/ai-core, copies the ui-kit assets into homebridge-ui/public/lib, then tsc

このリポジトリは npm ワークスペースです。ルートは ai-kit、packages/ai-core は ai-core です。ルートのスクリプトは両方のパッケージを実行します（先に ai-core）。npm run <script> -w packages/ai-core を実行すると、ai-core のスクリプトだけを実行できます。ai-kit のテストでは @mp-consulting/homebridge-ai-core をソースに解決しますが、typecheck と build では ai-core の dist を使用するため、先にビルドします。

npm run dev            # MCP server on stdio with tsx
npm test               # Run tests
npm run test:coverage  # Tests with coverage thresholds (as CI does)
npm run lint           # ESLint
npm run typecheck      # Type-check src and test (both packages)

公開。 リリースワークフローでは、まず @mp-consulting/homebridge-ai-core を公開します（そのバージョンがすでに npm にある場合はスキップ）。次に、それに依存する @mp-consulting/homebridge-ai-kit を公開します。どちらも npm の信頼された公開（OIDC）を使用します。最初のリリース前に、新しい @mp-consulting/homebridge-ai-core のパッケージ名についても、npmjs.com で信頼されたパブリッシャーを設定してください（リポジトリ mp-consulting/homebridge-ai-kit、ワークフロー publish.yml）。既存のパッケージにしか追加できない場合は、packages/ai-core から ai-core 2.0.0 を一度手動で公開してください。ai-kit 2.0.0 を npm からインストールできるようにするには、先に ai-core の初回リリースを公開する必要があります。

npm への公開後、同じワークフローで scripts/make-mcpb.sh を使って Claude 拡張機能をビルドします（マニフェストのテンプレートは mcpb/manifest.json、ツール一覧は scripts/mcpb-tools.mjs から取得します）。DEVELOPER_ID_CERTIFICATE と DEVELOPER_ID_CERTIFICATE_PASSWORD のシークレットが設定されている場合は mcpb sign で署名し、リリースに添付して、server.json を MCP レジストリに公開します（GitHub OIDC）。mp-consulting/homebrew-tap の Homebrew フォーミュラは、npm の各バージョンを自動で取得します（6 時間ごと）。

ライセンス

MIT