ha-mcp-dev 7.6.0.dev627__tar.gz → 7.6.0.dev629__tar.gz

{ha_mcp_dev-7.6.0.dev627/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.6.0.dev629}/PKG-INFO

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

{ha_mcp_dev-7.6.0.dev627 → ha_mcp_dev-7.6.0.dev629}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.6.0.dev627"
+version = "7.6.0.dev629"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -147,7 +147,6 @@ ignore = [
 # C901 ignores for tools files with complex methods (see #925).
 # Remove lines as individual methods are simplified below threshold.
 "src/ha_mcp/tools/tools_config_dashboards.py" = ["C901"]
-"src/ha_mcp/tools/tools_config_helpers.py" = ["C901"]
 "src/ha_mcp/tools/tools_entities.py" = ["C901"]
 "src/ha_mcp/tools/tools_registry.py" = ["C901"]
 "src/ha_mcp/tools/tools_search.py" = ["C901"]

{ha_mcp_dev-7.6.0.dev627 → ha_mcp_dev-7.6.0.dev629}/src/ha_mcp/client/websocket_client.py

@@ -235,6 +235,10 @@ class HomeAssistantWebSocketClient:
         self._send_lock: asyncio.Lock | None = None
         self._lock_loop: asyncio.AbstractEventLoop | None = None
         self._state = WebSocketConnectionState()
+        # Reason the most recent connect() attempt failed (exception text),
+        # or None. Surfaced by callers so the agent sees *why* a WebSocket
+        # connection failed instead of an opaque "Failed to connect" string.
+        self._last_connect_error: str | None = None
 
         # Parse URL to get WebSocket endpoint
         parsed = urlparse(self.base_url)
@@ -259,6 +263,7 @@ class HomeAssistantWebSocketClient:
         try:
             logger.info(f"Connecting to Home Assistant WebSocket: {self.ws_url}")
             self._state.reset_connection()
+            self._last_connect_error = None
 
             # Only configure an SSLContext for wss://; ws:// (Supervisor
             # proxy) doesn't use TLS and gets ssl=None.
@@ -326,6 +331,7 @@ class HomeAssistantWebSocketClient:
             return True
 
         except Exception as e:
+            self._last_connect_error = f"{type(e).__name__}: {e}"
             if _is_ssl_error(e) and self.verify_ssl:
                 logger.error(
                     "WebSocket TLS verification failed for %s: %s. "
@@ -925,6 +931,17 @@ class HomeAssistantWebSocketClient:
         """Check if WebSocket is connected and authenticated."""
         return self._state.is_ready
 
+    @property
+    def last_connect_error(self) -> str | None:
+        """Reason the most recent ``connect()`` attempt failed, or ``None``.
+
+        Captured from the underlying exception (e.g. an auth timeout, a
+        handshake HTTP/TLS error, or "Did not receive auth_required") so
+        callers can surface *why* the connection failed instead of an
+        opaque "Failed to connect to Home Assistant WebSocket".
+        """
+        return self._last_connect_error
+
 
 MAX_POOL_SIZE = 50
 
@@ -1059,7 +1076,14 @@ class WebSocketManager:
 
             connected = await client.connect()
             if not connected:
-                raise Exception("Failed to connect to Home Assistant WebSocket")
+                reason = client.last_connect_error
+                # Append only an actual string reason; the isinstance guard
+                # keeps a non-str (e.g. a MagicMock in tests) from polluting
+                # the message with a repr.
+                detail = f": {reason}" if isinstance(reason, str) else ""
+                raise Exception(
+                    "Failed to connect to Home Assistant WebSocket" + detail
+                )
 
             self._clients[key] = client
             self._last_used[key] = time.monotonic()

{ha_mcp_dev-7.6.0.dev627 → ha_mcp_dev-7.6.0.dev629}/src/ha_mcp/tools/helpers.py

@@ -182,14 +182,19 @@ async def get_connected_ws_client(
     ws_client = HomeAssistantWebSocketClient(base_url, token, verify_ssl=verify_ssl)
     connected = await ws_client.connect()
     if not connected:
+        reason = ws_client.last_connect_error
+        details = (
+            reason
+            if isinstance(reason, str)
+            else "WebSocket connection could not be established"
+        )
         return None, create_connection_error(
             "Failed to connect to Home Assistant WebSocket",
-            details="WebSocket connection could not be established",
+            details=details,
         )
     return ws_client, None
 
 
-
 def _classify_api_status(
     error: HomeAssistantAPIError,
     error_msg: str,
@@ -202,13 +207,17 @@ def _classify_api_status(
             if entity_id:
                 result = create_entity_not_found_error(entity_id, details=error_msg)
             else:
-                result = create_error_response(ErrorCode.RESOURCE_NOT_FOUND, error_msg, context=context)
+                result = create_error_response(
+                    ErrorCode.RESOURCE_NOT_FOUND, error_msg, context=context
+                )
         case 401 | 403:
             result = create_auth_error(error_msg, context=context)
         case 400:
             result = create_validation_error(error_msg, context=context)
         case _:
-            result = create_error_response(ErrorCode.SERVICE_CALL_FAILED, error_msg, context=context)
+            result = create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED, error_msg, context=context
+            )
     return result
 
 
@@ -244,7 +253,9 @@ def _classify_exception(
         case TimeoutError():
             operation = context.get("operation", "request") if context else "request"
             timeout_seconds = context.get("timeout_seconds", 30) if context else 30
-            result = create_timeout_error(operation, timeout_seconds, details=error_msg, context=context)
+            result = create_timeout_error(
+                operation, timeout_seconds, details=error_msg, context=context
+            )
         case ValueError():
             result = create_validation_error(error_msg, context=context)
 
@@ -276,7 +287,9 @@ def _classify_by_message(
                 "unknown type",
             )
         )
-        or re.search(r"expected (?:a |str|int|bool|dict|list|float|type|one of)", error_str)
+        or re.search(
+            r"expected (?:a |str|int|bool|dict|list|float|type|one of)", error_str
+        )
     ):
         # Supervisor schema validation: vol.Invalid message arriving as a
         # HomeAssistantCommandError via HA Core's hassio WS bridge. The
@@ -298,20 +311,27 @@ def _classify_by_message(
         if entity_id:
             result = create_entity_not_found_error(entity_id, details=error_msg)
         else:
-            result = create_error_response(ErrorCode.RESOURCE_NOT_FOUND, error_msg, context=context)
+            result = create_error_response(
+                ErrorCode.RESOURCE_NOT_FOUND, error_msg, context=context
+            )
     elif "timeout" in error_str:
-        result = create_timeout_error("operation", 30, details=error_msg, context=context)
+        result = create_timeout_error(
+            "operation", 30, details=error_msg, context=context
+        )
     elif "connection" in error_str or "connect" in error_str:
         result = create_connection_error(error_msg, context=context)
-    elif any(
-        phrase in error_str
-        for phrase in (
-            "unauthorized",
-            "authentication",
-            "invalid token",
-            "access denied",
+    elif (
+        any(
+            phrase in error_str
+            for phrase in (
+                "unauthorized",
+                "authentication",
+                "invalid token",
+                "access denied",
+            )
         )
-    ) or "401" in error_str:
+        or "401" in error_str
+    ):
         result = create_auth_error(error_msg, context=context)
     elif error_str.startswith("command failed:"):
         # HomeAssistantCommandError fallback: WS ``success=False`` with a
@@ -319,10 +339,15 @@ def _classify_by_message(
         # known failure mode (the WS command itself failed), not an
         # unexpected internal error — route to SERVICE_CALL_FAILED,
         # mirroring the 4xx fallback in _classify_api_status.
-        result = create_error_response(ErrorCode.SERVICE_CALL_FAILED, error_msg, context=context)
+        result = create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED, error_msg, context=context
+        )
     else:
         result = create_error_response(
-            ErrorCode.INTERNAL_ERROR, "An unexpected error occurred", details=error_msg, context=context
+            ErrorCode.INTERNAL_ERROR,
+            "An unexpected error occurred",
+            details=error_msg,
+            context=context,
         )
     return result
 
@@ -418,7 +443,11 @@ def exception_to_structured_error(
     ):
         logger.exception("Unclassified exception: %s", error_msg)
 
-    if suggestions and "error" in error_response and isinstance(error_response["error"], dict):
+    if (
+        suggestions
+        and "error" in error_response
+        and isinstance(error_response["error"], dict)
+    ):
         # Set both `suggestion` (singular, first item) and `suggestions`
         # (plural, full list). create_error_response (errors.py) sets the
         # singular key; existing tests for exception_to_structured_error
@@ -535,6 +564,4 @@ def register_tool_methods(mcp: Any, instance: Any) -> None:
             mcp.add_tool(method)
             count += 1
     if count == 0:
-        logger.warning(
-            f"No @tool-decorated methods found on {type(instance).__name__}"
-        )
+        logger.warning(f"No @tool-decorated methods found on {type(instance).__name__}")