v1.0

homey-mcp/README.md

@@ -6,16 +6,21 @@ It talks to Homey's local HTTP Web API (`/api/manager/...`) using a Personal Acc
 
 ## Features
 
-Tools:
+Tools (read-only ones carry `readOnlyHint`; zone/home-wide and flow tools are marked `destructiveHint`):
 
-- `ping` — verify connectivity / return Homey system info
-- `list_devices(zone_id?)` — devices with current capability values
-- `get_device(device_id)` — full device object
-- `list_zones` — rooms / areas
-- `set_capability(device_id, capability, value)` — set `onoff`, `dim`, `target_temperature`, …
-- `list_flows` — all flows
-- `trigger_flow(flow_id)` — start a flow
-- `list_recent_events(limit, kind?)` — recent realtime events from the in-memory buffer
+- Connectivity: `ping`
+- Devices: `list_devices(zone_id?)`, `find_devices(query, zone?)`, `get_device(device_id)`
+- Zones: `list_zones`
+- Status views: `get_zone_status(zone)`, `get_house_status(class_filter?)`, `get_temperatures`
+- Capabilities: `get_capability`, `set_capability`, `set_light`, `set_capabilities_bulk`
+- Zone / home control: `control_zone(zone, capability, value)`, `control_all(capability, value, device_class?)`
+- Flows: `list_flows`, `find_flows(query)`, `trigger_flow(flow_id)`
+- Logic variables: `list_variables`, `set_variable`
+- Notifications: `send_notification(title, excerpt?)`
+- Events: `list_recent_events(limit, kind?)` — realtime events from the in-memory buffer
+
+Zone names resolve exact match → prefix → substring, so `Wohnzimmer` never picks
+`Wohnzimmer Ecke`. IDs are URL-encoded before they reach Homey's API.
 
 Resources:
 
@@ -104,11 +109,13 @@ The remote client connects to `http://<this-machine-ip>:8080/mcp`
 URL may use `http://<this-machine-ip>:8080/`; MCP traffic at `/` is forwarded
 to `/mcp`, while an ordinary browser GET returns service discovery.
 
-**Important for MCP transport over LAN:** The MCP SDK validates that clients
-send the correct `Host` header. If you bind to `0.0.0.0`, you **must** set
-`HOMEY_MCP_ADVERTISED_HOST` to your actual server IP (e.g., `10.10.10.50`).
-If you instead bind to a specific IP, omit `HOMEY_MCP_ADVERTISED_HOST` and it
-will default to the bind address.
+**Important for MCP transport over LAN:** requests are only accepted when their
+`Host` header is `HOMEY_MCP_ADVERTISED_HOST`, `localhost` or `127.0.0.1`
+(otherwise `421 Misdirected Request`). This blocks DNS-rebinding attacks, where a
+web page in any browser on your LAN rebinds its domain to this server. If you
+bind to `0.0.0.0`, set `HOMEY_MCP_ADVERTISED_HOST` to the IP clients use; add
+further names (e.g. a DNS name) to `HOMEY_MCP_ALLOWED_HOSTS` (comma-separated,
+`*` disables the check). Without either, the check is off and a warning is logged.
 
 `HOMEY_MCP_AUTH_MODE=none` is the compatible mode for OAuth-negotiating MCP
 clients such as Odysseus, because this server is not an OAuth authorization
@@ -119,7 +126,9 @@ dynamic registration are not provided. Generate a token with
 `python -c "import secrets; print(secrets.token_urlsafe(32))"`.
 
 When `HOMEY_MCP_AUTH_TOKEN` is set, the OpenAPI REST routes always require it,
-regardless of the MCP auth mode.
+regardless of the MCP auth mode. In `bearer` mode every MCP route requires it
+too (`/mcp`, the root alias, and `/sse` + `/messages/` for the SSE transport);
+only `GET /` (discovery) and `/openapi.json` stay public.
 
 This is independent of Javis's own connection: Javis keeps talking to
 homey-mcp over stdio via `mcp_servers.json` as before — run the LAN instance
@@ -179,7 +188,7 @@ If `homey-mcp` is not on PATH, use the full venv path, e.g. `C:\\local\\Code\\PR
 - Local API only (no cloud OAuth).
 - LAN MCP transport authentication is controlled by `HOMEY_MCP_AUTH_MODE`.
   Never expose `none` mode beyond a trusted, firewall-restricted LAN.
-- Realtime events are best-effort — if the Socket.IO connection fails the REST tools still work. Set `HOMEY_REALTIME=false` to disable.
+- Realtime events are best-effort — if the Socket.IO connection fails the REST tools still work. Set `HOMEY_REALTIME=false` to disable. The server performs Homey's `handshakeClient` and subscribes to `homey:manager:devices` plus each `homey:device:<id>` (capability changes).
 - No admin operations (zone/user/app management) are exposed.
 - Capability values are typed as `bool | int | float | str`; the model picks based on the capability (`onoff` → bool, `dim` → 0..1 float, etc.).