smarthome-port

smarthome-port

smarthome-port 通过 Home Assistant 实例的 REST API 与其通信。在 Home Assistant 中，一切都是实体—— light.kitchen、sensor.temp、switch.porch——其 API 也反映了这一结构：读取实体状态、调用某个 domain 上的服务（light.turn_on、switch.toggle）、查看近期历史记录、读取核心配置、在服务器上渲染 Jinja 模板，以及向事件总线触发事件。smarthome-port 通过一个二进制程序提供这六种操作，以及实体和服务列表查询；该程序既提供命令行界面， 也提供 stdio MCP 服务。

必须设置两个配置项，且两者都没有内置默认值：

• 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，调用失败时为 1（包括缺少配置或 API 错误），用法错误时为 2。

MCP 服务

一个二进制程序同时提供两种使用方式。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（可选）	实体状态；如果提供 domain，则在客户端筛选出该 domain 的实体。
get_entity_state	entity_id（必需）	单个实体的完整状态。
call_service	domain、service（必需），entity_id、service_data（可选）	服务调用结果；service_data 会与 entity_id 合并。
list_services	domain（可选）	按 domain 列出服务；如果提供 domain，则只返回该 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。