@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.3.1

package/src/haClient/updates.ts

@@ -1,58 +0,0 @@
-/**
- * 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/haClient/wsCommand.ts

@@ -1,44 +0,0 @@
-/**
- * One-shot Home Assistant WebSocket command: connect, authenticate, send one
- * command, return its result, disconnect. For the few HA APIs that exist only
- * over WebSocket (e.g. automation traces), usable in every transport mode.
- */
-
-import { EventSubscriber } from './events.js';
-
-export type HaWebSocketCommand = <T = unknown>(command: { type: string; [key: string]: unknown }) => Promise<T>;
-
-export function createHaWebSocketCommand(config: {
-    baseUrl: string;
-    token: string;
-    strictSsl?: boolean;
-    /** One deadline for connecting, authenticating and the command (ms). Default 30 s. */
-    timeoutMs?: number;
-}): HaWebSocketCommand {
-    const timeoutMs = config.timeoutMs ?? 30000;
-    return async <T>(command: { type: string; [key: string]: unknown }): Promise<T> => {
-        const connection = new EventSubscriber({
-            baseUrl: config.baseUrl,
-            token: config.token,
-            strictSsl: config.strictSsl,
-            maxReconnectAttempts: 0,
-            connectTimeout: timeoutMs,
-        });
-        let timer: ReturnType<typeof setTimeout> | undefined;
-        const deadline = new Promise<never>((_, reject) => {
-            timer = setTimeout(() => reject(new Error(`Home Assistant command '${command.type}' timed out`)), timeoutMs);
-        });
-        const work = (async () => {
-            await connection.connect();
-            return await connection.sendCommand<T>(command, timeoutMs);
-        })();
-        // If the deadline wins, the abandoned attempt still settles later: observe it.
-        work.catch(() => undefined);
-        try {
-            return await Promise.race([work, deadline]);
-        } finally {
-            clearTimeout(timer);
-            connection.disconnect();
-        }
-    };
-}

package/src/index.ts

@@ -1,164 +0,0 @@
-#!/usr/bin/env node
-/**
- * Home Assistant MCP Server
- * Entry point for the Model Context Protocol server
- * Supports transport modes: stdio, HTTP (Streamable HTTP)
- */
-
-import { loadConfig } from './config.js';
-import { HaClient } from './haClient/index.js';
-import { LocalAIClient } from './localAI/index.js';
-import { OmadaClient } from './omadaClient/index.js';
-import { checkConfiguredSite } from './omadaClient/site.js';
-import { startHttpServer } from './server/http.js';
-import { startStdioServer } from './server/stdio.js';
-import { initLogger, logger } from './utils/logger.js';
-import { VERSION } from './version.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(`mcp-ha-connect v${VERSION} starting`);
-    logger.info('Loaded configuration', {
-      haPluginEnabled: config.haPluginEnabled,
-      aiPluginEnabled: config.aiPluginEnabled,
-      omadaPluginEnabled: config.omadaPluginEnabled,
-      useHttp: config.useHttp,
-    });
-
-    // Create Home Assistant client (if plugin enabled and configured)
-    let haClient: HaClient | undefined;
-    if (config.haPluginEnabled) {
-      if (config.baseUrl && config.token) {
-        haClient = new HaClient({
-          baseUrl: config.baseUrl,
-          token: config.token,
-          timeout: config.timeout,
-          strictSsl: config.strictSsl,
-        });
-
-        // Test Home Assistant connection
-        const apiCheck = await haClient.checkApi();
-        logger.info('Connected to Home Assistant', { message: apiCheck.message });
-      } else {
-        logger.warn('HA plugin enabled but HA_URL or HA_TOKEN not set');
-      }
-    } else {
-      logger.info('Home Assistant plugin disabled');
-    }
-
-    // Create Omada client (if plugin enabled and configured)
-    let omadaClient: OmadaClient | undefined;
-    if (config.omadaPluginEnabled) {
-      if (config.omadaBaseUrl && config.omadaClientId && config.omadaClientSecret && config.omadacId) {
-        try {
-          omadaClient = new OmadaClient({
-            baseUrl: config.omadaBaseUrl,
-            clientId: config.omadaClientId,
-            clientSecret: config.omadaClientSecret,
-            omadacId: config.omadacId,
-            siteId: config.siteId,
-            strictSsl: config.omadaStrictSsl,
-            requestTimeout: config.requestTimeout,
-          });
-
-          // Test Omada connection by listing sites
-          const sites = await omadaClient.listSites();
-
-          // Omada is the source of truth: a configured OMADA_SITE_ID that isn't
-          // on the controller is a deployment bug (drifted site id), not a
-          // transient outage. Fail the Omada plugin loudly — HA and AI keep
-          // working — instead of silently scoping every read to a dead site.
-          const siteError = checkConfiguredSite(config.siteId, sites);
-          if (siteError) {
-            logger.error(`Omada plugin disabled - invalid OMADA_SITE_ID. ${siteError}`);
-            omadaClient = undefined;
-          } else {
-            logger.info('Connected to Omada controller', { siteCount: sites.length });
-          }
-        } catch (error) {
-          logger.warn('Omada controller not available - Omada tools will be disabled', {
-            error: error instanceof Error ? error.message : String(error),
-          });
-          omadaClient = undefined;
-        }
-      } else {
-        logger.warn('Omada plugin enabled but required config not set (OMADA_BASE_URL, OMADA_CLIENT_ID, OMADA_CLIENT_SECRET, OMADA_OMADAC_ID)');
-      }
-    } else {
-      logger.info('Omada plugin disabled');
-    }
-
-    // Create Local AI client (if plugin enabled)
-    let aiClient: LocalAIClient | undefined;
-    if (config.aiPluginEnabled) {
-      if (config.aiProvider === 'none') {
-        logger.info('AI plugin enabled but 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;
-        }
-      }
-    } else {
-      logger.info('AI plugin disabled');
-    }
-
-    // Start server in appropriate mode
-    if (config.useHttp) {
-      await startHttpServer({ haClient, omadaClient, aiClient, config });
-    } else {
-      await startStdioServer({
-        haClient,
-        omadaClient,
-        aiClient,
-        restActions: config.restActions,
-        toolRegistrationMode: config.toolRegistrationMode,
-      });
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    logger.error('Failed to start 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;
-});

package/src/localAI/index.ts

@@ -1,88 +0,0 @@
-/**
- * Local AI Client
- * Factory and facade for AI providers
- */
-
-import { logger } from '../utils/logger.js';
-import type { EnvironmentConfig } from '../config.js';
-import type { AIProviderConfig, AIProviderInterface, AnalysisResult, SensorData } from './types.js';
-import { OllamaProvider } from './providers/ollama.js';
-import { OpenAICompatibleProvider } from './providers/openai.js';
-
-// Re-export types for convenience
-export type { SensorData, AnalysisResult, AIProviderType } from './types.js';
-
-/**
- * Create the appropriate AI provider based on configuration
- */
-function createProvider(providerConfig: AIProviderConfig): AIProviderInterface {
-  switch (providerConfig.provider) {
-    case 'openai':
-      return new OpenAICompatibleProvider(providerConfig);
-    case 'ollama':
-    default:
-      return new OllamaProvider(providerConfig);
-  }
-}
-
-/**
- * Local AI Client
- * Facade for AI analysis using configurable providers
- */
-export class LocalAIClient {
-  private provider: AIProviderInterface;
-  private providerConfig: AIProviderConfig;
-
-  constructor(config: EnvironmentConfig) {
-    this.providerConfig = {
-      provider: config.aiProvider,
-      baseUrl: config.aiUrl,
-      model: config.aiModel,
-      timeout: config.aiTimeout,
-      apiKey: config.aiApiKey,
-    };
-
-    this.provider = createProvider(this.providerConfig);
-
-    logger.info('LocalAIClient initialized', {
-      provider: this.providerConfig.provider,
-      model: this.providerConfig.model,
-      url: this.providerConfig.baseUrl,
-    });
-  }
-
-  /**
-   * Analyze sensor data using AI
-   */
-  async analyzeSensors(sensors: SensorData): Promise<AnalysisResult> {
-    return this.provider.analyzeSensors(sensors);
-  }
-
-  /**
-   * Check if the AI provider is available
-   */
-  async checkHealth(): Promise<boolean> {
-    return this.provider.checkHealth();
-  }
-
-  /**
-   * Get the provider name
-   */
-  getProviderName(): string {
-    return this.provider.getProviderName();
-  }
-
-  /**
-   * Get the configured model name
-   */
-  getModelName(): string {
-    return this.providerConfig.model;
-  }
-
-  /**
-   * Get the provider configuration
-   */
-  getConfig(): Readonly<AIProviderConfig> {
-    return { ...this.providerConfig };
-  }
-}

package/src/localAI/prompts.ts

@@ -1,50 +0,0 @@
-/**
- * AI System Prompts
- * Shared prompts for sensor analysis across all providers
- */
-
-/**
- * System prompt for sensor analysis
- */
-export const SENSOR_ANALYSIS_SYSTEM_PROMPT = `You are a home automation AI analyzing Home Assistant sensors.
-
-SEVERITY RULES:
-- critical: Gas/smoke/CO detected, fire, temp>40°C indoors, power spike>500%, door open>2h with alarm
-- high: Battery<10%, power spike>300%, door open>30min with alarm, temp>35°C
-- medium: Battery<20%, connectivity issues, minor anomalies
-- low: Informational warnings
-
-OUTPUT FORMAT (JSON only, no markdown):
-{
-  "severity": "critical|high|medium|low",
-  "issue": "brief description",
-  "reasoning": "detailed explanation",
-  "recommended_actions": ["action1", "action2"],
-  "ssh_diagnostics": ["command1", "command2"],
-  "confidence": 0.85
-}
-
-Respond with JSON only. No extra text.`;
-
-/**
- * Build the full prompt for sensor analysis
- */
-export function buildSensorAnalysisPrompt(sensors: Record<string, unknown>): string {
-  return `${SENSOR_ANALYSIS_SYSTEM_PROMPT}\n\nAnalyze these sensors: ${JSON.stringify(sensors)}\n\nProvide JSON only:`;
-}
-
-/**
- * Build messages array for OpenAI-compatible APIs
- */
-export function buildChatMessages(sensors: Record<string, unknown>): Array<{ role: string; content: string }> {
-  return [
-    {
-      role: 'system',
-      content: SENSOR_ANALYSIS_SYSTEM_PROMPT,
-    },
-    {
-      role: 'user',
-      content: `Analyze these sensors: ${JSON.stringify(sensors)}\n\nProvide JSON only:`,
-    },
-  ];
-}

package/src/localAI/providers/base.ts

@@ -1,120 +0,0 @@
-/**
- * Base AI Provider
- * Abstract class with shared logic for all AI providers
- */
-
-import { logger } from '../../utils/logger.js';
-import type { AIProviderConfig, AIProviderInterface, AnalysisResult, SensorData } from '../types.js';
-
-/**
- * Raw analysis result from AI (before adding metadata)
- */
-export interface RawAnalysisResult {
-  severity: 'critical' | 'high' | 'medium' | 'low';
-  issue: string;
-  reasoning: string;
-  recommended_actions: string[];
-  ssh_diagnostics: string[];
-  confidence: number;
-}
-
-/**
- * Abstract base class for AI providers
- */
-export abstract class BaseAIProvider implements AIProviderInterface {
-  protected baseUrl: string;
-  protected model: string;
-  protected timeout: number;
-  protected apiKey?: string;
-
-  constructor(config: AIProviderConfig) {
-    this.baseUrl = config.baseUrl;
-    this.model = config.model;
-    this.timeout = config.timeout;
-    this.apiKey = config.apiKey;
-  }
-
-  /**
-   * Get the provider name - must be implemented by subclasses
-   */
-  abstract getProviderName(): string;
-
-  /**
-   * Make the actual API request - must be implemented by subclasses
-   */
-  protected abstract makeRequest(sensors: SensorData): Promise<string>;
-
-  /**
-   * Check health - must be implemented by subclasses
-   */
-  abstract checkHealth(): Promise<boolean>;
-
-  /**
-   * Analyze sensors using AI
-   */
-  async analyzeSensors(sensors: SensorData): Promise<AnalysisResult> {
-    const sensorCount = Object.keys(sensors).length;
-    const providerName = this.getProviderName();
-
-    logger.info('Starting AI analysis', { sensorCount, model: this.model, provider: providerName });
-
-    const startTime = Date.now();
-
-    try {
-      const aiText = await this.makeRequest(sensors);
-
-      if (!aiText) {
-        throw new Error(`Empty response from ${providerName}`);
-      }
-
-      // Extract JSON from response (handles potential text around JSON)
-      const analysis = this.extractJson(aiText);
-      const elapsed = (Date.now() - startTime) / 1000;
-
-      logger.info('AI analysis complete', {
-        severity: analysis.severity,
-        elapsed: `${elapsed.toFixed(2)}s`,
-        model: this.model,
-        provider: providerName,
-      });
-
-      return {
-        ...analysis,
-        model: this.model,
-        provider: providerName,
-        response_time: parseFloat(elapsed.toFixed(2)),
-      };
-    } catch (error) {
-      const elapsed = (Date.now() - startTime) / 1000;
-      logger.error('AI analysis failed', {
-        error: error instanceof Error ? error.message : String(error),
-        elapsed: `${elapsed.toFixed(2)}s`,
-        provider: providerName,
-      });
-      throw error;
-    }
-  }
-
-  /**
-   * Extract JSON from AI response text
-   */
-  protected extractJson(text: string): RawAnalysisResult {
-    // Try to find JSON object in the response
-    const jsonMatch = text.match(/\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}/);
-    if (!jsonMatch) {
-      throw new Error(`No JSON found in AI response: ${text.substring(0, 200)}`);
-    }
-
-    return JSON.parse(jsonMatch[0]) as RawAnalysisResult;
-  }
-
-  /**
-   * Build authorization headers if API key is set
-   */
-  protected getAuthHeaders(): Record<string, string> {
-    if (this.apiKey) {
-      return { Authorization: `Bearer ${this.apiKey}` };
-    }
-    return {};
-  }
-}

package/src/localAI/providers/ollama.ts

@@ -1,78 +0,0 @@
-/**
- * Ollama AI Provider
- * Native Ollama API implementation
- */
-
-import type { AIProviderConfig, SensorData } from '../types.js';
-import { buildSensorAnalysisPrompt } from '../prompts.js';
-import { BaseAIProvider } from './base.js';
-
-/**
- * Ollama API response format
- */
-interface OllamaResponse {
-  response?: string;
-  error?: string;
-}
-
-/**
- * Ollama AI provider using native Ollama API
- */
-export class OllamaProvider extends BaseAIProvider {
-  constructor(config: AIProviderConfig) {
-    super(config);
-  }
-
-  getProviderName(): string {
-    return 'ollama';
-  }
-
-  /**
-   * Make request to Ollama API
-   */
-  protected async makeRequest(sensors: SensorData): Promise<string> {
-    const prompt = buildSensorAnalysisPrompt(sensors);
-
-    const response = await fetch(`${this.baseUrl}/api/generate`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...this.getAuthHeaders(),
-      },
-      body: JSON.stringify({
-        model: this.model,
-        prompt,
-        stream: false,
-        options: {
-          temperature: 0.3,
-          num_predict: 2000,
-          num_ctx: 4096,
-        },
-      }),
-      signal: AbortSignal.timeout(this.timeout),
-    });
-
-    if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(`Ollama request failed: ${response.status} ${errorText}`);
-    }
-
-    const result = (await response.json()) as OllamaResponse;
-    return result.response ?? '';
-  }
-
-  /**
-   * Check if Ollama is available
-   */
-  async checkHealth(): Promise<boolean> {
-    try {
-      const response = await fetch(`${this.baseUrl}/api/tags`, {
-        headers: this.getAuthHeaders(),
-        signal: AbortSignal.timeout(5000),
-      });
-      return response.ok;
-    } catch {
-      return false;
-    }
-  }
-}

package/src/localAI/providers/openai.ts

@@ -1,86 +0,0 @@
-/**
- * OpenAI-Compatible AI Provider
- * Works with LocalAI, LM Studio, vLLM, and any OpenAI-compatible API
- */
-
-import type { AIProviderConfig, SensorData } from '../types.js';
-import { buildChatMessages } from '../prompts.js';
-import { BaseAIProvider } from './base.js';
-
-/**
- * OpenAI chat completion response format
- */
-interface OpenAIChatResponse {
-  choices?: Array<{
-    message?: {
-      content?: string;
-    };
-  }>;
-  error?: {
-    message?: string;
-  };
-}
-
-/**
- * OpenAI-compatible AI provider
- * Works with LocalAI, LM Studio, vLLM, and other OpenAI-compatible APIs
- */
-export class OpenAICompatibleProvider extends BaseAIProvider {
-  constructor(config: AIProviderConfig) {
-    super(config);
-  }
-
-  getProviderName(): string {
-    return 'openai-compatible';
-  }
-
-  /**
-   * Make request to OpenAI-compatible API
-   */
-  protected async makeRequest(sensors: SensorData): Promise<string> {
-    const messages = buildChatMessages(sensors);
-
-    const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...this.getAuthHeaders(),
-      },
-      body: JSON.stringify({
-        model: this.model,
-        messages,
-        temperature: 0.3,
-        max_tokens: 2000,
-      }),
-      signal: AbortSignal.timeout(this.timeout),
-    });
-
-    if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(`OpenAI-compatible API request failed: ${response.status} ${errorText}`);
-    }
-
-    const result = (await response.json()) as OpenAIChatResponse;
-
-    if (result.error) {
-      throw new Error(`API error: ${result.error.message}`);
-    }
-
-    return result.choices?.[0]?.message?.content ?? '';
-  }
-
-  /**
-   * Check if the OpenAI-compatible API is available
-   */
-  async checkHealth(): Promise<boolean> {
-    try {
-      const response = await fetch(`${this.baseUrl}/v1/models`, {
-        headers: this.getAuthHeaders(),
-        signal: AbortSignal.timeout(5000),
-      });
-      return response.ok;
-    } catch {
-      return false;
-    }
-  }
-}