ha-mcp-dev 6.3.1.dev137__py3-none-any.whl

ha_mcp/errors.py

@@ -0,0 +1,399 @@
+"""
+Structured error handling for Home Assistant MCP Server.
+
+This module provides standardized error codes, error response models, and helper
+functions for creating consistent, informative error responses across all MCP tools.
+
+The structured error format enables AI agents to:
+- Diagnose issues programmatically using error codes
+- Provide helpful suggestions to users
+- Understand the context and details of failures
+"""
+
+from enum import Enum
+from typing import Any
+
+
+class ErrorCode(str, Enum):
+    """
+    Standard error codes for Home Assistant MCP operations.
+
+    Error codes are grouped by category:
+    - CONNECTION_*: Network and connectivity issues
+    - AUTH_*: Authentication and authorization issues
+    - ENTITY_*: Entity-related issues
+    - SERVICE_*: Service call issues
+    - CONFIG_*: Configuration issues
+    - VALIDATION_*: Input validation issues
+    - TIMEOUT_*: Timeout issues
+    - INTERNAL_*: Internal server errors
+    """
+
+    # Connection errors
+    CONNECTION_FAILED = "CONNECTION_FAILED"
+    CONNECTION_TIMEOUT = "CONNECTION_TIMEOUT"
+    WEBSOCKET_DISCONNECTED = "WEBSOCKET_DISCONNECTED"
+    WEBSOCKET_NOT_AUTHENTICATED = "WEBSOCKET_NOT_AUTHENTICATED"
+
+    # Authentication errors
+    AUTH_INVALID_TOKEN = "AUTH_INVALID_TOKEN"
+    AUTH_EXPIRED = "AUTH_EXPIRED"
+    AUTH_INSUFFICIENT_PERMISSIONS = "AUTH_INSUFFICIENT_PERMISSIONS"
+
+    # Entity errors
+    ENTITY_NOT_FOUND = "ENTITY_NOT_FOUND"
+    ENTITY_UNAVAILABLE = "ENTITY_UNAVAILABLE"
+    ENTITY_INVALID_ID = "ENTITY_INVALID_ID"
+    ENTITY_DOMAIN_MISMATCH = "ENTITY_DOMAIN_MISMATCH"
+
+    # Service errors
+    SERVICE_NOT_FOUND = "SERVICE_NOT_FOUND"
+    SERVICE_INVALID_DOMAIN = "SERVICE_INVALID_DOMAIN"
+    SERVICE_INVALID_ACTION = "SERVICE_INVALID_ACTION"
+    SERVICE_CALL_FAILED = "SERVICE_CALL_FAILED"
+
+    # Configuration errors
+    CONFIG_NOT_FOUND = "CONFIG_NOT_FOUND"
+    CONFIG_INVALID = "CONFIG_INVALID"
+    CONFIG_MISSING_REQUIRED_FIELDS = "CONFIG_MISSING_REQUIRED_FIELDS"
+    CONFIG_VALIDATION_FAILED = "CONFIG_VALIDATION_FAILED"
+
+    # Validation errors
+    VALIDATION_FAILED = "VALIDATION_FAILED"
+    VALIDATION_INVALID_JSON = "VALIDATION_INVALID_JSON"
+    VALIDATION_INVALID_PARAMETER = "VALIDATION_INVALID_PARAMETER"
+    VALIDATION_MISSING_PARAMETER = "VALIDATION_MISSING_PARAMETER"
+
+    # Timeout errors
+    TIMEOUT_OPERATION = "TIMEOUT_OPERATION"
+    TIMEOUT_WEBSOCKET = "TIMEOUT_WEBSOCKET"
+    TIMEOUT_API_REQUEST = "TIMEOUT_API_REQUEST"
+
+    # Internal errors
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    INTERNAL_UNEXPECTED = "INTERNAL_UNEXPECTED"
+
+    # Resource errors
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND"
+    RESOURCE_ALREADY_EXISTS = "RESOURCE_ALREADY_EXISTS"
+    RESOURCE_LOCKED = "RESOURCE_LOCKED"
+
+
+# Default suggestions for common error codes
+DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
+    ErrorCode.CONNECTION_FAILED: [
+        "Check if Home Assistant is running and accessible",
+        "Verify the HOMEASSISTANT_URL environment variable is correct",
+        "Check network connectivity to Home Assistant",
+    ],
+    ErrorCode.CONNECTION_TIMEOUT: [
+        "Home Assistant may be overloaded or slow to respond",
+        "Check network latency to Home Assistant",
+        "Try increasing the timeout value if available",
+    ],
+    ErrorCode.WEBSOCKET_DISCONNECTED: [
+        "WebSocket connection was lost",
+        "Check Home Assistant logs for errors",
+        "The operation may need to be retried",
+    ],
+    ErrorCode.WEBSOCKET_NOT_AUTHENTICATED: [
+        "WebSocket connection is not authenticated",
+        "Verify the access token is valid",
+        "Try reconnecting to Home Assistant",
+    ],
+    ErrorCode.AUTH_INVALID_TOKEN: [
+        "Verify the HOMEASSISTANT_TOKEN is correct",
+        "Generate a new long-lived access token in Home Assistant",
+        "Check token has not been revoked",
+    ],
+    ErrorCode.AUTH_EXPIRED: [
+        "The access token has expired",
+        "Generate a new long-lived access token in Home Assistant",
+    ],
+    ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS: [
+        "The access token does not have sufficient permissions",
+        "Check token permissions in Home Assistant",
+        "Create a new token with required permissions",
+    ],
+    ErrorCode.ENTITY_NOT_FOUND: [
+        "Use ha_search_entities() to find correct entity ID",
+        "Verify the entity exists in Home Assistant",
+        "Check for typos in the entity ID",
+    ],
+    ErrorCode.ENTITY_UNAVAILABLE: [
+        "The entity exists but is currently unavailable",
+        "Check if the device is powered on and connected",
+        "Check Home Assistant integration status",
+    ],
+    ErrorCode.ENTITY_INVALID_ID: [
+        "Entity ID must be in format: domain.name",
+        "Use ha_search_entities() to find valid entity IDs",
+    ],
+    ErrorCode.ENTITY_DOMAIN_MISMATCH: [
+        "Cannot change entity to a different domain",
+        "Entity domain must match the original domain",
+    ],
+    ErrorCode.SERVICE_NOT_FOUND: [
+        "Use ha_get_domain_docs() to see available services",
+        "Check the service name spelling",
+        "Verify the domain supports this service",
+    ],
+    ErrorCode.SERVICE_INVALID_DOMAIN: [
+        "Use ha_get_overview() to see available domains",
+        "Check the domain name spelling",
+    ],
+    ErrorCode.SERVICE_INVALID_ACTION: [
+        "Check available actions for this domain",
+        "Common actions: turn_on, turn_off, toggle",
+        "Use ha_get_domain_docs() for service documentation",
+    ],
+    ErrorCode.SERVICE_CALL_FAILED: [
+        "Check the service parameters are correct",
+        "Verify the target entity supports this service",
+        "Check Home Assistant logs for detailed error",
+    ],
+    ErrorCode.CONFIG_NOT_FOUND: [
+        "Verify the resource exists",
+        "Use search tools to find the correct identifier",
+    ],
+    ErrorCode.CONFIG_INVALID: [
+        "Review the configuration format",
+        "Use ha_get_domain_docs() for configuration help",
+    ],
+    ErrorCode.CONFIG_MISSING_REQUIRED_FIELDS: [
+        "Check documentation for required fields",
+        "Ensure all required parameters are provided",
+    ],
+    ErrorCode.VALIDATION_INVALID_JSON: [
+        "Ensure the parameter is valid JSON",
+        "Check for syntax errors in JSON",
+        "Use a JSON validator to verify the format",
+    ],
+    ErrorCode.VALIDATION_INVALID_PARAMETER: [
+        "Check the parameter type and format",
+        "Review the tool documentation for expected values",
+    ],
+    ErrorCode.TIMEOUT_OPERATION: [
+        "The operation took too long to complete",
+        "Home Assistant may be under heavy load",
+        "Try the operation again",
+    ],
+    ErrorCode.INTERNAL_ERROR: [
+        "An internal error occurred",
+        "Check Home Assistant MCP server logs",
+        "Report this issue if it persists",
+    ],
+}
+
+
+def create_error_response(
+    code: ErrorCode,
+    message: str,
+    details: str | None = None,
+    suggestions: list[str] | None = None,
+    context: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    Create a structured error response.
+
+    Args:
+        code: Error code from ErrorCode enum
+        message: Human-readable error message
+        details: Additional details about the error (optional)
+        suggestions: List of suggestions to resolve the error (optional)
+        context: Additional context data (e.g., entity_id, domain) (optional)
+
+    Returns:
+        Structured error response dictionary with success=False
+
+    Example:
+        >>> create_error_response(
+        ...     ErrorCode.ENTITY_NOT_FOUND,
+        ...     "Entity light.nonexistent not found",
+        ...     details="No entity with this ID exists in Home Assistant",
+        ...     context={"entity_id": "light.nonexistent"}
+        ... )
+        {
+            "success": False,
+            "error": {
+                "code": "ENTITY_NOT_FOUND",
+                "message": "Entity light.nonexistent not found",
+                "details": "No entity with this ID exists in Home Assistant",
+                "suggestion": "Use ha_search_entities() to find correct entity ID"
+            },
+            "entity_id": "light.nonexistent"
+        }
+    """
+    # Use provided suggestions or fall back to defaults
+    error_suggestions = suggestions if suggestions else DEFAULT_SUGGESTIONS.get(code, [])
+
+    error_dict: dict[str, Any] = {
+        "code": code.value,
+        "message": message,
+    }
+
+    if details:
+        error_dict["details"] = details
+
+    if error_suggestions:
+        # Include first suggestion as primary, all suggestions in list
+        error_dict["suggestion"] = error_suggestions[0]
+        if len(error_suggestions) > 1:
+            error_dict["suggestions"] = error_suggestions
+
+    response: dict[str, Any] = {
+        "success": False,
+        "error": error_dict,
+    }
+
+    # Add context fields at top level for easy access
+    if context:
+        response.update(context)
+
+    return response
+
+
+def create_connection_error(
+    message: str,
+    details: str | None = None,
+    timeout: bool = False,
+) -> dict[str, Any]:
+    """Create a connection error response."""
+    code = ErrorCode.CONNECTION_TIMEOUT if timeout else ErrorCode.CONNECTION_FAILED
+    return create_error_response(code, message, details)
+
+
+def create_auth_error(
+    message: str,
+    details: str | None = None,
+    expired: bool = False,
+) -> dict[str, Any]:
+    """Create an authentication error response."""
+    code = ErrorCode.AUTH_EXPIRED if expired else ErrorCode.AUTH_INVALID_TOKEN
+    return create_error_response(code, message, details)
+
+
+def create_entity_not_found_error(
+    entity_id: str,
+    details: str | None = None,
+) -> dict[str, Any]:
+    """Create an entity not found error response."""
+    return create_error_response(
+        ErrorCode.ENTITY_NOT_FOUND,
+        f"Entity '{entity_id}' not found",
+        details=details or f"No entity with ID '{entity_id}' exists in Home Assistant",
+        context={"entity_id": entity_id},
+    )
+
+
+def create_service_error(
+    domain: str,
+    service: str,
+    message: str,
+    details: str | None = None,
+    entity_id: str | None = None,
+) -> dict[str, Any]:
+    """Create a service call error response."""
+    context: dict[str, Any] = {"domain": domain, "service": service}
+    if entity_id:
+        context["entity_id"] = entity_id
+
+    return create_error_response(
+        ErrorCode.SERVICE_CALL_FAILED,
+        message,
+        details=details,
+        context=context,
+    )
+
+
+def create_validation_error(
+    message: str,
+    parameter: str | None = None,
+    details: str | None = None,
+    invalid_json: bool = False,
+    context: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Create a validation error response."""
+    code = ErrorCode.VALIDATION_INVALID_JSON if invalid_json else ErrorCode.VALIDATION_FAILED
+    # Build context, prioritizing explicit context but adding parameter if provided
+    final_context: dict[str, Any] = {}
+    if context:
+        final_context.update(context)
+    if parameter:
+        final_context["parameter"] = parameter
+    return create_error_response(code, message, details, context=final_context if final_context else None)
+
+
+def create_config_error(
+    message: str,
+    identifier: str | None = None,
+    missing_fields: list[str] | None = None,
+    details: str | None = None,
+) -> dict[str, Any]:
+    """Create a configuration error response."""
+    if missing_fields:
+        code = ErrorCode.CONFIG_MISSING_REQUIRED_FIELDS
+        details = details or f"Missing required fields: {', '.join(missing_fields)}"
+    else:
+        code = ErrorCode.CONFIG_INVALID
+
+    context: dict[str, Any] = {}
+    if identifier:
+        context["identifier"] = identifier
+    if missing_fields:
+        context["missing_fields"] = missing_fields
+
+    return create_error_response(code, message, details, context=context or None)
+
+
+def create_timeout_error(
+    operation: str,
+    timeout_seconds: float,
+    details: str | None = None,
+) -> dict[str, Any]:
+    """Create a timeout error response."""
+    return create_error_response(
+        ErrorCode.TIMEOUT_OPERATION,
+        f"Operation '{operation}' timed out after {timeout_seconds}s",
+        details=details,
+        context={"operation": operation, "timeout_seconds": timeout_seconds},
+    )
+
+
+def create_resource_not_found_error(
+    resource_type: str,
+    identifier: str,
+    details: str | None = None,
+) -> dict[str, Any]:
+    """Create a resource not found error response."""
+    return create_error_response(
+        ErrorCode.RESOURCE_NOT_FOUND,
+        f"{resource_type} '{identifier}' not found",
+        details=details,
+        context={"resource_type": resource_type, "identifier": identifier},
+    )
+
+
+def is_error_response(response: dict[str, Any]) -> bool:
+    """Check if a response is an error response."""
+    return response.get("success") is False and "error" in response
+
+
+def get_error_code(response: dict[str, Any]) -> str | None:
+    """Extract the error code from an error response."""
+    if is_error_response(response):
+        error = response.get("error", {})
+        if isinstance(error, dict):
+            return error.get("code")
+    return None
+
+
+def get_error_message(response: dict[str, Any]) -> str | None:
+    """Extract the error message from an error response."""
+    if is_error_response(response):
+        error = response.get("error", {})
+        if isinstance(error, dict):
+            return error.get("message")
+        if isinstance(error, str):
+            return error
+    return None

ha_mcp/resources/card_types.json

@@ -0,0 +1,48 @@
+{
+  "card_types": [
+    "alarm-panel",
+    "area",
+    "button",
+    "calendar",
+    "clock",
+    "conditional",
+    "energy",
+    "entities",
+    "entity-filter",
+    "entity",
+    "gauge",
+    "glance",
+    "grid",
+    "heading",
+    "history-graph",
+    "horizontal-stack",
+    "humidifier",
+    "iframe",
+    "light",
+    "logbook",
+    "map",
+    "markdown",
+    "masonry",
+    "media-control",
+    "panel",
+    "picture-elements",
+    "picture-entity",
+    "picture-glance",
+    "picture",
+    "plant-status",
+    "sections",
+    "sensor",
+    "shopping-list",
+    "sidebar",
+    "statistic",
+    "statistics-graph",
+    "thermostat",
+    "tile",
+    "todo-list",
+    "vertical-stack",
+    "weather-forecast"
+  ],
+  "total_count": 41,
+  "documentation_base_url": "https://raw.githubusercontent.com/home-assistant/home-assistant.io/refs/heads/current/source/_dashboards",
+  "usage": "Use ha-dashboard://card-docs/{card-type} to get documentation for specific card type"
+}