@orellbuehler/homeassistant-mcp 0.2.0 → 0.4.0

package/README.md

@@ -31,7 +31,7 @@ claude mcp add homeassistant \
 
 See [Usage with Claude Code](#usage-with-claude-code) for the equivalent JSON config. For any other
 MCP client, run the package directly — `npx -y @orellbuehler/homeassistant-mcp` with `HASS_URL` and
-`HASS_TOKEN` set in the environment. Requires Node.js 18+.
+`HASS_TOKEN` set in the environment. Requires Node.js 20+.
 
 ## Getting a token
 
@@ -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)
 
@@ -144,7 +148,20 @@ available immediately. Verify with `claude mcp list` (should show `homeassistant
 
 The Energy dashboard config lives in `.storage/energy` and is only reachable over WebSocket (not
 REST). The write tools (`save_energy_prefs`, `add_`/`remove_energy_devices`, `set_energy_*`) call
-`energy/save_prefs`, which **requires an admin token**.
+`energy/save_prefs`, which **requires an admin token**. They are read-modify-write (fetch the current
+prefs, then save), so editing the Energy dashboard in the HA UI at the same moment can be overwritten
+— this is fine for the intended single-agent use.
+
+**Traces** (WebSocket, read-only)
+
+| Tool                 | Description                                                                         |
+| -------------------- | ----------------------------------------------------------------------------------- |
+| `list_traces`        | Recent execution traces (newest first) for an `automation.*`/`script.*` entity.     |
+| `get_trace`          | Full step-by-step trace for one run (config, variables, context, error).            |
+| `get_trace_contexts` | Map context ids to the trace run that produced them (causality across automations). |
+
+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.
 
 ## Safety boundary
 

package/dist/hass/rest.js

@@ -1,9 +1,11 @@
 export class HassClient {
     baseUrl;
     token;
-    constructor(baseUrl, token) {
+    timeoutMs;
+    constructor(baseUrl, token, timeoutMs = 15000) {
         this.baseUrl = baseUrl.replace(/\/+$/, "");
         this.token = token;
+        this.timeoutMs = timeoutMs;
     }
     headers(options) {
         return {
@@ -12,15 +14,29 @@ export class HassClient {
             ...(options.headers ?? {}),
         };
     }
-    async fetch(path, options = {}) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            ...options,
-            headers: this.headers(options),
-        });
+    async request(path, options) {
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                ...options,
+                headers: this.headers(options),
+                signal: options.signal ?? AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (e) {
+            if (e instanceof DOMException && e.name === "TimeoutError") {
+                throw new Error(`Home Assistant request timed out after ${this.timeoutMs}ms`, { cause: e });
+            }
+            throw e;
+        }
         if (!res.ok) {
             const body = await res.text();
             throw new Error(`${res.status} ${res.statusText}: ${body}`);
         }
+        return res;
+    }
+    async fetch(path, options = {}) {
+        const res = await this.request(path, options);
         if (res.status === 204)
             return { success: true };
         const ct = res.headers.get("content-type") ?? "";
@@ -29,14 +45,6 @@ export class HassClient {
         return res.text();
     }
     async fetchText(path, options = {}) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            ...options,
-            headers: this.headers(options),
-        });
-        if (!res.ok) {
-            const body = await res.text();
-            throw new Error(`${res.status} ${res.statusText}: ${body}`);
-        }
-        return res.text();
+        return (await this.request(path, options)).text();
     }
 }

package/dist/index.js

@@ -4,4 +4,10 @@ import { client, wsClient } from "./config.js";
 import { createServer } from "./server.js";
 const server = createServer(client, wsClient);
 const transport = new StdioServerTransport();
-await server.connect(transport);
+try {
+    await server.connect(transport);
+}
+catch (e) {
+    console.error(`Failed to start homeassistant-mcp: ${String(e)}`);
+    process.exit(1);
+}

package/dist/server.js

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

package/dist/tools/energy.js

@@ -145,7 +145,7 @@ export function registerEnergyTools(server, ws, client) {
             return err(e);
         }
     });
-    server.tool("validate_energy_prefs", "Run Home Assistant's energy/validate against the current preferences and return per-item issues. device_consumption and energy_sources issues are correlated with their stat_consumption / source so you can see which entity each issue belongs to. Includes the raw validation result.", {}, async () => {
+    server.tool("validate_energy_prefs", "Run Home Assistant's energy/validate against the current preferences and return per-item issues. device_consumption, device_consumption_water and energy_sources issues are correlated with their stat_consumption / source so you can see which entity each issue belongs to. Includes the raw validation result.", {}, async () => {
         try {
             const prefs = await getPrefs(ws);
             const result = (await ws.command("energy/validate"));
@@ -155,10 +155,16 @@ export function registerEnergyTools(server, ws, client) {
                 issues,
             }))
                 .filter((d) => Array.isArray(d.issues) && d.issues.length > 0);
+            const device_consumption_water = (result.device_consumption_water ?? [])
+                .map((issues, i) => ({
+                stat_consumption: prefs.device_consumption_water?.[i]?.stat_consumption ?? null,
+                issues,
+            }))
+                .filter((d) => Array.isArray(d.issues) && d.issues.length > 0);
             const energy_sources = (result.energy_sources ?? [])
                 .map((issues, i) => ({ source: prefs.energy_sources?.[i] ?? null, issues }))
                 .filter((s) => Array.isArray(s.issues) && s.issues.length > 0);
-            return ok({ device_consumption, energy_sources, raw: result });
+            return ok({ device_consumption, device_consumption_water, energy_sources, raw: result });
         }
         catch (e) {
             return err(e);

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/reload.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { ok, err } from "../hass/format.js";
-const RELOAD_TARGETS = {
+export const RELOAD_TARGETS = {
     all: { domain: "homeassistant", service: "reload_all" },
     core: { domain: "homeassistant", service: "reload_core_config" },
     automation: { domain: "automation", service: "reload" },

package/dist/tools/system.js

@@ -21,6 +21,7 @@ export function registerSystemTools(server, client) {
         lines: z
             .number()
             .int()
+            .min(0)
             .optional()
             .describe("Number of trailing lines to return (default 100; use 0 for the full log)"),
     }, async ({ lines }) => {

package/dist/tools/trace.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { ok, err, domainOf } from "../hass/format.js";
+async function resolveTarget(entityId, client) {
+    const domain = domainOf(entityId);
+    if (domain !== "automation" && domain !== "script") {
+        throw new Error(`Traces are only available for automation.* or script.* entities, got ${entityId}`);
+    }
+    const objectId = entityId.slice(domain.length + 1);
+    if (!objectId) {
+        throw new Error(`Invalid ${domain} entity id: ${entityId}`);
+    }
+    if (domain === "script") {
+        return { domain, item_id: objectId };
+    }
+    const state = (await client.fetch(`/api/states/${encodeURIComponent(entityId)}`));
+    const id = state.attributes?.id;
+    if (id === undefined || id === null || id === "") {
+        throw new Error(`Automation ${entityId} has no 'id' attribute, so Home Assistant stores no traces for it`);
+    }
+    return { domain, item_id: String(id) };
+}
+function startMs(t) {
+    const s = t.timestamp?.start;
+    const n = s ? Date.parse(s) : 0;
+    return Number.isNaN(n) ? 0 : n;
+}
+export function registerTraceTools(server, ws, client) {
+    server.tool("list_traces", "List recent execution traces (newest first) for an automation or script via the WebSocket trace API — to debug whether and how it ran. Each summary has run_id, state, script_execution (finished/error/aborted/cancelled/…), last_step, timestamp and any error. Use get_trace with a run_id for the full step-by-step trace.", { entity_id: z.string().describe("An automation.* or script.* entity id") }, async ({ entity_id }) => {
+        try {
+            const { domain, item_id } = await resolveTarget(entity_id, client);
+            const list = ((await ws.command("trace/list", { domain, item_id })) ??
+                []);
+            const traces = [...list]
+                .sort((a, b) => startMs(b) - startMs(a))
+                .map((t) => {
+                const row = {
+                    run_id: t.run_id,
+                    state: t.state,
+                    script_execution: t.script_execution,
+                    last_step: t.last_step,
+                    timestamp: t.timestamp,
+                };
+                if (t.error !== undefined)
+                    row.error = t.error;
+                return row;
+            });
+            return ok({ entity_id, domain, item_id, count: traces.length, traces });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("get_trace", "Get the full execution trace for one run of an automation or script: the per-step path with each step's result, the config, variables, context and any error. Find run_id with list_traces.", {
+        entity_id: z.string().describe("An automation.* or script.* entity id"),
+        run_id: z.string().describe("Run id from list_traces"),
+    }, async ({ entity_id, run_id }) => {
+        try {
+            const { domain, item_id } = await resolveTarget(entity_id, client);
+            return ok(await ws.command("trace/get", { domain, item_id, run_id }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("get_trace_contexts", "Map Home Assistant context ids to the trace run that produced them for an automation or script (trace/contexts) — useful for tracing causality, e.g. which automation run triggered another.", { entity_id: z.string().describe("An automation.* or script.* entity id") }, async ({ entity_id }) => {
+        try {
+            const { domain, item_id } = await resolveTarget(entity_id, client);
+            return ok(await ws.command("trace/contexts", { domain, item_id }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orellbuehler/homeassistant-mcp",
-  "version": "0.2.0",
+  "version": "0.4.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": {
@@ -11,7 +11,7 @@
     "!dist/__tests__"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -19,10 +19,10 @@
     "lint": "eslint src",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "prepare": "npm run build"
+    "prepare": "npm run build && prek install"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "mcp",
@@ -54,6 +54,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@j178/prek": "^0.4.4",
     "@types/node": "^22.15.3",
     "@types/ws": "^8.5.12",
     "eslint": "^10.4.1",