maintenance.tool.ts•17.9 kB
/**
* Maintenance Tool for Home Assistant
*
* Provides recursive maintenance tasks similar to Spook add-on:
* - Clean up orphaned (verwaiste) devices
* - Analyze light usage patterns
* - Monitor energy consumption
* - Device health checks
*/
import { z } from "zod";
import { UserError } from "fastmcp";
import { logger } from "../../utils/logger.js";
import { BaseTool } from "../base-tool.js";
import { MCPContext } from "../../mcp/types.js";
import { get_hass } from "../../hass/index.js";
import { Tool } from "../../types/index.js";
// Define the schema for maintenance tool parameters
const maintenanceSchema = z.object({
action: z
.enum([
"find_orphaned_devices",
"analyze_light_usage",
"analyze_energy_consumption",
"cleanup_orphaned_entities",
"device_health_check",
"find_unused_automations",
"find_unavailable_entities",
])
.describe("The maintenance action to perform"),
days: z
.number()
.min(1)
.max(365)
.optional()
.default(30)
.describe("Number of days to analyze for usage patterns"),
cleanup: z
.boolean()
.optional()
.default(false)
.describe("Actually perform cleanup (default: false, only report)"),
entity_filter: z
.string()
.optional()
.describe("Filter entities by domain (e.g., 'light', 'sensor')"),
});
type MaintenanceParams = z.infer<typeof maintenanceSchema>;
interface OrphanedDevice {
entity_id: string;
state: string;
last_updated?: string;
friendly_name: string;
reason: string;
}
interface LightUsageAnalysis {
total_lights: number;
currently_on: number;
currently_off: number;
unavailable: number;
lights_by_room: Record<string, { total: number; on: number; off: number; unavailable: number }>;
never_used: Array<{
entity_id: string;
friendly_name: string;
last_changed?: string;
days_inactive: number | string;
}>;
high_usage: unknown[];
recommendations: string[];
}
interface EnergyItem {
entity_id: string;
friendly_name: string;
value: number;
unit: string;
device_class: string;
}
interface DeviceHealthInfo {
entity_id: string;
friendly_name: string;
battery_level: number;
}
// Maintenance service class
class HomeAssistantMaintenanceService {
/**
* Find orphaned devices that are unavailable or not responding
*/
async findOrphanedDevices(): Promise<OrphanedDevice[]> {
try {
const hass = await get_hass();
const states = await hass.getStates();
const orphanedDevices = states.filter((state) => {
const unavailable = state.state === "unavailable" || state.state === "unknown";
const notUpdatedRecently =
(state.last_updated ?? "").length > 0 &&
new Date(state.last_updated ?? "").getTime() < Date.now() - 30 * 24 * 60 * 60 * 1000;
return unavailable || notUpdatedRecently;
});
return orphanedDevices.map((device) => ({
entity_id: device.entity_id,
state: device.state,
last_updated: device.last_updated,
friendly_name: (device.attributes.friendly_name as string | undefined) ?? device.entity_id,
reason:
device.state === "unavailable"
? "unavailable"
: device.state === "unknown"
? "unknown"
: "not_updated",
}));
} catch (error) {
logger.error("Failed to find orphaned devices:", error);
throw error;
}
}
/**
* Analyze light usage patterns
*/
async analyzeLightUsage(days: number = 30): Promise<LightUsageAnalysis> {
try {
const hass = await get_hass();
const states = await hass.getStates();
const lights = states.filter((s) => s.entity_id.startsWith("light."));
const analysis: LightUsageAnalysis = {
total_lights: lights.length,
currently_on: lights.filter((l) => l.state === "on").length,
currently_off: lights.filter((l) => l.state === "off").length,
unavailable: lights.filter((l) => l.state === "unavailable").length,
lights_by_room: {},
never_used: [],
high_usage: [],
recommendations: [],
};
// Group by area/room
for (const light of lights) {
const area = ((light.attributes.area_id as string | undefined) ?? "") || "unassigned";
if (!analysis.lights_by_room[area]) {
analysis.lights_by_room[area] = {
total: 0,
on: 0,
off: 0,
unavailable: 0,
};
}
analysis.lights_by_room[area].total++;
if (light.state === "on") analysis.lights_by_room[area].on++;
if (light.state === "off") analysis.lights_by_room[area].off++;
if (light.state === "unavailable") analysis.lights_by_room[area].unavailable++;
}
// Find lights that are never used (always off or unavailable)
analysis.never_used = lights
.filter((l) => {
const lastChanged =
(l.last_changed ?? "").length > 0 ? new Date(l.last_changed ?? "") : null;
const daysSinceChange = lastChanged
? (Date.now() - lastChanged.getTime()) / (1000 * 60 * 60 * 24)
: Infinity;
return daysSinceChange > days;
})
.map((l) => ({
entity_id: l.entity_id,
friendly_name: (l.attributes.friendly_name as string | undefined) ?? l.entity_id,
last_changed: l.last_changed,
days_inactive:
(l.last_changed ?? "").length > 0
? Math.floor(
(Date.now() - new Date(l.last_changed ?? "").getTime()) / (1000 * 60 * 60 * 24),
)
: "unknown",
}));
// Generate recommendations
if (analysis.never_used.length > 0) {
analysis.recommendations.push(
`${analysis.never_used.length} lights haven't been used in ${days} days. Consider removing or checking them.`,
);
}
if (analysis.unavailable > 0) {
analysis.recommendations.push(
`${analysis.unavailable} lights are unavailable. Check their connections.`,
);
}
if (analysis.currently_on > analysis.total_lights * 0.3) {
analysis.recommendations.push(
`${analysis.currently_on} lights (${Math.round((analysis.currently_on / analysis.total_lights) * 100)}%) are currently on. Consider creating automations to turn them off.`,
);
}
return analysis;
} catch (error) {
logger.error("Failed to analyze light usage:", error);
throw error;
}
}
/**
* Analyze energy consumption
*/
async analyzeEnergyConsumption(_days: number = 30): Promise<{
total_sensors: number;
power_sensors: number;
energy_sensors: number;
current_consumption: EnergyItem[];
high_consumers: EnergyItem[];
recommendations: string[];
}> {
try {
const hass = await get_hass();
const states = await hass.getStates();
// Find energy sensors
const energySensors = states.filter(
(s) =>
s.entity_id.includes("energy") ||
s.entity_id.includes("power") ||
s.attributes.unit_of_measurement === "W" ||
s.attributes.unit_of_measurement === "kWh" ||
s.attributes.device_class === "energy" ||
s.attributes.device_class === "power",
);
const currentConsumption: EnergyItem[] = [];
// Analyze current consumption
for (const sensor of energySensors) {
const value = parseFloat(sensor.state);
if (!isNaN(value) && value > 0) {
currentConsumption.push({
entity_id: sensor.entity_id,
friendly_name:
(sensor.attributes.friendly_name as string | undefined) ?? sensor.entity_id,
value: value,
unit: (sensor.attributes.unit_of_measurement as string | undefined) ?? "",
device_class: (sensor.attributes.device_class as string | undefined) ?? "",
});
}
}
// Find high consumers (over 100W for power, over 1kWh for energy)
const highConsumers = currentConsumption
.filter(
(item) =>
(item.unit === "W" && item.value > 100) || (item.unit === "kWh" && item.value > 1),
)
.sort((a, b) => b.value - a.value)
.slice(0, 10);
const analysis = {
total_sensors: energySensors.length,
power_sensors: energySensors.filter((s) => s.attributes.unit_of_measurement === "W").length,
energy_sensors: energySensors.filter((s) => s.attributes.unit_of_measurement === "kWh")
.length,
current_consumption: currentConsumption,
high_consumers: highConsumers,
recommendations: [] as string[],
};
// Generate recommendations
if (analysis.high_consumers.length > 0) {
analysis.recommendations.push(
`Found ${analysis.high_consumers.length} high energy consumers. Consider creating automations to manage them.`,
);
}
if (analysis.power_sensors === 0) {
analysis.recommendations.push(
"No power sensors found. Consider adding energy monitoring devices to track consumption.",
);
}
return analysis;
} catch (error) {
logger.error("Failed to analyze energy consumption:", error);
throw error;
}
}
/**
* Find unavailable entities
*/
async findUnavailableEntities(entityFilter?: string): Promise<
Array<{
entity_id: string;
state: string;
friendly_name: string;
domain: string;
last_updated?: string;
}>
> {
try {
const hass = await get_hass();
const states = await hass.getStates();
let unavailable = states.filter((s) => s.state === "unavailable" || s.state === "unknown");
if (entityFilter !== undefined && entityFilter.length > 0) {
unavailable = unavailable.filter((s) => s.entity_id.startsWith(entityFilter + "."));
}
return unavailable.map((entity) => ({
entity_id: entity.entity_id,
state: entity.state,
friendly_name: (entity.attributes.friendly_name as string | undefined) ?? entity.entity_id,
domain: entity.entity_id.split(".")[0],
last_updated: entity.last_updated,
}));
} catch (error) {
logger.error("Failed to find unavailable entities:", error);
throw error;
}
}
/**
* Device health check
*/
async deviceHealthCheck(): Promise<{
total_entities: number;
healthy: number;
unavailable: number;
unknown: number;
battery_low: DeviceHealthInfo[];
offline_devices: Array<{ entity_id: string; friendly_name: string; domain: string }>;
by_domain: Record<string, { total: number; healthy: number; issues: number }>;
issues: string[];
}> {
try {
const hass = await get_hass();
const states = await hass.getStates();
const health = {
total_entities: states.length,
healthy: 0,
unavailable: 0,
unknown: 0,
battery_low: [] as DeviceHealthInfo[],
offline_devices: [] as Array<{ entity_id: string; friendly_name: string; domain: string }>,
by_domain: {} as Record<string, { total: number; healthy: number; issues: number }>,
issues: [] as string[],
};
for (const state of states) {
const domain = state.entity_id.split(".")[0];
// Count by domain
if (!health.by_domain[domain]) {
health.by_domain[domain] = { total: 0, healthy: 0, issues: 0 };
}
health.by_domain[domain].total++;
// Check state
if (state.state === "unavailable") {
health.unavailable++;
health.by_domain[domain].issues++;
health.offline_devices.push({
entity_id: state.entity_id,
friendly_name:
(state.attributes.friendly_name as string | undefined) ?? state.entity_id,
domain: domain,
});
} else if (state.state === "unknown") {
health.unknown++;
health.by_domain[domain].issues++;
} else {
health.healthy++;
health.by_domain[domain].healthy++;
}
// Check battery level
if (state.attributes.battery_level !== undefined) {
const batteryLevel = parseFloat(state.attributes.battery_level as string);
if (!isNaN(batteryLevel) && batteryLevel < 20) {
health.battery_low.push({
entity_id: state.entity_id,
friendly_name:
(state.attributes.friendly_name as string | undefined) ?? state.entity_id,
battery_level: batteryLevel,
});
}
}
}
// Generate issues
if (health.unavailable > 0) {
health.issues.push(
`${health.unavailable} entities are unavailable (${Math.round((health.unavailable / health.total_entities) * 100)}%)`,
);
}
if (health.unknown > 0) {
health.issues.push(`${health.unknown} entities have unknown state`);
}
if (health.battery_low.length > 0) {
health.issues.push(`${health.battery_low.length} devices have low battery (<20%)`);
}
return health;
} catch (error) {
logger.error("Failed to perform device health check:", error);
throw error;
}
}
}
// Singleton instance
const maintenanceService = new HomeAssistantMaintenanceService();
// Execute maintenance logic
async function executeMaintenanceLogic(params: MaintenanceParams): Promise<string> {
logger.debug(`Executing maintenance action: ${params.action}`);
switch (params.action) {
case "find_orphaned_devices": {
const orphaned = await maintenanceService.findOrphanedDevices();
return JSON.stringify(
{
action: params.action,
total_found: orphaned.length,
devices: orphaned,
recommendation:
orphaned.length > 0
? `Found ${orphaned.length} orphaned devices. Review and consider removing them from your configuration.`
: "No orphaned devices found. Your system is clean!",
},
null,
2,
);
}
case "analyze_light_usage": {
const analysis = await maintenanceService.analyzeLightUsage(params.days);
return JSON.stringify(
{
action: params.action,
analysis_period_days: params.days,
...analysis,
},
null,
2,
);
}
case "analyze_energy_consumption": {
const analysis = await maintenanceService.analyzeEnergyConsumption(params.days);
return JSON.stringify(
{
action: params.action,
analysis_period_days: params.days,
...analysis,
},
null,
2,
);
}
case "find_unavailable_entities": {
const unavailable = await maintenanceService.findUnavailableEntities(params.entity_filter);
return JSON.stringify(
{
action: params.action,
filter: params.entity_filter || "all",
total_found: unavailable.length,
entities: unavailable,
recommendation:
unavailable.length > 0
? `Found ${unavailable.length} unavailable entities. Check their connections and configuration.`
: "All entities are available!",
},
null,
2,
);
}
case "device_health_check": {
const health = await maintenanceService.deviceHealthCheck();
return JSON.stringify(
{
action: params.action,
timestamp: new Date().toISOString(),
...health,
},
null,
2,
);
}
case "cleanup_orphaned_entities": {
if (!params.cleanup) {
throw new UserError(
"Cleanup not enabled. Set 'cleanup: true' to actually remove entities. " +
"Run 'find_orphaned_devices' first to see what would be removed.",
);
}
// For now, just return what would be cleaned up
const orphaned = await maintenanceService.findOrphanedDevices();
return JSON.stringify(
{
action: params.action,
warning:
"Automatic cleanup not yet implemented. Please remove entities manually through Home Assistant UI.",
entities_to_remove: orphaned,
},
null,
2,
);
}
case "find_unused_automations": {
throw new UserError(
"Finding unused automations requires automation history analysis. This feature is planned for a future update.",
);
}
default:
throw new UserError(`Unknown action: ${params.action}`);
}
}
// Export the tool
export const maintenanceTool: Tool = {
name: "maintenance",
description:
"Perform maintenance tasks: find orphaned devices, analyze light usage and energy consumption, device health checks",
parameters: maintenanceSchema,
execute: executeMaintenanceLogic,
};
// Export class for compatibility
export class MaintenanceTool extends BaseTool {
constructor() {
super({
name: maintenanceTool.name,
description: maintenanceTool.description,
parameters: maintenanceSchema,
metadata: {
category: "maintenance",
version: "1.0.0",
tags: ["maintenance", "cleanup", "analysis", "health"],
},
});
}
public async execute(params: MaintenanceParams, context: MCPContext): Promise<string> {
logger.debug(`Executing MaintenanceTool with params: ${JSON.stringify(params)}`);
try {
const validatedParams = this.validateParams(params);
return await executeMaintenanceLogic(validatedParams);
} catch (error) {
logger.error(`Error in MaintenanceTool: ${String(error)}`);
throw error;
}
}
}