@orellbuehler/homeassistant-mcp 0.2.0 → 0.3.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
 
@@ -144,7 +144,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.3.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/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.3.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",