@coffeerunhobby/mcp-ha-connect 0.5.0

package/src/haClient/index.ts

@@ -0,0 +1,287 @@
+/**
+ * Home Assistant API Client
+ * Main client class that composes all operation modules
+ */
+
+import type { EnvironmentConfig } from '../config.js';
+import type {
+  Entity,
+  ServiceCallData,
+  ServiceCallResponse,
+  Automation,
+  AutomationConfig,
+  DomainSummary,
+  HaVersion,
+  LogbookEntry,
+  UpdateInfo,
+} from '../types/index.js';
+import { logger } from '../utils/logger.js';
+
+import { AutomationOperations } from './automations.js';
+import { ConfigOperations } from './config.js';
+import { DeviceOperations } from './devices.js';
+import { EntityOperations } from './entities.js';
+import { HistoryOperations } from './history.js';
+import { RequestHandler } from './request.js';
+import { ServiceOperations } from './services.js';
+import { StateOperations } from './states.js';
+import { UpdateOperations } from './updates.js';
+
+/**
+ * Main client for interacting with the Home Assistant API.
+ * Organized with dedicated operation classes for each domain.
+ */
+export class HaClient {
+  private readonly request: RequestHandler;
+  private readonly stateOps: StateOperations;
+  private readonly serviceOps: ServiceOperations;
+  private readonly entityOps: EntityOperations;
+  private readonly automationOps: AutomationOperations;
+  private readonly historyOps: HistoryOperations;
+  private readonly updateOps: UpdateOperations;
+  private readonly configOps: ConfigOperations;
+  public readonly devices: DeviceOperations;
+
+  constructor(config: EnvironmentConfig) {
+    logger.debug('Initializing HaClient');
+
+    // Initialize request handler
+    this.request = new RequestHandler({
+      baseUrl: config.baseUrl,
+      token: config.token,
+      timeout: config.timeout,
+      strictSsl: config.strictSsl,
+    });
+
+    // Initialize operation modules with dependencies
+    this.stateOps = new StateOperations(this.request);
+    this.serviceOps = new ServiceOperations(this.request);
+    this.entityOps = new EntityOperations(this.stateOps);
+    this.automationOps = new AutomationOperations(this.stateOps, this.serviceOps, this.request);
+    this.historyOps = new HistoryOperations(this.request);
+    this.updateOps = new UpdateOperations(this.entityOps);
+    this.configOps = new ConfigOperations(this.request);
+    this.devices = new DeviceOperations(this.serviceOps, this.stateOps);
+
+    logger.info('HaClient initialized');
+  }
+
+  // ===== State Operations =====
+
+  /**
+   * Get all states (entities)
+   */
+  async getStates(): Promise<Entity[]> {
+    return this.stateOps.getStates();
+  }
+
+  /**
+   * Get state of a specific entity
+   */
+  async getState(entityId: string): Promise<Entity | null> {
+    return this.stateOps.getState(entityId);
+  }
+
+  /**
+   * Get all sensors (sensor.* and binary_sensor.* entities)
+   */
+  async getAllSensors(): Promise<Entity[]> {
+    return this.stateOps.getAllSensors();
+  }
+
+  // ===== Service Operations =====
+
+  /**
+   * Call a service
+   */
+  async callService(data: ServiceCallData): Promise<ServiceCallResponse> {
+    return this.serviceOps.callService(data);
+  }
+
+  /**
+   * Restart Home Assistant
+   */
+  async restartServer(): Promise<void> {
+    return this.serviceOps.restartServer();
+  }
+
+  // ===== Entity Operations =====
+
+  /**
+   * Get entities filtered by domain
+   */
+  async getEntitiesByDomain(domain: string): Promise<Entity[]> {
+    return this.entityOps.getEntitiesByDomain(domain);
+  }
+
+  /**
+   * Search entities by name or entity_id
+   */
+  async searchEntities(query: string): Promise<Entity[]> {
+    return this.entityOps.searchEntities(query);
+  }
+
+  /**
+   * Get domain summary with entity counts and state breakdown
+   */
+  async getDomainSummary(domain: string): Promise<DomainSummary> {
+    return this.entityOps.getDomainSummary(domain);
+  }
+
+  /**
+   * List entities with optional filtering
+   */
+  async listEntities(options: {
+    domain?: string;
+    search?: string;
+    limit?: number;
+    state?: string;
+  } = {}): Promise<Entity[]> {
+    return this.entityOps.listEntities(options);
+  }
+
+  // ===== Automation Operations =====
+
+  /**
+   * Get all automations
+   */
+  async getAutomations(): Promise<Automation[]> {
+    return this.automationOps.getAutomations();
+  }
+
+  /**
+   * Get a single automation by entity_id
+   */
+  async getAutomation(entityId: string): Promise<Automation | null> {
+    return this.automationOps.getAutomation(entityId);
+  }
+
+  /**
+   * Trigger an automation manually
+   */
+  async triggerAutomation(entityId: string, variables?: Record<string, unknown>): Promise<ServiceCallResponse> {
+    return this.automationOps.triggerAutomation(entityId, variables);
+  }
+
+  /**
+   * Enable an automation
+   */
+  async enableAutomation(entityId: string): Promise<ServiceCallResponse> {
+    return this.automationOps.enableAutomation(entityId);
+  }
+
+  /**
+   * Disable an automation
+   */
+  async disableAutomation(entityId: string): Promise<ServiceCallResponse> {
+    return this.automationOps.disableAutomation(entityId);
+  }
+
+  /**
+   * Toggle an automation
+   */
+  async toggleAutomation(entityId: string): Promise<ServiceCallResponse> {
+    return this.automationOps.toggleAutomation(entityId);
+  }
+
+  /**
+   * Reload all automations from configuration
+   */
+  async reloadAutomations(): Promise<void> {
+    return this.automationOps.reloadAutomations();
+  }
+
+  /**
+   * Create a new automation
+   */
+  async createAutomation(config: AutomationConfig): Promise<{ id: string }> {
+    return this.automationOps.createAutomation(config);
+  }
+
+  /**
+   * Update an existing automation
+   */
+  async updateAutomation(automationId: string, config: Partial<AutomationConfig>): Promise<void> {
+    return this.automationOps.updateAutomation(automationId, config);
+  }
+
+  /**
+   * Delete an automation
+   */
+  async deleteAutomation(automationId: string): Promise<void> {
+    return this.automationOps.deleteAutomation(automationId);
+  }
+
+  /**
+   * Get automation execution trace
+   */
+  async getAutomationTrace(entityId: string): Promise<unknown[]> {
+    return this.automationOps.getAutomationTrace(entityId);
+  }
+
+  // ===== History Operations =====
+
+  /**
+   * Get historical data for an entity
+   */
+  async getHistory(entityId: string, hours: number = 24): Promise<Entity[][]> {
+    return this.historyOps.getHistory(entityId, hours);
+  }
+
+  /**
+   * Get system log entries from the logbook
+   */
+  async getSystemLog(options: {
+    hours?: number;
+    entity_id?: string;
+  } = {}): Promise<LogbookEntry[]> {
+    return this.historyOps.getSystemLog(options);
+  }
+
+  // ===== Update Operations =====
+
+  /**
+   * Get available updates by checking update.* entities
+   */
+  async getAvailableUpdates(): Promise<{
+    updates: UpdateInfo[];
+    entities: Entity[];
+  }> {
+    return this.updateOps.getAvailableUpdates();
+  }
+
+  // ===== Config Operations =====
+
+  /**
+   * Get config
+   */
+  async getConfig(): Promise<Record<string, unknown>> {
+    return this.configOps.getConfig();
+  }
+
+  /**
+   * Check API (health check)
+   */
+  async checkApi(): Promise<{ message: string }> {
+    return this.configOps.checkApi();
+  }
+
+  /**
+   * Get Home Assistant version and configuration info
+   */
+  async getVersion(): Promise<HaVersion> {
+    return this.configOps.getVersion();
+  }
+}
+
+// Re-export operation classes for testing
+export { RequestHandler } from './request.js';
+export { StateOperations } from './states.js';
+export { ServiceOperations } from './services.js';
+export { EntityOperations } from './entities.js';
+export { AutomationOperations } from './automations.js';
+export { HistoryOperations } from './history.js';
+export { UpdateOperations } from './updates.js';
+export { ConfigOperations } from './config.js';
+export { DeviceOperations } from './devices.js';
+export type { LightControlOptions, ClimateControlOptions, MediaPlayerControlOptions, CoverControlOptions, FanControlOptions } from './devices.js';

package/src/haClient/request.ts

@@ -0,0 +1,127 @@
+/**
+ * HTTP Request Handler for Home Assistant API
+ * Handles authentication and HTTP requests
+ */
+
+import https from 'https';
+import type { RequestOptions } from '../types/index.js';
+import { AuthenticationError, ApiError } from '../types/index.js';
+import { logger } from '../utils/logger.js';
+
+export interface RequestHandlerConfig {
+  baseUrl: string;
+  token: string;
+  timeout: number;
+  strictSsl: boolean;
+}
+
+/**
+ * HTTP request handler for Home Assistant API calls.
+ */
+export class RequestHandler {
+  private httpsAgent?: https.Agent;
+  private baseUrl: string;
+  private token: string;
+  private timeout: number;
+
+  constructor(config: RequestHandlerConfig) {
+    this.baseUrl = config.baseUrl;
+    this.token = config.token;
+    this.timeout = config.timeout;
+
+    // Create HTTPS agent with custom SSL settings
+    if (!config.strictSsl) {
+      this.httpsAgent = new https.Agent({
+        rejectUnauthorized: false,
+      });
+      logger.warn('SSL certificate validation is disabled');
+    }
+  }
+
+  /**
+   * Make authenticated request to Home Assistant API
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const url = new URL(`${this.baseUrl}/api${path}`);
+
+    // Add query parameters
+    if (options.params) {
+      Object.entries(options.params).forEach(([key, value]) => {
+        url.searchParams.append(key, String(value));
+      });
+    }
+
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${this.token}`,
+      'Content-Type': 'application/json',
+      ...options.headers,
+    };
+
+    logger.debug('Making API request', {
+      method: options.method ?? 'GET',
+      path,
+      params: options.params,
+    });
+
+    try {
+      const response = await fetch(url.toString(), {
+        method: options.method ?? 'GET',
+        headers,
+        body: options.body ? JSON.stringify(options.body) : undefined,
+        // @ts-expect-error - agent is valid but not in types
+        agent: this.httpsAgent,
+        signal: AbortSignal.timeout(this.timeout),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+
+        if (response.status === 401) {
+          throw new AuthenticationError(
+            'Invalid Home Assistant token',
+            { status: response.status, body: errorText }
+          );
+        }
+
+        throw new ApiError(
+          `API request failed: ${response.statusText}`,
+          response.status,
+          { path, body: errorText }
+        );
+      }
+
+      // Handle empty responses
+      const contentType = response.headers.get('content-type');
+      if (!contentType?.includes('application/json')) {
+        return {} as T;
+      }
+
+      const data = await response.json();
+      return data as T;
+    } catch (error) {
+      if (error instanceof AuthenticationError || error instanceof ApiError) {
+        throw error;
+      }
+
+      throw new ApiError(
+        `Request failed: ${error instanceof Error ? error.message : String(error)}`,
+        500,
+        { path }
+      );
+    }
+  }
+
+  /**
+   * Make a GET request
+   */
+  async get<T>(path: string, params?: Record<string, string | number>): Promise<T> {
+    return this.request<T>(path, { params });
+  }
+
+  /**
+   * Make a POST request
+   */
+  async post<T>(path: string, body?: unknown): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body });
+  }
+}

package/src/haClient/services.ts

@@ -0,0 +1,45 @@
+/**
+ * Service Operations for Home Assistant API
+ * Handles service calls and server management
+ */
+
+import type { ServiceCallData, ServiceCallResponse } from '../types/index.js';
+import { logger } from '../utils/logger.js';
+import type { RequestHandler } from './request.js';
+
+/**
+ * Service-related operations for the Home Assistant API.
+ */
+export class ServiceOperations {
+  constructor(private readonly request: RequestHandler) {}
+
+  /**
+   * Call a service
+   */
+  async callService(data: ServiceCallData): Promise<ServiceCallResponse> {
+    logger.info('Calling service', {
+      domain: data.domain,
+      service: data.service,
+      hasTarget: !!data.target,
+    });
+
+    const path = `/services/${data.domain}/${data.service}`;
+    const body = {
+      ...data.service_data,
+      ...data.target,
+    };
+
+    return await this.request.post<ServiceCallResponse>(path, body);
+  }
+
+  /**
+   * Restart Home Assistant
+   */
+  async restartServer(): Promise<void> {
+    logger.warn('Restarting Home Assistant');
+
+    await this.request.post('/services/homeassistant/restart', {});
+
+    logger.info('Home Assistant restart initiated');
+  }
+}

package/src/haClient/states.ts

@@ -0,0 +1,60 @@
+/**
+ * State Operations for Home Assistant API
+ * Handles entity state retrieval
+ */
+
+import type { Entity } from '../types/index.js';
+import { ApiError } from '../types/index.js';
+import { logger } from '../utils/logger.js';
+import type { RequestHandler } from './request.js';
+
+/**
+ * State-related operations for the Home Assistant API.
+ */
+export class StateOperations {
+  constructor(private readonly request: RequestHandler) {}
+
+  /**
+   * Get all states (entities)
+   */
+  async getStates(): Promise<Entity[]> {
+    logger.debug('Fetching all states');
+    const states = await this.request.get<Entity[]>('/states');
+    logger.info('Fetched states', { count: states.length });
+    return states;
+  }
+
+  /**
+   * Get state of a specific entity
+   */
+  async getState(entityId: string): Promise<Entity | null> {
+    logger.debug('Fetching state', { entityId });
+
+    try {
+      const state = await this.request.get<Entity>(`/states/${entityId}`);
+      return state;
+    } catch (error) {
+      if (error instanceof ApiError && error.statusCode === 404) {
+        logger.warn('Entity not found', { entityId });
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get all sensors (sensor.* and binary_sensor.* entities)
+   */
+  async getAllSensors(): Promise<Entity[]> {
+    logger.debug('Fetching all sensors');
+
+    const allStates = await this.getStates();
+    const sensors = allStates.filter(entity =>
+      entity.entity_id.startsWith('sensor.') ||
+      entity.entity_id.startsWith('binary_sensor.')
+    );
+
+    logger.info('Fetched sensors', { count: sensors.length });
+    return sensors;
+  }
+}

package/src/haClient/updates.ts

@@ -0,0 +1,58 @@
+/**
+ * Update Operations for Home Assistant API
+ * Handles checking for available updates
+ */
+
+import type { Entity, UpdateInfo } from '../types/index.js';
+import { logger } from '../utils/logger.js';
+import type { EntityOperations } from './entities.js';
+
+/**
+ * Update-related operations for the Home Assistant API.
+ */
+export class UpdateOperations {
+  constructor(private readonly entityOps: EntityOperations) {}
+
+  /**
+   * Get available updates by checking update.* entities
+   * Works with regular long-lived access tokens
+   */
+  async getAvailableUpdates(): Promise<{
+    updates: UpdateInfo[];
+    entities: Entity[];
+  }> {
+    logger.debug('Fetching available updates from update entities');
+
+    // Get all update entities
+    const updateEntities = await this.entityOps.getEntitiesByDomain('update');
+
+    // Filter to only those with updates available (state = 'on')
+    const updates: UpdateInfo[] = [];
+
+    for (const entity of updateEntities) {
+      const attrs = entity.attributes;
+      const installedVersion = attrs.installed_version as string | undefined;
+      const latestVersion = attrs.latest_version as string | undefined;
+      const title = attrs.title as string || attrs.friendly_name as string || entity.entity_id;
+
+      // state 'on' means update is available
+      if (entity.state === 'on' && installedVersion && latestVersion) {
+        updates.push({
+          update_type: entity.entity_id.includes('core') ? 'core' :
+                       entity.entity_id.includes('supervisor') ? 'supervisor' :
+                       entity.entity_id.includes('operating_system') ? 'os' : 'addon',
+          name: title,
+          version_current: installedVersion,
+          version_latest: latestVersion,
+        });
+      }
+    }
+
+    logger.info('Fetched available updates', { updateCount: updates.length, totalEntities: updateEntities.length });
+
+    return {
+      updates,
+      entities: updateEntities,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * Home Assistant MCP Server
+ * Entry point for the Model Context Protocol server
+ * Supports multiple transport modes: stdio, HTTP+SSE, HTTP+Stream
+ */
+
+import { loadConfig } from './config.js';
+import { HaClient } from './haClient/index.js';
+import { LocalAIClient } from './localAI/index.js';
+import { startHttpServer } from './server/http.js';
+import { startStdioServer } from './server/stdio.js';
+import { initLogger, logger } from './utils/logger.js';
+
+async function main(): Promise<void> {
+  try {
+    // Load and validate configuration
+    const config = loadConfig();
+
+    // When running in stdio mode, logs must go to stderr to avoid interfering with MCP protocol on stdout
+    const useStderr = !config.useHttp;
+
+    // Initialize logger with configured level, format, and output stream
+    initLogger(config.logLevel, config.logFormat, useStderr);
+
+    logger.info('Loaded Home Assistant configuration', {
+      baseUrl: config.baseUrl,
+      hasToken: !!config.token,
+      strictSsl: config.strictSsl,
+      timeout: config.timeout,
+      useHttp: config.useHttp,
+      httpTransport: config.useHttp ? config.httpTransport : undefined,
+      aiProvider: config.aiProvider,
+      aiUrl: config.aiUrl,
+      aiModel: config.aiModel,
+    });
+
+    // Create Home Assistant client
+    const client = new HaClient(config);
+
+    // Test Home Assistant connection
+    const apiCheck = await client.checkApi();
+    logger.info('Connected to Home Assistant', { message: apiCheck.message });
+
+    // Create Local AI client for AI analysis (unless explicitly disabled)
+    let aiClient: LocalAIClient | undefined;
+    if (config.aiProvider === 'none') {
+      logger.info('AI features disabled (AI_PROVIDER=none)');
+    } else {
+      aiClient = new LocalAIClient(config);
+      const aiHealthy = await aiClient.checkHealth();
+      if (aiHealthy) {
+        logger.info('Connected to AI provider', {
+          provider: aiClient.getProviderName(),
+          url: config.aiUrl,
+          model: config.aiModel,
+        });
+      } else {
+        logger.warn('AI provider not available - AI analysis tool will be disabled', {
+          provider: config.aiProvider,
+          url: config.aiUrl,
+        });
+        aiClient = undefined;
+      }
+    }
+
+    // Start server in appropriate mode
+    if (config.useHttp) {
+      await startHttpServer(client, config, aiClient);
+    } else {
+      await startStdioServer(client, aiClient);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error('Failed to start Home Assistant MCP server', {
+      error: message,
+      stack: error instanceof Error ? error.stack : undefined,
+    });
+    process.exitCode = 1;
+  }
+}
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+  logger.info('Received SIGINT, shutting down gracefully');
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  logger.info('Received SIGTERM, shutting down gracefully');
+  process.exit(0);
+});
+
+// Start the server
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  logger.error('Unhandled error in main', { error: message });
+  process.exitCode = 1;
+});