ha-ai-mcp-server 0.3.8

package/src/core/errors.ts

@@ -0,0 +1,28 @@
+/**
+ * Application domain errors.
+ */
+
+export class AppError extends Error {
+  constructor(message: string, public readonly code: string = "APP_ERROR") {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+export class ConfigurationError extends AppError {
+  constructor(message: string) {
+    super(message, "CONFIG_ERROR");
+  }
+}
+
+export class ClientError extends AppError {
+  constructor(message: string, public readonly statusCode?: number) {
+    super(message, "CLIENT_ERROR");
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string) {
+    super(message, "VALIDATION_ERROR");
+  }
+}

package/src/core/logger.ts

@@ -0,0 +1,27 @@
+/**
+ * Safe logger routing diagnostic messages strictly to stderr to preserve stdio MCP transport integrity.
+ */
+
+export class Logger {
+  constructor(private readonly context: string = "App") {}
+
+  info(message: string, ...args: any[]): void {
+    console.error(`[INFO] [${this.context}] ${message}`, ...args);
+  }
+
+  warn(message: string, ...args: any[]): void {
+    console.error(`[WARN] [${this.context}] ${message}`, ...args);
+  }
+
+  error(message: string, error?: any): void {
+    console.error(`[ERROR] [${this.context}] ${message}`, error ?? "");
+  }
+
+  debug(message: string, ...args: any[]): void {
+    if (process.env.DEBUG) {
+      console.error(`[DEBUG] [${this.context}] ${message}`, ...args);
+    }
+  }
+}
+
+export const defaultLogger = new Logger("HA-AI");

package/src/domain/models/automation.ts

@@ -0,0 +1,19 @@
+export interface AutomationSummary {
+  entity_id: string;
+  id?: string;
+  alias?: string;
+  state: string;
+  description?: string;
+  last_triggered?: string | null;
+}
+
+export interface AutomationBlock {
+  id?: string;
+  alias?: string;
+  description?: string;
+  trigger?: any[];
+  condition?: any[];
+  action?: any[];
+  mode?: "single" | "restart" | "queued" | "parallel";
+  [key: string]: any;
+}

package/src/domain/models/dashboard.ts

@@ -0,0 +1,23 @@
+export type DevicePreset = "desktop" | "tablet" | "mobile";
+
+export interface ViewportDimensions {
+  width: number;
+  height: number;
+}
+
+export interface RenderOptions {
+  urlPath: string;
+  viewport?: ViewportDimensions;
+  devicePreset?: DevicePreset;
+  darkMode?: boolean;
+  elementSelector?: string;
+  timeoutMs?: number;
+}
+
+export interface RenderResult {
+  imageBuffer: Buffer;
+  base64Png: string;
+  width: number;
+  height: number;
+  url: string;
+}

package/src/domain/models/entity.ts

@@ -0,0 +1,13 @@
+export interface HAEntityState {
+  entity_id: string;
+  state: string;
+  attributes: Record<string, any>;
+  last_changed?: string;
+  last_updated?: string;
+  context?: Record<string, any>;
+}
+
+export interface EntityFilter {
+  domain?: string;
+  query?: string;
+}

package/src/domain/models/system.ts

@@ -0,0 +1,37 @@
+export interface SystemHealth {
+  status: "ok" | "degraded" | "error";
+  homeAssistant: {
+    reachable: boolean;
+    message?: string;
+  };
+  addon: {
+    reachable: boolean;
+    version?: string;
+    configRoot?: string;
+    snapshotsCount?: number;
+    memoryMb?: number;
+    error?: string;
+  };
+}
+
+export interface SnapshotInfo {
+  snapshot_id: string;
+  original_relative_path: string;
+  created_at: string;
+  size_bytes: number;
+  label: string;
+  is_new_file?: boolean;
+  backup_filename?: string;
+}
+
+export interface BackupRestoreResult {
+  success: boolean;
+  restored_file: string;
+  restored_from: string;
+  safety_backup: string;
+}
+
+export interface LogsTailResult {
+  lines: string[];
+  count: number;
+}

package/src/domain/ports/addon-client.port.ts

@@ -0,0 +1,35 @@
+import { BackupRestoreResult, LogsTailResult, SnapshotInfo } from "../models/system.js";
+
+export interface FileReadResult {
+  path: string;
+  content: string;
+  size_bytes: number;
+}
+
+export interface FileWriteResult {
+  success: boolean;
+  path: string;
+  snapshot_id: string;
+  bytes_written: number;
+}
+
+export interface AddonHealthResult {
+  status: string;
+  version: string;
+  config_root: string;
+  snapshots_count: number;
+  memory_mb: number;
+}
+
+export interface IAddonClient {
+  checkHealth(): Promise<AddonHealthResult>;
+  readFile(path: string): Promise<FileReadResult>;
+  writeFile(
+    path: string,
+    content: string,
+    options?: { validateYaml?: boolean; label?: string }
+  ): Promise<FileWriteResult>;
+  listSnapshots(): Promise<SnapshotInfo[]>;
+  restoreSnapshot(snapshotId: string): Promise<BackupRestoreResult>;
+  getLogs(lines?: number): Promise<LogsTailResult>;
+}

package/src/domain/ports/ha-client.port.ts

@@ -0,0 +1,16 @@
+import { HAEntityState } from "../models/entity.js";
+
+export interface IHARestClient {
+  checkApi(): Promise<{ message: string }>;
+  getStates(): Promise<HAEntityState[]>;
+  callService(domain: string, service: string, serviceData?: Record<string, any>): Promise<any>;
+  getSupervisorLogs(linesCount?: number): Promise<string[]>;
+}
+
+export interface IHAWsClient {
+  connect(): Promise<void>;
+  disconnect(): void | Promise<void>;
+  getLovelaceConfig(urlPath?: string | null): Promise<Record<string, any>>;
+  saveLovelaceConfig(config: Record<string, any>, urlPath?: string | null): Promise<any>;
+  fetchStates(): Promise<HAEntityState[]>;
+}

package/src/domain/ports/renderer.port.ts

@@ -0,0 +1,7 @@
+import { RenderOptions, RenderResult } from "../models/dashboard.js";
+
+export interface IDashboardRenderer {
+  initBrowser(headless?: boolean): Promise<void>;
+  close(): Promise<void>;
+  captureDashboard(options: RenderOptions): Promise<RenderResult>;
+}

package/src/index.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { fileURLToPath } from "url";
+import path from "path";
+
+import { loadConfig } from "./core/config.js";
+import { defaultLogger } from "./core/logger.js";
+import { HARestAdapter } from "./adapters/ha/ha-rest.adapter.js";
+import { HAWsAdapter } from "./adapters/ha/ha-ws.adapter.js";
+import { AddonAdapter } from "./adapters/addon/addon.adapter.js";
+import { PlaywrightDashboardAdapter } from "./adapters/browser/playwright.adapter.js";
+import { registerDashboardTools } from "./tools/dashboard.js";
+import { registerAutomationTools } from "./tools/automation.js";
+import { registerSystemTools } from "./tools/system.js";
+import type { ToolClients } from "./tools/types.js";
+
+export function createClients(): ToolClients {
+  const config = loadConfig();
+  const restClient = new HARestAdapter({ haUrl: config.haUrl, haToken: config.haToken });
+  const wsClient = new HAWsAdapter({ haUrl: config.haUrl, haToken: config.haToken });
+  const addonClient = new AddonAdapter({ addonUrl: config.addonUrl, addonKey: config.addonKey });
+  const renderer = new PlaywrightDashboardAdapter({
+    haUrl: config.haUrl,
+    haToken: config.haToken,
+    browserStateDir: config.browserStateDir,
+  });
+
+  return { restClient, wsClient, addonClient, renderer };
+}
+
+export function createServer(providedClients?: ToolClients): {
+  server: McpServer;
+  clients: ToolClients;
+} {
+  const clients = providedClients || createClients();
+
+  const server = new McpServer({
+    name: "ha-ai-mcp",
+    version: "1.0.0",
+  });
+
+  registerDashboardTools(server, clients);
+  registerAutomationTools(server, clients);
+  registerSystemTools(server, clients);
+
+  return { server, clients };
+}
+
+// Backward-compatible alias
+export const createMcpServer = createServer;
+
+async function main(): Promise<void> {
+  const { server, clients } = createServer();
+  const transport = new StdioServerTransport();
+
+  const cleanup = async () => {
+    defaultLogger.info("Shutting down Home Assistant AI MCP Server...");
+    try {
+      clients.wsClient.disconnect();
+      await clients.renderer.close();
+      await server.close();
+    } catch {
+      // Ignore teardown errors during exit
+    }
+    process.exit(0);
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+
+  try {
+    await server.connect(transport);
+    defaultLogger.info("Home Assistant AI MCP Server running on stdio.");
+  } catch (err: any) {
+    defaultLogger.error("Fatal MCP Server startup error:", err);
+    process.exit(1);
+  }
+}
+
+const isDirectEntrypoint = (): boolean => {
+  if (!process.argv[1]) return false;
+  try {
+    const currentFilePath = fileURLToPath(import.meta.url).toLowerCase();
+    const executedScriptPath = path.resolve(process.argv[1]).toLowerCase();
+    const normalizedArg = process.argv[1].replace(/\\/g, "/").toLowerCase();
+    return (
+      currentFilePath === executedScriptPath ||
+      normalizedArg.endsWith("dist/index.js") ||
+      normalizedArg.endsWith("src/index.ts")
+    );
+  } catch {
+    return false;
+  }
+};
+
+if (isDirectEntrypoint()) {
+  main().catch((err) => {
+    defaultLogger.error("Unhandled top-level error:", err);
+    process.exit(1);
+  });
+}

package/src/services/automation.service.ts

@@ -0,0 +1,142 @@
+import { IHARestClient } from "../domain/ports/ha-client.port.js";
+import { IAddonClient } from "../domain/ports/addon-client.port.js";
+import { AutomationSummary } from "../domain/models/automation.js";
+import { ValidationError } from "../core/errors.js";
+
+function splitYamlBlocks(yamlContent: string): string[] {
+  if (!yamlContent.trim()) {
+    return [];
+  }
+  const lines = yamlContent.split("\n");
+  const blocks: string[] = [];
+  let currentBlock: string[] = [];
+
+  for (const line of lines) {
+    if (line.startsWith("- ") && currentBlock.length > 0) {
+      blocks.push(currentBlock.join("\n").trim());
+      currentBlock = [line];
+    } else {
+      currentBlock.push(line);
+    }
+  }
+
+  if (currentBlock.length > 0) {
+    const trimmed = currentBlock.join("\n").trim();
+    if (trimmed) {
+      blocks.push(trimmed);
+    }
+  }
+
+  return blocks;
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function blockMatchesIdOrAlias(block: string, targetId: string): boolean {
+  const idRegex = new RegExp(`(^|\\n)\\s*-\\s*id:\\s*['"]?${escapeRegex(targetId)}['"]?(\\s|$)|(^|\\n)\\s*id:\\s*['"]?${escapeRegex(targetId)}['"]?(\\s|$)`, "i");
+  const aliasRegex = new RegExp(`(^|\\n)\\s*alias:\\s*['"]?${escapeRegex(targetId)}['"]?(\\s|$)`, "i");
+  return idRegex.test(block) || aliasRegex.test(block);
+}
+
+export class AutomationService {
+  constructor(
+    private readonly restClient: IHARestClient,
+    private readonly addonClient: IAddonClient
+  ) {}
+
+  async listAutomations(domain: "automation" | "script" | "scene" = "automation"): Promise<AutomationSummary[]> {
+    const states = await this.restClient.getStates();
+    const prefix = `${domain}.`;
+
+    return states
+      .filter((s) => s.entity_id.startsWith(prefix))
+      .map((s) => ({
+        entity_id: s.entity_id,
+        id: s.attributes?.id || s.entity_id.replace(prefix, ""),
+        alias: s.attributes?.friendly_name || s.attributes?.alias,
+        state: s.state,
+        description: s.attributes?.description,
+        last_triggered: s.attributes?.last_triggered || null,
+      }));
+  }
+
+  async readAutomation(automationId: string): Promise<string> {
+    const cleanId = automationId.replace(/^automation\./, "").trim();
+    const file = await this.addonClient.readFile("automations.yaml");
+    const blocks = splitYamlBlocks(file.content);
+
+    const matchedBlock = blocks.find((b) => blockMatchesIdOrAlias(b, cleanId));
+    if (!matchedBlock) {
+      throw new ValidationError(`Automation "${cleanId}" not found in automations.yaml`);
+    }
+
+    return matchedBlock;
+  }
+
+  async writeAutomation(
+    automationId: string,
+    yamlCode: string,
+    label?: string
+  ): Promise<{ success: boolean; snapshotId: string; path: string }> {
+    const cleanId = automationId.replace(/^automation\./, "").trim();
+
+    let existingContent = "";
+    try {
+      const fileRes = await this.addonClient.readFile("automations.yaml");
+      existingContent = fileRes.content;
+    } catch {
+      existingContent = "";
+    }
+
+    const blocks = splitYamlBlocks(existingContent);
+    let formattedNewBlock = yamlCode.trim();
+
+    if (!formattedNewBlock.startsWith("- ")) {
+      const lines = formattedNewBlock.split("\n");
+      const firstLine = `- ${lines[0]}`;
+      const restLines = lines.slice(1).map((l) => (l.trim() ? `  ${l}` : l));
+      formattedNewBlock = [firstLine, ...restLines].join("\n");
+    }
+
+    const existingIndex = blocks.findIndex((b) => blockMatchesIdOrAlias(b, cleanId));
+    if (existingIndex >= 0) {
+      blocks[existingIndex] = formattedNewBlock;
+    } else {
+      blocks.push(formattedNewBlock);
+    }
+
+    const updatedYaml = blocks.join("\n\n") + "\n";
+    const snapshotLabel = label || `Update automation ${cleanId}`;
+
+    const writeRes = await this.addonClient.writeFile("automations.yaml", updatedYaml, {
+      validateYaml: true,
+      label: snapshotLabel,
+    });
+
+    try {
+      await this.restClient.callService("automation", "reload");
+    } catch {
+      // Reload is best-effort
+    }
+
+    return {
+      success: true,
+      snapshotId: writeRes.snapshot_id,
+      path: writeRes.path,
+    };
+  }
+
+  async triggerAutomation(entityId: string): Promise<{ success: boolean; entityId: string }> {
+    const cleanEntityId = entityId.trim();
+    const domain = cleanEntityId.split(".")[0] || "automation";
+
+    await this.restClient.callService(domain, "trigger", { entity_id: cleanEntityId });
+
+    return {
+      success: true,
+      entityId: cleanEntityId,
+    };
+  }
+}

package/src/services/dashboard.service.ts

@@ -0,0 +1,83 @@
+import { IHAWsClient } from "../domain/ports/ha-client.port.js";
+import { IAddonClient } from "../domain/ports/addon-client.port.js";
+import { IDashboardRenderer } from "../domain/ports/renderer.port.js";
+import { RenderOptions, RenderResult } from "../domain/models/dashboard.js";
+
+export class DashboardService {
+  constructor(
+    private readonly wsClient: IHAWsClient,
+    private readonly addonClient: IAddonClient,
+    private readonly renderer: IDashboardRenderer
+  ) {}
+
+  async getConfig(dashboardSlug?: string): Promise<{ source: string; config: any; rawContent?: string }> {
+    try {
+      const config = await this.wsClient.getLovelaceConfig(dashboardSlug ?? null);
+      if (config) {
+        return {
+          source: "websocket",
+          config,
+          rawContent: JSON.stringify(config, null, 2),
+        };
+      }
+    } catch {
+      // Fallback to Addon file read
+    }
+
+    const candidatePaths = dashboardSlug && dashboardSlug !== "lovelace"
+      ? [`dashboards/${dashboardSlug}.yaml`, `.storage/lovelace.${dashboardSlug}`]
+      : ["ui-lovelace.yaml", ".storage/lovelace"];
+
+    for (const filePath of candidatePaths) {
+      try {
+        const file = await this.addonClient.readFile(filePath);
+        return {
+          source: `addon_file:${filePath}`,
+          config: file.content,
+          rawContent: file.content,
+        };
+      } catch {
+        continue;
+      }
+    }
+
+    return {
+      source: "empty",
+      config: { title: "Home", views: [] },
+      rawContent: "title: Home\nviews: []\n",
+    };
+  }
+
+  async saveConfig(
+    configYaml: string,
+    dashboardSlug?: string,
+    label: string = "mcp-dashboard-update"
+  ): Promise<{ success: boolean; snapshotId?: string; message: string }> {
+    const slug = dashboardSlug?.trim() || "lovelace";
+    const targetFile = slug !== "lovelace" ? `dashboards/${slug}.yaml` : "ui-lovelace.yaml";
+
+    const writeResult = await this.addonClient.writeFile(targetFile, configYaml, {
+      validateYaml: true,
+      label,
+    });
+
+    try {
+      const parsed = JSON.parse(configYaml);
+      if (typeof parsed === "object" && parsed !== null) {
+        await this.wsClient.saveLovelaceConfig(parsed, slug === "lovelace" ? null : slug);
+      }
+    } catch {
+      // Not JSON or WS save skipped; YAML file write succeeded
+    }
+
+    return {
+      success: true,
+      snapshotId: writeResult.snapshot_id,
+      message: `Dashboard configuration successfully saved to "${targetFile}". Pre-edit snapshot ID: ${writeResult.snapshot_id}.`,
+    };
+  }
+
+  async renderScreenshot(options: RenderOptions): Promise<RenderResult> {
+    return this.renderer.captureDashboard(options);
+  }
+}

package/src/services/system.service.ts

@@ -0,0 +1,94 @@
+import { IHARestClient } from "../domain/ports/ha-client.port.js";
+import { IAddonClient } from "../domain/ports/addon-client.port.js";
+import { BackupRestoreResult, LogsTailResult, SnapshotInfo, SystemHealth } from "../domain/models/system.js";
+import { HAEntityState } from "../domain/models/entity.js";
+
+export class SystemService {
+  constructor(
+    private readonly restClient: IHARestClient,
+    private readonly addonClient: IAddonClient
+  ) {}
+
+  async getHealth(): Promise<SystemHealth> {
+    let haOk = false;
+    let haMsg = "";
+    try {
+      const resp = await this.restClient.checkApi();
+      haOk = true;
+      haMsg = resp.message || "API running";
+    } catch (err: any) {
+      haMsg = err.message;
+    }
+
+    let addonOk = false;
+    let addonInfo: any = {};
+    try {
+      const health = await this.addonClient.checkHealth();
+      addonOk = true;
+      addonInfo = health;
+    } catch (err: any) {
+      addonInfo = { error: err.message };
+    }
+
+    const overallStatus: "ok" | "degraded" | "error" =
+      haOk && addonOk ? "ok" : haOk || addonOk ? "degraded" : "error";
+
+    return {
+      status: overallStatus,
+      homeAssistant: {
+        reachable: haOk,
+        message: haMsg,
+      },
+      addon: {
+        reachable: addonOk,
+        version: addonInfo.version,
+        configRoot: addonInfo.config_root,
+        snapshotsCount: addonInfo.snapshots_count,
+        memoryMb: addonInfo.memory_mb,
+        error: addonInfo.error,
+      },
+    };
+  }
+
+  async listEntities(domainFilter?: string, searchQuery?: string): Promise<HAEntityState[]> {
+    const states = await this.restClient.getStates();
+
+    return states.filter((s) => {
+      if (domainFilter && !s.entity_id.startsWith(`${domainFilter}.`)) {
+        return false;
+      }
+      if (searchQuery) {
+        const q = searchQuery.toLowerCase();
+        const entityMatches = s.entity_id.toLowerCase().includes(q);
+        const nameMatches = String(s.attributes?.friendly_name || "").toLowerCase().includes(q);
+        if (!entityMatches && !nameMatches) {
+          return false;
+        }
+      }
+      return true;
+    });
+  }
+
+  async getLogs(lines: number = 100): Promise<LogsTailResult> {
+    return this.addonClient.getLogs(lines);
+  }
+
+  async createBackup(label: string = "manual-checkpoint"): Promise<{ snapshot_id: string; label: string }> {
+    const res = await this.addonClient.writeFile("automations.yaml", "", {
+      validateYaml: false,
+      label,
+    });
+    return {
+      snapshot_id: res.snapshot_id,
+      label,
+    };
+  }
+
+  async listSnapshots(): Promise<SnapshotInfo[]> {
+    return this.addonClient.listSnapshots();
+  }
+
+  async restoreBackup(snapshotId: string): Promise<BackupRestoreResult> {
+    return this.addonClient.restoreSnapshot(snapshotId);
+  }
+}