automation-access-broker

Automation MCP access broker: tiered, human-gated access to Home Assistant entities, on the access-broker suite architecture (see AUTHORS.md for provenance). Formerly smarthome-access-broker; the product renamed to automation-access-broker (2026-09-21 decision: the domain's invariant is an access that ends in a physical change, automated for the user).

What it is

One MCP server brokering an AI agent's access to a Home Assistant instance: the agent sees the house freely, adjusts reversible comfort freely, and touches locks, alarm panels, covers, and climate setpoints only through per-operation human approvals (Matrix reactions), with admin functions gated and never delegated. Built on access-broker-core (grant lifecycle, hash-chained write-before-operate audit, tier mechanics, approval-gateway core); this broker contributes the smart home wall (entity/class scoping), the Home Assistant backend, and the physical-domain tier table.

Related MCP server: Phoenix MCP

The tier model for physics

• T0 free reads: entity state, entity list, subscriptions. Occupancy-derived reads (person, device_tracker, zones, motion/occupancy/presence sensors) are audit-logged even though free.

• T1 free, audit-logged (reversible comfort): lights, fans, switches, media player, input helpers.

• T2 gated, per operation (no batches): lock/unlock/open, alarm arming/disarming, cover open/close/position/tilt, climate set-temperature/preset. Physical actuators have no version history; per-operation approval is the compensating-control argument applied honestly. A configurable climate band narrows set-temperature calls: in-band calls ride an approved band grant (a grant carrying the climate_band marker, requested automatically for in-band calls); outside the band is always gated and rides only an explicit per-operation grant.

• Fan-out: scenes and scripts are classified by what they expand to, not their names. An unresolvable expansion fails closed to gated.

• T3 gated, never delegated: automation/script reload, HA restart/stop, zone/person/config administration.

What is NOT here (v1)

Hubitat (Maker API tokens are all-or-nothing: a permanent custody caveat, designed-unbuilt), Matter native adapter, raw MQTT (untyped pub/sub has no scope object to grant). File storage is the data broker's domain; PIM is the groupware broker's; chat is the communications broker's.

Status

Production alpha (owner-verified live 2026-09-22 through the native MCP client: a comfort-tier switch op executed and audited in the free lane, and the full gated loop on a garage cover — pending request, human approval, execute, state read back through the broker, per- operation grant granularity confirmed). 350 tests across fourteen files. See CHANGELOG.md and DEPLOYMENT.md (including the user-space systemd supervision section).

Production-alpha notes

• Bearer transport contract. Transport http requires auth.bearer.token_env (refuse-to-start without it): every request presents Authorization: Bearer <token>, compared constant-time through the core's check_static_credential before any MCP parsing.

• Lifecycle notices. The approval gateway announces gateway started / gateway stopping in the approval room; a delivery failure is logged and swallowed (a notice must never kill the gateway).

• Service-name shape. call_entity_service requires the full domain.service form (switch.turn_off); a bare service name is refused with a named error. Cosmetic item on the queue: accept the bare form when the entity's domain disambiguates it.

• T2 grant semantics (open, owner decision pending, suite-wide). An approved T2 grant carries a time window; no consume-on-use path exists in v1. Options on record: execute-time self-revocation after a gated op fires, or a docstring correction to match the window. Per-operation grant granularity is confirmed live: an open grant did not cover close.

• Shared-room routing. When one approval room serves several broker gateways (Option B), every typed command carries the broker's tag (automation approve 3) and every outbound message is stamped [automation]; unprefixed commands are refused with a hint, never guessed at.

License

GPL-3.0-or-later. See AUTHORS.md for provenance.