@orellbuehler/homeassistant-mcp 0.4.0 → 0.5.1

package/README.md

@@ -163,6 +163,26 @@ prefs, then save), so editing the Energy dashboard in the HA UI at the same mome
 Pass an `automation.*` or `script.*` entity id; the trace key is resolved automatically. Use these
 to debug **whether and how** an automation you authored actually ran.
 
+**ZHA / Zigbee groups** (WebSocket)
+
+| Tool                       | Description                                                                         |
+| -------------------------- | ----------------------------------------------------------------------------------- |
+| `list_zha_groups`          | Existing ZHA groups (group_id, name, members).                                      |
+| `list_zha_groupable`       | Endpoints that can join a group (ieee + endpoint_id + their entities).              |
+| `create_zha_group`         | Create a group on the coordinator; members by `entity_id` or `{ieee, endpoint_id}`. |
+| `add_zha_group_members`    | Add members to a group.                                                             |
+| `remove_zha_group_members` | Remove members from a group.                                                        |
+| `remove_zha_group`         | Delete group(s) by id (member devices untouched).                                   |
+
+A ZHA group lives on the Zigbee coordinator and is exposed to HA as one group entity (e.g. a single
+`light.*` that drives all members together via Zigbee multicast). This is **configuration
+authoring**, not device control — like creating a helper, it changes what entities exist, not their
+on/off state. The write tools call `zha/group/*` and **require an admin token**. Members must be
+groupable ZHA endpoints (devices that support the Zigbee Groups cluster); `create_zha_group` /
+`add_zha_group_members` accept `entity_id`s and resolve them to `{ieee, endpoint_id}` via
+`list_zha_groupable`, or you can pass the `{ieee, endpoint_id}` pairs directly. The HA group entity
+is created asynchronously, so read its final `entity_id` from the entity registry afterwards.
+
 ## Safety boundary
 
 - **No device control.** There is no generic `call_service`, no `set_state`, and no `fire_event`.
@@ -172,6 +192,9 @@ to debug **whether and how** an automation you authored actually ran.
 - **Energy dashboard config is writable** via `energy/save_prefs` (the `*_energy_*` tools). This is
   configuration authoring — the dashboard's sources and Individual-devices list — not device control,
   and it needs an admin token. No `call_service`, `set_state`, or `fire_event` is added.
+- **ZHA groups are writable** via `zha/group/*` (the `*_zha_group*` tools). Creating/editing a Zigbee
+  group changes which group entities exist (config authoring), not any device's on/off state, and it
+  needs an admin token. Still no `call_service`, `set_state`, or `fire_event`.
 - **Read tools expose your home's data** (entity names, states, areas) to the agent/LLM. Use a
   scoped HA user if that matters to you.
 - Prefer `https` and a trusted network path to your instance.

package/dist/server.js

@@ -8,8 +8,9 @@ import { registerReloadTools } from "./tools/reload.js";
 import { registerRegistryTools } from "./tools/registry.js";
 import { registerEnergyTools } from "./tools/energy.js";
 import { registerTraceTools } from "./tools/trace.js";
+import { registerZhaTools } from "./tools/zha.js";
 export function createServer(client, wsClient) {
-    const server = new McpServer({ name: "homeassistant-mcp", version: "0.4.0" });
+    const server = new McpServer({ name: "homeassistant-mcp", version: "0.5.1" });
     registerEntityTools(server, client);
     registerServiceTools(server, client);
     registerSystemTools(server, client);
@@ -19,5 +20,6 @@ export function createServer(client, wsClient) {
     registerRegistryTools(server, wsClient);
     registerEnergyTools(server, wsClient, client);
     registerTraceTools(server, wsClient, client);
+    registerZhaTools(server, wsClient);
     return server;
 }

package/dist/tools/zha.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import { ok, err } from "../hass/format.js";
+// An entity_id can be listed either on the groupable endpoint itself or, on some
+// HA versions where the endpoint list comes back empty/null, only under the
+// device. Check both.
+function endpointHasEntity(ep, entityId) {
+    const onEndpoint = ep.entities?.some((e) => e?.entity_id === entityId);
+    const onDevice = ep.device?.entities?.some((e) => e?.entity_id === entityId);
+    return Boolean(onEndpoint || onDevice);
+}
+function endpointEntityIds(ep) {
+    const refs = [...(ep.entities ?? []), ...(ep.device?.entities ?? [])];
+    return [
+        ...new Set(refs.filter((e) => !!e?.entity_id).map((e) => e.entity_id)),
+    ];
+}
+const memberSchema = z.union([
+    z.string(),
+    z.object({
+        ieee: z.string(),
+        endpoint_id: z.number().int().nonnegative(),
+    }),
+]);
+async function resolveMembers(ws, members) {
+    const needLookup = members.some((m) => typeof m === "string");
+    let groupable = [];
+    if (needLookup) {
+        groupable = (await ws.command("zha/devices/groupable"));
+    }
+    return members.map((m) => {
+        if (typeof m !== "string")
+            return { ieee: m.ieee, endpoint_id: m.endpoint_id };
+        const hit = groupable.find((ep) => endpointHasEntity(ep, m));
+        if (!hit) {
+            throw new Error(`'${m}' is not a groupable ZHA entity. A ZHA group member must be a ZHA entity on an endpoint that supports the Zigbee Groups cluster (see list_zha_groupable). Non-ZHA entities (Wi-Fi/Shelly/Hue-bridge/etc.) cannot join a ZHA group.`);
+        }
+        return { ieee: hit.device.ieee, endpoint_id: hit.endpoint_id };
+    });
+}
+export function registerZhaTools(server, ws) {
+    server.tool("list_zha_groups", "List existing ZHA (Zigbee) groups via the WebSocket API (zha/groups). Each group has a group_id, name and its members. A ZHA group lives on the Zigbee coordinator and is exposed to HA as a single group entity (e.g. one light.* that drives all members together via Zigbee multicast).", {}, async () => {
+        try {
+            return ok(await ws.command("zha/groups"));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("list_zha_groupable", "List ZHA device endpoints that can be added to a ZHA group (zha/devices/groupable) — endpoints whose device supports the Zigbee Groups cluster. Returns, per endpoint, its ieee + endpoint_id and the entities on it, so you can choose group members by entity_id. Use this to see what create_zha_group / add_zha_group_members accept.", {}, async () => {
+        try {
+            const eps = (await ws.command("zha/devices/groupable"));
+            const endpoints = eps.map((ep) => ({
+                ieee: ep.device?.ieee ?? null,
+                endpoint_id: ep.endpoint_id,
+                device_name: ep.device?.user_given_name ?? ep.device?.name ?? null,
+                entities: endpointEntityIds(ep),
+            }));
+            return ok({ count: endpoints.length, endpoints });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("create_zha_group", "Create a ZHA (Zigbee) group on the coordinator (zha/group/add) and return the new group (group_id, name, members). This is configuration authoring — it does not switch anything; it tells the Zigbee network to treat the members as one group, and HA then exposes a single group entity (e.g. light.<name>) that controls them together via Zigbee multicast. 'members' is optional and accepts entity_ids (resolved to ieee+endpoint via list_zha_groupable) and/or explicit {ieee, endpoint_id} objects; only groupable ZHA entities are valid. The HA group entity is created asynchronously and may not be in this response — read its entity_id from the entity registry afterwards.", {
+        name: z.string().describe("Friendly name for the new group, e.g. 'Iris TV'"),
+        members: z
+            .array(memberSchema)
+            .optional()
+            .describe("Initial members: entity_ids (e.g. 'light.philips_iris_tv_left') and/or {ieee, endpoint_id} objects. Omit to create an empty group and add members later."),
+    }, async ({ name, members }) => {
+        try {
+            const payload = { group_name: name };
+            if (members && members.length)
+                payload.members = await resolveMembers(ws, members);
+            return ok(await ws.command("zha/group/add", payload));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("add_zha_group_members", "Add members to an existing ZHA group (zha/group/members/add). 'members' accepts entity_ids (resolved via list_zha_groupable) and/or {ieee, endpoint_id} objects. Returns the updated group.", {
+        group_id: z.number().int().describe("Target group_id (from list_zha_groups)"),
+        members: z
+            .array(memberSchema)
+            .min(1)
+            .describe("Members to add: entity_ids and/or {ieee, endpoint_id} objects"),
+    }, async ({ group_id, members }) => {
+        try {
+            const resolved = await resolveMembers(ws, members);
+            return ok(await ws.command("zha/group/members/add", { group_id, members: resolved }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("remove_zha_group_members", "Remove members from an existing ZHA group (zha/group/members/remove). 'members' accepts entity_ids (resolved via list_zha_groupable) and/or {ieee, endpoint_id} objects. Returns the updated group.", {
+        group_id: z.number().int().describe("Target group_id (from list_zha_groups)"),
+        members: z
+            .array(memberSchema)
+            .min(1)
+            .describe("Members to remove: entity_ids and/or {ieee, endpoint_id} objects"),
+    }, async ({ group_id, members }) => {
+        try {
+            const resolved = await resolveMembers(ws, members);
+            return ok(await ws.command("zha/group/members/remove", { group_id, members: resolved }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("remove_zha_group", "Delete one or more ZHA groups by id (zha/group/remove). This removes the group from the Zigbee coordinator and its HA group entity; the member devices themselves are untouched. Returns the remaining groups.", {
+        group_ids: z.array(z.number().int()).min(1).describe("group_id(s) to delete"),
+    }, async ({ group_ids }) => {
+        try {
+            return ok(await ws.command("zha/group/remove", { group_ids }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orellbuehler/homeassistant-mcp",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Model Context Protocol server for Home Assistant: introspect entities, services, events, registries, render templates and validate configuration to help AI agents author HA configs and automations.",
   "type": "module",
   "bin": {