@coffeerunhobby/mcp-ha-connect 2.1.1 → 2.2.0

package/src/server/http.ts

@@ -15,6 +15,7 @@ import { handleEventSubscription } from './eventSubscription.js';
 import { RateLimiter } from './rateLimiter.js';
 import { createAuthMiddleware } from './auth.js';
 import { sanitizeError } from '../utils/sanitizeError.js';
+import { OwnerQuestionService } from '../ownerQuestions/service.js';
 import {
   LEGACY_BINDINGS,
   resolveChatBindings,
@@ -343,23 +344,45 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
     audience: config.authAudience,
   });
 
-  // Initialize event subscriber if SSE events are enabled and HA is configured
+  // Initialize the HA event subscriber when SSE events or owner questions need it
   let eventSubscriber: EventSubscriber | null = null;
-  if (config.sseEventsEnabled && config.baseUrl && config.token) {
+  if ((config.sseEventsEnabled || config.ownerQuestionsEnabled) && config.baseUrl && config.token) {
     eventSubscriber = new EventSubscriber({
       baseUrl: config.baseUrl,
       token: config.token,
+      strictSsl: config.strictSsl,
     });
 
-    // Connect to Home Assistant WebSocket
+    // Connect to Home Assistant WebSocket. On failure the subscriber keeps
+    // retrying in the background; it is kept (not dropped) so events and owner
+    // questions start working as soon as Home Assistant is reachable.
     try {
       await eventSubscriber.connect();
       logger.info('Event subscriber connected to Home Assistant');
     } catch (error) {
-      logger.warn('Failed to connect event subscriber, SSE events will be unavailable', {
+      logger.warn('Home Assistant WebSocket not reachable yet; retrying in the background', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  // Owner questions (askOwner & co.) listen for notification taps on the subscriber.
+  let ownerQuestions: OwnerQuestionService | undefined;
+  if (config.ownerQuestionsEnabled && eventSubscriber && client) {
+    const subscriber = eventSubscriber;
+    const service = new OwnerQuestionService({
+      notify: (target, serviceData) => client.callService({ domain: 'notify', service: target, service_data: serviceData }),
+      subscribe: (eventType, callback, onRejected) => subscriber.subscribeEventType(eventType, callback, onRejected),
+      secret: config.authSecret,
+      allowedUserIds: config.ownerQuestionsHaUsers,
+    });
+    try {
+      await service.start();
+      ownerQuestions = service;
+    } catch (error) {
+      logger.warn('Owner questions unavailable: could not subscribe to notification taps', {
         error: error instanceof Error ? error.message : String(error),
       });
-      eventSubscriber = null;
     }
   }
 
@@ -482,7 +505,7 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
         const existingState = sessionId ? sessions.get(sessionId) : undefined;
 
         const body = req.method !== 'GET' ? await parseBody(req) : undefined;
-        const streamOptions: StreamTransportOptions = { haClient: client, omadaClient, aiClient, config };
+        const streamOptions: StreamTransportOptions = { haClient: client, omadaClient, aiClient, config, ownerQuestions };
         const state = await handleStreamRequest(streamOptions, req, res, body, existingState);
 
         if (state && config.stateful && sessionId) {
@@ -562,6 +585,7 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
     sessions.clear();
 
     // Close event subscriber
+    ownerQuestions?.stop();
     if (eventSubscriber) {
       eventSubscriber.disconnect();
     }

package/src/server/stream.ts

@@ -12,6 +12,7 @@ import type { LocalAIClient } from '../localAI/index.js';
 import type { OmadaClient } from '../omadaClient/index.js';
 import { logger } from '../utils/logger.js';
 import { createServer } from './common.js';
+import type { OwnerQuestionService } from '../ownerQuestions/service.js';
 import type { AuthenticatedRequest } from './auth.js';
 
 interface StreamTransportState {
@@ -27,6 +28,7 @@ export interface StreamTransportOptions {
   omadaClient?: OmadaClient;
   aiClient?: LocalAIClient;
   config: EnvironmentConfig;
+  ownerQuestions?: OwnerQuestionService;
 }
 
 export interface TransportSecurityOptions {
@@ -94,11 +96,12 @@ export function buildTransportSecurityOptions(config: EnvironmentConfig): Transp
  * This implements the MCP protocol version 2025-03-26
  */
 export function createStreamTransport(options: StreamTransportOptions, callerPermissions?: number): StreamTransportState {
-  const { haClient, omadaClient, aiClient, config } = options;
+  const { haClient, omadaClient, aiClient, config, ownerQuestions } = options;
   const mcpServer = createServer({
     haClient,
     omadaClient,
     aiClient,
+    ownerQuestions,
     restActions: config.restActions,
     toolRegistrationMode: config.toolRegistrationMode,
     // Hide tools this caller can never use from tools/list (RBAC still enforced per call).

package/src/tools/common.ts

@@ -147,7 +147,10 @@ export function wrapToolHandler<T>(
       }, true);
     }
 
-    logger.info('Tool invoked', { tool: name, sessionId, args: safeSerialize(args) });
+    // Arguments can carry message text, entity names or MAC addresses: they are
+    // logged at debug level only, never in normal (info) operation.
+    logger.info('Tool invoked', { tool: name, sessionId });
+    logger.debug('Tool arguments', { tool: name, sessionId, args: safeSerialize(args) });
 
     try {
       const result = await handler(args, extra);

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.1';
+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' }));
+  });
+});