@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.4.0

package/src/tools/omada/searchDevices.ts

@@ -1,20 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-
-import type { OmadaClient } from '../../omadaClient/index.js';
-import { toToolResult, wrapToolHandler, Permission } from '../common.js';
-
-const searchDevicesSchema = z.object({
-    searchKey: z.string().min(1, 'searchKey is required'),
-});
-
-export function registerSearchDevicesTool(server: McpServer, client: OmadaClient): void {
-    server.registerTool(
-        'omada_searchDevices',
-        {
-            description: 'Search for devices globally across all sites',
-            inputSchema: searchDevicesSchema,
-        },
-        wrapToolHandler('omada_searchDevices', async ({ searchKey }) => toToolResult(await client.searchDevices(searchKey)), Permission.QUERY)
-    );
-}

package/src/tools/omada/setClientRateLimit.ts

@@ -1,26 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-
-import type { OmadaClient } from '../../omadaClient/index.js';
-import { toToolResult, wrapToolHandler, Permission } from '../common.js';
-
-export function registerSetClientRateLimitTool(server: McpServer, client: OmadaClient): void {
-    const inputSchema = z.object({
-        clientMac: z.string().min(1, 'clientMac (MAC address) is required'),
-        downLimit: z.number().positive('downLimit must be a positive number (in Kbps)'),
-        upLimit: z.number().positive('upLimit must be a positive number (in Kbps)'),
-        siteId: z.string().min(1).optional(),
-    });
-
-    server.registerTool(
-        'omada_setClientRateLimit',
-        {
-            description: 'Set custom bandwidth limits for a client (download/upload in Kbps)',
-            inputSchema: inputSchema,
-        },
-        wrapToolHandler('omada_setClientRateLimit', async ({ clientMac, downLimit, upLimit, siteId }) =>
-            toToolResult(await client.setClientRateLimit(clientMac, downLimit, upLimit, siteId)),
-            Permission.CONTROL
-        )
-    );
-}

package/src/tools/omada/setClientRateLimitProfile.ts

@@ -1,25 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-
-import type { OmadaClient } from '../../omadaClient/index.js';
-import { toToolResult, wrapToolHandler, Permission } from '../common.js';
-
-export function registerSetClientRateLimitProfileTool(server: McpServer, client: OmadaClient): void {
-    const inputSchema = z.object({
-        clientMac: z.string().min(1, 'clientMac (MAC address) is required'),
-        profileId: z.string().min(1, 'profileId (rate limit profile ID) is required'),
-        siteId: z.string().min(1).optional(),
-    });
-
-    server.registerTool(
-        'omada_setClientRateLimitProfile',
-        {
-            description: 'Apply a rate limit profile to a client',
-            inputSchema: inputSchema,
-        },
-        wrapToolHandler('omada_setClientRateLimitProfile', async ({ clientMac, profileId, siteId }) =>
-            toToolResult(await client.setClientRateLimitProfile(clientMac, profileId, siteId)),
-            Permission.CONTROL
-        )
-    );
-}

package/src/tools/omada/setSiteNtpServers.ts

@@ -1,36 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-
-import type { OmadaClient } from '../../omadaClient/index.js';
-import { MAX_NTP_SERVERS } from '../../omadaClient/site.js';
-import { toToolResult, wrapToolHandler, Permission } from '../common.js';
-
-export const setSiteNtpServersSchema = z.object({
-    servers: z
-        .array(z.string().min(1))
-        .max(MAX_NTP_SERVERS)
-        .describe(`NTP server addresses (hostname or IPv4), in priority order; at most ${MAX_NTP_SERVERS}. Replaces the current list.`),
-    enabled: z.boolean().optional().describe('Turn the site NTP setting on (default) or off'),
-    siteId: z.string().min(1).optional(),
-    dryRun: z.boolean().optional().describe('If true, return the exact change without writing it'),
-});
-
-export function registerSetSiteNtpServersTool(server: McpServer, client: OmadaClient): void {
-    server.registerTool(
-        'omada_setSiteNtpServers',
-        {
-            description:
-                "Set a site's NTP (network time) servers, replacing the current list. " +
-                'Omada stores NTP in the site settings, so this re-writes the site settings with only the NTP fields changed; ' +
-                'the result shows the list before and after. Use dryRun first to preview. ' +
-                'Wrong time breaks certificates, logs and schedules on every network device - confirm with the user before applying.',
-            inputSchema: setSiteNtpServersSchema,
-        },
-        wrapToolHandler(
-            'omada_setSiteNtpServers',
-            async ({ servers, enabled, siteId, dryRun }: z.infer<typeof setSiteNtpServersSchema>) =>
-                toToolResult(await client.setSiteNtpServers(servers, { enabled, siteId, dryRun })),
-            Permission.CONFIGURE
-        )
-    );
-}

package/src/tools/omada/setSsidEnabled.ts

@@ -1,38 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-
-import type { OmadaClient } from '../../omadaClient/index.js';
-import { toToolResult, wrapToolHandler, Permission } from '../common.js';
-
-export const setSsidEnabledSchema = z.object({
-    ssid: z.string().min(1, 'ssid (SSID name or ssidId) is required'),
-    enabled: z.boolean(),
-    siteId: z.string().min(1).optional(),
-});
-
-/**
- * Shared handler — used by the MCP registration below AND the chat face
- * (`POST /api/tools/omada_setSsidEnabled`), so both doors run identical
- * validation + RBAC (v1.7 single-source-of-truth rule).
- */
-export function createSetSsidEnabledHandler(client: OmadaClient) {
-    return wrapToolHandler('omada_setSsidEnabled', async ({ ssid, enabled, siteId }: z.infer<typeof setSsidEnabledSchema>) =>
-        toToolResult(await client.setSsidEnabled(ssid, enabled, siteId)),
-        Permission.CONTROL
-    );
-}
-
-export function registerSetSsidEnabledTool(server: McpServer, client: OmadaClient): void {
-    server.registerTool(
-        'omada_setSsidEnabled',
-        {
-            description:
-                'Turn an SSID (WiFi network, e.g. the guest network) on or off by name or ssidId. ' +
-                'Omada has no direct SSID switch, so disabling applies a 24/7 "radio off" WLAN schedule ' +
-                '(the SSID stops broadcasting entirely) and enabling removes it — fully reversible. ' +
-                'All clients on that SSID lose connectivity when disabled - confirm with the user before applying.',
-            inputSchema: setSsidEnabledSchema,
-        },
-        createSetSsidEnabledHandler(client)
-    );
-}

package/src/tools/omada/unblockClient.ts

@@ -1,26 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-
-import type { OmadaClient } from '../../omadaClient/index.js';
-import { toToolResult, wrapToolHandler, Permission } from '../common.js';
-
-export function registerUnblockClientTool(server: McpServer, client: OmadaClient): void {
-    const inputSchema = z.object({
-        clientMac: z.string().min(1, 'clientMac (MAC address) is required'),
-        siteId: z.string().min(1).optional(),
-    });
-
-    server.registerTool(
-        'omada_unblockClient',
-        {
-            description:
-                'Unblock a previously blocked client by MAC address, restoring its network access. ' +
-                'Use omada_listClients first to find the exact MAC.',
-            inputSchema: inputSchema,
-        },
-        wrapToolHandler('omada_unblockClient', async ({ clientMac, siteId }) =>
-            toToolResult(await client.unblockClient(clientMac, siteId)),
-            Permission.CONTROL
-        )
-    );
-}

package/src/tools/types.ts

@@ -1,11 +0,0 @@
-/**
- * Tool type definitions
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../haClient/index.js';
-import type { LocalAIClient } from '../localAI/index.js';
-
-export interface ToolRegistration {
-  register(server: McpServer, client: HaClient, aiClient?: LocalAIClient): void;
-}

package/src/tools/utils/pagination-schema.ts

@@ -1,27 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Standard Omada API pagination parameters.
- * All paginated Omada API endpoints require both page and pageSize parameters.
- *
- * According to the API specification:
- * - page: Start page number. Start from 1. (required)
- * - pageSize: Number of entries per page. Range: 1-1000. (required)
- *
- * @param defaultPageSize - Default page size to use (default: 10)
- * @returns Zod object shape with page and pageSize fields
- */
-export function createPaginationSchema(defaultPageSize = 10) {
-    return {
-        page: z.number().int().min(1).default(1).describe('Start page number. Start from 1.'),
-        pageSize: z.number().int().min(1).max(1000).default(defaultPageSize).describe('Number of entries per page. Range: 1-1000.'),
-    };
-}
-
-/**
- * Type representing the pagination parameters shape.
- */
-export interface PaginationParams {
-    page: number;
-    pageSize: number;
-}

package/src/types/ai/index.ts

@@ -1,11 +0,0 @@
-/**
- * AI type exports
- */
-
-export type {
-  AIProviderType,
-  SensorData,
-  AnalysisResult,
-  AIProviderConfig,
-  AIProviderInterface,
-} from './types.js';

package/src/types/ai/types.ts

@@ -1,67 +0,0 @@
-/**
- * Local AI Client Types
- * Shared interfaces for AI provider implementations
- */
-
-/**
- * Supported AI provider types
- * Use 'none' to explicitly disable AI features
- */
-export type AIProviderType = 'ollama' | 'openai' | 'none';
-
-/**
- * Sensor data input for analysis
- */
-export interface SensorData {
-  [entity_id: string]: {
-    state: string;
-    unit?: string;
-    attributes?: Record<string, unknown>;
-  };
-}
-
-/**
- * AI analysis result
- */
-export interface AnalysisResult {
-  severity: 'critical' | 'high' | 'medium' | 'low';
-  issue: string;
-  reasoning: string;
-  recommended_actions: string[];
-  ssh_diagnostics: string[];
-  confidence: number;
-  model: string;
-  provider: string;
-  response_time: number;
-}
-
-/**
- * AI provider configuration
- */
-export interface AIProviderConfig {
-  provider: AIProviderType;
-  baseUrl: string;
-  model: string;
-  timeout: number;
-  apiKey?: string;
-}
-
-/**
- * AI provider interface - all providers must implement this
- */
-export interface AIProviderInterface {
-  /**
-   * Analyze sensor data using AI
-   */
-  analyzeSensors(sensors: SensorData): Promise<AnalysisResult>;
-
-  /**
-   * Check if the AI provider is available
-   */
-  checkHealth(): Promise<boolean>;
-
-  /**
-   * Get the provider name
-   */
-  getProviderName(): string;
-}

package/src/types/homeassistant/automations.ts

@@ -1,43 +0,0 @@
-/**
- * Automation-related types for Home Assistant
- */
-
-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 {
-  id?: string;
-  alias: string;
-  description?: string;
-  mode?: 'single' | 'restart' | 'queued' | 'parallel';
-  trigger: AutomationTrigger | AutomationTrigger[];
-  condition?: AutomationCondition | AutomationCondition[];
-  action: AutomationAction | AutomationAction[];
-}

package/src/types/homeassistant/calendars.ts

@@ -1,26 +0,0 @@
-/**
- * Calendar types for Home Assistant
- */
-
-export interface CalendarEvent {
-  summary: string;
-  start: {
-    dateTime?: string;
-    date?: string;
-  };
-  end: {
-    dateTime?: string;
-    date?: string;
-  };
-  description?: string;
-  location?: string;
-  uid?: string;
-  recurrence_id?: string;
-  rrule?: string;
-}
-
-export interface Calendar {
-  entity_id: string;
-  name: string;
-  state: string;
-}

package/src/types/homeassistant/config.ts

@@ -1,14 +0,0 @@
-/**
- * Home Assistant configuration and version types
- * Note: Only safe, public information - sensitive fields are filtered out
- */
-
-export interface HaVersion {
-  version: string;
-  location_name?: string;
-  time_zone?: string;
-  unit_system?: Record<string, string>;
-  // Excluded for privacy/security: config_dir, components, allowlist_external_dirs,
-  // allowlist_external_urls, state, external_url, internal_url, latitude, longitude,
-  // elevation, currency, country, language
-}

package/src/types/homeassistant/entities.ts

@@ -1,14 +0,0 @@
-/**
- * Entity summary types for Home Assistant
- */
-
-export interface DomainSummary {
-  domain: string;
-  count: number;
-  states: Record<string, number>;
-  entities: Array<{
-    entity_id: string;
-    state: string;
-    friendly_name?: string;
-  }>;
-}

package/src/types/homeassistant/errors.ts

@@ -1,33 +0,0 @@
-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/homeassistant/haConfig.ts

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

package/src/types/homeassistant/history.ts

@@ -1,13 +0,0 @@
-/**
- * History and logbook types for Home Assistant
- */
-
-export interface LogbookEntry {
-  when: string;
-  name: string;
-  message?: string;
-  entity_id?: string;
-  state?: string;
-  domain?: string;
-  context_user_id?: string;
-}

package/src/types/homeassistant/index.ts

@@ -1,46 +0,0 @@
-/**
- * Home Assistant type exports
- */
-
-// Configuration types
-export type { HaConfig } from './haConfig.js';
-export type { HaVersion } from './config.js';
-
-// State types
-export type { Entity, EntityListResponse, LightweightEntity, PaginatedEntityResponse } from './states.js';
-export { toLightweight } from './states.js';
-
-// Automation types
-export type {
-  Automation,
-  AutomationConfig,
-  AutomationTrigger,
-  AutomationCondition,
-  AutomationAction,
-} from './automations.js';
-
-// Entity summary types
-export type { DomainSummary } from './entities.js';
-
-// History types
-export type { LogbookEntry } from './history.js';
-
-// Update types
-export type {
-  UpdateInfo,
-  SupervisorCoreInfo,
-  SupervisorInfo,
-  SupervisorOsInfo,
-} from './updates.js';
-
-// Calendar types
-export type { CalendarEvent, Calendar } from './calendars.js';
-
-// Service call types
-export type { ServiceCallData, ServiceCallResponse } from './serviceCall.js';
-
-// Request types
-export type { RequestOptions } from './request.js';
-
-// Error types
-export { HaError, AuthenticationError, ApiError, ConfigurationError } from './errors.js';

package/src/types/homeassistant/request.ts

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

package/src/types/homeassistant/serviceCall.ts

@@ -1,18 +0,0 @@
-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/homeassistant/states.ts

@@ -1,58 +0,0 @@
-/**
- * State-related types for Home Assistant entities
- */
-
-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;
-  };
-}
-
-/**
- * Lightweight entity representation for reduced payload size.
- * Contains only essential fields needed for browsing/listing entities.
- */
-export interface LightweightEntity {
-  entity_id: string;
-  state: string;
-  friendly_name?: string;
-  unit_of_measurement?: string;
-  last_changed: string;
-}
-
-/**
- * Convert a full Entity to a LightweightEntity.
- * Reduces payload size by ~90% by excluding full attributes.
- */
-export function toLightweight(entity: Entity): LightweightEntity {
-  return {
-    entity_id: entity.entity_id,
-    state: entity.state,
-    friendly_name: entity.attributes?.friendly_name as string | undefined,
-    unit_of_measurement: entity.attributes?.unit_of_measurement as string | undefined,
-    last_changed: entity.last_changed,
-  };
-}
-
-/**
- * Paginated response for entity listings.
- */
-export interface PaginatedEntityResponse<T = LightweightEntity> {
-  page: number;
-  pageSize: number;
-  totalCount: number;
-  totalPages: number;
-  entities: T[];
-}
-
-export interface EntityListResponse {
-  entities: Entity[];
-  total: number;
-}

package/src/types/homeassistant/updates.ts

@@ -1,28 +0,0 @@
-/**
- * Update and supervisor types for Home Assistant
- */
-
-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/index.ts

@@ -1,12 +0,0 @@
-/**
- * Type exports - organized by domain
- */
-
-// Home Assistant types
-export * from './homeassistant/index.js';
-
-// Omada types
-export * from './omada/index.js';
-
-// AI types
-export * from './ai/index.js';

package/src/types/omada/activeClientInfo.ts

@@ -1,17 +0,0 @@
-/**
- * Active client information from dashboard.
- */
-export interface ActiveClientInfo {
-    /** Client name */
-    name: string;
-    /** Whether the client is wireless */
-    wireless: boolean;
-    /** Client device type */
-    type: string;
-    /** Client device model */
-    model: string;
-    /** Client MAC address */
-    mac: string;
-    /** Total traffic in bytes */
-    totalTraffic: number;
-}