ha-ai-mcp-server 0.3.8

package/src/tools/automation.ts

@@ -0,0 +1,300 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ToolClients, McpToolResult } from "./types.js";
+
+export const listAutomationsSchema = {
+  domain: z
+    .enum(["automation", "script", "scene"])
+    .optional()
+    .describe("Domain to list (defaults to 'automation')"),
+};
+
+export const readAutomationSchema = {
+  automation_id: z
+    .string()
+    .describe("Automation ID or alias to locate in automations.yaml"),
+};
+
+export const writeAutomationSchema = {
+  automation_id: z
+    .string()
+    .describe("Automation ID to insert or update"),
+  yaml_code: z
+    .string()
+    .describe("YAML configuration block for the automation"),
+  label: z
+    .string()
+    .optional()
+    .describe("Optional snapshot label for safety backup"),
+};
+
+export const triggerAutomationSchema = {
+  entity_id: z
+    .string()
+    .describe("Automation entity_id to trigger (e.g. 'automation.evening_lights')"),
+};
+
+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 async function handleAutomationList(
+  clients: ToolClients,
+  args: { domain?: "automation" | "script" | "scene" }
+): Promise<McpToolResult> {
+  try {
+    const domain = args.domain || "automation";
+    const states = await clients.restClient.getStates();
+
+    const filtered = states
+      .filter((s) => s.entity_id.startsWith(`${domain}.`))
+      .map((s) => ({
+        entity_id: s.entity_id,
+        state: s.state,
+        friendly_name: s.attributes?.friendly_name || s.entity_id,
+        last_triggered: s.attributes?.last_triggered || null,
+        description: s.attributes?.description,
+        mode: s.attributes?.mode,
+        current: s.attributes?.current,
+      }));
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(filtered, null, 2),
+        },
+      ],
+    };
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Failed to list automations: ${error.message || String(error)}`,
+        },
+      ],
+    };
+  }
+}
+
+export async function handleAutomationRead(
+  clients: ToolClients,
+  args: { automation_id: string }
+): Promise<McpToolResult> {
+  try {
+    const fileRes = await clients.addonClient.readFile("automations.yaml");
+    const blocks = splitYamlBlocks(fileRes.content);
+    const targetId = args.automation_id.trim();
+
+    const matchedBlock = blocks.find((b) => blockMatchesIdOrAlias(b, targetId));
+
+    if (!matchedBlock) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Automation "${targetId}" not found in automations.yaml`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: matchedBlock,
+        },
+      ],
+    };
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Failed to read automation: ${error.message || String(error)}`,
+        },
+      ],
+    };
+  }
+}
+
+export async function handleAutomationWrite(
+  clients: ToolClients,
+  args: { automation_id: string; yaml_code: string; label?: string }
+): Promise<McpToolResult> {
+  try {
+    let existingContent = "";
+    try {
+      const fileRes = await clients.addonClient.readFile("automations.yaml");
+      existingContent = fileRes.content;
+    } catch {
+      existingContent = "";
+    }
+
+    const blocks = splitYamlBlocks(existingContent);
+    const targetId = args.automation_id.trim();
+    let formattedNewBlock = args.yaml_code.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, targetId));
+
+    if (existingIndex >= 0) {
+      blocks[existingIndex] = formattedNewBlock;
+    } else {
+      blocks.push(formattedNewBlock);
+    }
+
+    const updatedYaml = blocks.join("\n\n") + "\n";
+    const label = args.label || `Update automation ${targetId}`;
+
+    const writeRes = await clients.addonClient.writeFile("automations.yaml", updatedYaml, {
+      validateYaml: true,
+      label,
+    });
+
+    try {
+      await clients.restClient.callService("automation", "reload");
+    } catch (reloadErr: any) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Automation "${targetId}" written to automations.yaml (Snapshot: ${writeRes.snapshot_id}), but service reload failed: ${reloadErr.message}`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Automation "${targetId}" successfully saved and automations reloaded. Snapshot ID: ${writeRes.snapshot_id}.`,
+        },
+      ],
+    };
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Failed to write automation: ${error.message || String(error)}`,
+        },
+      ],
+    };
+  }
+}
+
+export async function handleAutomationTrigger(
+  clients: ToolClients,
+  args: { entity_id: string }
+): Promise<McpToolResult> {
+  try {
+    const entityId = args.entity_id.trim();
+    const domain = entityId.split(".")[0] || "automation";
+
+    await clients.restClient.callService(domain, "trigger", { entity_id: entityId });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Successfully triggered ${entityId}`,
+        },
+      ],
+    };
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Failed to trigger ${args.entity_id}: ${error.message || String(error)}`,
+        },
+      ],
+    };
+  }
+}
+
+export function registerAutomationTools(server: McpServer, clients: ToolClients): void {
+  server.registerTool(
+    "ha_automation_list",
+    {
+      description: "List all Home Assistant automations, scripts, or scenes with their current states.",
+      inputSchema: listAutomationsSchema,
+    },
+    async (args) => handleAutomationList(clients, args)
+  );
+
+  server.registerTool(
+    "ha_automation_read",
+    {
+      description: "Read the YAML configuration block of a specific automation from automations.yaml.",
+      inputSchema: readAutomationSchema,
+    },
+    async (args) => handleAutomationRead(clients, args)
+  );
+
+  server.registerTool(
+    "ha_automation_write",
+    {
+      description: "Safely create or update an automation in automations.yaml with automated backup snapshot and service reload.",
+      inputSchema: writeAutomationSchema,
+    },
+    async (args) => handleAutomationWrite(clients, args)
+  );
+
+  server.registerTool(
+    "ha_automation_trigger",
+    {
+      description: "Trigger a Home Assistant automation or script entity immediately.",
+      inputSchema: triggerAutomationSchema,
+    },
+    async (args) => handleAutomationTrigger(clients, args)
+  );
+}

package/src/tools/dashboard.ts

@@ -0,0 +1,206 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolClients, McpToolResult } from "./types.js";
+
+export const getDashboardConfigSchema = {
+  dashboard_slug: z
+    .string()
+    .optional()
+    .describe("Dashboard slug (e.g. 'lovelace', 'dashboard-energy', or omit for default)"),
+};
+
+export const saveDashboardConfigSchema = {
+  config_yaml: z
+    .string()
+    .describe("Lovelace configuration content in YAML or JSON format"),
+  dashboard_slug: z
+    .string()
+    .optional()
+    .describe("Dashboard slug (e.g. 'lovelace', 'dashboard-test')"),
+  label: z
+    .string()
+    .optional()
+    .describe("Optional backup/snapshot label description"),
+};
+
+export const renderScreenshotSchema = {
+  url_path: z
+    .string()
+    .describe("Lovelace dashboard URL path to render (e.g. 'lovelace/0', 'dashboard-energy')"),
+  device_preset: z
+    .enum(["desktop", "tablet", "mobile"])
+    .optional()
+    .describe("Device viewport preset ('desktop' = 1920x1080, 'tablet' = 768x1024, 'mobile' = 375x812)"),
+  dark_mode: z
+    .boolean()
+    .optional()
+    .describe("Render with dark mode color scheme emulation"),
+  element_selector: z
+    .string()
+    .optional()
+    .describe("Optional CSS selector to capture an isolated card or component (e.g. '#card-light')"),
+};
+
+export async function handleDashboardGetConfig(
+  clients: ToolClients,
+  args: { dashboard_slug?: string }
+): Promise<McpToolResult> {
+  try {
+    const slug = args.dashboard_slug?.trim() || null;
+    let config: any;
+
+    try {
+      if (clients.wsClient) {
+        config = await clients.wsClient.getLovelaceConfig(slug);
+      }
+    } catch {
+      const fallbackPath = slug && slug !== "lovelace" ? `dashboards/${slug}.yaml` : "ui-lovelace.yaml";
+      const fileRes = await clients.addonClient.readFile(fallbackPath);
+      config = fileRes.content;
+    }
+
+    if (config === undefined || config === null) {
+      const fallbackPath = slug && slug !== "lovelace" ? `dashboards/${slug}.yaml` : "ui-lovelace.yaml";
+      const fileRes = await clients.addonClient.readFile(fallbackPath);
+      config = fileRes.content;
+    }
+
+    const outputText = typeof config === "string" ? config : JSON.stringify(config, null, 2);
+    return {
+      content: [
+        {
+          type: "text",
+          text: outputText,
+        },
+      ],
+    };
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Failed to get dashboard configuration: ${error.message || String(error)}`,
+        },
+      ],
+    };
+  }
+}
+
+export async function handleDashboardSaveConfig(
+  clients: ToolClients,
+  args: { config_yaml: string; dashboard_slug?: string; label?: string }
+): Promise<McpToolResult> {
+  try {
+    const slug = args.dashboard_slug?.trim() || "lovelace";
+    const filePath = slug && slug !== "lovelace" ? `dashboards/${slug}.yaml` : "ui-lovelace.yaml";
+    const label = args.label || `Dashboard update (${slug})`;
+
+    const writeRes = await clients.addonClient.writeFile(filePath, args.config_yaml, {
+      validateYaml: true,
+      label,
+    });
+
+    try {
+      const parsedJson = JSON.parse(args.config_yaml);
+      if (typeof parsedJson === "object" && parsedJson !== null) {
+        await clients.wsClient.saveLovelaceConfig(parsedJson, slug === "lovelace" ? null : slug);
+      }
+    } catch {
+      // Not JSON or WS save skipped; YAML file write succeeded
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Dashboard configuration successfully saved for "${slug}". Snapshot ID: ${writeRes.snapshot_id} (${writeRes.bytes_written} bytes written to ${writeRes.path}).`,
+        },
+      ],
+    };
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Failed to save dashboard configuration: ${error.message || String(error)}`,
+        },
+      ],
+    };
+  }
+}
+
+export async function handleDashboardRenderScreenshot(
+  clients: ToolClients,
+  args: {
+    url_path: string;
+    device_preset?: "desktop" | "tablet" | "mobile";
+    dark_mode?: boolean;
+    element_selector?: string;
+  }
+): Promise<McpToolResult> {
+  try {
+    const result = await clients.renderer.captureDashboard({
+      urlPath: args.url_path,
+      devicePreset: args.device_preset,
+      darkMode: args.dark_mode,
+      elementSelector: args.element_selector,
+    });
+
+    return {
+      content: [
+        {
+          type: "image",
+          data: result.base64Png,
+          mimeType: "image/png",
+        },
+        {
+          type: "text",
+          text: `Dashboard screenshot rendered for ${result.url} (${result.width}x${result.height})${
+            args.element_selector ? ` [selector: ${args.element_selector}]` : ""
+          }`,
+        },
+      ],
+    };
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Failed to capture dashboard screenshot: ${error.message || String(error)}`,
+        },
+      ],
+    };
+  }
+}
+
+export function registerDashboardTools(server: McpServer, clients: ToolClients): void {
+  server.registerTool(
+    "ha_dashboard_get_config",
+    {
+      description: "Retrieve Home Assistant Lovelace dashboard configuration via WebSocket or storage file.",
+      inputSchema: getDashboardConfigSchema,
+    },
+    async (args) => handleDashboardGetConfig(clients, args)
+  );
+
+  server.registerTool(
+    "ha_dashboard_save_config",
+    {
+      description: "Validate, snapshot, and save Home Assistant Lovelace dashboard configuration.",
+      inputSchema: saveDashboardConfigSchema,
+    },
+    async (args) => handleDashboardSaveConfig(clients, args)
+  );
+
+  server.registerTool(
+    "ha_dashboard_render_screenshot",
+    {
+      description: "Render a high-resolution screenshot of a Home Assistant dashboard or card via headless browser.",
+      inputSchema: renderScreenshotSchema,
+    },
+    async (args) => handleDashboardRenderScreenshot(clients, args)
+  );
+}