An MCP (Model Context Protocol) server for HomeAssistant integration that provides SSE-based communication with Claude Desktop, enabling tools to interact with HomeAssistant entities, services, and automations
This MCP server exposes 20 HomeAssistant integration tools with significant quality gaps. While tool names follow verb_noun convention (get_, set_, call_, etc.), critical deficiencies exist: (1) Descriptions are present but generic and brief (average ~40 chars), lacking context about when to use each tool or what dependencies exist. (2) Input schemas are incomplete, most tools lack proper parameter descriptions. For example, 'get_config' and 'get_states' accept empty input schemas but provide no guidance on what they return or their prerequisites. (3) Output schemas are entirely undocumented, the source shows tool registration but no response structure documentation, forcing LLMs to guess what fields are returned. (4) Error handling is absent, no recovery guidance, no categorization of retryable vs fatal errors, no actionable error messages. (5) Security considerations are not visible, no documentation of what permissions each tool requires, no indication of secret injection patterns, no audit trail guidance. (6) The parameter descriptions that do exist are minimal (e.g., 'entity_id' for get_state is described as 'The entity ID to get state for', tautological and unhelpful). The server implements core MCP protocol mechanics but the tools themselves lack the polish required for reliable agent use. Code review perspective: this is a 'working but not production-ready' implementation that would need extensive documentation and schema refinement before deployment.
Output schemas entirely undocumented. Source code shows tool registration but no response structure, field names, types, or examples. LLMs cannot plan tool chains without knowing what fields are returned.
Descriptions are generic and tautological. Examples: 'Get all entity states' (9 chars), 'Get registered panels' (21 chars), 'Check configuration' (18 chars). Below the 10 - 1024 char baseline and lack context about when to use each tool, prerequisites, or dependencies.
Add output schema documentation for all 20 tools. Define response structure: field names, types, examples. E.g., for get_state: {entity_id: string, state: string, last_changed: ISO8601, attributes: object}.
Expand tool descriptions to 50 - 200 characters with context. Example for get_states: 'Retrieve all entity state snapshots from HomeAssistant. Use this to discover available entities and their current values before calling set_state or call_service. Returns a list of {entity_id, state, attributes} objects.' Current: 'Get all entity states' (21 chars).
Document parameter descriptions and constraints for all 20 tools. For tools with empty input schemas (get_config, get_states, etc.), add descriptions explaining what they return and any pagination support. For tools with complex 'data' params (call_service, set_state, fire_event), provide schema examples or reference HomeAssistant API docs.
Implement error handling with actionable recovery guidance. Example: 'Entity not found: light.living_room. Call get_entities() first to see available entities, or check entity ID spelling.' For set_state failures: 'Invalid state for light.living_room: "maybe_on". Valid states: on, off, unavailable, unknown.'
Add confirmation/dry-run pattern for destructive tools. For delete_config_entry and delete_area, add an optional 'confirm' boolean parameter. If false, return a preview of what would be deleted and require a follow-up call with confirm=true.
Document scope requirements for each tool in its description. Example: 'set_state [requires write:state scope]. Updates entity state directly; use call_service for controlled state changes via automations.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Parameter descriptions are minimal or missing. Tools with empty input schemas (get_config, get_states, get_services, get_events, get_panels, get_error_log, check_config, get_config_entries, get_devices, get_entities, get_areas) provide zero guidance on what they retrieve or their prerequisites.
No error handling guidance. Source code provides no evidence of error categorization (retryable vs fatal), recovery steps, actionable error messages, or invalid input examples. An LLM receiving a 404 or validation error has no guidance on what to do next.
Destructive tools (delete_config_entry, delete_area) lack confirmation/dry-run mechanisms. No evidence of a confirmation request pattern or pre-execution verification. Agents can trigger permanent deletions without opportunity to verify intent.
No permission or scope documentation. Tools accept arbitrary service calls and state modifications but lack documentation of what permissions they require (read:config, write:state, admin:devices, etc.), enabling improper agent configurations.
Result pagination not visible for list/get tools. Tools like get_states, get_services, get_events, get_devices, get_entities return unknown cardinality, no evidence of limit, offset, or pagination support to protect against context window exhaustion.
Parameter names lack type suffixes for ambiguous identifiers. 'entity_id' and 'area_id' are clear, but tools accept generic 'update_data' and 'service_data' objects without schema defining expected fields, forcing LLMs to guess the structure.
Add pagination support (limit, offset, next_cursor) to list tools (get_states, get_services, get_events, get_devices, get_entities, get_areas). Document default limit and maximum, and return a total count or next_cursor in responses.
Provide schema constraints for 'service_data', 'event_data', and 'update_data' parameters. Link to HomeAssistant service documentation or define common fields inline. Example: 'service_data: object with service-specific fields (e.g., light.turn_on accepts {brightness: 0 - 255, color_temp: 2000 - 6500})'.
Split overly general tools. 'call_service' accepts any domain/service, consider creating domain-specific aliases (call_light_service, call_switch_service) for discovery and to constrain LLM reasoning.
Add audit trail and logging context. Ensure all state mutations (set_state, call_service, fire_event, delete_*, create_*, update_*) log caller, timestamp, parameters, and result for compliance and debugging.