@coffeerunhobby/mcp-ha-connect 2.1.0 → 2.2.0

package/src/tools/homeassistant/askOwner.ts

@@ -0,0 +1,133 @@
+/**
+ * Owner question tools: askOwner / getOwnerAnswer / cancelOwnerQuestion.
+ * See src/ownerQuestions/service.ts for the design.
+ */
+
+import type { McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+
+import { LIMITS, type OwnerQuestionService } from '../../ownerQuestions/service.js';
+import { validatePlainText } from '../../utils/plainText.js';
+import { toToolResult, wrapToolHandler, Permission, type ToolExtra } from '../common.js';
+
+const plainText = (field: string, maxLength: number, allowNewlines = false) =>
+    z.string().transform((value, ctx) => {
+        try {
+            return validatePlainText(value, { field, maxLength, allowNewlines });
+        } catch (error) {
+            ctx.addIssue({ code: 'custom', message: error instanceof Error ? error.message : String(error) });
+            return z.NEVER;
+        }
+    });
+
+export const askOwnerSchema = z.object({
+    question: plainText('question', LIMITS.questionChars, true).describe(
+        `The question, plain text only (no emoji), at most ${LIMITS.questionChars} characters; longer text is refused, not cut`
+    ),
+    title: plainText('title', LIMITS.titleChars).optional().describe(`Notification title, at most ${LIMITS.titleChars} characters (default "Approval needed")`),
+    buttons: z
+        .array(plainText('button label', LIMITS.buttonChars))
+        .min(1)
+        .max(LIMITS.maxButtons)
+        .refine((labels) => new Set(labels.map((l) => l.toLowerCase())).size === labels.length, 'Button labels must be unique')
+        .optional()
+        .describe('1-3 button labels; default ["Approve", "Deny"]. The answer reports the tapped index (0 = first).'),
+    target: z
+        .string()
+        .regex(/^mobile_app_[a-z0-9_]{1,64}$/, 'target must be a mobile app notify service, e.g. "mobile_app_pixel_7"')
+        .describe('The phone to ask: its notify service name, e.g. "mobile_app_pixel_7"'),
+    timeoutSeconds: z
+        .number()
+        .int()
+        .min(LIMITS.minTimeoutSeconds)
+        .max(LIMITS.maxTimeoutSeconds)
+        .optional()
+        .describe(`How long the question stays open (default ${LIMITS.defaultTimeoutSeconds} s, max 7 days). No answer by then = timeout, treat as NO.`),
+    channel: plainText('channel', 40).optional().describe('Android notification channel name'),
+    importance: z.enum(['high', 'default', 'low', 'min']).optional().describe('Android notification channel importance'),
+});
+
+const requestIdSchema = z.string().min(1).max(4096).describe('The requestId returned by askOwner');
+
+export const getOwnerAnswerSchema = z.object({
+    requestId: requestIdSchema,
+    waitSeconds: z
+        .number()
+        .int()
+        .min(0)
+        .max(LIMITS.maxWaitSeconds)
+        .optional()
+        .describe(`Wait up to this many seconds for an answer before returning "pending" (default 25, max ${LIMITS.maxWaitSeconds})`),
+});
+
+export const cancelOwnerQuestionSchema = z.object({ requestId: requestIdSchema });
+
+/** The token `sub` of the caller; stdio (local trust) has none. */
+function callerOf(extra: ToolExtra): string {
+    return extra.http?.authInfo?.clientId ?? 'local';
+}
+
+export function registerOwnerQuestionTools(server: McpServer, service: OwnerQuestionService): number {
+    server.registerTool(
+        'askOwner',
+        {
+            description:
+                "Ask the owner a question on their phone with up to 3 buttons (default Approve / Deny) and return immediately with a requestId. " +
+                'Then call getOwnerAnswer(requestId) until the status is not "pending". ' +
+                'Anything except an explicit approving answer must be treated as NO: deny, timeout, cancelled and unknown. ' +
+                'The owner may be away from the phone for hours; use a timeout that fits.',
+            inputSchema: askOwnerSchema,
+        },
+        wrapToolHandler(
+            'askOwner',
+            async (args: z.infer<typeof askOwnerSchema>, extra: ToolExtra) =>
+                toToolResult(
+                    await service.ask(
+                        {
+                            question: args.question,
+                            title: args.title ?? 'Approval needed',
+                            buttons: args.buttons ?? ['Approve', 'Deny'],
+                            target: args.target,
+                            timeoutSeconds: args.timeoutSeconds ?? LIMITS.defaultTimeoutSeconds,
+                            channel: args.channel,
+                            importance: args.importance,
+                        },
+                        callerOf(extra)
+                    )
+                ),
+            Permission.NOTIFY
+        )
+    );
+
+    server.registerTool(
+        'getOwnerAnswer',
+        {
+            description:
+                'Get the answer to an askOwner question, waiting up to waitSeconds. Status: "answered" (with index, button, answeredAt, answeredBy), ' +
+                '"pending" (ask again), "timeout", "cancelled" or "unknown". Only the client that asked can read the answer.',
+            inputSchema: getOwnerAnswerSchema,
+        },
+        wrapToolHandler(
+            'getOwnerAnswer',
+            async (args: z.infer<typeof getOwnerAnswerSchema>, extra: ToolExtra) =>
+                toToolResult(await service.getAnswer(args.requestId, callerOf(extra), args.waitSeconds ?? 25)),
+            Permission.NOTIFY
+        )
+    );
+
+    server.registerTool(
+        'cancelOwnerQuestion',
+        {
+            description: 'Withdraw an open askOwner question; the phone notification changes to "Cancelled". Returns the final status.',
+            inputSchema: cancelOwnerQuestionSchema,
+        },
+        wrapToolHandler(
+            'cancelOwnerQuestion',
+            async (args: z.infer<typeof cancelOwnerQuestionSchema>, extra: ToolExtra) =>
+                toToolResult(await service.cancel(args.requestId, callerOf(extra))),
+            Permission.NOTIFY
+        )
+    );
+
+    return 3;
+}

package/src/tools/homeassistant/getAutomationTrace.ts

@@ -3,22 +3,28 @@
  */
 
 import type { McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
 import type { HaClient } from '../../haClient/index.js';
 import { entityIdSchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
-import type { z } from 'zod';
 
-type EntityIdArgs = z.infer<typeof entityIdSchema>;
+export const getAutomationTraceSchema = entityIdSchema.extend({
+  limit: z.number().int().min(1).max(20).optional().describe('How many of the most recent runs to return (default 5, max 20)'),
+});
+
+type GetAutomationTraceArgs = z.infer<typeof getAutomationTraceSchema>;
 
 export function registerGetAutomationTraceTool(server: McpServer, client: HaClient): void {
   server.registerTool(
     'getAutomationTrace',
     {
-      description: 'Get the execution trace (history) of an automation. Shows when it was triggered and what actions were executed.',
-      inputSchema: entityIdSchema,
+      description:
+        'Get the most recent runs of an automation, newest first: when it ran, what triggered it, how it ended (state, last step, error). ' +
+        'Only automations with an id (created in the UI, or YAML with an id) have traces.',
+      inputSchema: getAutomationTraceSchema,
     },
-    wrapToolHandler('getAutomationTrace', async ({ entity_id }: EntityIdArgs) => {
-      const trace = await client.getAutomationTrace(entity_id);
-      return toToolResult({ entity_id, trace_count: Array.isArray(trace) ? trace.length : 0, traces: trace });
+    wrapToolHandler('getAutomationTrace', async ({ entity_id, limit }: GetAutomationTraceArgs) => {
+      const traces = await client.getAutomationTrace(entity_id, limit);
+      return toToolResult({ entity_id, trace_count: traces.length, traces });
     }, Permission.QUERY)
   );
 }

package/src/tools/index.ts

@@ -13,6 +13,8 @@ import { registerHomeAssistantTools } from './homeassistant/index.js';
 import { registerOmadaTools, type OmadaRegistrationMode } from './omada/index.js';
 import { registerAITools } from './ai/index.js';
 import { registerInfraTools, type RestAction } from './infra/index.js';
+import { registerOwnerQuestionTools } from './homeassistant/askOwner.js';
+import type { OwnerQuestionService } from '../ownerQuestions/service.js';
 
 export interface RegisterToolsOptions {
   server: McpServer;
@@ -23,13 +25,15 @@ export interface RegisterToolsOptions {
   restActions?: Record<string, RestAction>;
   /** Tool registration strategy for the Omada plugin (default 'eager'). */
   toolRegistrationMode?: OmadaRegistrationMode;
+  /** Owner questions (askOwner & co.); registered only when the service is running. */
+  ownerQuestions?: OwnerQuestionService;
 }
 
 /**
  * Register all available tools based on configured clients
  */
 export function registerAllTools(options: RegisterToolsOptions): void {
-  const { server, haClient, omadaClient, aiClient, restActions, toolRegistrationMode } = options;
+  const { server, haClient, omadaClient, aiClient, restActions, toolRegistrationMode, ownerQuestions } = options;
   logger.debug('Registering all tools');
 
   let totalTools = 0;
@@ -38,6 +42,9 @@ export function registerAllTools(options: RegisterToolsOptions): void {
   if (haClient) {
     const haToolCount = registerHomeAssistantTools(server, haClient);
     totalTools += haToolCount;
+    if (ownerQuestions) {
+      totalTools += registerOwnerQuestionTools(server, ownerQuestions);
+    }
   }
 
   // Omada tools (if client provided)

package/src/utils/plainText.ts

@@ -0,0 +1,48 @@
+/**
+ * Plain-text validation for user-visible strings we put on the owner's phone.
+ *
+ * Text is NFC-normalized first (so composed letters such as Romanian ș/ț/ă count
+ * as one character), then every character must be a letter, digit, punctuation,
+ * a math/currency/modifier symbol, the degree sign, or a plain space; line
+ * breaks only where allowed. Everything else is refused, never stripped:
+ * emoji and pictographs, control and invisible format characters (zero-width
+ * joiners, bidi overrides that make text display differently than it reads),
+ * variation selectors and leftover combining marks ("zalgo"), private-use and
+ * lone surrogates.
+ */
+
+const ALLOWED_CHAR = /^[\p{L}\p{N}\p{P}\p{Sm}\p{Sc}\p{Sk}° ]$/u;
+
+export interface PlainTextOptions {
+    field: string;
+    maxLength: number;
+    allowNewlines?: boolean;
+}
+
+/**
+ * @returns the NFC-normalized text
+ * @throws Error naming the field and the first offending character
+ */
+export function validatePlainText(text: string, options: PlainTextOptions): string {
+    const normalized = text.normalize('NFC');
+    const chars = [...normalized];
+    if (chars.length === 0 || normalized.trim() === '') {
+        throw new Error(`${options.field} must not be empty`);
+    }
+    if (chars.length > options.maxLength) {
+        throw new Error(`${options.field} is ${chars.length} characters; the maximum is ${options.maxLength}`);
+    }
+    for (const [index, char] of chars.entries()) {
+        if (char === '\n' && options.allowNewlines) {
+            continue;
+        }
+        if (!ALLOWED_CHAR.test(char)) {
+            const codePoint = char.codePointAt(0)!.toString(16).toUpperCase().padStart(4, '0');
+            throw new Error(
+                `${options.field} contains a disallowed character U+${codePoint} at position ${index + 1}; ` +
+                'only plain text is accepted (no emoji, control or invisible characters)'
+            );
+        }
+    }
+    return normalized;
+}

package/src/version.ts

@@ -2,4 +2,4 @@
  * Package version - hardcoded at build time for reliability
  * Keep in sync with package.json version
  */
-export const VERSION = '2.1.0';
+export const VERSION = '2.2.0';

package/tests/config.test.ts

@@ -37,6 +37,18 @@ describe('loadConfig', () => {
     expect(config.stateful).toBe(false);
   });
 
+  it('parses owner question settings (enabled by default; HA users as a trimmed list)', () => {
+    const base = { HA_URL: 'http://homeassistant.10.0.0.19.nip.io:8123', HA_TOKEN: 't' };
+
+    const defaults = loadConfig(base);
+    expect(defaults.ownerQuestionsEnabled).toBe(true);
+    expect(defaults.ownerQuestionsHaUsers).toEqual([]);
+
+    const set = loadConfig({ ...base, MCP_OWNER_QUESTIONS_ENABLED: 'false', MCP_OWNER_QUESTIONS_HA_USERS: ' a1b2 , c3d4 ,' });
+    expect(set.ownerQuestionsEnabled).toBe(false);
+    expect(set.ownerQuestionsHaUsers).toEqual(['a1b2', 'c3d4']);
+  });
+
   it('should apply default values for optional fields', () => {
     const env = {
       HA_URL: 'http://homeassistant.10.0.0.19.nip.io:8123',

package/tests/haClient/automationTrace.test.ts

@@ -0,0 +1,59 @@
+/**
+ * getAutomationTrace goes over the WebSocket (`trace/list`), keyed by the
+ * automation's config id — there is no REST trace endpoint in Home Assistant.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+
+import { AutomationOperations } from '../../src/haClient/automations.js';
+import type { StateOperations } from '../../src/haClient/states.js';
+
+function setup(state: unknown, traces: unknown = []) {
+    const stateOps = { getState: vi.fn().mockResolvedValue(state) } as unknown as StateOperations;
+    const wsCommand = vi.fn().mockResolvedValue(traces);
+    const request = { get: vi.fn() };
+    const ops = new AutomationOperations(stateOps, undefined, request as never, wsCommand as never);
+    return { ops, wsCommand, request };
+}
+
+const automation = (attributes: Record<string, unknown>) => ({ entity_id: 'automation.relay', state: 'on', attributes });
+
+const run = (id: string, start: string) => ({ run_id: id, timestamp: { start, finish: start }, trigger: 'state of sensor.x' });
+
+describe('AutomationOperations.getAutomationTrace', () => {
+    it('lists traces by the automation id attribute, newest first, over the WebSocket only', async () => {
+        const { ops, wsCommand, request } = setup(automation({ id: '1700000000000' }), [
+            run('a', '2026-10-07T08:00:00Z'),
+            run('c', '2026-10-07T10:00:00Z'),
+            run('b', '2026-10-07T09:00:00Z'),
+        ]);
+
+        const traces = await ops.getAutomationTrace('automation.relay');
+
+        expect(wsCommand).toHaveBeenCalledWith({ type: 'trace/list', domain: 'automation', item_id: '1700000000000' });
+        expect(traces.map((t) => t.run_id)).toEqual(['c', 'b', 'a']);
+        expect(request.get).not.toHaveBeenCalled();
+    });
+
+    it('returns at most `limit` runs (default 5)', async () => {
+        const many = Array.from({ length: 8 }, (_, i) => run(String(i), `2026-10-07T0${i}:00:00Z`));
+        const { ops } = setup(automation({ id: 7 }), many);
+
+        expect(await ops.getAutomationTrace('automation.relay')).toHaveLength(5);
+        expect((await ops.getAutomationTrace('automation.relay', 2)).map((t) => t.run_id)).toEqual(['7', '6']);
+    });
+
+    it('explains that a YAML automation without an id has no traces', async () => {
+        const { ops, wsCommand } = setup(automation({ friendly_name: 'Relay' }));
+
+        await expect(ops.getAutomationTrace('automation.relay')).rejects.toThrow(/has no 'id'.*no traces/);
+        expect(wsCommand).not.toHaveBeenCalled();
+    });
+
+    it('reports an unknown automation', async () => {
+        const { ops, wsCommand } = setup(null);
+
+        await expect(ops.getAutomationTrace('automation.nope')).rejects.toThrow('Automation automation.nope not found');
+        expect(wsCommand).not.toHaveBeenCalled();
+    });
+});

package/tests/haClient/automations.test.ts

@@ -131,3 +131,19 @@ describe('AutomationOperations', () => {
     });
   });
 });
+
+describe('AutomationOperations.createAutomation path encoding', () => {
+  it('encodes the automation id in the URL path but keeps it unchanged in the body', async () => {
+    const post = vi.fn().mockResolvedValue({ result: 'ok' });
+    const serviceOps = { callService: vi.fn().mockResolvedValue([]) };
+    const ops = new AutomationOperations(
+      { getState: vi.fn() } as unknown as StateOperations,
+      serviceOps as never,
+      { post, get: vi.fn() } as never
+    );
+
+    await ops.createAutomation({ id: 'room/a?b', alias: 'Test', trigger: [], action: [] } as never);
+
+    expect(post).toHaveBeenCalledWith('/config/automation/config/room%2Fa%3Fb', expect.objectContaining({ id: 'room/a?b' }));
+  });
+});