@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.3.1

package/src/server/instructions.ts

@@ -1,97 +0,0 @@
-/**
- * MCP Server Instructions
- *
- * Provides guidance to LLMs on how to optimally use the server's tools.
- * These instructions are sent during initialization and help LLMs understand
- * tool relationships, best practices, and constraints.
- *
- * @see https://blog.modelcontextprotocol.io/posts/2025-11-03-using-server-instructions/
- */
-
-export interface InstructionsConfig {
-  haEnabled: boolean;
-  omadaEnabled: boolean;
-  aiEnabled: boolean;
-}
-
-/**
- * Generates server instructions based on enabled plugins.
- * Instructions are kept concise and actionable per MCP best practices.
- */
-export function generateInstructions(config: InstructionsConfig): string {
-  const sections: string[] = [];
-
-  // Base instructions
-  sections.push(
-    'MCP-HA-Connect: Smart home control via Home Assistant with network management via TP-Link Omada.'
-  );
-
-  if (config.haEnabled) {
-    sections.push(getHomeAssistantInstructions());
-  }
-
-  if (config.omadaEnabled) {
-    sections.push(getOmadaInstructions());
-  }
-
-  if (config.aiEnabled) {
-    sections.push(getAIInstructions());
-  }
-
-  // Cross-plugin relationships
-  if (config.haEnabled && config.omadaEnabled) {
-    sections.push(getCrossPluginInstructions());
-  }
-
-  return sections.join(' ');
-}
-
-function getHomeAssistantInstructions(): string {
-  return [
-    // Entity queries
-    'ENTITY QUERIES: Entity tools return paginated results (50/page default). Use includeAttributes=true only when full attribute data is needed. For people/family queries, use listPersons instead of searchEntities.',
-
-    // State management
-    'STATE: getState returns single entity; getStates returns all entities paginated. Use getDomainSummary for quick counts by domain.',
-
-    // Device control
-    'CONTROL: Use specialized control tools (controlLight, controlClimate, controlFan, controlCover, controlMediaPlayer) instead of generic callService when available - they provide better validation and defaults.',
-
-    // Automations
-    'AUTOMATIONS: After createAutomation, automations reload automatically. Use listAutomations to verify. triggerAutomation can pass variables to test automations safely.',
-
-    // Notifications
-    'NOTIFICATIONS: Use listNotificationTargets to discover available mobile devices before sendNotification. Target format is usually mobile_app_<device_name>.',
-  ].join(' ');
-}
-
-function getOmadaInstructions(): string {
-  return [
-    // Site context
-    'OMADA: Most Omada tools require siteId. Use omada_listSites first to get available sites if siteId is unknown.',
-
-    // Client vs Device
-    'CLIENTS vs DEVICES: Clients are connected users/devices (phones, laptops). Devices are network infrastructure (APs, switches, gateways). Use omada_listClients for user devices, omada_listDevices for infrastructure.',
-
-    // Rate limiting
-    'RATE LIMITS: Use omada_getRateLimitProfiles before setting limits. omada_setClientRateLimitProfile applies predefined profiles; omada_setClientRateLimit sets custom Kbps values.',
-
-    // Remote-hands actions (v1.6)
-    'ACTIONS: omada_cyclePoePort power-cycles PoE ports (remote-reboots APs/cameras; switch MAC via omada_listDevices). omada_setSsidEnabled toggles an SSID by name (guest WiFi on/off). omada_setSiteNtpServers sets site NTP.',
-
-    // Read-only preference
-    'SAFETY: Prefer read-only Omada tools. Rate limits, PoE cycling, and SSID toggles affect real availability - confirm with user before applying.',
-  ].join(' ');
-}
-
-function getAIInstructions(): string {
-  return [
-    'AI ANALYSIS: analyzeSensors uses local Ollama for privacy-preserving sensor analysis. Pass sensor data as key-value pairs. Useful for anomaly detection and recommendations.',
-  ].join(' ');
-}
-
-function getCrossPluginInstructions(): string {
-  return [
-    'INTEGRATION: Network clients from Omada can correlate with HA device_trackers for presence detection. HA person entities link to device_trackers which may correspond to Omada clients.',
-  ].join(' ');
-}

package/src/server/rateLimiter.ts

@@ -1,227 +0,0 @@
-/**
- * Rate Limiter Middleware
- * Simple token bucket rate limiter for HTTP endpoints
- */
-
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import { logger } from '../utils/logger.js';
-
-export interface RateLimitConfig {
-  windowMs?: number;      // Time window in milliseconds (default: 60000 = 1 minute)
-  maxRequests?: number;   // Maximum requests per window (default: 100)
-  skipPaths?: string[];   // Paths to skip rate limiting (e.g., health checks)
-  keyGenerator?: (req: IncomingMessage) => string;  // Custom key generator
-  /**
-   * Immediate-peer IPs whose forwarding headers (CF-Connecting-IP / X-Forwarded-For /
-   * X-Real-IP) may be trusted to identify the real client (M4). Empty by default —
-   * with no trusted proxy, client-supplied headers are IGNORED and the socket
-   * address is used, so a forged header cannot evade limits or grow the bucket map.
-   */
-  trustedProxies?: string[];
-}
-
-interface RateLimitEntry {
-  count: number;
-  windowStart: number;
-}
-
-/**
- * Rate Limiter class
- */
-export class RateLimiter {
-  private readonly windowMs: number;
-  private readonly maxRequests: number;
-  private readonly skipPaths: Set<string>;
-  private readonly keyGenerator: (req: IncomingMessage) => string;
-  private readonly trustedProxies: Set<string>;
-  private readonly entries = new Map<string, RateLimitEntry>();
-  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
-
-  constructor(config: RateLimitConfig = {}) {
-    this.windowMs = config.windowMs ?? 60000; // 1 minute default
-    this.maxRequests = config.maxRequests ?? 100; // 100 requests per minute
-    this.skipPaths = new Set(config.skipPaths ?? ['/health', '/healthcheck']);
-    this.trustedProxies = new Set(config.trustedProxies ?? []);
-    // Bind so a custom generator OR the default both see `this`.
-    this.keyGenerator = config.keyGenerator ?? ((req) => this.defaultKeyGenerator(req));
-
-    // Start cleanup interval to prevent memory leaks
-    this.startCleanup();
-  }
-
-  /** First value of a possibly-array header, trimmed; undefined if absent/empty. */
-  private firstHeader(value: string | string[] | undefined): string | undefined {
-    const v = Array.isArray(value) ? value[0] : value;
-    const trimmed = v?.trim();
-    return trimmed ? trimmed : undefined;
-  }
-
-  /**
-   * Default key generator (M4 / OWASP API4:2023).
-   *
-   * Client-supplied forwarding headers are honored ONLY when the immediate peer
-   * (`socket.remoteAddress`) is a configured trusted proxy. Otherwise we key on the
-   * socket address — an attacker cannot forge that, so they can neither evade the
-   * limit by rotating X-Forwarded-For nor exhaust memory with unbounded forged keys.
-   */
-  private defaultKeyGenerator(req: IncomingMessage): string {
-    const socketAddr = req.socket?.remoteAddress ?? 'unknown';
-
-    if (!this.trustedProxies.has(socketAddr)) {
-      return socketAddr;
-    }
-
-    // Behind a trusted proxy: prefer Cloudflare's single-client CF-Connecting-IP,
-    // then the left-most X-Forwarded-For hop, then X-Real-IP.
-    const cf = this.firstHeader(req.headers['cf-connecting-ip']);
-    if (cf) {
-      return cf;
-    }
-
-    const xff = this.firstHeader(req.headers['x-forwarded-for']);
-    if (xff) {
-      return xff.split(',')[0].trim();
-    }
-
-    const realIp = this.firstHeader(req.headers['x-real-ip']);
-    if (realIp) {
-      return realIp;
-    }
-
-    return socketAddr;
-  }
-
-  /**
-   * Start periodic cleanup of expired entries
-   */
-  private startCleanup(): void {
-    // Cleanup every window period
-    this.cleanupInterval = setInterval(() => {
-      const now = Date.now();
-      let cleaned = 0;
-
-      for (const [key, entry] of this.entries) {
-        if (now - entry.windowStart > this.windowMs * 2) {
-          this.entries.delete(key);
-          cleaned++;
-        }
-      }
-
-      if (cleaned > 0) {
-        logger.debug('Rate limiter cleanup', { entriesRemoved: cleaned, remaining: this.entries.size });
-      }
-    }, this.windowMs);
-  }
-
-  /**
-   * Stop cleanup interval
-   */
-  stop(): void {
-    if (this.cleanupInterval) {
-      clearInterval(this.cleanupInterval);
-      this.cleanupInterval = null;
-    }
-  }
-
-  /**
-   * Check if request should be allowed
-   */
-  check(req: IncomingMessage): { allowed: boolean; remaining: number; resetTime: number } {
-    const url = req.url ?? '/';
-    const path = url.split('?')[0];
-
-    // Skip rate limiting for certain paths
-    if (this.skipPaths.has(path)) {
-      return { allowed: true, remaining: this.maxRequests, resetTime: 0 };
-    }
-
-    const key = this.keyGenerator(req);
-    const now = Date.now();
-    let entry = this.entries.get(key);
-
-    // Create new entry or reset if window expired
-    if (!entry || now - entry.windowStart > this.windowMs) {
-      entry = { count: 0, windowStart: now };
-      this.entries.set(key, entry);
-    }
-
-    // Increment count
-    entry.count++;
-
-    const remaining = Math.max(0, this.maxRequests - entry.count);
-    const resetTime = entry.windowStart + this.windowMs;
-
-    if (entry.count > this.maxRequests) {
-      logger.warn('Rate limit exceeded', {
-        key,
-        count: entry.count,
-        limit: this.maxRequests,
-        path,
-      });
-      return { allowed: false, remaining: 0, resetTime };
-    }
-
-    return { allowed: true, remaining, resetTime };
-  }
-
-  /**
-   * Middleware function for HTTP server
-   */
-  middleware(): (req: IncomingMessage, res: ServerResponse) => boolean {
-    return (req: IncomingMessage, res: ServerResponse): boolean => {
-      const result = this.check(req);
-
-      // Add rate limit headers
-      res.setHeader('X-RateLimit-Limit', this.maxRequests.toString());
-      res.setHeader('X-RateLimit-Remaining', result.remaining.toString());
-      res.setHeader('X-RateLimit-Reset', Math.ceil(result.resetTime / 1000).toString());
-
-      if (!result.allowed) {
-        res.setHeader('Retry-After', Math.ceil((result.resetTime - Date.now()) / 1000).toString());
-        res.writeHead(429, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-          error: 'Too Many Requests',
-          message: 'Rate limit exceeded. Please try again later.',
-          retryAfter: Math.ceil((result.resetTime - Date.now()) / 1000),
-        }));
-        return false;
-      }
-
-      return true;
-    };
-  }
-
-  /**
-   * Get current stats
-   */
-  getStats(): { totalEntries: number; config: { windowMs: number; maxRequests: number } } {
-    return {
-      totalEntries: this.entries.size,
-      config: {
-        windowMs: this.windowMs,
-        maxRequests: this.maxRequests,
-      },
-    };
-  }
-
-  /**
-   * Reset rate limit for a specific key
-   */
-  reset(key: string): boolean {
-    return this.entries.delete(key);
-  }
-
-  /**
-   * Clear all rate limit entries
-   */
-  clear(): void {
-    this.entries.clear();
-  }
-}
-
-/**
- * Create a rate limiter instance with default config
- */
-export function createRateLimiter(config?: RateLimitConfig): RateLimiter {
-  return new RateLimiter(config);
-}

package/src/server/stdio.ts

@@ -1,41 +0,0 @@
-/**
- * Stdio transport for MCP server
- * Used for Claude Desktop and other stdio-based clients
- */
-
-import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
-import type { HaClient } from '../haClient/index.js';
-import type { LocalAIClient } from '../localAI/index.js';
-import type { OmadaClient } from '../omadaClient/index.js';
-import { logger } from '../utils/logger.js';
-import { setLocalFullTrust } from '../tools/common.js';
-import type { OmadaRegistrationMode } from '../tools/omada/index.js';
-import type { RestAction } from '../tools/infra/index.js';
-import { createServer } from './common.js';
-
-export interface StdioServerOptions {
-  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;
-}
-
-export async function startStdioServer(options: StdioServerOptions): Promise<void> {
-  logger.info('Starting stdio server');
-
-  // L3: stdio has no per-request auth; the local process owner is trusted. Grant
-  // full permissions to tool calls that arrive without an explicit mask. HTTP
-  // transports never enable this — they fail closed on a missing mask.
-  setLocalFullTrust(true);
-
-  const server = createServer(options);
-  const transport = new StdioServerTransport();
-
-  logger.info('Connecting stdio server');
-  await server.connect(transport);
-
-  logger.info('Stdio server connected and ready');
-}

package/src/server/stream.ts

@@ -1,205 +0,0 @@
-/**
- * Streamable HTTP transport for MCP server
- * Implements the MCP protocol version 2025-03-26 (current/recommended)
- */
-
-import { randomUUID } from 'node:crypto';
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
-import type { EnvironmentConfig } from '../config.js';
-import type { HaClient } from '../haClient/index.js';
-import type { LocalAIClient } from '../localAI/index.js';
-import type { OmadaClient } from '../omadaClient/index.js';
-import { logger } from '../utils/logger.js';
-import { createServer } from './common.js';
-import type { OwnerQuestionService } from '../ownerQuestions/service.js';
-import type { AuthenticatedRequest } from './auth.js';
-
-interface StreamTransportState {
-  transport: NodeStreamableHTTPServerTransport;
-  server: ReturnType<typeof createServer>;
-}
-
-// Export the type for use in http.ts
-export type { StreamTransportState };
-
-export interface StreamTransportOptions {
-  haClient?: HaClient;
-  omadaClient?: OmadaClient;
-  aiClient?: LocalAIClient;
-  config: EnvironmentConfig;
-  ownerQuestions?: OwnerQuestionService;
-}
-
-export interface TransportSecurityOptions {
-  allowedOrigins: string[];
-  allowedHosts: string[];
-  enableDnsRebindingProtection: boolean;
-}
-
-/**
- * Build the DNS-rebinding protection options for the Streamable HTTP transport
- * (M3 / OWASP A05:2021).
- *
- * Host-header validation is **opt-in**. The SDK only validates the `Host` header
- * when `allowedHosts` is non-empty (EXACT string match), and only validates
- * `Origin` when `allowedOrigins` is non-empty. CORS/Origin enforcement already
- * lives in the HTTP layer, so this helper governs ONLY the Host check and leaves
- * `allowedOrigins` empty to avoid double-enforcing origins at the transport.
- *
- * - `MCP_HTTP_ALLOWED_HOSTS` UNSET → Host validation OFF (protection disabled).
- *   This preserves pre-1.3.0 behavior: an upgrade never silently 403s clients
- *   that reach the server by a host not listed in the (CORS) origins. The
- *   server's own reachable host and its allowed CORS origins are frequently
- *   different addresses, so deriving hosts from origins would break real setups.
- * - `MCP_HTTP_ALLOWED_HOSTS` SET → enforce exactly those host[:port] values, plus
- *   loopback/bind-address conveniences so on-box health checks and local tools
- *   keep working. Any other `Host` header is rejected with a 403.
- */
-export function buildTransportSecurityOptions(config: EnvironmentConfig): TransportSecurityOptions {
-  const explicitHosts = config.httpAllowedHosts ?? [];
-
-  // Opt-out by default: no explicit hosts ⇒ no Host-header validation.
-  if (explicitHosts.length === 0) {
-    return { allowedOrigins: [], allowedHosts: [], enableDnsRebindingProtection: false };
-  }
-
-  const port = config.httpPort ?? 3000;
-  const bindAddr = config.httpBindAddr ?? '127.0.0.1';
-  const hosts = new Set<string>();
-
-  for (const entry of explicitHosts) {
-    try {
-      // Accept a full URL form (e.g. https://example.com) → host header form.
-      hosts.add(new URL(entry).host);
-    } catch {
-      // Bare hostname / IP[:port] already in host-header form.
-      hosts.add(entry);
-    }
-  }
-
-  // Always permit direct loopback / bind-address access on the listen port.
-  for (const host of [bindAddr, 'localhost', '127.0.0.1']) {
-    hosts.add(host);
-    hosts.add(`${host}:${port}`);
-  }
-
-  return {
-    allowedOrigins: [],
-    allowedHosts: [...hosts],
-    enableDnsRebindingProtection: true,
-  };
-}
-
-/**
- * Creates a Streamable HTTP transport
- * This implements the MCP protocol version 2025-03-26
- */
-export function createStreamTransport(options: StreamTransportOptions, callerPermissions?: number): StreamTransportState {
-  const { haClient, omadaClient, aiClient, config, ownerQuestions } = options;
-  const mcpServer = createServer({
-    haClient,
-    omadaClient,
-    aiClient,
-    ownerQuestions,
-    restActions: config.restActions,
-    toolRegistrationMode: config.toolRegistrationMode,
-    // Hide tools this caller can never use from tools/list (RBAC still enforced per call).
-    callerPermissions,
-  });
-
-  const enableStatefulSessions = config.stateful;
-  const sessionIdGenerator = enableStatefulSessions ? () => randomUUID() : undefined;
-
-  if (!enableStatefulSessions) {
-    logger.info('Starting Streamable HTTP transport in stateless mode; Mcp-Session-Id headers are optional');
-  }
-
-  const security = buildTransportSecurityOptions(config);
-
-  const transport = new NodeStreamableHTTPServerTransport({
-    sessionIdGenerator,
-    allowedOrigins: security.allowedOrigins,
-    allowedHosts: security.allowedHosts,
-    enableDnsRebindingProtection: security.enableDnsRebindingProtection,
-    onsessioninitialized: (sessionId: string) => {
-      logger.info('Session initialized', { sessionId });
-    },
-    onsessionclosed: (sessionId: string) => {
-      logger.info('Session closed', { sessionId });
-    },
-  });
-
-  transport.onerror = (error: Error) => {
-    logger.error('Streamable HTTP transport error', {
-      error,
-      message: error.message,
-    });
-  };
-
-  return { transport, server: mcpServer };
-}
-
-/**
- * Handles incoming Streamable HTTP requests (GET, POST, DELETE)
- * For stateful mode, transports should be stored and reused by the caller
- */
-export async function handleStreamRequest(
-  options: StreamTransportOptions,
-  req: IncomingMessage,
-  res: ServerResponse,
-  parsedBody?: unknown,
-  existingTransport?: StreamTransportState
-): Promise<StreamTransportState | void> {
-  const { config } = options;
-  const originHeader = req.headers.origin;
-  const hostHeader = req.headers.host;
-
-  logger.info('Streamable HTTP request received', {
-    method: req.method,
-    url: req.url,
-    sessionId: req.headers['mcp-session-id'] ?? undefined,
-    origin: originHeader ?? '(not set)',
-    host: hostHeader ?? '(not set)',
-  });
-
-  // Reuse existing transport if provided, otherwise create new one
-  // The auth middleware attached the caller's mask; a new server lists only the tools it permits.
-  const callerPermissions = (req as AuthenticatedRequest).auth?.extra?.permissions as number | undefined;
-  const state = existingTransport ?? createStreamTransport(options, callerPermissions);
-
-  if (!existingTransport) {
-    await state.server.connect(state.transport);
-  }
-
-  // Ensure Accept header includes required MIME types for SDK compatibility
-  // Some MCP clients (like n8n) don't send the full Accept header
-  const acceptHeader = req.headers.accept ?? '';
-  if (!acceptHeader.includes('text/event-stream') || !acceptHeader.includes('application/json')) {
-    req.headers.accept = 'application/json, text/event-stream';
-  }
-
-  try {
-    await state.transport.handleRequest(req, res, parsedBody);
-
-    logger.debug('Streamable HTTP request handled', {
-      method: req.method,
-      sessionId: req.headers['mcp-session-id'] ?? undefined,
-    });
-  } catch (error) {
-    logger.error('Failed to handle Streamable HTTP request', {
-      error,
-      method: req.method,
-      url: req.url,
-      origin: originHeader ?? '(not set)',
-      host: hostHeader ?? '(not set)',
-      allowedOrigins: config.httpAllowedOrigins,
-    });
-    throw error;
-  }
-
-  // Return state for session management if stateful
-  if (config.stateful) {
-    return state;
-  }
-}

package/src/tools/ai/analyzeSensors.ts

@@ -1,33 +0,0 @@
-/**
- * analyzeSensors tool - AI-powered sensor analysis
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { LocalAIClient, SensorData } from '../../localAI/index.js';
-import { analyzeSensorsSchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
-import type { z } from 'zod';
-
-type AnalyzeSensorsArgs = z.infer<typeof analyzeSensorsSchema>;
-
-export function registerAnalyzeSensorsTool(server: McpServer, aiClient?: LocalAIClient): void {
-  server.registerTool(
-    'analyzeSensors',
-    {
-      description: 'Analyze sensor data using AI (Ollama) to detect issues and provide recommendations.',
-      inputSchema: analyzeSensorsSchema,
-    },
-    wrapToolHandler('analyzeSensors', async ({ sensors }: AnalyzeSensorsArgs) => {
-      if (!aiClient) {
-        return toToolResult({
-          error: 'AI client not configured',
-          message: 'AI analysis requires AI_URL to be set (or legacy OLLAMA_URL)',
-        }, true);
-      }
-      if (!sensors || typeof sensors !== 'object') {
-        return toToolResult({ error: 'sensors object is required' }, true);
-      }
-      const analysis = await aiClient.analyzeSensors(sensors as SensorData);
-      return toToolResult(analysis);
-    }, Permission.AI)
-  );
-}

package/src/tools/ai/index.ts

@@ -1,20 +0,0 @@
-/**
- * AI tools index - registers all AI-powered MCP tools
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { LocalAIClient } from '../../localAI/index.js';
-import { logger } from '../../utils/logger.js';
-
-import { registerAnalyzeSensorsTool } from './analyzeSensors.js';
-
-export function registerAITools(server: McpServer, aiClient?: LocalAIClient): number {
-  logger.debug('Registering AI tools');
-  let toolCount = 0;
-
-  registerAnalyzeSensorsTool(server, aiClient);
-  toolCount += 1;
-
-  logger.info('AI tools registered', { toolCount, aiEnabled: !!aiClient });
-  return toolCount;
-}