@orellbuehler/homeassistant-mcp 0.3.0 → 0.5.0

package/README.md

@@ -120,15 +120,19 @@ available immediately. Verify with `claude mcp list` (should show `homeassistant
 
 **Registries** (WebSocket)
 
-| Tool                     | Description                                                                 |
-| ------------------------ | --------------------------------------------------------------------------- |
-| `list_registry_entities` | ALL registered entities, incl. disabled/unavailable (area, device, status). |
-| `list_devices`           | Devices (id, name, manufacturer, model, area).                              |
-| `list_areas`             | Areas (area_id, name, floor).                                               |
-| `list_labels`            | Labels (label_id, name, color, icon).                                       |
+| Tool                     | Description                                                                              |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
+| `list_registry_entities` | ALL registered entities, incl. disabled/unavailable (area, device, status).              |
+| `rename_entity`          | Set an entity's registry `name` and/or `new_entity_id` (config edit, no device control). |
+| `list_devices`           | Devices (id, name, manufacturer, model, area).                                           |
+| `list_areas`             | Areas (area_id, name, floor).                                                            |
+| `list_labels`            | Labels (label_id, name, color, icon).                                                    |
 
 `list_entities` (REST) shows entities that currently have state; `list_registry_entities`
 (WebSocket) shows everything registered, including disabled entities, with area/device grouping.
+`rename_entity` writes the registry via `config/entity_registry/update` (requires an admin token):
+`name` overrides the friendly name (null reverts to the integration's `original_name`) and
+`new_entity_id` renames the entity_id within the same domain.
 
 **Energy dashboard** (WebSocket)
 
@@ -159,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`.
@@ -168,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.3.0" });
+    const server = new McpServer({ name: "homeassistant-mcp", version: "0.5.0" });
     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/registry.js

@@ -31,6 +31,38 @@ export function registerRegistryTools(server, ws) {
             return err(e);
         }
     });
+    server.tool("rename_entity", "Rename an entity in the entity registry via the WebSocket API (config/entity_registry/update). Set 'name' to override the friendly name (pass null to revert to the integration's original_name) and/or 'new_entity_id' to change the entity_id itself (must keep the same domain). At least one of name or new_entity_id is required. This edits registry config only — it does not control any device. Returns the updated entity_entry.", {
+        entity_id: z
+            .string()
+            .describe("Current entity_id to rename, e.g. 'cover.storen_wohnzimmer_links'"),
+        name: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("New friendly name; null reverts to the integration's original_name"),
+        new_entity_id: z
+            .string()
+            .optional()
+            .describe("New entity_id; must keep the same domain, e.g. 'cover.wohnzimmer_links'"),
+    }, async ({ entity_id, name, new_entity_id }) => {
+        try {
+            if (name === undefined && new_entity_id === undefined) {
+                throw new Error("Provide at least one of 'name' or 'new_entity_id' to rename the entity");
+            }
+            if (new_entity_id !== undefined && domainOf(new_entity_id) !== domainOf(entity_id)) {
+                throw new Error(`new_entity_id must stay in the '${domainOf(entity_id)}' domain (got '${new_entity_id}')`);
+            }
+            const payload = { entity_id };
+            if (name !== undefined)
+                payload.name = name;
+            if (new_entity_id !== undefined)
+                payload.new_entity_id = new_entity_id;
+            return ok(await ws.command("config/entity_registry/update", payload));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
     server.tool("list_devices", "List devices from the device registry via the WebSocket API (id, name, manufacturer, model, area_id). Useful for grouping entities by physical device when writing automations.", {}, async () => {
         try {
             const list = (await ws.command("config/device_registry/list"));

package/dist/tools/zha.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { ok, err } from "../hass/format.js";
+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) => ep.entities?.some((e) => e.entity_id === 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: (ep.entities ?? []).map((e) => e.entity_id),
+            }));
+            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.3.0",
+  "version": "0.5.0",
   "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": {