@coffeerunhobby/mcp-ha-connect 0.5.0

package/src/config.ts

@@ -0,0 +1,260 @@
+import { z } from 'zod';
+import { isValidBindAddress, isValidOrigin } from './utils/config-validations.js';
+import { logger } from './utils/logger.js';
+import type { AIProviderType } from './localAI/types.js';
+
+const createBooleanStringSchema = (
+  defaultValue: boolean
+): z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodLiteral<'true'>, z.ZodLiteral<'false'>]>>, boolean, 'true' | 'false' | undefined> =>
+  z
+    .union([z.literal('true'), z.literal('false')])
+    .optional()
+    .transform((value: 'true' | 'false' | undefined) => {
+      if (value === undefined) return defaultValue;
+      return value === 'true';
+    });
+
+const numericStringSchema = z
+  .string()
+  .optional()
+  .transform((value: string | undefined) => (value ? Number.parseInt(value, 10) : undefined))
+  .pipe(z.number().positive().optional());
+
+const listStringSchema = z
+  .string()
+  .optional()
+  .transform((value: string | undefined) =>
+    value
+      ? value
+          .split(',')
+          .map((s: string) => s.trim())
+          .filter(Boolean)
+      : undefined
+  );
+
+const envSchema = z
+  .object({
+    // Home Assistant Client Configuration
+    haUrl: z.string().url({ message: 'HA_URL must be a valid URL' }),
+    haToken: z.string().min(1, 'HA_TOKEN is required'),
+    haStrictSsl: createBooleanStringSchema(true),
+    haTimeout: numericStringSchema,
+
+    // AI Provider Configuration (use 'none' to disable AI features)
+    aiProvider: z.enum(['ollama', 'openai', 'none']).optional(),
+    aiUrl: z.string().url().optional(),
+    aiModel: z.string().optional(),
+    aiTimeout: numericStringSchema,
+    aiApiKey: z.string().optional(),
+
+    // MCP Generic Server Configuration
+    logLevel: z.enum(['debug', 'info', 'warn', 'error']).optional().default('info'),
+    logFormat: z.enum(['plain', 'json', 'gcp-json']).optional().default('plain'),
+    useHttp: createBooleanStringSchema(false),
+    stateful: createBooleanStringSchema(false),
+
+    // MCP Server HTTP Configuration
+    httpPort: numericStringSchema,
+    httpTransport: z.enum(['stream', 'sse']).optional().default('stream'),
+    httpBindAddr: z.string().optional(),
+    httpPath: z.string().optional(),
+    httpEnableHealthcheck: createBooleanStringSchema(true),
+    httpHealthcheckPath: z.string().optional(),
+    httpAllowCors: createBooleanStringSchema(true),
+    httpAllowedOrigins: listStringSchema,
+
+    // SSE Event Subscription Configuration
+    sseEventsEnabled: createBooleanStringSchema(true),
+    sseEventsPath: z.string().optional(),
+
+    // Rate Limiting Configuration
+    rateLimitEnabled: createBooleanStringSchema(true),
+    rateLimitWindowMs: numericStringSchema,
+    rateLimitMaxRequests: numericStringSchema,
+  })
+  .refine(
+    (data) => {
+      // Validate httpBindAddr if provided
+      if (data.httpBindAddr && !isValidBindAddress(data.httpBindAddr)) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: 'MCP_HTTP_BIND_ADDR must be a valid IPv4 or IPv6 address',
+      path: ['httpBindAddr'],
+    }
+  )
+  .refine(
+    (data) => {
+      // Validate httpAllowedOrigins if provided
+      if (data.httpAllowedOrigins) {
+        for (const origin of data.httpAllowedOrigins) {
+          if (!isValidOrigin(origin)) {
+            return false;
+          }
+        }
+      }
+      return true;
+    },
+    (data) => {
+      const invalidOrigin = data.httpAllowedOrigins?.find((origin) => !isValidOrigin(origin));
+      return {
+        message: `MCP_HTTP_ALLOWED_ORIGINS contains invalid origin: ${invalidOrigin}`,
+        path: ['httpAllowedOrigins'],
+      };
+    }
+  );
+
+export interface EnvironmentConfig {
+  // Home Assistant Client Configuration
+  baseUrl: string;
+  token: string;
+  strictSsl: boolean;
+  timeout: number;
+
+  // AI Provider Configuration
+  aiProvider: AIProviderType;
+  aiUrl: string;
+  aiModel: string;
+  aiTimeout: number;
+  aiApiKey?: string;
+
+  // MCP Generic Server Configuration
+  logLevel: 'debug' | 'info' | 'warn' | 'error';
+  logFormat: 'plain' | 'json' | 'gcp-json';
+  useHttp: boolean;
+  stateful: boolean;
+
+  // MCP Server HTTP Configuration
+  httpPort?: number;
+  httpTransport: 'stream' | 'sse';
+  httpBindAddr?: string;
+  httpPath?: string;
+  httpEnableHealthcheck: boolean;
+  httpHealthcheckPath?: string;
+  httpAllowCors: boolean;
+  httpAllowedOrigins?: string[];
+
+  // SSE Event Subscription Configuration
+  sseEventsEnabled: boolean;
+  sseEventsPath: string;
+
+  // Rate Limiting Configuration
+  rateLimitEnabled: boolean;
+  rateLimitWindowMs: number;
+  rateLimitMaxRequests: number;
+}
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentConfig {
+  const parsed = envSchema.safeParse({
+    // Home Assistant Client Configuration
+    haUrl: env.HA_URL,
+    haToken: env.HA_TOKEN,
+    haStrictSsl: env.HA_STRICT_SSL,
+    haTimeout: env.HA_TIMEOUT,
+
+    // AI Provider Configuration
+    aiProvider: env.AI_PROVIDER,
+    aiUrl: env.AI_URL,
+    aiModel: env.AI_MODEL,
+    aiTimeout: env.AI_TIMEOUT,
+    aiApiKey: env.AI_API_KEY,
+
+    // MCP Generic Server Configuration
+    logLevel: env.MCP_SERVER_LOG_LEVEL,
+    logFormat: env.MCP_SERVER_LOG_FORMAT,
+    useHttp: env.MCP_SERVER_USE_HTTP,
+    stateful: env.MCP_SERVER_STATEFUL,
+
+    // MCP Server HTTP Configuration
+    httpPort: env.MCP_HTTP_PORT,
+    httpTransport: env.MCP_HTTP_TRANSPORT,
+    httpBindAddr: env.MCP_HTTP_BIND_ADDR,
+    httpPath: env.MCP_HTTP_PATH,
+    httpEnableHealthcheck: env.MCP_HTTP_ENABLE_HEALTHCHECK,
+    httpHealthcheckPath: env.MCP_HTTP_HEALTHCHECK_PATH,
+    httpAllowCors: env.MCP_HTTP_ALLOW_CORS,
+    httpAllowedOrigins: env.MCP_HTTP_ALLOWED_ORIGINS,
+
+    // SSE Event Subscription Configuration
+    sseEventsEnabled: env.MCP_SSE_EVENTS_ENABLED,
+    sseEventsPath: env.MCP_SSE_EVENTS_PATH,
+
+    // Rate Limiting Configuration
+    rateLimitEnabled: env.MCP_RATE_LIMIT_ENABLED,
+    rateLimitWindowMs: env.MCP_RATE_LIMIT_WINDOW_MS,
+    rateLimitMaxRequests: env.MCP_RATE_LIMIT_MAX_REQUESTS,
+  });
+
+  if (!parsed.success) {
+    const messages = parsed.error.issues.map((issue: z.ZodIssue) => issue.message);
+    throw new Error(`Invalid environment configuration:\n${messages.join('\n')}`);
+  }
+
+  // Determine default httpPath based on transport if not explicitly set
+  const defaultPath = parsed.data.httpTransport === 'sse' ? '/sse' : '/mcp';
+  const httpPath = parsed.data.httpPath ?? defaultPath;
+
+  // Set default bind address and allowed origins for security
+  const httpBindAddr = parsed.data.httpBindAddr ?? '127.0.0.1';
+  let httpAllowedOrigins = parsed.data.httpAllowedOrigins ?? ['127.0.0.1', 'localhost'];
+
+  // If wildcard is present, use empty array to disable SDK origin validation
+  if (httpAllowedOrigins.includes('*')) {
+    logger.warn('Wildcard (*) origin allowed - origin validation is disabled. This should only be used in development.');
+    httpAllowedOrigins = [];
+  }
+
+  return {
+    // Home Assistant Client Configuration
+    baseUrl: parsed.data.haUrl.replace(/\/$/, ''),
+    token: parsed.data.haToken,
+    strictSsl: parsed.data.haStrictSsl,
+    timeout: parsed.data.haTimeout ?? 30000,
+
+    // AI Provider Configuration
+    aiProvider: (parsed.data.aiProvider ?? 'ollama') as AIProviderType,
+    aiUrl: parsed.data.aiUrl ?? 'http://localhost:11434',
+    aiModel: parsed.data.aiModel ?? 'qwen3:14b',
+    aiTimeout: parsed.data.aiTimeout ?? 60000,
+    aiApiKey: parsed.data.aiApiKey,
+
+    // MCP Generic Server Configuration
+    logLevel: parsed.data.logLevel,
+    logFormat: parsed.data.logFormat,
+    useHttp: parsed.data.useHttp,
+    stateful: parsed.data.stateful,
+
+    // MCP Server HTTP Configuration
+    httpPort: parsed.data.httpPort,
+    httpTransport: parsed.data.httpTransport,
+    httpBindAddr,
+    httpPath,
+    httpEnableHealthcheck: parsed.data.httpEnableHealthcheck,
+    httpHealthcheckPath: parsed.data.httpHealthcheckPath,
+    httpAllowCors: parsed.data.httpAllowCors,
+    httpAllowedOrigins,
+
+    // SSE Event Subscription Configuration
+    sseEventsEnabled: parsed.data.sseEventsEnabled,
+    sseEventsPath: parsed.data.sseEventsPath ?? '/subscribe_events',
+
+    // Rate Limiting Configuration
+    rateLimitEnabled: parsed.data.rateLimitEnabled,
+    rateLimitWindowMs: parsed.data.rateLimitWindowMs ?? 60000,
+    rateLimitMaxRequests: parsed.data.rateLimitMaxRequests ?? 100,
+  };
+}
+
+// Legacy compatibility functions
+export function validateConfig(config: EnvironmentConfig): void {
+  // Config is already validated by Zod, this is for compatibility
+  if (!config.baseUrl || !config.token) {
+    throw new Error('Invalid configuration: missing baseUrl or token');
+  }
+}
+
+export function loadConfigFromEnv(): EnvironmentConfig {
+  return loadConfig();
+}

package/src/haClient/automations.ts

@@ -0,0 +1,217 @@
+/**
+ * Automation Operations for Home Assistant API
+ * Handles automation listing and management
+ */
+
+import type { Automation, AutomationConfig, ServiceCallResponse } from '../types/index.js';
+import { logger } from '../utils/logger.js';
+import type { StateOperations } from './states.js';
+import type { ServiceOperations } from './services.js';
+import type { RequestHandler } from './request.js';
+
+/**
+ * Automation-related operations for the Home Assistant API.
+ */
+export class AutomationOperations {
+  constructor(
+    private readonly stateOps: StateOperations,
+    private readonly serviceOps?: ServiceOperations,
+    private readonly request?: RequestHandler
+  ) {}
+
+  /**
+   * Get all automations
+   */
+  async getAutomations(): Promise<Automation[]> {
+    logger.debug('Fetching automations');
+
+    const allStates = await this.stateOps.getStates();
+    const automations = allStates
+      .filter(entity => entity.entity_id.startsWith('automation.'))
+      .map(entity => ({
+        id: entity.entity_id,
+        alias: String(entity.attributes.friendly_name || entity.entity_id.replace('automation.', '')),
+        state: entity.state as 'on' | 'off',
+        last_triggered: entity.attributes.last_triggered as string | null,
+        description: entity.attributes.description as string | undefined,
+        mode: entity.attributes.mode as Automation['mode'],
+      }));
+
+    logger.info('Fetched automations', { count: automations.length });
+    return automations;
+  }
+
+  /**
+   * Get a single automation by entity_id
+   */
+  async getAutomation(entityId: string): Promise<Automation | null> {
+    logger.debug('Fetching automation', { entityId });
+
+    const state = await this.stateOps.getState(entityId);
+    if (!state || !entityId.startsWith('automation.')) {
+      return null;
+    }
+
+    return {
+      id: state.entity_id,
+      alias: String(state.attributes.friendly_name || state.entity_id.replace('automation.', '')),
+      state: state.state as 'on' | 'off',
+      last_triggered: state.attributes.last_triggered as string | null,
+      description: state.attributes.description as string | undefined,
+      mode: state.attributes.mode as Automation['mode'],
+    };
+  }
+
+  /**
+   * Trigger an automation manually
+   */
+  async triggerAutomation(entityId: string, variables?: Record<string, unknown>): Promise<ServiceCallResponse> {
+    if (!this.serviceOps) {
+      throw new Error('ServiceOperations not available');
+    }
+
+    logger.info('Triggering automation', { entityId, variables });
+
+    return this.serviceOps.callService({
+      domain: 'automation',
+      service: 'trigger',
+      target: { entity_id: entityId },
+      service_data: variables ? { variables } : undefined,
+    });
+  }
+
+  /**
+   * Enable an automation
+   */
+  async enableAutomation(entityId: string): Promise<ServiceCallResponse> {
+    if (!this.serviceOps) {
+      throw new Error('ServiceOperations not available');
+    }
+
+    logger.info('Enabling automation', { entityId });
+
+    return this.serviceOps.callService({
+      domain: 'automation',
+      service: 'turn_on',
+      target: { entity_id: entityId },
+    });
+  }
+
+  /**
+   * Disable an automation
+   */
+  async disableAutomation(entityId: string): Promise<ServiceCallResponse> {
+    if (!this.serviceOps) {
+      throw new Error('ServiceOperations not available');
+    }
+
+    logger.info('Disabling automation', { entityId });
+
+    return this.serviceOps.callService({
+      domain: 'automation',
+      service: 'turn_off',
+      target: { entity_id: entityId },
+    });
+  }
+
+  /**
+   * Toggle an automation (enable if disabled, disable if enabled)
+   */
+  async toggleAutomation(entityId: string): Promise<ServiceCallResponse> {
+    if (!this.serviceOps) {
+      throw new Error('ServiceOperations not available');
+    }
+
+    logger.info('Toggling automation', { entityId });
+
+    return this.serviceOps.callService({
+      domain: 'automation',
+      service: 'toggle',
+      target: { entity_id: entityId },
+    });
+  }
+
+  /**
+   * Reload all automations from configuration
+   */
+  async reloadAutomations(): Promise<void> {
+    if (!this.serviceOps) {
+      throw new Error('ServiceOperations not available');
+    }
+
+    logger.info('Reloading automations');
+
+    await this.serviceOps.callService({
+      domain: 'automation',
+      service: 'reload',
+    });
+  }
+
+  /**
+   * Create a new automation via the config API
+   * Note: Requires Home Assistant 2023.7+ with config flow support
+   */
+  async createAutomation(config: AutomationConfig): Promise<{ id: string }> {
+    if (!this.request) {
+      throw new Error('RequestHandler not available');
+    }
+
+    logger.info('Creating automation', { alias: config.alias });
+
+    // Use the config/automation/config endpoint to create automations
+    const result = await this.request.post<{ result: string }>('/config/automation/config', {
+      alias: config.alias,
+      description: config.description,
+      mode: config.mode ?? 'single',
+      trigger: config.trigger,
+      condition: config.condition,
+      action: config.action,
+    });
+
+    return { id: result.result };
+  }
+
+  /**
+   * Update an existing automation
+   * Note: Requires the automation's unique_id from the automation registry
+   */
+  async updateAutomation(automationId: string, config: Partial<AutomationConfig>): Promise<void> {
+    if (!this.request) {
+      throw new Error('RequestHandler not available');
+    }
+
+    logger.info('Updating automation', { automationId, alias: config.alias });
+
+    await this.request.post(`/config/automation/config/${automationId}`, config);
+  }
+
+  /**
+   * Delete an automation
+   * Note: Only works for automations created via the UI/API
+   */
+  async deleteAutomation(automationId: string): Promise<void> {
+    if (!this.request) {
+      throw new Error('RequestHandler not available');
+    }
+
+    logger.info('Deleting automation', { automationId });
+
+    await this.request.request(`/config/automation/config/${automationId}`, {
+      method: 'DELETE',
+    });
+  }
+
+  /**
+   * Get automation trace (execution history)
+   */
+  async getAutomationTrace(entityId: string): Promise<unknown[]> {
+    if (!this.request) {
+      throw new Error('RequestHandler not available');
+    }
+
+    const automationId = entityId.replace('automation.', '');
+    logger.debug('Fetching automation trace', { automationId });
+
+    return this.request.get<unknown[]>(`/trace/automation/${automationId}`);
+  }
+}

package/src/haClient/config.ts

@@ -0,0 +1,41 @@
+/**
+ * Config Operations for Home Assistant API
+ * Handles configuration and version information
+ */
+
+import type { HaVersion } from '../types/index.js';
+import { logger } from '../utils/logger.js';
+import type { RequestHandler } from './request.js';
+
+/**
+ * Config-related operations for the Home Assistant API.
+ */
+export class ConfigOperations {
+  constructor(private readonly request: RequestHandler) {}
+
+  /**
+   * Get config
+   */
+  async getConfig(): Promise<Record<string, unknown>> {
+    logger.debug('Fetching config');
+    return await this.request.get<Record<string, unknown>>('/config');
+  }
+
+  /**
+   * Check API (health check)
+   */
+  async checkApi(): Promise<{ message: string }> {
+    logger.debug('Checking API health');
+    return await this.request.get<{ message: string }>('/');
+  }
+
+  /**
+   * Get Home Assistant version and configuration info
+   */
+  async getVersion(): Promise<HaVersion> {
+    logger.debug('Fetching Home Assistant version');
+    const config = await this.request.get<HaVersion>('/config');
+    logger.info('Fetched version', { version: config.version });
+    return config;
+  }
+}