@coffeerunhobby/mcp-ha-connect 0.5.0

package/src/tools/searchEntities.ts

@@ -0,0 +1,92 @@
+/**
+ * Search Entities Tool
+ * Search for entities by name or entity_id
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import type { HaClient } from '../haClient/index.js';
+import { logger } from '../utils/logger.js';
+
+export function registerSearchEntitiesTool(server: Server, client: HaClient): void {
+  logger.debug('Registering searchEntities tool');
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: 'searchEntities',
+          description: 'Search for entities by name or entity_id. Returns all matching entities.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              query: {
+                type: 'string',
+                description: 'Search query (searches in entity_id and friendly_name)',
+              },
+            },
+            required: ['query'],
+          },
+        },
+      ],
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name !== 'searchEntities') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ error: 'Unknown tool' }),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    try {
+      const { query } = request.params.arguments as { query: string };
+
+      if (!query) {
+        throw new Error('query is required');
+      }
+
+      logger.info('Executing searchEntities tool', { query });
+      const entities = await client.searchEntities(query);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              query,
+              count: entities.length,
+              entities,
+            }, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      logger.error('Failed to search entities', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              error: 'Failed to search entities',
+              message: error instanceof Error ? error.message : String(error),
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+}

package/src/types/entity.ts

@@ -0,0 +1,110 @@
+export interface Entity {
+  entity_id: string;
+  state: string;
+  attributes: Record<string, unknown>;
+  last_changed: string;
+  last_updated: string;
+  context: {
+    id: string;
+    parent_id: string | null;
+    user_id: string | null;
+  };
+}
+
+export interface EntityListResponse {
+  entities: Entity[];
+  total: number;
+}
+
+export interface Automation {
+  id: string;
+  alias: string;
+  state: 'on' | 'off';
+  last_triggered: string | null;
+  description?: string;
+  mode?: 'single' | 'restart' | 'queued' | 'parallel';
+}
+
+export interface AutomationTrigger {
+  platform: string;
+  [key: string]: unknown;
+}
+
+export interface AutomationCondition {
+  condition: string;
+  [key: string]: unknown;
+}
+
+export interface AutomationAction {
+  service?: string;
+  target?: {
+    entity_id?: string | string[];
+    device_id?: string | string[];
+    area_id?: string | string[];
+  };
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface AutomationConfig {
+  alias: string;
+  description?: string;
+  mode?: 'single' | 'restart' | 'queued' | 'parallel';
+  trigger: AutomationTrigger | AutomationTrigger[];
+  condition?: AutomationCondition | AutomationCondition[];
+  action: AutomationAction | AutomationAction[];
+}
+
+export interface DomainSummary {
+  domain: string;
+  count: number;
+  states: Record<string, number>;
+  entities: Array<{
+    entity_id: string;
+    state: string;
+    friendly_name?: string;
+  }>;
+}
+
+export interface HaVersion {
+  version: string;
+  location_name?: string;
+  config_dir?: string;
+  time_zone?: string;
+  unit_system?: Record<string, string>;
+}
+
+export interface LogbookEntry {
+  when: string;
+  name: string;
+  message?: string;
+  entity_id?: string;
+  state?: string;
+  domain?: string;
+  context_user_id?: string;
+}
+
+export interface UpdateInfo {
+  update_type: 'core' | 'supervisor' | 'os' | 'addon';
+  name: string;
+  version_current: string;
+  version_latest: string;
+}
+
+export interface SupervisorCoreInfo {
+  version: string;
+  version_latest?: string;
+  update_available?: boolean;
+}
+
+export interface SupervisorInfo {
+  version: string;
+  version_latest?: string;
+  update_available?: boolean;
+}
+
+export interface SupervisorOsInfo {
+  version: string;
+  version_latest?: string;
+  update_available?: boolean;
+}

package/src/types/errors.ts

@@ -0,0 +1,33 @@
+export class HaError extends Error {
+  constructor(
+    message: string,
+    public code?: string,
+    public statusCode?: number,
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = 'HaError';
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class AuthenticationError extends HaError {
+  constructor(message: string, details?: unknown) {
+    super(message, 'AUTH_ERROR', 401, details);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class ApiError extends HaError {
+  constructor(message: string, statusCode: number, details?: unknown) {
+    super(message, 'API_ERROR', statusCode, details);
+    this.name = 'ApiError';
+  }
+}
+
+export class ConfigurationError extends HaError {
+  constructor(message: string, details?: unknown) {
+    super(message, 'CONFIG_ERROR', undefined, details);
+    this.name = 'ConfigurationError';
+  }
+}

package/src/types/haConfig.ts

@@ -0,0 +1,7 @@
+export interface HaConfig {
+  baseUrl: string;
+  token: string;
+  strictSsl: boolean;
+  timeout: number;
+  logLevel: 'debug' | 'info' | 'warn' | 'error';
+}

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export type { HaConfig } from './haConfig.js';
+export type { Entity, EntityListResponse, Automation, AutomationConfig, AutomationTrigger, AutomationCondition, AutomationAction, DomainSummary, HaVersion, LogbookEntry, UpdateInfo, SupervisorCoreInfo, SupervisorInfo, SupervisorOsInfo } from './entity.js';
+export type { ServiceCallData, ServiceCallResponse } from './serviceCall.js';
+export type { RequestOptions } from './request.js';
+export { HaError, AuthenticationError, ApiError, ConfigurationError } from './errors.js';

package/src/types/request.ts

@@ -0,0 +1,6 @@
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  body?: unknown;
+  headers?: Record<string, string>;
+  params?: Record<string, string | number | boolean>;
+}

package/src/types/serviceCall.ts

@@ -0,0 +1,18 @@
+export interface ServiceCallData {
+  domain: string;
+  service: string;
+  service_data?: Record<string, unknown>;
+  target?: {
+    entity_id?: string | string[];
+    device_id?: string | string[];
+    area_id?: string | string[];
+  };
+}
+
+export interface ServiceCallResponse {
+  context: {
+    id: string;
+    parent_id: string | null;
+    user_id: string | null;
+  };
+}

package/src/types.ts

@@ -0,0 +1,2 @@
+// Barrel re-export from types folder
+export * from './types/index.js';

package/src/utils/config-validations.ts

@@ -0,0 +1,46 @@
+/**
+ * Configuration validation utilities
+ */
+
+/**
+ * Validates if a string is a valid IPv4 or IPv6 address
+ */
+export function isValidBindAddress(addr: string): boolean {
+  // IPv4 regex
+  const ipv4Regex = /^(\d{1,3}\.){3}\d{1,3}$/;
+  // IPv6 regex (simplified)
+  const ipv6Regex = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;
+
+  if (ipv4Regex.test(addr)) {
+    // Validate each octet is 0-255
+    const octets = addr.split('.');
+    return octets.every((octet) => {
+      const num = Number.parseInt(octet, 10);
+      return num >= 0 && num <= 255;
+    });
+  }
+
+  return ipv6Regex.test(addr) || addr === '::' || addr === '::1';
+}
+
+/**
+ * Validates if a string is a valid origin (for CORS)
+ */
+export function isValidOrigin(origin: string): boolean {
+  // Allow wildcard
+  if (origin === '*') return true;
+
+  // Allow localhost and specific hostnames
+  if (origin === 'localhost' || origin === '127.0.0.1' || origin === '::1') {
+    return true;
+  }
+
+  // Validate URL format
+  try {
+    new URL(origin);
+    return true;
+  } catch {
+    // If not a valid URL, check if it's just a hostname/IP
+    return /^[\w.-]+$/.test(origin) || isValidBindAddress(origin);
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,114 @@
+import pino from 'pino';
+
+type LogFields = Record<string, unknown>;
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+type LogFormat = 'plain' | 'json' | 'gcp-json';
+
+const levelToSeverity: Record<string, string> = {
+  trace: 'DEBUG',
+  debug: 'DEBUG',
+  info: 'INFO',
+  warn: 'WARNING',
+  error: 'ERROR',
+  fatal: 'CRITICAL',
+};
+
+let instance: pino.Logger;
+
+function createLogger(level: LogLevel = 'info', format: LogFormat = 'plain', useStderr = false): pino.Logger {
+  const baseConfig: pino.LoggerOptions = {
+    level,
+    base: undefined,
+    messageKey: 'message',
+    timestamp: pino.stdTimeFunctions.isoTime,
+  };
+
+  // Configure formatters based on format
+  if (format === 'gcp-json') {
+    baseConfig.formatters = {
+      level(label) {
+        return { severity: levelToSeverity[label] ?? label.toUpperCase() };
+      },
+    };
+  } else if (format === 'plain') {
+    baseConfig.formatters = {
+      level(label) {
+        return { level: label.toUpperCase() };
+      },
+    };
+  }
+  // For 'json' format, use default pino JSON output (no special formatters)
+
+  // When running in stdio mode, always log to stderr to avoid interfering with MCP protocol on stdout
+  return useStderr ? pino(baseConfig, process.stderr) : pino(baseConfig);
+}
+
+// Initialize with default, will be reconfigured by calling initLogger
+const defaultLevel = (process.env.MCP_SERVER_LOG_LEVEL as LogLevel | undefined) ?? 'info';
+instance = createLogger(defaultLevel);
+
+/**
+ * Initialize the logger with a specific log level and format.
+ * This should be called once during application startup.
+ * @param level - The minimum log level to output
+ * @param format - The output format (plain, json, or gcp-json)
+ * @param useStderr - If true, logs to stderr instead of stdout (required for stdio transport)
+ */
+export function initLogger(level: LogLevel, format: LogFormat = 'plain', useStderr = false): void {
+  instance = createLogger(level, format, useStderr);
+}
+
+/**
+ * Set the logger level dynamically
+ * @param level - The new log level
+ */
+export function setLevel(level: LogLevel): void {
+  instance.level = level;
+}
+
+function normalizeMeta(meta?: LogFields): LogFields | undefined {
+  if (!meta) {
+    return undefined;
+  }
+
+  const normalized: LogFields = {};
+  for (const [key, value] of Object.entries(meta)) {
+    if (value instanceof Error) {
+      normalized[key] = { message: value.message, stack: value.stack };
+      continue;
+    }
+
+    normalized[key] = value;
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+function write(level: LogLevel, message: string, meta?: LogFields): void {
+  const fields = normalizeMeta(meta);
+  if (fields) {
+    instance[level](fields, message);
+  } else {
+    instance[level](message);
+  }
+}
+
+export const logger = {
+  debug(message: string, meta?: LogFields) {
+    write('debug', message, meta);
+  },
+  info(message: string, meta?: LogFields) {
+    write('info', message, meta);
+  },
+  warn(message: string, meta?: LogFields) {
+    write('warn', message, meta);
+  },
+  error(message: string, meta?: LogFields) {
+    write('error', message, meta);
+  },
+};
+
+// Export types
+export type { LogLevel, LogFormat, LogFields };