ha-ai-mcp-server 0.3.8

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "ha-ai-mcp-server",
+  "version": "0.3.8",
+  "description": "Model Context Protocol server for Home Assistant with Playwright visual feedback",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ha-ai-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/index.js",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "axios": "^1.7.9",
+    "playwright": "^1.50.0",
+    "ws": "^8.18.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.19",
+    "@types/ws": "^8.5.14",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.11"
+  },
+  "keywords": [
+    "home-assistant",
+    "mcp",
+    "model-context-protocol",
+    "playwright",
+    "lovelace",
+    "ai-agents"
+  ],
+  "license": "Apache-2.0"
+}

package/src/adapters/addon/addon.adapter.ts

@@ -0,0 +1,113 @@
+import axios, { AxiosInstance } from "axios";
+import {
+  AddonHealthResult,
+  FileReadResult,
+  FileWriteResult,
+  IAddonClient,
+} from "../../domain/ports/addon-client.port.js";
+import { BackupRestoreResult, LogsTailResult, SnapshotInfo } from "../../domain/models/system.js";
+import { ClientError } from "../../core/errors.js";
+
+export interface AddonClientOptions {
+  addonUrl: string;
+  addonKey: string;
+  timeoutMs?: number;
+}
+
+export class AddonAdapter implements IAddonClient {
+  private readonly client: AxiosInstance;
+
+  constructor(options: AddonClientOptions | string, addonKey?: string) {
+    let url: string;
+    let key: string;
+    let timeout = 10000;
+
+    if (typeof options === "string") {
+      url = options;
+      key = addonKey ?? "";
+    } else {
+      url = options.addonUrl;
+      key = options.addonKey;
+      timeout = options.timeoutMs ?? 10000;
+    }
+
+    const cleanUrl = url.replace(/\/+$/, "");
+
+    this.client = axios.create({
+      baseURL: cleanUrl,
+      timeout,
+      headers: {
+        "X-Addon-API-Key": key,
+        "Content-Type": "application/json",
+      },
+    });
+  }
+
+  async checkHealth(): Promise<AddonHealthResult> {
+    try {
+      const resp = await this.client.get<AddonHealthResult>("/api/v1/health");
+      return resp.data;
+    } catch (err: any) {
+      throw new ClientError(`Addon health check failed: ${err.message}`, err.response?.status);
+    }
+  }
+
+  async readFile(path: string): Promise<FileReadResult> {
+    try {
+      const resp = await this.client.post<FileReadResult>("/api/v1/file/read", { path });
+      return resp.data;
+    } catch (err: any) {
+      throw new ClientError(`Addon readFile failed: ${err.message}`, err.response?.status);
+    }
+  }
+
+  async writeFile(
+    path: string,
+    content: string,
+    options: { validateYaml?: boolean; label?: string } = {}
+  ): Promise<FileWriteResult> {
+    try {
+      const resp = await this.client.post<FileWriteResult>("/api/v1/file/write", {
+        path,
+        content,
+        validate_yaml: options.validateYaml ?? true,
+        label: options.label ?? "",
+      });
+      return resp.data;
+    } catch (err: any) {
+      throw new ClientError(`Addon writeFile failed: ${err.message}`, err.response?.status);
+    }
+  }
+
+  async listSnapshots(): Promise<SnapshotInfo[]> {
+    try {
+      const resp = await this.client.get<SnapshotInfo[]>("/api/v1/backup/list");
+      return resp.data;
+    } catch (err: any) {
+      throw new ClientError(`Addon listSnapshots failed: ${err.message}`, err.response?.status);
+    }
+  }
+
+  async restoreSnapshot(snapshotId: string): Promise<BackupRestoreResult> {
+    try {
+      const resp = await this.client.post<BackupRestoreResult>("/api/v1/backup/restore", {
+        snapshot_id: snapshotId,
+      });
+      return resp.data;
+    } catch (err: any) {
+      throw new ClientError(`Addon restoreSnapshot failed: ${err.message}`, err.response?.status);
+    }
+  }
+
+  async getLogs(lines: number = 100): Promise<LogsTailResult> {
+    try {
+      const resp = await this.client.get<LogsTailResult>(`/api/v1/logs/tail?lines=${lines}`);
+      return resp.data;
+    } catch (err: any) {
+      throw new ClientError(`Addon getLogs failed: ${err.message}`, err.response?.status);
+    }
+  }
+}
+
+// Backward-compatible alias
+export { AddonAdapter as AddonClient };

package/src/adapters/browser/playwright.adapter.ts

@@ -0,0 +1,186 @@
+import path from "path";
+import os from "os";
+import { Browser, BrowserContext, chromium } from "playwright";
+import { IDashboardRenderer } from "../../domain/ports/renderer.port.js";
+import { DevicePreset, RenderOptions, RenderResult, ViewportDimensions } from "../../domain/models/dashboard.js";
+import { ClientError } from "../../core/errors.js";
+
+export interface RendererConfig {
+  haUrl: string;
+  haToken: string;
+  browserStateDir?: string;
+}
+
+export const DEVICE_PRESETS: Record<DevicePreset, ViewportDimensions> = {
+  desktop: { width: 1920, height: 1080 },
+  tablet: { width: 768, height: 1024 },
+  mobile: { width: 375, height: 812 },
+};
+
+export function resolveViewport(options: RenderOptions): ViewportDimensions {
+  if (options.viewport) {
+    return options.viewport;
+  }
+  if (options.devicePreset && DEVICE_PRESETS[options.devicePreset]) {
+    return DEVICE_PRESETS[options.devicePreset];
+  }
+  return DEVICE_PRESETS.desktop;
+}
+
+export function resolveUrl(baseUrl: string, urlPath: string): string {
+  if (urlPath.startsWith("http://") || urlPath.startsWith("https://")) {
+    return urlPath;
+  }
+  const cleanBase = baseUrl.replace(/\/+$/, "");
+  const cleanPath = urlPath.startsWith("/") ? urlPath.slice(1) : urlPath;
+  return cleanPath ? `${cleanBase}/${cleanPath}` : `${cleanBase}/`;
+}
+
+export class PlaywrightDashboardAdapter implements IDashboardRenderer {
+  private readonly haUrl: string;
+  private readonly haToken: string;
+  private readonly browserStateDir: string;
+  private browser: Browser | null = null;
+
+  constructor(config: RendererConfig) {
+    this.haUrl = config.haUrl.replace(/\/+$/, "");
+    this.haToken = config.haToken;
+    this.browserStateDir = config.browserStateDir || path.join(os.homedir(), ".ha-ai");
+  }
+
+  get isInitialized(): boolean {
+    return this.browser !== null;
+  }
+
+  async initBrowser(headless: boolean = true): Promise<void> {
+    if (!this.browser) {
+      try {
+        this.browser = await chromium.launch({
+          headless,
+          args: ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"],
+        });
+      } catch (err: any) {
+        throw new ClientError(`Failed to launch Chromium browser via Playwright: ${err.message}`);
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.browser) {
+      await this.browser.close();
+      this.browser = null;
+    }
+  }
+
+  resolveViewport(options: RenderOptions): ViewportDimensions {
+    return resolveViewport(options);
+  }
+
+  resolveUrl(urlPath: string): string {
+    return resolveUrl(this.haUrl, urlPath);
+  }
+
+  async setupAuth(context: BrowserContext): Promise<void> {
+    const authData = {
+      access_token: this.haToken,
+      token_type: "Bearer",
+      expires_in: 315360000,
+      hassUrl: this.haUrl,
+    };
+
+    await context.addInitScript(
+      (data) => {
+        try {
+          const storage = (globalThis as any).localStorage;
+          if (storage) {
+            storage.setItem("hassTokens", JSON.stringify(data));
+            storage.setItem("dockedSidebar", '"auto"');
+          }
+        } catch {
+          // ignore in environments without localStorage
+        }
+      },
+      authData
+    );
+  }
+
+  async captureDashboard(options: RenderOptions): Promise<RenderResult> {
+    await this.initBrowser(true);
+
+    if (!this.browser) {
+      throw new ClientError("Browser instance is not initialized");
+    }
+
+    const viewport = this.resolveViewport(options);
+    const targetUrl = this.resolveUrl(options.urlPath);
+    const timeoutMs = options.timeoutMs ?? 15000;
+
+    let colorScheme: "dark" | "light" | "no-preference" = "no-preference";
+    if (options.darkMode === true) {
+      colorScheme = "dark";
+    } else if (options.darkMode === false) {
+      colorScheme = "light";
+    }
+
+    const context = await this.browser.newContext({
+      viewport,
+      colorScheme,
+      deviceScaleFactor: 1,
+    });
+
+    try {
+      await this.setupAuth(context);
+      const page = await context.newPage();
+
+      try {
+        await page.goto(targetUrl, {
+          waitUntil: "domcontentloaded",
+          timeout: timeoutMs,
+        });
+
+        await Promise.race([
+          page.waitForLoadState("networkidle", { timeout: 3000 }),
+          new Promise((resolve) => setTimeout(resolve, 1000)),
+        ]).catch(() => {});
+
+        try {
+          await page.waitForSelector("home-assistant, home-assistant-main, hui-view, ha-card", {
+            timeout: 2000,
+          });
+        } catch {
+          // Continue if selector is delayed
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, 300));
+      } catch (err: any) {
+        throw new ClientError(`Failed loading dashboard at ${targetUrl}: ${err.message}`);
+      }
+
+      let buffer: Buffer;
+
+      if (options.elementSelector) {
+        const element = await page.$(options.elementSelector);
+        if (!element) {
+          throw new ClientError(`Element selector not found on page: ${options.elementSelector}`);
+        }
+        buffer = await element.screenshot({ type: "png" });
+      } else {
+        buffer = await page.screenshot({ type: "png", fullPage: false });
+      }
+
+      const base64Png = buffer.toString("base64");
+
+      return {
+        imageBuffer: buffer,
+        base64Png,
+        width: viewport.width,
+        height: viewport.height,
+        url: targetUrl,
+      };
+    } finally {
+      await context.close();
+    }
+  }
+}
+
+export { PlaywrightDashboardAdapter as DashboardRenderer };

package/src/adapters/ha/ha-rest.adapter.ts

@@ -0,0 +1,82 @@
+import axios, { AxiosInstance } from "axios";
+import { IHARestClient } from "../../domain/ports/ha-client.port.js";
+import { HAEntityState } from "../../domain/models/entity.js";
+import { ClientError } from "../../core/errors.js";
+
+export interface HARestOptions {
+  haUrl: string;
+  haToken: string;
+  timeoutMs?: number;
+}
+
+export class HARestAdapter implements IHARestClient {
+  private readonly client: AxiosInstance;
+
+  constructor(options: HARestOptions | string, haToken?: string) {
+    let url: string;
+    let token: string;
+    let timeout = 10000;
+
+    if (typeof options === "string") {
+      url = options;
+      token = haToken ?? "";
+    } else {
+      url = options.haUrl;
+      token = options.haToken;
+      timeout = options.timeoutMs ?? 10000;
+    }
+
+    const cleanUrl = url.replace(/\/+$/, "");
+
+    this.client = axios.create({
+      baseURL: cleanUrl,
+      timeout,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+    });
+  }
+
+  async checkApi(): Promise<{ message: string }> {
+    try {
+      const resp = await this.client.get<{ message: string }>("/api/");
+      return resp.data;
+    } catch (err: any) {
+      throw new ClientError(`HA REST /api/ check failed: ${err.message}`, err.response?.status);
+    }
+  }
+
+  async getStates(): Promise<HAEntityState[]> {
+    try {
+      const resp = await this.client.get<HAEntityState[]>("/api/states");
+      return resp.data;
+    } catch (err: any) {
+      throw new ClientError(`Failed to fetch HA states: ${err.message}`, err.response?.status);
+    }
+  }
+
+  async callService(domain: string, service: string, serviceData: Record<string, any> = {}): Promise<any> {
+    try {
+      const resp = await this.client.post(`/api/services/${domain}/${service}`, serviceData);
+      return resp.data;
+    } catch (err: any) {
+      throw new ClientError(`Failed calling service ${domain}.${service}: ${err.message}`, err.response?.status);
+    }
+  }
+
+  async getSupervisorLogs(linesCount = 100): Promise<string[]> {
+    try {
+      const resp = await this.client.get<string>("/api/hassio/supervisor/logs", {
+        responseType: "text",
+      });
+      const lines = String(resp.data).split("\n").filter(Boolean);
+      return lines.slice(-linesCount);
+    } catch {
+      return [];
+    }
+  }
+}
+
+// Backward-compatible alias
+export { HARestAdapter as HARestClient };

package/src/adapters/ha/ha-ws.adapter.ts

@@ -0,0 +1,212 @@
+import WebSocket from "ws";
+import { IHAWsClient } from "../../domain/ports/ha-client.port.js";
+import { HAEntityState } from "../../domain/models/entity.js";
+import { ClientError } from "../../core/errors.js";
+
+export interface HAWsOptions {
+  haUrl: string;
+  haToken: string;
+  connectTimeoutMs?: number;
+  requestTimeoutMs?: number;
+}
+
+interface PendingRequest {
+  resolve: (value: any) => void;
+  reject: (reason: any) => void;
+  timer: NodeJS.Timeout;
+}
+
+export class HAWsAdapter implements IHAWsClient {
+  private readonly wsUrl: string;
+  private readonly haToken: string;
+  private readonly connectTimeoutMs: number;
+  private readonly requestTimeoutMs: number;
+  private ws: WebSocket | null = null;
+  private messageId = 1;
+  private pendingRequests = new Map<number, PendingRequest>();
+  private isAuthenticated = false;
+
+  constructor(options: HAWsOptions | string, haToken?: string) {
+    let url: string;
+    let token: string;
+
+    if (typeof options === "string") {
+      url = options;
+      token = haToken ?? "";
+      this.connectTimeoutMs = 10000;
+      this.requestTimeoutMs = 15000;
+    } else {
+      url = options.haUrl;
+      token = options.haToken;
+      this.connectTimeoutMs = options.connectTimeoutMs ?? 10000;
+      this.requestTimeoutMs = options.requestTimeoutMs ?? 15000;
+    }
+
+    this.haToken = token;
+    const cleanUrl = url.replace(/\/+$/, "");
+    if (cleanUrl.startsWith("http://")) {
+      this.wsUrl = `ws://${cleanUrl.slice("http://".length)}/api/websocket`;
+    } else if (cleanUrl.startsWith("https://")) {
+      this.wsUrl = `wss://${cleanUrl.slice("https://".length)}/api/websocket`;
+    } else if (cleanUrl.startsWith("ws://") || cleanUrl.startsWith("wss://")) {
+      this.wsUrl = cleanUrl.endsWith("/api/websocket") ? cleanUrl : `${cleanUrl}/api/websocket`;
+    } else {
+      this.wsUrl = `ws://${cleanUrl}/api/websocket`;
+    }
+  }
+
+  get isConnected(): boolean {
+    return this.isAuthenticated && this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+
+  async connect(): Promise<void> {
+    if (this.ws && this.isAuthenticated && this.ws.readyState === WebSocket.OPEN) {
+      return;
+    }
+
+    return new Promise((resolve, reject) => {
+      let isSettled = false;
+      const timeout = setTimeout(() => {
+        if (!isSettled) {
+          isSettled = true;
+          this.disconnect();
+          reject(new ClientError("HA WebSocket connection timed out"));
+        }
+      }, this.connectTimeoutMs);
+
+      try {
+        this.ws = new WebSocket(this.wsUrl);
+      } catch (err: any) {
+        clearTimeout(timeout);
+        return reject(new ClientError(`WebSocket initialization failed: ${err.message}`));
+      }
+
+      this.ws.on("open", () => {});
+
+      this.ws.on("message", (raw: WebSocket.RawData) => {
+        try {
+          const msg = JSON.parse(raw.toString("utf-8"));
+
+          if (msg.type === "auth_required") {
+            this.ws?.send(JSON.stringify({ type: "auth", access_token: this.haToken }));
+            return;
+          }
+
+          if (msg.type === "auth_ok") {
+            this.isAuthenticated = true;
+            if (!isSettled) {
+              isSettled = true;
+              clearTimeout(timeout);
+              resolve();
+            }
+            return;
+          }
+
+          if (msg.type === "auth_invalid") {
+            this.isAuthenticated = false;
+            if (!isSettled) {
+              isSettled = true;
+              clearTimeout(timeout);
+              reject(new ClientError(`HA WebSocket authentication failed: ${msg.message || "Invalid token"}`));
+            }
+            this.disconnect();
+            return;
+          }
+
+          if (typeof msg.id === "number" && this.pendingRequests.has(msg.id)) {
+            const pending = this.pendingRequests.get(msg.id)!;
+            this.pendingRequests.delete(msg.id);
+            clearTimeout(pending.timer);
+
+            if (msg.success) {
+              pending.resolve(msg.result ?? null);
+            } else {
+              pending.reject(new ClientError(msg.error?.message || `WebSocket command ${msg.id} failed`));
+            }
+          }
+        } catch (err) {
+          // Ignore non-json frames
+        }
+      });
+
+      this.ws.on("error", (err: Error) => {
+        if (!isSettled) {
+          isSettled = true;
+          clearTimeout(timeout);
+          reject(new ClientError(`HA WebSocket error: ${err.message}`));
+        }
+      });
+
+      this.ws.on("close", () => {
+        this.isAuthenticated = false;
+        for (const [id, pending] of this.pendingRequests) {
+          clearTimeout(pending.timer);
+          pending.reject(new ClientError(`WebSocket closed before request ${id} resolved`));
+        }
+        this.pendingRequests.clear();
+      });
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.ws) {
+      try {
+        this.ws.terminate();
+      } catch {
+        // ignore
+      }
+      this.ws = null;
+    }
+    this.isAuthenticated = false;
+  }
+
+  async sendMessage<T = any>(command: Record<string, any>): Promise<T> {
+    return this.sendCommand<T>(command);
+  }
+
+  private async sendCommand<T = any>(command: Record<string, any>): Promise<T> {
+    await this.connect();
+
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new ClientError("WebSocket is not connected");
+    }
+
+    const id = this.messageId++;
+    const payload = { ...command, id };
+
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.pendingRequests.has(id)) {
+          this.pendingRequests.delete(id);
+          reject(new ClientError(`WebSocket command ${id} timed out after ${this.requestTimeoutMs}ms`));
+        }
+      }, this.requestTimeoutMs);
+
+      this.pendingRequests.set(id, { resolve, reject, timer });
+      this.ws!.send(JSON.stringify(payload));
+    });
+  }
+
+  async getLovelaceConfig(urlPath?: string | null): Promise<Record<string, any>> {
+    const cmd: Record<string, any> = { type: "lovelace/config" };
+    if (urlPath) {
+      cmd.url_path = urlPath;
+    }
+    return this.sendCommand<Record<string, any>>(cmd);
+  }
+
+  async saveLovelaceConfig(config: Record<string, any>, urlPath?: string | null): Promise<null> {
+    const cmd: Record<string, any> = { type: "lovelace/config/save", config };
+    if (urlPath) {
+      cmd.url_path = urlPath;
+    }
+    return this.sendCommand<null>(cmd);
+  }
+
+  async fetchStates(): Promise<HAEntityState[]> {
+    return this.sendCommand<HAEntityState[]>({ type: "get_states" });
+  }
+}
+
+// Backward-compatible alias
+export { HAWsAdapter as HAWsClient };

package/src/browser/renderer.ts

@@ -0,0 +1,7 @@
+export * from "../adapters/browser/playwright.adapter.js";
+export {
+  PlaywrightDashboardAdapter as DashboardRenderer,
+  resolveViewport,
+  resolveUrl,
+  DEVICE_PRESETS,
+} from "../adapters/browser/playwright.adapter.js";

package/src/clients/addon-client.ts

@@ -0,0 +1,2 @@
+export * from "../adapters/addon/addon.adapter.js";
+export { AddonAdapter as AddonClient } from "../adapters/addon/addon.adapter.js";

package/src/clients/ha-rest.ts

@@ -0,0 +1,2 @@
+export * from "../adapters/ha/ha-rest.adapter.js";
+export { HARestAdapter as HARestClient } from "../adapters/ha/ha-rest.adapter.js";

package/src/clients/ha-ws.ts

@@ -0,0 +1,2 @@
+export * from "../adapters/ha/ha-ws.adapter.js";
+export { HAWsAdapter as HAWsClient } from "../adapters/ha/ha-ws.adapter.js";

package/src/config.ts

@@ -0,0 +1 @@
+export * from "./core/config.js";

package/src/core/config.ts

@@ -0,0 +1,39 @@
+import os from "os";
+import path from "path";
+import { z } from "zod";
+
+export const ConfigSchema = z.object({
+  HA_URL: z.string().url().default("http://localhost:8123"),
+  HA_TOKEN: z.string().default(""),
+  ADDON_URL: z.string().url().default("http://localhost:8099"),
+  ADDON_KEY: z.string().default(""),
+  BROWSER_STATE_DIR: z.string().default(() => path.join(os.homedir(), ".ha-ai")),
+});
+
+export type RawConfig = z.infer<typeof ConfigSchema>;
+
+export interface AppConfig {
+  haUrl: string;
+  haToken: string;
+  addonUrl: string;
+  addonKey: string;
+  browserStateDir: string;
+}
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): AppConfig {
+  const parsed = ConfigSchema.parse({
+    HA_URL: env.HA_URL,
+    HA_TOKEN: env.HA_TOKEN,
+    ADDON_URL: env.ADDON_URL,
+    ADDON_KEY: env.ADDON_KEY,
+    BROWSER_STATE_DIR: env.BROWSER_STATE_DIR,
+  });
+
+  return {
+    haUrl: parsed.HA_URL.replace(/\/+$/, ""),
+    haToken: parsed.HA_TOKEN,
+    addonUrl: parsed.ADDON_URL.replace(/\/+$/, ""),
+    addonKey: parsed.ADDON_KEY,
+    browserStateDir: parsed.BROWSER_STATE_DIR,
+  };
+}