smarthome-port

smarthome-port

smarthome-port は、REST API を通じて Home Assistant のインスタンスと通信します。Home Assistant のすべての要素はエンティティです。たとえば light.kitchen、sensor.temp、switch.porch などです。API もこの形式を反映しており、エンティティの状態の読み取り、ドメインに対するサービスの呼び出し（light.turn_on、switch.toggle）、最近の履歴の確認、コア設定の読み取り、サーバー上での Jinja テンプレートのレンダリング、イベントバスへのイベント送信ができます。smarthome-port は、エンティティとサービスの一覧取得に加えて、これら6つの操作を、コマンドラインインターフェイスと stdio MCP サーバーの両方を提供する1つのバイナリで実行します。

必須の設定は2つで、どちらにも組み込みのデフォルト値はありません。

• HOME_ASSISTANT_URL — インスタンスのベース URL です。例：http://homeassistant.local:8123。末尾のスラッシュは削除されます。
• HOME_ASSISTANT_TOKEN — 長期アクセストークンです（Home Assistant のプロフィールから作成してください）。Authorization: Bearer ヘッダーとして送信され、出力に表示されることはありません。

どちらかの変数が設定されていない場合、リクエストを行う前に、不足している変数名を示すエラーですべての呼び出しが失敗します。

対応しているのは REST API のみです。WebSocket API は実装されていません。

インストール

npx @reneturcios/smarthome-port entities

または、コンテナーイメージを実行します。

docker run -i -e HOME_ASSISTANT_URL -e HOME_ASSISTANT_TOKEN ghcr.io/cloudcorprecords/smarthome-port

コンテナーはデフォルトで MCP サーバーを起動します（下記を参照）。代わりに CLI として使用するには、CLI 引数を渡してください。

CLI

export HOME_ASSISTANT_URL=http://homeassistant.local:8123
export HOME_ASSISTANT_TOKEN=<your long-lived access token>

smarthome-port entities
smarthome-port entities --domain light
smarthome-port state sensor.temp
smarthome-port call light turn_on --entity light.kitchen --data '{"brightness_pct":50}'
smarthome-port services
smarthome-port services --domain light
smarthome-port history sensor.temp --hours 6
smarthome-port config
smarthome-port render "{{ states('sensor.temp') }}"
smarthome-port fire my_event --data '{"device":"kitchen"}'

smarthome-port --version

各コマンドは、上流の JSON ペイロードを出力します（テンプレートのレンダリングでは {"rendered": "..."} を出力します）。終了コード：成功時は 0、呼び出し失敗時（設定不足や API エラーを含む）は 1、使用方法の誤りの場合は 2 です。

MCP サーバー

1つのバイナリで両方の機能を提供します。mcp サブコマンドは stdio MCP サーバーを起動します。

npx -y @reneturcios/smarthome-port mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "smarthome-port": {
      "command": "npx",
      "args": ["-y", "@reneturcios/smarthome-port", "mcp"],
      "env": {
        "HOME_ASSISTANT_URL": "http://homeassistant.local:8123",
        "HOME_ASSISTANT_TOKEN": "..."
      }
    }
  }
}

ツール

ツール	入力	戻り値
list_entities	domain（任意）	エンティティの状態を返します。指定された場合は、クライアント側で1つのドメインに絞り込みます。
get_entity_state	entity_id（必須）	1つのエンティティの完全な状態を返します。
call_service	domain、service（必須）、entity_id、service_data（任意）	サービス呼び出しの結果を返します。service_data は entity_id とマージされます。
list_services	domain（任意）	ドメインごとのサービスを返します。指定された場合は、そのドメインの項目のみを返します。
get_history	entity_id（必須）、hours（任意、デフォルトは24）	現在を終了時刻とする期間内の、エンティティの最近の履歴を返します。
get_config	（なし）	コア設定を返します。
render_template	template（必須）	{"rendered": "..."} を返します。上流からの応答はプレーンテキストです。
fire_event	event_type（必須）、event_data（任意）	上流からの応答を返します。event_data のデフォルト値は {} です。

すべての呼び出しは {HOME_ASSISTANT_URL}/api に送信されます。entity_id にはドット（domain.object_id）が含まれている必要があり、domain、service、event_type は空であってはなりません。いずれもリクエストの前に検証されます。履歴のタイムスタンプはクライアント側で現在時刻から計算されます。HTTP エラーが発生した場合は、ステータスと、Home Assistant が message を返す場合はその内容がエラーとして示されます。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。