ha-mcp-dev 6.5.0.dev182__tar.gz → 6.5.0.dev184__tar.gz

{ha_mcp_dev-6.5.0.dev182/src/ha_mcp_dev.egg-info → ha_mcp_dev-6.5.0.dev184}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 6.5.0.dev182
+Version: 6.5.0.dev184
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-6.5.0.dev182 → ha_mcp_dev-6.5.0.dev184}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "6.5.0.dev182"
+version = "6.5.0.dev184"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

ha_mcp_dev-6.5.0.dev184/src/ha_mcp/tools/helpers.py

@@ -0,0 +1,257 @@
+"""
+Reusable helper functions for MCP tools.
+
+Centralized utilities that can be shared across multiple tool implementations.
+"""
+
+import functools
+import json
+import logging
+import time
+from typing import Any, Literal, NoReturn, overload
+
+from fastmcp.exceptions import ToolError
+
+from ..client.rest_client import (
+    HomeAssistantAPIError,
+    HomeAssistantAuthError,
+    HomeAssistantConnectionError,
+)
+from ..client.websocket_client import HomeAssistantWebSocketClient
+from ..errors import (
+    ErrorCode,
+    create_auth_error,
+    create_connection_error,
+    create_entity_not_found_error,
+    create_error_response,
+    create_timeout_error,
+    create_validation_error,
+)
+from ..utils.usage_logger import log_tool_call
+
+logger = logging.getLogger(__name__)
+
+
+def raise_tool_error(error_response: dict[str, Any]) -> NoReturn:
+    """
+    Raise a ToolError with structured error information.
+
+    This function converts a structured error response dictionary into a ToolError
+    exception, which signals to MCP clients that the tool execution failed via
+    the isError flag in the protocol response.
+
+    The structured error information is preserved as JSON in the error message,
+    allowing AI agents to parse and act on the detailed error information.
+
+    Args:
+        error_response: Structured error response dictionary with 'success': False
+                       and 'error' containing code, message, suggestions, etc.
+
+    Raises:
+        ToolError: Always raises with the JSON-serialized error response
+
+    Example:
+        >>> error = create_error_response(
+        ...     ErrorCode.ENTITY_NOT_FOUND,
+        ...     "Entity light.nonexistent not found"
+        ... )
+        >>> raise_tool_error(error)  # Raises ToolError with isError=true
+    """
+    raise ToolError(json.dumps(error_response, indent=2, default=str))
+
+
+async def get_connected_ws_client(
+    base_url: str, token: str
+) -> tuple[HomeAssistantWebSocketClient | None, dict[str, Any] | None]:
+    """
+    Create and connect a WebSocket client.
+
+    Args:
+        base_url: Home Assistant base URL
+        token: Authentication token
+
+    Returns:
+        Tuple of (ws_client, error_dict). If connection fails, ws_client is None.
+    """
+    ws_client = HomeAssistantWebSocketClient(base_url, token)
+    connected = await ws_client.connect()
+    if not connected:
+        return None, create_connection_error(
+            "Failed to connect to Home Assistant WebSocket",
+            details="WebSocket connection could not be established",
+        )
+    return ws_client, None
+
+
+@overload
+def exception_to_structured_error(
+    error: Exception,
+    context: dict[str, Any] | None = None,
+    *,
+    raise_error: Literal[False] = False,
+) -> dict[str, Any]: ...
+
+
+@overload
+def exception_to_structured_error(
+    error: Exception,
+    context: dict[str, Any] | None = None,
+    *,
+    raise_error: Literal[True],
+) -> NoReturn: ...
+
+
+def exception_to_structured_error(
+    error: Exception,
+    context: dict[str, Any] | None = None,
+    *,
+    raise_error: bool = False,
+) -> dict[str, Any]:
+    """
+    Convert an exception to a structured error response.
+
+    This function maps common exception types to appropriate error codes
+    and creates informative error responses.
+
+    Args:
+        error: The exception to convert
+        context: Additional context to include in the response
+        raise_error: If True, raises ToolError with the structured error.
+                    If False (default), returns the error dict.
+
+                    NOTE: The default will change to True in a future PR once
+                    all tools are updated to use ToolError. New code should
+                    explicitly pass raise_error=True for forward compatibility.
+
+    Returns:
+        Structured error response dictionary (only if raise_error=False)
+
+    Raises:
+        ToolError: If raise_error=True, raises with JSON-serialized error
+    """
+    error_str = str(error).lower()
+    error_msg = str(error)
+
+    error_response: dict[str, Any]
+
+    # Handle specific exception types
+    if isinstance(error, HomeAssistantConnectionError):
+        if "timeout" in error_str:
+            error_response = create_connection_error(error_msg, timeout=True)
+        else:
+            error_response = create_connection_error(error_msg)
+
+    elif isinstance(error, HomeAssistantAuthError):
+        if "expired" in error_str:
+            error_response = create_auth_error(error_msg, expired=True)
+        else:
+            error_response = create_auth_error(error_msg)
+
+    elif isinstance(error, HomeAssistantAPIError):
+        # Check for specific error patterns
+        match error.status_code:
+            case 404:
+                # Entity or resource not found
+                entity_id = context.get("entity_id") if context else None
+                if entity_id:
+                    error_response = create_entity_not_found_error(entity_id, details=error_msg)
+                else:
+                    error_response = create_error_response(
+                        ErrorCode.RESOURCE_NOT_FOUND,
+                        error_msg,
+                        context=context,
+                    )
+            case 401 | 403:
+                error_response = create_auth_error(error_msg)
+            case 400:
+                error_response = create_validation_error(error_msg, context=context)
+            case _:
+                # Generic API error
+                error_response = create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    error_msg,
+                    context=context,
+                )
+
+    elif isinstance(error, TimeoutError):
+        operation = context.get("operation", "request") if context else "request"
+        timeout_seconds = context.get("timeout_seconds", 30) if context else 30
+        error_response = create_timeout_error(operation, timeout_seconds, details=error_msg)
+
+    elif isinstance(error, ValueError):
+        error_response = create_validation_error(error_msg)
+
+    # Check for common error patterns in error message
+    elif "not found" in error_str or "404" in error_str:
+        entity_id = context.get("entity_id") if context else None
+        if entity_id:
+            error_response = create_entity_not_found_error(entity_id, details=error_msg)
+        else:
+            error_response = create_error_response(
+                ErrorCode.RESOURCE_NOT_FOUND,
+                error_msg,
+                context=context,
+            )
+
+    elif "timeout" in error_str:
+        error_response = create_timeout_error("operation", 30, details=error_msg)
+
+    elif "connection" in error_str or "connect" in error_str:
+        error_response = create_connection_error(error_msg)
+
+    elif "auth" in error_str or "token" in error_str or "401" in error_str:
+        error_response = create_auth_error(error_msg)
+
+    else:
+        # Default to internal error
+        error_response = create_error_response(
+            ErrorCode.INTERNAL_ERROR,
+            error_msg,
+            details="An unexpected error occurred",
+            context=context,
+        )
+
+    if raise_error:
+        raise_tool_error(error_response)
+
+    return error_response
+
+
+def log_tool_usage(func: Any) -> Any:
+    """
+    Decorator to automatically log MCP tool usage.
+
+    Tracks execution time, success/failure, and response size for all tool calls.
+    """
+
+    @functools.wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        start_time = time.time()
+        tool_name = func.__name__
+        success = True
+        error_message = None
+        response_size = None
+
+        try:
+            result = await func(*args, **kwargs)
+            if isinstance(result, str):
+                response_size = len(result.encode("utf-8"))
+            elif hasattr(result, "__len__"):
+                response_size = len(str(result).encode("utf-8"))
+            return result
+        except Exception as e:
+            success = False
+            error_message = str(e)
+            raise
+        finally:
+            execution_time_ms = (time.time() - start_time) * 1000
+            log_tool_call(
+                tool_name=tool_name,
+                parameters=kwargs,
+                execution_time_ms=execution_time_ms,
+                success=success,
+                error_message=error_message,
+                response_size_bytes=response_size,
+            )
+
+    return wrapper

{ha_mcp_dev-6.5.0.dev182 → ha_mcp_dev-6.5.0.dev184}/src/ha_mcp/tools/tools_config_automations.py

@@ -8,6 +8,7 @@ Home Assistant automation configurations.
 import logging
 from typing import Annotated, Any, cast
 
+from fastmcp.exceptions import ToolError
 from pydantic import Field
 
 from ..errors import (
@@ -15,7 +16,7 @@ from ..errors import (
     create_resource_not_found_error,
     create_validation_error,
 )
-from .helpers import exception_to_structured_error, log_tool_usage
+from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
 from .util_helpers import parse_json_param
 
 logger = logging.getLogger(__name__)
@@ -249,12 +250,13 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
                 )
                 error_response["action"] = "get"
                 error_response["reason"] = "not_found"
-                return error_response
+                raise_tool_error(error_response)
 
             logger.error(f"Error getting automation: {e}")
             error_response = exception_to_structured_error(
                 e,
                 context={"identifier": identifier, "action": "get"},
+                raise_error=False,
             )
             # Add automation-specific suggestions
             if "error" in error_response and isinstance(error_response["error"], dict):
@@ -263,7 +265,7 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
                     "Check Home Assistant connection",
                     "Use ha_get_domain_docs('automation') for configuration help",
                 ]
-            return error_response
+            raise_tool_error(error_response)
 
     @mcp.tool(
         annotations={
@@ -411,19 +413,19 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
             try:
                 parsed_config = parse_json_param(config, "config")
             except ValueError as e:
-                return create_validation_error(
+                raise_tool_error(create_validation_error(
                     f"Invalid config parameter: {e}",
                     parameter="config",
                     invalid_json=True,
-                )
+                ))
 
             # Ensure config is a dict
             if parsed_config is None or not isinstance(parsed_config, dict):
-                return create_validation_error(
+                raise_tool_error(create_validation_error(
                     "Config parameter must be a JSON object",
                     parameter="config",
                     details=f"Received type: {type(parsed_config).__name__}",
-                )
+                ))
 
             config_dict = cast(dict[str, Any], parsed_config)
 
@@ -441,11 +443,11 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
 
             missing_fields = [f for f in required_fields if f not in config_dict]
             if missing_fields:
-                return create_config_error(
+                raise_tool_error(create_config_error(
                     f"Missing required fields: {', '.join(missing_fields)}",
                     identifier=identifier,
                     missing_fields=missing_fields,
-                )
+                ))
 
             result = await client.upsert_automation_config(config_dict, identifier)
             return {
@@ -454,11 +456,14 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
                 "config_provided": config_dict,
             }
 
+        except ToolError:
+            raise
         except Exception as e:
             logger.error(f"Error upserting automation: {e}")
             error_response = exception_to_structured_error(
                 e,
                 context={"identifier": identifier},
+                raise_error=False,
             )
             # Add automation-specific suggestions
             if "error" in error_response and isinstance(error_response["error"], dict):
@@ -469,7 +474,7 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
                     "Use ha_search_entities(domain_filter='automation') to find automations",
                     "Use ha_get_domain_docs('automation') for comprehensive configuration help",
                 ]
-            return error_response
+            raise_tool_error(error_response)
 
     @mcp.tool(
         annotations={
@@ -513,6 +518,7 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
                 error_response = exception_to_structured_error(
                     e,
                     context={"identifier": identifier},
+                    raise_error=False,
                 )
             error_response["action"] = "delete"
             # Add automation-specific suggestions
@@ -522,4 +528,4 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
                     "Use entity_id format: automation.morning_routine or unique_id",
                     "Check Home Assistant connection",
                 ]
-            return error_response
+            raise_tool_error(error_response)

{ha_mcp_dev-6.5.0.dev182 → ha_mcp_dev-6.5.0.dev184}/src/ha_mcp/tools/tools_registry.py

@@ -16,7 +16,7 @@ from typing import Annotated, Any
 from pydantic import Field
 
 from ..errors import ErrorCode, create_error_response
-from .helpers import log_tool_usage
+from .helpers import log_tool_usage, raise_tool_error
 from .util_helpers import coerce_bool_param, parse_string_list_param
 
 # Known voice assistant identifiers
@@ -785,10 +785,10 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             try:
                 parsed_labels = parse_string_list_param(labels, "labels")
             except ValueError as e:
-                return create_error_response(
+                raise_tool_error(create_error_response(
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
                     f"Invalid labels parameter: {e}",
-                )
+                ))
 
         # Delegate to internal implementation
         return await _update_device_internal(

{ha_mcp_dev-6.5.0.dev182 → ha_mcp_dev-6.5.0.dev184}/src/ha_mcp/tools/tools_service.py

@@ -7,12 +7,13 @@ This module provides service execution and WebSocket-enabled operation monitorin
 from typing import Any, cast
 
 import httpx
+from fastmcp.exceptions import ToolError
 
 from ..errors import (
     create_validation_error,
 )
 from ..client.rest_client import HomeAssistantConnectionError
-from .helpers import exception_to_structured_error, log_tool_usage
+from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
 from .util_helpers import coerce_bool_param, parse_json_param
 
 
@@ -79,11 +80,11 @@ def register_service_tools(mcp, client, **kwargs):
             try:
                 parsed_data = parse_json_param(data, "data")
             except ValueError as e:
-                return create_validation_error(
+                raise_tool_error(create_validation_error(
                     f"Invalid data parameter: {e}",
                     parameter="data",
                     invalid_json=True,
-                )
+                ))
 
             # Ensure service_data is a dict
             service_data: dict[str, Any] = {}
@@ -91,11 +92,11 @@ def register_service_tools(mcp, client, **kwargs):
                 if isinstance(parsed_data, dict):
                     service_data = parsed_data
                 else:
-                    return create_validation_error(
+                    raise_tool_error(create_validation_error(
                         "Data parameter must be a JSON object",
                         parameter="data",
                         details=f"Received type: {type(parsed_data).__name__}",
-                    )
+                    ))
 
             if entity_id:
                 service_data["entity_id"] = entity_id
@@ -154,10 +155,13 @@ def register_service_tools(mcp, client, **kwargs):
                     "service": service,
                     "entity_id": entity_id,
                 },
+                raise_error=False,
             )
             if "error" in error_response and isinstance(error_response["error"], dict):
                 error_response["error"]["suggestions"] = _build_service_suggestions(domain, service, entity_id)
-            return error_response
+            raise_tool_error(error_response)
+        except ToolError:
+            raise
         except Exception as error:
             # Use structured error response
             error_response = exception_to_structured_error(
@@ -167,6 +171,7 @@ def register_service_tools(mcp, client, **kwargs):
                     "service": service,
                     "entity_id": entity_id,
                 },
+                raise_error=False,
             )
             suggestions = _build_service_suggestions(domain, service, entity_id)
             if entity_id:
@@ -177,7 +182,7 @@ def register_service_tools(mcp, client, **kwargs):
             # Merge suggestions into error response
             if "error" in error_response and isinstance(error_response["error"], dict):
                 error_response["error"]["suggestions"] = suggestions
-            return error_response
+            raise_tool_error(error_response)
 
     @mcp.tool(annotations={"readOnlyHint": True, "title": "Get Operation Status"})
     @log_tool_usage
@@ -204,19 +209,19 @@ def register_service_tools(mcp, client, **kwargs):
         try:
             parsed_operations = parse_json_param(operations, "operations")
         except ValueError as e:
-            return create_validation_error(
+            raise_tool_error(create_validation_error(
                 f"Invalid operations parameter: {e}",
                 parameter="operations",
                 invalid_json=True,
-            )
+            ))
 
         # Ensure operations is a list of dicts
         if parsed_operations is None or not isinstance(parsed_operations, list):
-            return create_validation_error(
+            raise_tool_error(create_validation_error(
                 "Operations parameter must be a list",
                 parameter="operations",
                 details=f"Received type: {type(parsed_operations).__name__}",
-            )
+            ))
 
         operations_list = cast(list[dict[str, Any]], parsed_operations)
         result = await device_tools.bulk_device_control(

{ha_mcp_dev-6.5.0.dev182 → ha_mcp_dev-6.5.0.dev184/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 6.5.0.dev182
+Version: 6.5.0.dev184
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

ha_mcp_dev-6.5.0.dev182/src/ha_mcp/tools/helpers.py

@@ -1,184 +0,0 @@
-"""
-Reusable helper functions for MCP tools.
-
-Centralized utilities that can be shared across multiple tool implementations.
-"""
-
-import functools
-import logging
-import time
-from typing import Any
-
-from ..client.rest_client import (
-    HomeAssistantAPIError,
-    HomeAssistantAuthError,
-    HomeAssistantConnectionError,
-)
-from ..client.websocket_client import HomeAssistantWebSocketClient
-from ..errors import (
-    ErrorCode,
-    create_auth_error,
-    create_connection_error,
-    create_entity_not_found_error,
-    create_error_response,
-    create_timeout_error,
-    create_validation_error,
-)
-from ..utils.usage_logger import log_tool_call
-
-logger = logging.getLogger(__name__)
-
-
-async def get_connected_ws_client(
-    base_url: str, token: str
-) -> tuple[HomeAssistantWebSocketClient | None, dict[str, Any] | None]:
-    """
-    Create and connect a WebSocket client.
-
-    Args:
-        base_url: Home Assistant base URL
-        token: Authentication token
-
-    Returns:
-        Tuple of (ws_client, error_dict). If connection fails, ws_client is None.
-    """
-    ws_client = HomeAssistantWebSocketClient(base_url, token)
-    connected = await ws_client.connect()
-    if not connected:
-        return None, create_connection_error(
-            "Failed to connect to Home Assistant WebSocket",
-            details="WebSocket connection could not be established",
-        )
-    return ws_client, None
-
-
-def exception_to_structured_error(
-    error: Exception,
-    context: dict[str, Any] | None = None,
-) -> dict[str, Any]:
-    """
-    Convert an exception to a structured error response.
-
-    This function maps common exception types to appropriate error codes
-    and creates informative error responses.
-
-    Args:
-        error: The exception to convert
-        context: Additional context to include in the response
-
-    Returns:
-        Structured error response dictionary
-    """
-    error_str = str(error).lower()
-    error_msg = str(error)
-
-    # Handle specific exception types
-    if isinstance(error, HomeAssistantConnectionError):
-        if "timeout" in error_str:
-            return create_connection_error(error_msg, timeout=True)
-        return create_connection_error(error_msg)
-
-    if isinstance(error, HomeAssistantAuthError):
-        if "expired" in error_str:
-            return create_auth_error(error_msg, expired=True)
-        return create_auth_error(error_msg)
-
-    if isinstance(error, HomeAssistantAPIError):
-        # Check for specific error patterns
-        if error.status_code == 404:
-            # Entity or resource not found
-            entity_id = context.get("entity_id") if context else None
-            if entity_id:
-                return create_entity_not_found_error(entity_id, details=error_msg)
-            return create_error_response(
-                ErrorCode.RESOURCE_NOT_FOUND,
-                error_msg,
-                context=context,
-            )
-        if error.status_code == 401:
-            return create_auth_error(error_msg)
-        if error.status_code == 400:
-            return create_validation_error(error_msg, context=context)
-
-        # Generic API error
-        return create_error_response(
-            ErrorCode.SERVICE_CALL_FAILED,
-            error_msg,
-            context=context,
-        )
-
-    if isinstance(error, TimeoutError):
-        operation = context.get("operation", "request") if context else "request"
-        timeout_seconds = context.get("timeout_seconds", 30) if context else 30
-        return create_timeout_error(operation, timeout_seconds, details=error_msg)
-
-    if isinstance(error, ValueError):
-        return create_validation_error(error_msg)
-
-    # Check for common error patterns in error message
-    if "not found" in error_str or "404" in error_str:
-        entity_id = context.get("entity_id") if context else None
-        if entity_id:
-            return create_entity_not_found_error(entity_id, details=error_msg)
-        return create_error_response(
-            ErrorCode.RESOURCE_NOT_FOUND,
-            error_msg,
-            context=context,
-        )
-
-    if "timeout" in error_str:
-        return create_timeout_error("operation", 30, details=error_msg)
-
-    if "connection" in error_str or "connect" in error_str:
-        return create_connection_error(error_msg)
-
-    if "auth" in error_str or "token" in error_str or "401" in error_str:
-        return create_auth_error(error_msg)
-
-    # Default to internal error
-    return create_error_response(
-        ErrorCode.INTERNAL_ERROR,
-        error_msg,
-        details="An unexpected error occurred",
-        context=context,
-    )
-
-
-def log_tool_usage(func: Any) -> Any:
-    """
-    Decorator to automatically log MCP tool usage.
-
-    Tracks execution time, success/failure, and response size for all tool calls.
-    """
-
-    @functools.wraps(func)
-    async def wrapper(*args: Any, **kwargs: Any) -> Any:
-        start_time = time.time()
-        tool_name = func.__name__
-        success = True
-        error_message = None
-        response_size = None
-
-        try:
-            result = await func(*args, **kwargs)
-            if isinstance(result, str):
-                response_size = len(result.encode("utf-8"))
-            elif hasattr(result, "__len__"):
-                response_size = len(str(result).encode("utf-8"))
-            return result
-        except Exception as e:
-            success = False
-            error_message = str(e)
-            raise
-        finally:
-            execution_time_ms = (time.time() - start_time) * 1000
-            log_tool_call(
-                tool_name=tool_name,
-                parameters=kwargs,
-                execution_time_ms=execution_time_ms,
-                success=success,
-                error_message=error_message,
-                response_size_bytes=response_size,
-            )
-
-    return wrapper