@orellbuehler/homeassistant-mcp 0.5.0 → 0.6.0

package/README.md

@@ -12,9 +12,9 @@ AI agents.
 It is built to **help an agent author and validate Home Assistant configuration and automations** —
 not to control your home. It tells the agent what exists live (entities, services, events, areas,
 devices), validates the agent's work (render Jinja2 templates, check config, read the error log),
-can reload reloadable domains after YAML edits, and can configure the Energy dashboard (sources and
-the Individual-devices list). It deliberately has **no tools to turn devices on/off, set states, or
-fire events**.
+can reload reloadable domains after YAML edits, can configure the Energy dashboard (sources and the
+Individual-devices list), manage Lovelace resources, and prune HACS repositories. It deliberately has
+**no tools to turn devices on/off, set states, or fire events**.
 
 ## Install
 
@@ -183,6 +183,33 @@ groupable ZHA endpoints (devices that support the Zigbee Groups cluster); `creat
 `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.
 
+**Lovelace resources** (WebSocket)
+
+| Tool                       | Description                                                                |
+| -------------------------- | -------------------------------------------------------------------------- |
+| `list_lovelace_resources`  | Registered dashboard resources (id, type, url), e.g. `/hacsfiles/…`.       |
+| `create_lovelace_resource` | Register a JS/CSS URL loaded on every dashboard (defaults to module).      |
+| `update_lovelace_resource` | Change a resource's url and/or type by id.                                 |
+| `delete_lovelace_resource` | Remove a resource by id (e.g. the dangling one left after a HACS removal). |
+
+Resources are the JS/CSS bundles loaded into every dashboard (Settings → Dashboards → Resources).
+The write tools call `lovelace/resources/*`, **require an admin token**, and only work when the
+resource registry is in **storage mode** (`lovelace: mode: storage`); they are disabled if Lovelace
+is globally in YAML mode. This is config authoring, not device control.
+
+**HACS** (WebSocket)
+
+| Tool                     | Description                                                                     |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| `list_hacs_repositories` | HACS repositories (installed-only by default): id, category, versions, paths.   |
+| `remove_hacs_repository` | Uninstall a repository by id — deletes its downloaded files and unregisters it. |
+
+`list_hacs_repositories` maps each repo to `id` + `local_path`/`file_name`, so you can tell which
+`/hacsfiles/…` Lovelace resource belongs to a plugin. `remove_hacs_repository` calls
+`hacs/repository/remove` (**admin token**) and deletes the plugin's files, but not its Lovelace
+resource — pair it with `delete_lovelace_resource` to fully clean up a frontend plugin. Removing an
+integration you still reference in YAML will break that config, so check usage first.
+
 ## Safety boundary
 
 - **No device control.** There is no generic `call_service`, no `set_state`, and no `fire_event`.
@@ -195,6 +222,11 @@ is created asynchronously, so read its final `entity_id` from the entity registr
 - **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`.
+- **Lovelace resources are writable** via `lovelace/resources/*` (the `*_lovelace_resource` tools) —
+  which JS/CSS bundles load into dashboards. Config authoring, admin token, storage-mode only.
+- **HACS repositories are removable** via `hacs/repository/remove` (`remove_hacs_repository`). This
+  uninstalls a plugin/integration/theme and deletes its files (admin token); there is no install tool
+  (the server never downloads third-party code). 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

@@ -9,8 +9,10 @@ import { registerRegistryTools } from "./tools/registry.js";
 import { registerEnergyTools } from "./tools/energy.js";
 import { registerTraceTools } from "./tools/trace.js";
 import { registerZhaTools } from "./tools/zha.js";
+import { registerHacsTools } from "./tools/hacs.js";
+import { registerResourceTools } from "./tools/resources.js";
 export function createServer(client, wsClient) {
-    const server = new McpServer({ name: "homeassistant-mcp", version: "0.5.0" });
+    const server = new McpServer({ name: "homeassistant-mcp", version: "0.6.0" });
     registerEntityTools(server, client);
     registerServiceTools(server, client);
     registerSystemTools(server, client);
@@ -21,5 +23,7 @@ export function createServer(client, wsClient) {
     registerEnergyTools(server, wsClient, client);
     registerTraceTools(server, wsClient, client);
     registerZhaTools(server, wsClient);
+    registerHacsTools(server, wsClient);
+    registerResourceTools(server, wsClient);
     return server;
 }

package/dist/tools/hacs.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { ok, err } from "../hass/format.js";
+function summarize(r) {
+    return {
+        id: r.id,
+        name: r.name,
+        full_name: r.full_name,
+        category: r.category,
+        installed_version: r.installed_version,
+        available_version: r.available_version,
+        pending_upgrade: r.pending_upgrade,
+        local_path: r.local_path,
+        file_name: r.file_name,
+        domain: r.domain,
+    };
+}
+export function registerHacsTools(server, ws) {
+    server.tool("list_hacs_repositories", "List HACS repositories (hacs/repositories/list) — the frontend plugins, integrations and themes HACS manages. Defaults to installed-only, trimmed to the useful fields (id, name, full_name, category, versions, local_path, file_name, domain). Use the returned id with remove_hacs_repository. For a frontend plugin, local_path/file_name tell you which /hacsfiles/… Lovelace resource points at it (see list_lovelace_resources), so you can delete the dangling resource after removing the plugin.", {
+        installed_only: z
+            .boolean()
+            .optional()
+            .describe("Only repositories that are installed. Default true; set false to include the whole known store (large)."),
+        category: z
+            .string()
+            .optional()
+            .describe("Filter by HACS category, e.g. 'integration', 'plugin', 'theme'. Omit for all categories."),
+    }, async ({ installed_only, category }) => {
+        try {
+            const payload = category ? { categories: [category] } : {};
+            const repos = (await ws.command("hacs/repositories/list", payload));
+            const filtered = installed_only === false ? repos : repos.filter((r) => r.installed);
+            const repositories = filtered.map(summarize);
+            return ok({ count: repositories.length, repositories });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("remove_hacs_repository", "Uninstall a HACS repository by id (hacs/repository/remove) — deletes its downloaded files from the config (for a plugin, the JS under www/community/…) and unregisters it from HACS. Requires an admin token. This does NOT remove the plugin's Lovelace resource entry; after removing a frontend plugin, also delete its /hacsfiles/… resource with delete_lovelace_resource. Get the id from list_hacs_repositories. Removing an installed integration you still reference in YAML will break that config, so confirm nothing uses it first.", {
+        repository_id: z
+            .string()
+            .describe("The repository id from list_hacs_repositories (a numeric string, e.g. '172733314')."),
+    }, async ({ repository_id }) => {
+        try {
+            await ws.command("hacs/repository/remove", { repository: repository_id });
+            return ok({ repository_id, removed: true });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/resources.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { ok, err } from "../hass/format.js";
+const resType = z
+    .enum(["module", "css", "js", "html"])
+    .describe("Resource type. Lovelace cards use 'module'; 'css' for stylesheets. Rarely 'js'/'html'.");
+export function registerResourceTools(server, ws) {
+    server.tool("list_lovelace_resources", "List registered Lovelace (dashboard) resources (lovelace/resources) — the JS/CSS URLs, e.g. /hacsfiles/… bundles, loaded into every dashboard. Each item has an id (use it with update/delete), a type (module/css/js/html) and a url. Only works when the resource registry is in storage mode (lovelace: mode: storage); it is disabled if Lovelace is globally in YAML mode.", {}, async () => {
+        try {
+            return ok(await ws.command("lovelace/resources"));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("create_lovelace_resource", "Register a new Lovelace resource (lovelace/resources/create) so a card bundle/stylesheet loads on every dashboard. Config authoring (like adding it under Settings → Dashboards → Resources); requires an admin token and storage-mode resources. Returns the created resource incl. its new id.", {
+        url: z
+            .string()
+            .describe("Resource URL, e.g. '/hacsfiles/my-card/my-card.js' or '/local/aurora-cards.js'."),
+        res_type: resType.optional().describe("Defaults to 'module' (the type Lovelace cards use)."),
+    }, async ({ url, res_type }) => {
+        try {
+            return ok(await ws.command("lovelace/resources/create", { url, res_type: res_type ?? "module" }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("update_lovelace_resource", "Update an existing Lovelace resource (lovelace/resources/update) — change its url and/or type. Config authoring; requires an admin token and storage-mode resources. Get the resource_id from list_lovelace_resources.", {
+        resource_id: z.string().describe("The resource id from list_lovelace_resources."),
+        url: z.string().optional().describe("New URL. Omit to keep the current one."),
+        res_type: resType.optional().describe("New type. Omit to keep the current one."),
+    }, async ({ resource_id, url, res_type }) => {
+        try {
+            const payload = { resource_id };
+            if (url !== undefined)
+                payload.url = url;
+            if (res_type !== undefined)
+                payload.res_type = res_type;
+            return ok(await ws.command("lovelace/resources/update", payload));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("delete_lovelace_resource", "Delete a Lovelace resource (lovelace/resources/delete) by id — removes the JS/CSS URL from every dashboard. Config authoring; requires an admin token and storage-mode resources. Use this to clear the dangling /hacsfiles/… resource left behind after remove_hacs_repository. Get the resource_id from list_lovelace_resources.", {
+        resource_id: z.string().describe("The resource id from list_lovelace_resources."),
+    }, async ({ resource_id }) => {
+        try {
+            await ws.command("lovelace/resources/delete", { resource_id });
+            return ok({ resource_id, deleted: true });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/zha.js

@@ -1,5 +1,19 @@
 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({
@@ -16,7 +30,7 @@ async function resolveMembers(ws, members) {
     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));
+        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.`);
         }
@@ -39,7 +53,7 @@ export function registerZhaTools(server, ws) {
                 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),
+                entities: endpointEntityIds(ep),
             }));
             return ok({ count: endpoints.length, endpoints });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orellbuehler/homeassistant-mcp",
-  "version": "0.5.0",
+  "version": "0.6.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": {