@orellbuehler/homeassistant-mcp 0.5.1 → 0.7.0

package/README.md

@@ -12,9 +12,10 @@ 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**.
+authors automations (create/replace/delete via the config API), 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
 
@@ -118,6 +119,21 @@ available immediately. Verify with `claude mcp list` (should show `homeassistant
 | -------- | ------------------------------------------------------------------------------------------ |
 | `reload` | Reload a reloadable domain so YAML edits apply without a restart (`all`, `automation`, …). |
 
+**Automations** (REST, `/api/config/automation`)
+
+| Tool                    | Description                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `get_automation_config` | Stored config (triggers/conditions/actions/mode) of one automation.            |
+| `upsert_automation`     | Create a new automation or replace an existing one's config (validated by HA). |
+| `delete_automation`     | Delete a UI-managed automation.                                                |
+
+All three accept the `automation.*` entity id (the internal id is resolved automatically) or the
+internal id itself. Writes require an **admin token**; HA validates the config, stores it in
+`automations.yaml` and reloads automations automatically. `upsert_automation` replaces the whole
+config, so edit via `get_automation_config` → modify → `upsert_automation`. Only automations with
+an `id` (UI-created / `automations.yaml`) are reachable — automations defined elsewhere in YAML are
+not. Debug the result with the trace tools below.
+
 **Registries** (WebSocket)
 
 | Tool                     | Description                                                                              |
@@ -183,18 +199,56 @@ 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; when HACS manages
+resources (storage mode) it also drops the plugin's Lovelace resource for you, so verify with
+`list_lovelace_resources` and only `delete_lovelace_resource` one that's left behind. 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`.
   The server cannot turn things on/off.
 - **`reload` is restricted** to a fixed allowlist of `*.reload` / `homeassistant.reload_*` services.
   It restarts reloadable domains (e.g. re-reads `automations.yaml`) but cannot control devices.
+- **Automation configs are writable** via the `/api/config/automation` REST API
+  (`upsert_automation` / `delete_automation`). This is the server's core purpose — authoring
+  automations — and needs an admin token. Be aware that an automation, once written, runs its
+  actions whenever its triggers fire, so review configs before writing. The server still cannot run
+  services directly: no `call_service`, `set_state`, or `fire_event`.
 - **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`.
+- **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

@@ -5,21 +5,27 @@ import { registerSystemTools } from "./tools/system.js";
 import { registerTemplateTools } from "./tools/templates.js";
 import { registerHistoryTools } from "./tools/history.js";
 import { registerReloadTools } from "./tools/reload.js";
+import { registerAutomationTools } from "./tools/automations.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";
+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.1" });
+    const server = new McpServer({ name: "homeassistant-mcp", version: "0.7.0" });
     registerEntityTools(server, client);
     registerServiceTools(server, client);
     registerSystemTools(server, client);
     registerTemplateTools(server, client);
     registerHistoryTools(server, client);
     registerReloadTools(server, client);
+    registerAutomationTools(server, client);
     registerRegistryTools(server, wsClient);
     registerEnergyTools(server, wsClient, client);
     registerTraceTools(server, wsClient, client);
     registerZhaTools(server, wsClient);
+    registerHacsTools(server, wsClient);
+    registerResourceTools(server, wsClient);
     return server;
 }

package/dist/tools/automations.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { ok, err } from "../hass/format.js";
+async function resolveId(automation, client) {
+    if (!automation.startsWith("automation."))
+        return automation;
+    const state = (await client.fetch(`/api/states/${encodeURIComponent(automation)}`));
+    const id = state.attributes?.id;
+    if (id === undefined || id === null || id === "") {
+        throw new Error(`Automation ${automation} has no 'id' attribute, so it is not stored in automations.yaml and cannot be read or edited via the config API (it is defined elsewhere in YAML without an id)`);
+    }
+    return String(id);
+}
+const configPath = (id) => `/api/config/automation/config/${encodeURIComponent(id)}`;
+export function registerAutomationTools(server, client) {
+    server.tool("get_automation_config", "Get the stored configuration of an automation (alias, description, triggers, conditions, actions, mode) from automations.yaml via GET /api/config/automation/config/{id}. Accepts the automation.* entity id (the internal id is resolved automatically) or the internal id itself. Only automations with an 'id' (UI-created, stored in automations.yaml) are accessible.", {
+        automation: z
+            .string()
+            .describe("automation.* entity id, or the automation's internal id (the 'id' attribute)"),
+    }, async ({ automation }) => {
+        try {
+            const id = await resolveId(automation, client);
+            return ok(await client.fetch(configPath(id)));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("upsert_automation", "Create a new automation or replace an existing one via POST /api/config/automation/config/{id} (requires an admin token). Home Assistant validates the config, writes it to automations.yaml and reloads automations automatically — no separate reload needed. The config REPLACES the stored one entirely, so to edit call get_automation_config first and send back the modified object. Omit 'automation' to create a new one (an id is generated and returned); its entity id becomes automation.<slugified alias>. Note that once its triggers fire, an automation runs its actions — review the config before writing.", {
+        config: z
+            .record(z.unknown())
+            .describe("Full automation config as stored in automations.yaml: alias, description?, triggers, conditions?, actions, mode? (the legacy singular trigger/condition/action keys are also accepted)"),
+        automation: z
+            .string()
+            .optional()
+            .describe("Existing automation.* entity id or internal id to replace; omit to create a new automation"),
+    }, async ({ config, automation }) => {
+        try {
+            const id = automation ? await resolveId(automation, client) : String(Date.now());
+            const result = await client.fetch(configPath(id), {
+                method: "POST",
+                body: JSON.stringify(config),
+            });
+            return ok({ id, created: !automation, result });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("delete_automation", "Delete an automation from automations.yaml via DELETE /api/config/automation/config/{id} (requires an admin token). Accepts the automation.* entity id or the internal id. Only UI-managed automations (those stored in automations.yaml) can be deleted; Home Assistant reloads automations automatically afterwards.", {
+        automation: z
+            .string()
+            .describe("automation.* entity id, or the automation's internal id (the 'id' attribute)"),
+    }, async ({ automation }) => {
+        try {
+            const id = await resolveId(automation, client);
+            return ok(await client.fetch(configPath(id), { method: "DELETE" }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

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. When HACS manages resources (storage mode) it also removes the plugin's /hacsfiles/… Lovelace resource for you; verify with list_lovelace_resources and use delete_lovelace_resource only if one is left behind. 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 for manually-registered resources (e.g. /local/…) or a /hacsfiles/… resource that HACS did not auto-remove 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/package.json

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