@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.4.0

package/src/tools/homeassistant/getHistory.ts

@@ -1,24 +0,0 @@
-/**
- * getHistory tool - Get historical data for an entity
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { historySchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
-import type { z } from 'zod';
-
-type HistoryArgs = z.infer<typeof historySchema>;
-
-export function registerGetHistoryTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'getHistory',
-    {
-      description: 'Get historical data for an entity.',
-      inputSchema: historySchema,
-    },
-    wrapToolHandler('getHistory', async ({ entity_id, hours = 24 }: HistoryArgs) => {
-      const history = await client.getHistory(entity_id, hours);
-      return toToolResult(history);
-    }, Permission.QUERY)
-  );
-}

package/src/tools/homeassistant/getState.ts

@@ -1,24 +0,0 @@
-/**
- * getState tool - Get state of a specific entity
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { entityIdSchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
-
-export function registerGetStateTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'getState',
-    {
-      description: 'Get the state of a specific entity by entity_id.',
-      inputSchema: entityIdSchema,
-    },
-    wrapToolHandler('getState', async ({ entity_id }: { entity_id: string }) => {
-      const state = await client.getState(entity_id);
-      if (!state) {
-        return toToolResult({ error: 'Entity not found', entity_id, hint: 'Use the searchEntities tool with a keyword to find the correct entity_id' }, true);
-      }
-      return toToolResult(state);
-    }, Permission.QUERY)
-  );
-}

package/src/tools/homeassistant/getStates.ts

@@ -1,46 +0,0 @@
-/**
- * getStates tool - Get all entity states from Home Assistant
- * Returns paginated, lightweight entities by default to reduce response size.
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { toLightweight } from '../../types/index.js';
-import { haPaginationSchema, toToolResult, wrapToolHandler, Permission, paginateArray } from '../common.js';
-
-export function registerGetStatesTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'getStates',
-    {
-      description: 'Get all entity states from Home Assistant. Returns paginated lightweight entities by default (50 per page). Use includeAttributes=true for full entity data.',
-      inputSchema: haPaginationSchema,
-    },
-    wrapToolHandler('getStates', async (args) => {
-      const { page, pageSize, includeAttributes } = args;
-      const states = await client.getStates();
-
-      if (includeAttributes) {
-        // Return full entities with all attributes
-        const result = paginateArray(states, page, pageSize);
-        return toToolResult({
-          page: result.page,
-          pageSize: result.pageSize,
-          totalCount: result.totalCount,
-          totalPages: result.totalPages,
-          entities: result.items,
-        });
-      }
-
-      // Default: return lightweight entities
-      const lightweight = states.map(toLightweight);
-      const result = paginateArray(lightweight, page, pageSize);
-      return toToolResult({
-        page: result.page,
-        pageSize: result.pageSize,
-        totalCount: result.totalCount,
-        totalPages: result.totalPages,
-        entities: result.items,
-      });
-    }, Permission.QUERY)
-  );
-}

package/src/tools/homeassistant/getVersion.ts

@@ -1,21 +0,0 @@
-/**
- * getVersion tool - Get Home Assistant version info
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { emptySchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
-
-export function registerGetVersionTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'getVersion',
-    {
-      description: 'Get Home Assistant version and configuration information.',
-      inputSchema: emptySchema,
-    },
-    wrapToolHandler('getVersion', async () => {
-      const version = await client.getVersion();
-      return toToolResult(version);
-    }, Permission.QUERY)
-  );
-}

package/src/tools/homeassistant/index.ts

@@ -1,121 +0,0 @@
-/**
- * Home Assistant tools index - registers all HA MCP tools
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { logger } from '../../utils/logger.js';
-
-// State & Entity Tools
-import { registerGetStatesTool } from './getStates.js';
-import { registerGetStateTool } from './getState.js';
-import { registerGetEntitiesByDomainTool } from './getEntitiesByDomain.js';
-import { registerSearchEntitiesTool } from './searchEntities.js';
-import { registerGetAllSensorsTool } from './getAllSensors.js';
-import { registerListEntitiesTool } from './listEntities.js';
-import { registerGetDomainSummaryTool } from './getDomainSummary.js';
-import { registerGetHistoryTool } from './getHistory.js';
-
-// Service & Control Tools
-import { registerCallServiceTool } from './callService.js';
-import { registerEntityActionTool } from './entityAction.js';
-
-// Device Control Tools
-import { registerControlLightTool } from './controlLight.js';
-import { registerControlClimateTool } from './controlClimate.js';
-import { registerControlMediaPlayerTool } from './controlMediaPlayer.js';
-import { registerControlCoverTool } from './controlCover.js';
-import { registerControlFanTool } from './controlFan.js';
-import { registerActivateSceneTool, registerRunScriptTool } from './sceneAndScript.js';
-import { registerSendNotificationTool, registerListNotificationTargetsTool } from './sendNotification.js';
-
-// Automation Tools
-import { registerListAutomationsTool } from './listAutomations.js';
-import { registerTriggerAutomationTool } from './triggerAutomation.js';
-import {
-  registerEnableAutomationTool,
-  registerDisableAutomationTool,
-  registerToggleAutomationTool,
-  registerReloadAutomationsTool,
-} from './automationControls.js';
-import { registerCreateAutomationTool } from './createAutomation.js';
-import { registerDeleteAutomationTool } from './deleteAutomation.js';
-import { registerGetAutomationTraceTool } from './getAutomationTrace.js';
-
-// System Tools
-import { registerGetVersionTool } from './getVersion.js';
-import {
-  registerRestartHomeAssistantTool,
-  registerGetSystemLogTool,
-  registerCheckUpdatesTool,
-} from './systemTools.js';
-
-// Calendar Tools
-import { registerListCalendarsTool, registerGetCalendarEventsTool } from './calendar.js';
-
-// Person Tools
-import { registerListPersonsTool } from './listPersons.js';
-
-export function registerHomeAssistantTools(server: McpServer, client: HaClient): number {
-  logger.debug('Registering Home Assistant tools');
-  let toolCount = 0;
-
-  // State & Entity Tools
-  registerGetStatesTool(server, client);
-  registerGetStateTool(server, client);
-  registerGetEntitiesByDomainTool(server, client);
-  registerSearchEntitiesTool(server, client);
-  registerGetAllSensorsTool(server, client);
-  registerListEntitiesTool(server, client);
-  registerGetDomainSummaryTool(server, client);
-  registerGetHistoryTool(server, client);
-  toolCount += 8;
-
-  // Service & Control Tools
-  registerCallServiceTool(server, client);
-  registerEntityActionTool(server, client);
-  toolCount += 2;
-
-  // Device Control Tools
-  registerControlLightTool(server, client);
-  registerControlClimateTool(server, client);
-  registerControlMediaPlayerTool(server, client);
-  registerControlCoverTool(server, client);
-  registerControlFanTool(server, client);
-  registerActivateSceneTool(server, client);
-  registerRunScriptTool(server, client);
-  registerSendNotificationTool(server, client);
-  registerListNotificationTargetsTool(server, client);
-  toolCount += 9;
-
-  // Automation Tools
-  registerListAutomationsTool(server, client);
-  registerTriggerAutomationTool(server, client);
-  registerEnableAutomationTool(server, client);
-  registerDisableAutomationTool(server, client);
-  registerToggleAutomationTool(server, client);
-  registerReloadAutomationsTool(server, client);
-  registerCreateAutomationTool(server, client);
-  registerDeleteAutomationTool(server, client);
-  registerGetAutomationTraceTool(server, client);
-  toolCount += 9;
-
-  // System Tools
-  registerGetVersionTool(server, client);
-  registerRestartHomeAssistantTool(server, client);
-  registerGetSystemLogTool(server, client);
-  registerCheckUpdatesTool(server, client);
-  toolCount += 4;
-
-  // Calendar Tools
-  registerListCalendarsTool(server, client);
-  registerGetCalendarEventsTool(server, client);
-  toolCount += 2;
-
-  // Person Tools
-  registerListPersonsTool(server, client);
-  toolCount += 1;
-
-  logger.info('Home Assistant tools registered', { toolCount });
-  return toolCount;
-}

package/src/tools/homeassistant/listAutomations.ts

@@ -1,35 +0,0 @@
-/**
- * listAutomations tool - List all automations
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { automationFilterSchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
-import type { z } from 'zod';
-
-type ListAutomationsArgs = z.infer<typeof automationFilterSchema>;
-
-/**
- * Shared handler — used by the MCP registration below AND the chat face
- * (`POST /api/tools/listAutomations`) so both doors behave identically.
- */
-export function createListAutomationsHandler(client: HaClient) {
-  return wrapToolHandler('listAutomations', async ({ state }: ListAutomationsArgs) => {
-    let automations = await client.getAutomations();
-    if (state) {
-      automations = automations.filter(a => a.state === state);
-    }
-    return toToolResult({ count: automations.length, filter: state ? { state } : null, automations });
-  }, Permission.QUERY);
-}
-
-export function registerListAutomationsTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'listAutomations',
-    {
-      description: 'List all Home Assistant automations with their status and last triggered time.',
-      inputSchema: automationFilterSchema,
-    },
-    createListAutomationsHandler(client)
-  );
-}

package/src/tools/homeassistant/listEntities.ts

@@ -1,44 +0,0 @@
-/**
- * listEntities tool - List entities with optional filtering
- * Returns lightweight entities by default to reduce response size.
- */
-
-import { z } from 'zod';
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { toLightweight } from '../../types/index.js';
-import { toToolResult, wrapToolHandler, Permission } from '../common.js';
-
-const listEntitiesSchema = z.object({
-  domain: z.string().optional().describe('Filter by domain (e.g., "light", "switch", "sensor")'),
-  search: z.string().optional().describe('Search query to filter by entity_id or friendly_name'),
-  state: z.string().optional().describe('Filter by state (e.g., "on", "off", "unavailable")'),
-  limit: z.number().int().min(1).max(200).default(50).describe('Maximum number of entities to return (1-200, default 50)'),
-  includeAttributes: z.boolean().default(false).describe('Include full attributes (increases response size significantly)'),
-});
-
-type ListEntitiesArgs = z.infer<typeof listEntitiesSchema>;
-
-export function registerListEntitiesTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'listEntities',
-    {
-      description: 'List entities with optional filtering by domain, state, or search query. Returns lightweight entities by default (limit 50). Use includeAttributes=true for full entity data.',
-      inputSchema: listEntitiesSchema,
-    },
-    wrapToolHandler('listEntities', async (args: ListEntitiesArgs) => {
-      const { includeAttributes, ...filterArgs } = args;
-      const allEntities = await client.listEntities(filterArgs);
-
-      // Convert to lightweight entities unless full attributes requested
-      const entities = includeAttributes ? allEntities : allEntities.map(toLightweight);
-
-      return toToolResult({
-        count: entities.length,
-        limit: args.limit,
-        filters: { domain: args.domain, search: args.search, state: args.state },
-        entities,
-      });
-    }, Permission.QUERY)
-  );
-}

package/src/tools/homeassistant/listPersons.ts

@@ -1,46 +0,0 @@
-/**
- * listPersons tool - List all person entities (household members)
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { emptySchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
-
-export function registerListPersonsTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'listPersons',
-    {
-      description: `List all household members (person entities) in Home Assistant.
-
-Returns each person's name, location state (home/away/unknown), and linked device trackers.
-
-Use this tool when the user asks:
-- "Who's home?"
-- "Where is everyone?"
-- "List family members"
-- "Is anyone home?"
-- "Where is Dad/Mom/etc?"`,
-      inputSchema: emptySchema,
-    },
-    wrapToolHandler('listPersons', async () => {
-      const entities = await client.getEntitiesByDomain('person');
-
-      const persons = entities.map(entity => ({
-        entity_id: entity.entity_id,
-        name: entity.attributes.friendly_name || entity.entity_id.replace('person.', ''),
-        state: entity.state, // home, not_home, unknown
-        device_trackers: entity.attributes.source ? [entity.attributes.source] : [],
-      }));
-
-      const onsiteCount = persons.filter(p => p.state === 'home').length;
-      const awayCount = persons.filter(p => p.state === 'not_home').length;
-
-      return toToolResult({
-        count: persons.length,
-        onsite: onsiteCount,
-        away: awayCount,
-        persons,
-      });
-    }, Permission.QUERY)
-  );
-}

package/src/tools/homeassistant/sceneAndScript.ts

@@ -1,53 +0,0 @@
-/**
- * Scene and Script tools - Activate scenes and run scripts
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { entityIdSchema, runScriptSchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
-import { entityNotFoundResult } from './entityGuard.js';
-import type { z } from 'zod';
-
-type EntityIdArgs = z.infer<typeof entityIdSchema>;
-type RunScriptArgs = z.infer<typeof runScriptSchema>;
-
-export function registerActivateSceneTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'activateScene',
-    {
-      description: 'Activate a Home Assistant scene.',
-      inputSchema: entityIdSchema,
-    },
-    wrapToolHandler('activateScene', async ({ entity_id }: EntityIdArgs) => {
-      const missing = await entityNotFoundResult(client, entity_id);
-      if (missing) return missing;
-      const result = await client.callService({
-        domain: 'scene',
-        service: 'turn_on',
-        target: { entity_id },
-      });
-      return toToolResult({ success: true, entity_id, action: 'activated', context: result.context });
-    }, Permission.CONTROL)
-  );
-}
-
-export function registerRunScriptTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'runScript',
-    {
-      description: 'Run a Home Assistant script with optional variables.',
-      inputSchema: runScriptSchema,
-    },
-    wrapToolHandler('runScript', async ({ entity_id, variables }: RunScriptArgs) => {
-      const missing = await entityNotFoundResult(client, entity_id);
-      if (missing) return missing;
-      const result = await client.callService({
-        domain: 'script',
-        service: 'turn_on',
-        target: { entity_id },
-        service_data: variables as Record<string, unknown> | undefined,
-      });
-      return toToolResult({ success: true, entity_id, action: 'executed', context: result.context });
-    }, Permission.CONTROL)
-  );
-}

package/src/tools/homeassistant/searchEntities.ts

@@ -1,58 +0,0 @@
-/**
- * searchEntities tool - Search for entities by name or entity_id
- * Returns paginated, lightweight entities by default to reduce response size.
- */
-
-import { z } from 'zod';
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { toLightweight } from '../../types/index.js';
-import { toToolResult, wrapToolHandler, Permission, paginateArray } from '../common.js';
-
-const searchEntitiesSchema = z.object({
-  query: z.string().describe('Search query (searches in entity_id and friendly_name)'),
-  page: z.number().int().min(1).default(1).describe('Page number (starts at 1)'),
-  pageSize: z.number().int().min(1).max(200).default(50).describe('Entities per page (1-200, default 50)'),
-  includeAttributes: z.boolean().default(false).describe('Include full attributes (increases response size significantly)'),
-});
-
-export function registerSearchEntitiesTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'searchEntities',
-    {
-      description: `Search for entities by name or entity_id. Returns paginated lightweight entities by default (50 per page). Use includeAttributes=true for full entity data.
-
-Note: For queries about people, family members, or "who's home?", use the listPersons tool instead.`,
-      inputSchema: searchEntitiesSchema,
-    },
-    wrapToolHandler('searchEntities', async (args) => {
-      const { query, page, pageSize, includeAttributes } = args;
-      const allEntities = await client.searchEntities(query);
-
-      if (includeAttributes) {
-        // Return full entities with all attributes
-        const result = paginateArray(allEntities, page, pageSize);
-        return toToolResult({
-          query,
-          page: result.page,
-          pageSize: result.pageSize,
-          totalCount: result.totalCount,
-          totalPages: result.totalPages,
-          entities: result.items,
-        });
-      }
-
-      // Default: return lightweight entities
-      const lightweight = allEntities.map(toLightweight);
-      const result = paginateArray(lightweight, page, pageSize);
-      return toToolResult({
-        query,
-        page: result.page,
-        pageSize: result.pageSize,
-        totalCount: result.totalCount,
-        totalPages: result.totalPages,
-        entities: result.items,
-      });
-    }, Permission.QUERY)
-  );
-}

package/src/tools/homeassistant/sendNotification.ts

@@ -1,179 +0,0 @@
-/**
- * sendNotification tool - Send notifications through Home Assistant
- * Supports HA Mobile App notifications with actions, images, sounds, and more
- */
-
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { HaClient } from '../../haClient/index.js';
-import { sendNotificationSchema, listNotificationTargetsSchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
-import type { z } from 'zod';
-
-type SendNotificationArgs = z.infer<typeof sendNotificationSchema>;
-
-/**
- * Build notification data object for mobile app
- */
-function buildNotificationData(args: SendNotificationArgs): Record<string, unknown> {
-  const data: Record<string, unknown> = {};
-
-  // Tag and grouping
-  if (args.tag) data.tag = args.tag;
-  if (args.group) data.group = args.group;
-
-  // Priority and importance (Android)
-  if (args.priority) data.priority = args.priority;
-  if (args.importance) data.importance = args.importance;
-  if (args.ttl) data.ttl = args.ttl;
-
-  // Actions - format for mobile app
-  if (args.actions && args.actions.length > 0) {
-    data.actions = args.actions.map(action => ({
-      action: action.action,
-      title: action.title,
-      ...(action.uri && { uri: action.uri }),
-    }));
-  }
-
-  // Media
-  if (args.image) data.image = args.image;
-  if (args.video) data.video = args.video;
-  if (args.icon_url) data.icon_url = args.icon_url;
-
-  // Behavior
-  if (args.sticky !== undefined) data.sticky = args.sticky;
-  if (args.persistent !== undefined) data.persistent = args.persistent;
-  if (args.clickAction) data.clickAction = args.clickAction;
-
-  // Sound and vibration (Android)
-  if (args.channel) data.channel = args.channel;
-  if (args.vibrationPattern) data.vibrationPattern = args.vibrationPattern;
-  if (args.ledColor) data.ledColor = args.ledColor;
-
-  // iOS specific
-  if (args.sound) data.sound = args.sound;
-  if (args.badge !== undefined) data.badge = args.badge;
-  if (args.interruptionLevel) data['push'] = { 'interruption-level': args.interruptionLevel };
-
-  // Merge any raw data passed through
-  if (args.data) {
-    Object.assign(data, args.data);
-  }
-
-  return data;
-}
-
-export function registerSendNotificationTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'sendNotification',
-    {
-      description: `Send a notification through Home Assistant Mobile App or persistent notifications.
-
-Features for mobile app notifications:
-- Actionable notifications with up to 3 buttons
-- Images and videos
-- Custom sounds and vibration patterns
-- Notification grouping and replacement (via tag)
-- Priority and importance settings
-- Sticky/persistent notifications
-- iOS interruption levels (passive, active, time-sensitive, critical)
-
-To clear a notification, send message "clear_notification" with the same tag.
-
-Examples:
-- Simple: { message: "Hello!", target: "mobile_app_phone" }
-- With actions: { message: "Doorbell", target: "mobile_app_phone", actions: [{ action: "OPEN", title: "Open Door" }] }
-- With image: { message: "Camera alert", target: "mobile_app_phone", image: "/api/camera_proxy/camera.front" }`,
-      inputSchema: sendNotificationSchema,
-    },
-    wrapToolHandler('sendNotification', async (args: SendNotificationArgs) => {
-      const serviceData: Record<string, unknown> = { message: args.message };
-
-      if (args.title) serviceData.title = args.title;
-
-      // Build mobile app data if any mobile-specific options provided
-      const notificationData = buildNotificationData(args);
-      if (Object.keys(notificationData).length > 0) {
-        serviceData.data = notificationData;
-      }
-
-      const service = args.target || 'persistent_notification';
-      const result = await client.callService({
-        domain: 'notify',
-        service,
-        service_data: serviceData,
-      });
-
-      return toToolResult({
-        success: true,
-        service: `notify.${service}`,
-        message: args.message,
-        title: args.title,
-        tag: args.tag,
-        hasActions: args.actions && args.actions.length > 0,
-        context: result.context,
-      });
-    }, Permission.NOTIFY)
-  );
-}
-
-export function registerListNotificationTargetsTool(server: McpServer, client: HaClient): void {
-  server.registerTool(
-    'listNotificationTargets',
-    {
-      description: 'List available notification targets (mobile apps and other notify services). Use this to discover which devices can receive notifications.',
-      inputSchema: listNotificationTargetsSchema,
-    },
-    wrapToolHandler('listNotificationTargets', async () => {
-      // Get all entities and find mobile_app device trackers to infer notify services
-      const states = await client.getStates();
-
-      // Find mobile app related entities
-      const mobileApps: Array<{ target: string; friendly_name?: string; type: string }> = [];
-
-      for (const entity of states) {
-        // Look for device_tracker.mobile_app_* entities which indicate mobile app presence
-        if (entity.entity_id.startsWith('device_tracker.') &&
-            entity.attributes.source_type === 'gps') {
-          // This might be a mobile app - extract the device name
-          const match = entity.entity_id.match(/device_tracker\.(.+)/);
-          if (match) {
-            const deviceName = match[1];
-            // Mobile app notify services are typically notify.mobile_app_<device>
-            mobileApps.push({
-              target: `mobile_app_${deviceName}`,
-              friendly_name: entity.attributes.friendly_name as string,
-              type: 'mobile_app',
-            });
-          }
-        }
-
-        // Also check for notify.* entities directly if available
-        if (entity.entity_id.startsWith('notify.')) {
-          const serviceName = entity.entity_id.replace('notify.', '');
-          mobileApps.push({
-            target: serviceName,
-            friendly_name: entity.attributes.friendly_name as string,
-            type: 'notify_service',
-          });
-        }
-      }
-
-      // Always include persistent_notification as it's always available
-      const targets = [
-        { target: 'persistent_notification', friendly_name: 'Persistent Notification (Web UI)', type: 'built_in' },
-        ...mobileApps,
-      ];
-
-      // Remove duplicates
-      const uniqueTargets = targets.filter((t, i, arr) =>
-        arr.findIndex(x => x.target === t.target) === i
-      );
-
-      return toToolResult({
-        count: uniqueTargets.length,
-        targets: uniqueTargets,
-        note: 'Mobile app targets are typically named "mobile_app_<device_name>". Use the target value in sendNotification.',
-      });
-    }, Permission.QUERY)
-  );
-}