@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.3.1

package/src/server/chatSlice.ts

@@ -1,57 +0,0 @@
-/**
- * MCP_CHAT_TOOLS slice parsing — standalone module with zero imports so both
- * config.ts and the chat-face binding registry can use it without import cycles.
- *
- * Syntax (operator UX modeled on category:permission slicing):
- *   MCP_CHAT_TOOLS=ha-core:rw,ha-history:r,omada-read:r
- *
- * Unset -> undefined -> the chat face serves exactly the legacy 8 tools
- * (pre-v1.7 behavior). Set -> the slice governs which chat-ELIGIBLE bindings
- * are active; it can only narrow what the code marks eligible, never widen.
- */
-
-/** Chat-face tool categories. Deliberately few — this is a curated surface. */
-export const CHAT_CATEGORIES = [
-  'ha-core',        // states, search, summaries, version + callService (write)
-  'ha-history',     // entity history
-  'ha-automations', // list automations
-  'omada-read',     // omada_browse / omada_read (resource graph, read-only)
-  'omada-write',    // reversible network writes (SSID on/off)
-] as const;
-
-export type ChatCategory = (typeof CHAT_CATEGORIES)[number];
-export type ChatAccess = 'read' | 'write';
-
-/** Operator-selected slice: category -> allowed access levels. */
-export type ChatToolsSlice = Map<ChatCategory, Set<ChatAccess>>;
-
-/**
- * Parse `MCP_CHAT_TOOLS`. Returns `undefined` when unset/blank (legacy default).
- * Throws on malformed input so a config typo fails loudly at startup (same
- * philosophy as parseRestActions).
- */
-export function parseChatTools(raw: string | undefined): ChatToolsSlice | undefined {
-  if (!raw || raw.trim() === '') {
-    return undefined;
-  }
-
-  const slice: ChatToolsSlice = new Map();
-  for (const part of raw.split(',').map((p) => p.trim()).filter(Boolean)) {
-    const [name, access] = part.split(':').map((p) => p.trim());
-    if (!(CHAT_CATEGORIES as readonly string[]).includes(name)) {
-      throw new Error(
-        `Invalid MCP_CHAT_TOOLS category '${name}'. Known categories: ${CHAT_CATEGORIES.join(', ')}`
-      );
-    }
-    if (!access || !/^(r|w|rw)$/.test(access)) {
-      throw new Error(
-        `Invalid MCP_CHAT_TOOLS access '${access ?? ''}' for '${name}': use r, w, or rw (e.g. "${name}:r")`
-      );
-    }
-    const levels = slice.get(name as ChatCategory) ?? new Set<ChatAccess>();
-    if (access.includes('r')) levels.add('read');
-    if (access.includes('w')) levels.add('write');
-    slice.set(name as ChatCategory, levels);
-  }
-  return slice;
-}

package/src/server/common.ts

@@ -1,170 +0,0 @@
-/**
- * Common MCP server creation
- * Shared across all transport types (stdio, SSE, stream)
- */
-
-import { McpServer } from '@modelcontextprotocol/server';
-import type { RegisteredTool } from '@modelcontextprotocol/server';
-import type { HaClient } from '../haClient/index.js';
-import type { LocalAIClient } from '../localAI/index.js';
-import type { OmadaClient } from '../omadaClient/index.js';
-import { registerAllTools } from '../tools/index.js';
-import { isToolVisibleTo } from '../tools/common.js';
-import type { OmadaRegistrationMode } from '../tools/omada/index.js';
-import type { RestAction } from '../tools/infra/index.js';
-import { registerAllResources } from '../resources/index.js';
-import { generateInstructions } from './instructions.js';
-import { logger } from '../utils/logger.js';
-import type { OwnerQuestionService } from '../ownerQuestions/service.js';
-import { VERSION } from '../version.js';
-
-export interface CreateServerOptions {
-  haClient?: HaClient;
-  omadaClient?: OmadaClient;
-  aiClient?: LocalAIClient;
-  /** Pre-registered REST actions for invokeAction (empty/undefined = tool not registered). */
-  restActions?: Record<string, RestAction>;
-  /** Tool registration strategy for the Omada plugin (default 'eager'). */
-  toolRegistrationMode?: OmadaRegistrationMode;
-  /**
-   * The caller's permission mask. When set, tools whose static permission the
-   * caller lacks are disabled, which hides them from `tools/list` (and the SDK
-   * rejects calls to them). Undefined = no filtering (stdio local trust).
-   * Execution-time RBAC in wrapToolHandler still applies either way.
-   */
-  callerPermissions?: number;
-  /** Owner questions service (askOwner & co.), when running. */
-  ownerQuestions?: OwnerQuestionService;
-}
-
-export function createServer(options: CreateServerOptions): McpServer {
-  const { haClient, omadaClient, aiClient, restActions, toolRegistrationMode, callerPermissions, ownerQuestions } = options;
-  logger.debug('Creating MCP server instance');
-
-  // Generate instructions based on enabled plugins
-  const instructions = generateInstructions({
-    haEnabled: !!haClient,
-    omadaEnabled: !!omadaClient,
-    aiEnabled: !!aiClient,
-  });
-
-  const server = new McpServer(
-    {
-      name: 'mcp-ha-connect',
-      version: VERSION,
-    },
-    {
-      instructions,
-    }
-  );
-
-  logger.debug('Server instructions generated', { length: instructions.length });
-
-  // Register all tools based on configured clients, capturing each RegisteredTool
-  // handle so tools the caller can never use can be hidden afterwards.
-  const registeredTools = new Map<string, RegisteredTool>();
-  const originalRegisterTool = server.registerTool;
-  server.registerTool = ((...args: Parameters<McpServer['registerTool']>) => {
-    const config = args[1] as { inputSchema?: unknown; outputSchema?: unknown } | undefined;
-    memoizeJsonSchema(config?.inputSchema);
-    memoizeJsonSchema(config?.outputSchema);
-    const tool = (originalRegisterTool as (...a: unknown[]) => RegisteredTool).apply(server, args);
-    registeredTools.set(args[0], tool);
-    return tool;
-  }) as McpServer['registerTool'];
-  try {
-    registerAllTools({
-      server,
-      haClient,
-      omadaClient,
-      aiClient,
-      restActions,
-      toolRegistrationMode,
-      ownerQuestions,
-    });
-  } finally {
-    server.registerTool = originalRegisterTool;
-  }
-
-  if (callerPermissions !== undefined) {
-    const hidden = hideUnpermittedTools(registeredTools, callerPermissions);
-    logger.debug('Filtered tools by caller permissions', { visible: registeredTools.size - hidden, hidden });
-  }
-
-  // Register Home Assistant resources (if HA client provided)
-  if (haClient) {
-    registerAllResources(server, haClient);
-  }
-
-  logger.debug('MCP server instance created');
-
-  return server;
-}
-
-/**
- * Disable every tool the caller cannot use (it lacks the tool's static permission, or the
- * tool's visibility rule — e.g. omada_read's per-path one — finds nothing usable). Disabled
- * tools are omitted from `tools/list`, so an LLM client only plans with tools it can use.
- * Returns the number of tools hidden.
- */
-export function hideUnpermittedTools(tools: Map<string, RegisteredTool>, callerPermissions: number): number {
-  let hidden = 0;
-  for (const [name, tool] of tools) {
-    if (!isToolVisibleTo(name, callerPermissions)) {
-      tool.disable();
-      hidden++;
-    }
-  }
-  return hidden;
-}
-
-/** Schemas whose JSON Schema conversion is already memoized (process lifetime). */
-const memoizedSchemas = new WeakSet<object>();
-
-type JsonSchemaConverter = (options?: unknown) => unknown;
-
-/** Whether `schema`'s JSON Schema conversion has been memoized (for tests/diagnostics). */
-export function isJsonSchemaMemoized(schema: unknown): boolean {
-  return schema !== null && typeof schema === 'object' && memoizedSchemas.has(schema);
-}
-
-/**
- * Convert a tool schema to JSON Schema once per process instead of once per request.
- *
- * MCP SDK v2 converts every tool's schema to JSON Schema eagerly inside
- * `registerTool`, through the schema's Standard Schema `~standard.jsonSchema`
- * provider. The server is stateless and registers every tool on every request, so
- * that conversion (zod's `toJSONSchema`) became about half of request setup time. Tool
- * schemas are module-level constants, so the result never changes: this shadows the
- * provider on the schema instance with a cached one (the SDK's documented hook for a
- * custom provider). Each call returns a deep clone, so a caller that mutates the
- * result can never corrupt the cache. Validation (`~standard.validate`) is untouched.
- */
-export function memoizeJsonSchema(schema: unknown): void {
-  if (schema === null || typeof schema !== 'object' || memoizedSchemas.has(schema)) {
-    return;
-  }
-  memoizedSchemas.add(schema);
-  const std = (schema as { '~standard'?: { jsonSchema?: { input?: JsonSchemaConverter; output?: JsonSchemaConverter } } })[
-    '~standard'
-  ];
-  if (!std?.jsonSchema?.input || !std.jsonSchema.output) {
-    return; // Not a converter-carrying Standard Schema: leave it to the SDK as-is.
-  }
-  const memo = (convert: JsonSchemaConverter): JsonSchemaConverter => {
-    const cache = new Map<string, unknown>();
-    return (options) => {
-      const key = JSON.stringify(options ?? null);
-      if (!cache.has(key)) {
-        cache.set(key, convert(options));
-      }
-      return structuredClone(cache.get(key));
-    };
-  };
-  Object.defineProperty(schema, '~standard', {
-    value: { ...std, jsonSchema: { input: memo(std.jsonSchema.input), output: memo(std.jsonSchema.output) } },
-    configurable: true,
-    enumerable: false,
-    writable: false,
-  });
-}

package/src/server/eventSubscription.ts

@@ -1,343 +0,0 @@
-/**
- * SSE Event Subscription Endpoint
- * Allows HTTP clients to subscribe to Home Assistant events via Server-Sent Events
- */
-
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import { randomUUID } from 'node:crypto';
-import type { EventSubscriber, HaEvent } from '../haClient/events.js';
-import { logger } from '../utils/logger.js';
-import { sanitizeError } from '../utils/sanitizeError.js';
-import { Permission, hasPermission } from '../permissions/index.js';
-import type { AuthenticatedRequest } from './auth.js';
-
-export interface SSEClient {
-  id: string;
-  res: ServerResponse;
-  subscriptionIds: string[];
-  domain?: string;
-  entityId?: string;
-  eventTypes?: string[];
-  createdAt: Date;
-  lastEventAt?: Date;
-  eventCount: number;
-}
-
-// Store active SSE clients
-const clients = new Map<string, SSEClient>();
-
-/**
- * Generate an unguessable SSE client ID (L5).
- *
- * Uses a CSPRNG (randomUUID) rather than Math.random()/Date.now(), so a client
- * ID cannot be predicted or enumerated by an observer who knows roughly when a
- * connection was opened.
- */
-export function generateClientId(): string {
-  return randomUUID();
-}
-
-/**
- * Parse query parameters from URL
- */
-function parseQueryParams(url: string): URLSearchParams {
-  const queryIndex = url.indexOf('?');
-  if (queryIndex === -1) {
-    return new URLSearchParams();
-  }
-  return new URLSearchParams(url.slice(queryIndex + 1));
-}
-
-/**
- * Send SSE event to a client
- */
-function sendSSEEvent(res: ServerResponse, event: string, data: unknown): void {
-  if (res.writableEnded) {
-    return;
-  }
-
-  const payload = typeof data === 'string' ? data : JSON.stringify(data);
-  res.write(`event: ${event}\n`);
-  res.write(`data: ${payload}\n\n`);
-}
-
-/**
- * Send SSE comment (keep-alive)
- */
-function sendSSEComment(res: ServerResponse, comment: string): void {
-  if (res.writableEnded) {
-    return;
-  }
-  res.write(`: ${comment}\n\n`);
-}
-
-/**
- * Handle SSE subscription request
- */
-export async function handleEventSubscription(
-  req: IncomingMessage,
-  res: ServerResponse,
-  eventSubscriber: EventSubscriber
-): Promise<void> {
-  // L2: the SSE stream reads entity state — require QUERY, like every other read.
-  // Auth middleware has already populated req.auth; fail closed if the mask is absent.
-  const userPermissions = ((req as AuthenticatedRequest).auth?.extra?.permissions as number | undefined) ?? 0;
-  if (!hasPermission(userPermissions, Permission.QUERY)) {
-    logger.warn('SSE subscription denied: missing QUERY permission');
-    res.writeHead(403, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ error: 'Forbidden', message: 'SSE event subscription requires QUERY permission' }));
-    return;
-  }
-
-  const clientId = generateClientId();
-  const params = parseQueryParams(req.url ?? '');
-
-  // Parse filter parameters
-  const domain = params.get('domain') ?? undefined;
-  const entityId = params.get('entity_id') ?? undefined;
-  const eventTypesParam = params.get('event_types');
-  const eventTypes = eventTypesParam ? eventTypesParam.split(',').map(t => t.trim()) : undefined;
-
-  logger.info('New SSE subscription request', {
-    clientId,
-    domain,
-    entityId,
-    eventTypes,
-  });
-
-  // Set SSE headers
-  res.writeHead(200, {
-    'Content-Type': 'text/event-stream',
-    'Cache-Control': 'no-cache',
-    'Connection': 'keep-alive',
-    'Access-Control-Allow-Origin': req.headers.origin ?? '*',
-    'Access-Control-Allow-Credentials': 'true',
-    'X-Accel-Buffering': 'no', // Disable nginx buffering
-  });
-
-  // Create client record
-  const client: SSEClient = {
-    id: clientId,
-    res,
-    subscriptionIds: [],
-    domain,
-    entityId,
-    eventTypes,
-    createdAt: new Date(),
-    eventCount: 0,
-  };
-  clients.set(clientId, client);
-
-  // Send initial connection event
-  sendSSEEvent(res, 'connected', {
-    client_id: clientId,
-    message: 'Connected to Home Assistant event stream',
-    filters: { domain, entityId, eventTypes },
-    timestamp: new Date().toISOString(),
-  });
-
-  // Ensure event subscriber is connected
-  if (!eventSubscriber.isConnected()) {
-    try {
-      await eventSubscriber.connect();
-    } catch (error) {
-      logger.error('Failed to connect event subscriber', { error });
-      // M6: log detail above; the SSE client gets a generic message only.
-      sendSSEEvent(res, 'error', {
-        error: 'Failed to connect to Home Assistant',
-        message: sanitizeError(error),
-      });
-      res.end();
-      clients.delete(clientId);
-      return;
-    }
-  }
-
-  // Create event callback
-  const eventCallback = (event: HaEvent) => {
-    // Apply filters
-    if (eventTypes && !eventTypes.includes(event.event_type)) {
-      return;
-    }
-
-    if (domain && event.event_type === 'state_changed') {
-      const eventDomain = event.data.entity_id?.split('.')[0];
-      if (eventDomain !== domain) {
-        return;
-      }
-    }
-
-    if (entityId && event.data.entity_id !== entityId) {
-      return;
-    }
-
-    // Update client stats
-    client.lastEventAt = new Date();
-    client.eventCount++;
-
-    // Send event to client
-    sendSSEEvent(res, event.event_type, {
-      event_type: event.event_type,
-      entity_id: event.data.entity_id,
-      old_state: event.data.old_state,
-      new_state: event.data.new_state,
-      domain: event.data.domain,
-      service: event.data.service,
-      service_data: event.data.service_data,
-      time_fired: event.time_fired,
-      context: event.context,
-    });
-  };
-
-  // Subscribe to events based on filters
-  try {
-    let subscriptionId: string;
-
-    if (entityId) {
-      // Subscribe to specific entity
-      subscriptionId = await eventSubscriber.subscribeEntity(entityId, eventCallback);
-    } else if (domain) {
-      // Subscribe to domain
-      subscriptionId = await eventSubscriber.subscribeDomain(domain, eventCallback);
-    } else if (eventTypes && eventTypes.length === 1) {
-      // Subscribe to specific event type
-      subscriptionId = await eventSubscriber.subscribeEventType(eventTypes[0], eventCallback);
-    } else {
-      // Subscribe to all state_changed events by default
-      subscriptionId = await eventSubscriber.subscribeEventType('state_changed', eventCallback);
-    }
-
-    client.subscriptionIds.push(subscriptionId);
-
-    logger.info('SSE client subscribed to events', {
-      clientId,
-      subscriptionId,
-    });
-  } catch (error) {
-    logger.error('Failed to subscribe to events', { error, clientId });
-    // M6: log detail above; the SSE client gets a generic message only.
-    sendSSEEvent(res, 'error', {
-      error: 'Failed to subscribe to events',
-      message: sanitizeError(error),
-    });
-  }
-
-  // Keep-alive ping every 30 seconds
-  const keepAliveInterval = setInterval(() => {
-    if (res.writableEnded) {
-      clearInterval(keepAliveInterval);
-      return;
-    }
-    sendSSEComment(res, `keepalive ${new Date().toISOString()}`);
-  }, 30000);
-
-  // Handle client disconnect
-  req.on('close', () => {
-    clearInterval(keepAliveInterval);
-
-    // Unsubscribe from all events
-    for (const subId of client.subscriptionIds) {
-      eventSubscriber.unsubscribe(subId).catch(error => {
-        logger.error('Failed to unsubscribe', { error, subscriptionId: subId });
-      });
-    }
-
-    clients.delete(clientId);
-
-    logger.info('SSE client disconnected', {
-      clientId,
-      eventCount: client.eventCount,
-      duration: Date.now() - client.createdAt.getTime(),
-    });
-  });
-
-  // Handle errors
-  req.on('error', (error) => {
-    logger.error('SSE request error', { error, clientId });
-    clearInterval(keepAliveInterval);
-    clients.delete(clientId);
-  });
-}
-
-/**
- * Get list of active SSE clients
- */
-export function getActiveClients(): Array<{
-  id: string;
-  domain?: string;
-  entityId?: string;
-  eventTypes?: string[];
-  createdAt: Date;
-  lastEventAt?: Date;
-  eventCount: number;
-}> {
-  return Array.from(clients.values()).map(client => ({
-    id: client.id,
-    domain: client.domain,
-    entityId: client.entityId,
-    eventTypes: client.eventTypes,
-    createdAt: client.createdAt,
-    lastEventAt: client.lastEventAt,
-    eventCount: client.eventCount,
-  }));
-}
-
-/**
- * Get count of active SSE clients
- */
-export function getClientCount(): number {
-  return clients.size;
-}
-
-/**
- * Broadcast event to all matching clients
- */
-export function broadcastEvent(event: string, data: unknown, filter?: {
-  domain?: string;
-  entityId?: string;
-}): void {
-  for (const client of clients.values()) {
-    // Apply filter
-    if (filter?.domain && client.domain !== filter.domain) {
-      continue;
-    }
-    if (filter?.entityId && client.entityId !== filter.entityId) {
-      continue;
-    }
-
-    sendSSEEvent(client.res, event, data);
-    client.eventCount++;
-    client.lastEventAt = new Date();
-  }
-}
-
-/**
- * Disconnect a specific client
- */
-export function disconnectClient(clientId: string): boolean {
-  const client = clients.get(clientId);
-  if (!client) {
-    return false;
-  }
-
-  sendSSEEvent(client.res, 'disconnect', { reason: 'Server initiated disconnect' });
-  client.res.end();
-  clients.delete(clientId);
-
-  return true;
-}
-
-/**
- * Disconnect all clients
- */
-export function disconnectAllClients(): number {
-  const count = clients.size;
-
-  for (const client of clients.values()) {
-    sendSSEEvent(client.res, 'disconnect', { reason: 'Server shutdown' });
-    client.res.end();
-  }
-
-  clients.clear();
-  return count;
-}