@coffeerunhobby/mcp-ha-connect 0.5.0

package/src/server/rateLimiter.ts

@@ -0,0 +1,195 @@
+/**
+ * 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
+}
+
+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 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.keyGenerator = config.keyGenerator ?? this.defaultKeyGenerator;
+
+    // Start cleanup interval to prevent memory leaks
+    this.startCleanup();
+  }
+
+  /**
+   * Default key generator - uses IP address
+   */
+  private defaultKeyGenerator(req: IncomingMessage): string {
+    // Try to get real IP from common proxy headers
+    const forwardedFor = req.headers['x-forwarded-for'];
+    if (forwardedFor) {
+      const ips = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor;
+      return ips.split(',')[0].trim();
+    }
+
+    const realIp = req.headers['x-real-ip'];
+    if (realIp) {
+      return Array.isArray(realIp) ? realIp[0] : realIp;
+    }
+
+    // Fall back to socket remote address
+    return req.socket.remoteAddress ?? 'unknown';
+  }
+
+  /**
+   * 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/sse.ts

@@ -0,0 +1,120 @@
+/**
+ * SSE (Server-Sent Events) transport for MCP server
+ * Implements the legacy MCP protocol version 2024-11-05
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import type { EnvironmentConfig } from '../config.js';
+import type { HaClient } from '../haClient/index.js';
+import type { LocalAIClient } from '../localAI/index.js';
+import { logger } from '../utils/logger.js';
+import { createServer } from './common.js';
+
+const MESSAGE_PATH = '/messages';
+
+interface SSETransportState {
+  transport: SSEServerTransport;
+  server: ReturnType<typeof createServer>;
+}
+
+/**
+ * Creates an SSE transport for handling HTTP+SSE connections
+ */
+export function createSseTransport(
+  client: HaClient,
+  config: EnvironmentConfig,
+  endpoint: string,
+  res: ServerResponse,
+  aiClient?: LocalAIClient
+): SSETransportState {
+  const mcpServer = createServer(client, aiClient);
+
+  const transport = new SSEServerTransport(endpoint, res, {
+    allowedOrigins: config.httpAllowedOrigins,
+    enableDnsRebindingProtection: true,
+  });
+
+  transport.onerror = (error: Error) => {
+    logger.error('SSE transport error', {
+      error,
+      message: error.message,
+    });
+  };
+
+  return { transport, server: mcpServer };
+}
+
+/**
+ * Handles SSE connection establishment (GET request)
+ */
+export async function handleSseConnection(
+  client: HaClient,
+  config: EnvironmentConfig,
+  endpoint: string,
+  req: IncomingMessage,
+  res: ServerResponse,
+  aiClient?: LocalAIClient
+): Promise<SSETransportState> {
+  const originHeader = req.headers.origin;
+  const hostHeader = req.headers.host;
+
+  logger.info('SSE connection request received', {
+    method: req.method,
+    url: req.url,
+    origin: originHeader ?? '(not set)',
+    host: hostHeader ?? '(not set)',
+  });
+
+  try {
+    const { transport, server } = createSseTransport(client, config, endpoint, res, aiClient);
+
+    await server.connect(transport);
+    await transport.start();
+
+    logger.info('SSE connection established', {
+      sessionId: transport.sessionId,
+    });
+
+    return { transport, server };
+  } catch (error) {
+    logger.error('Failed to establish SSE connection', {
+      error,
+      origin: originHeader ?? '(not set)',
+      host: hostHeader ?? '(not set)',
+      allowedOrigins: config.httpAllowedOrigins,
+    });
+    throw error;
+  }
+}
+
+/**
+ * Handles SSE message POST requests
+ */
+export async function handleSseMessage(
+  transport: SSEServerTransport,
+  req: IncomingMessage,
+  res: ServerResponse,
+  parsedBody?: unknown
+): Promise<void> {
+  logger.debug('SSE message received', {
+    sessionId: transport.sessionId,
+    hasBody: !!parsedBody,
+  });
+
+  await transport.handlePostMessage(req, res, parsedBody);
+
+  logger.debug('SSE message handled', {
+    sessionId: transport.sessionId,
+  });
+}
+
+/**
+ * Returns the message endpoint path for SSE transport
+ */
+export function getSseMessagePath(): string {
+  return MESSAGE_PATH;
+}
+
+// Export type
+export type { SSETransportState };

package/src/server/stdio.ts

@@ -0,0 +1,22 @@
+/**
+ * Stdio transport for MCP server
+ * Used for Claude Desktop and other stdio-based clients
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import type { HaClient } from '../haClient/index.js';
+import type { LocalAIClient } from '../localAI/index.js';
+import { logger } from '../utils/logger.js';
+import { createServer } from './common.js';
+
+export async function startStdioServer(client: HaClient, aiClient?: LocalAIClient): Promise<void> {
+  logger.info('Starting stdio server');
+
+  const server = createServer(client, aiClient);
+  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

@@ -0,0 +1,113 @@
+/**
+ * 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 { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { EnvironmentConfig } from '../config.js';
+import type { HaClient } from '../haClient/index.js';
+import type { LocalAIClient } from '../localAI/index.js';
+import { logger } from '../utils/logger.js';
+import { createServer } from './common.js';
+
+interface StreamTransportState {
+  transport: StreamableHTTPServerTransport;
+  server: ReturnType<typeof createServer>;
+}
+
+// Export the type for use in http.ts
+export type { StreamTransportState };
+
+/**
+ * Creates a Streamable HTTP transport
+ * This implements the MCP protocol version 2025-03-26
+ */
+export function createStreamTransport(client: HaClient, config: EnvironmentConfig, aiClient?: LocalAIClient): StreamTransportState {
+  const mcpServer = createServer(client, aiClient);
+
+  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 transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator,
+    allowedOrigins: config.httpAllowedOrigins,
+    enableDnsRebindingProtection: true,
+    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(
+  client: HaClient,
+  config: EnvironmentConfig,
+  req: IncomingMessage,
+  res: ServerResponse,
+  parsedBody?: unknown,
+  existingTransport?: StreamTransportState,
+  aiClient?: LocalAIClient
+): Promise<StreamTransportState | void> {
+  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
+  const state = existingTransport ?? createStreamTransport(client, config, aiClient);
+
+  if (!existingTransport) {
+    await state.server.connect(state.transport);
+  }
+
+  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/callService.ts

@@ -0,0 +1,114 @@
+/**
+ * Call Service Tool
+ * Calls a Home Assistant service
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import type { HaClient } from '../haClient/index.js';
+import type { ServiceCallData } from '../types/index.js';
+import { logger } from '../utils/logger.js';
+
+export function registerCallServiceTool(server: Server, client: HaClient): void {
+  logger.debug('Registering callService tool');
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: 'callService',
+          description: 'Call a Home Assistant service (e.g., turn on a light, set temperature).',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              domain: {
+                type: 'string',
+                description: 'Service domain (e.g., "light", "switch", "climate", "notify")',
+              },
+              service: {
+                type: 'string',
+                description: 'Service name (e.g., "turn_on", "turn_off", "set_temperature")',
+              },
+              service_data: {
+                type: 'object',
+                description: 'Optional service data (e.g., {"brightness": 255})',
+              },
+              target: {
+                type: 'object',
+                description: 'Optional target (entity_id, device_id, or area_id)',
+                properties: {
+                  entity_id: {
+                    type: ['string', 'array'],
+                    description: 'Entity ID or array of entity IDs',
+                  },
+                },
+              },
+            },
+            required: ['domain', 'service'],
+          },
+        },
+      ],
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name !== 'callService') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ error: 'Unknown tool' }),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    try {
+      const args = request.params.arguments as unknown as ServiceCallData;
+
+      if (!args.domain || !args.service) {
+        throw new Error('domain and service are required');
+      }
+
+      logger.info('Executing callService tool', {
+        domain: args.domain,
+        service: args.service,
+      });
+
+      const result = await client.callService(args);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              success: true,
+              context: result.context,
+            }, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      logger.error('Failed to call service', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              error: 'Failed to call service',
+              message: error instanceof Error ? error.message : String(error),
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+}

package/src/tools/getEntitiesByDomain.ts

@@ -0,0 +1,92 @@
+/**
+ * Get Entities By Domain Tool
+ * Gets all entities for a specific domain
+ */
+
+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 registerGetEntitiesByDomainTool(server: Server, client: HaClient): void {
+  logger.debug('Registering getEntitiesByDomain tool');
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: 'getEntitiesByDomain',
+          description: 'Get all entities for a specific domain (e.g., all lights, all sensors).',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              domain: {
+                type: 'string',
+                description: 'Domain name (e.g., "light", "sensor", "switch", "climate")',
+              },
+            },
+            required: ['domain'],
+          },
+        },
+      ],
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name !== 'getEntitiesByDomain') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ error: 'Unknown tool' }),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    try {
+      const { domain } = request.params.arguments as { domain: string };
+
+      if (!domain) {
+        throw new Error('domain is required');
+      }
+
+      logger.info('Executing getEntitiesByDomain tool', { domain });
+      const entities = await client.getEntitiesByDomain(domain);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              domain,
+              count: entities.length,
+              entities,
+            }, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      logger.error('Failed to get entities by domain', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              error: 'Failed to get entities by domain',
+              message: error instanceof Error ? error.message : String(error),
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+}