ha-mcp-dev 7.14.0.dev2053__tar.gz → 7.14.0.dev2056__tar.gz

{ha_mcp_dev-7.14.0.dev2053/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.14.0.dev2056}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.14.0.dev2053
+Version: 7.14.0.dev2056
 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.14.0.dev2053 → ha_mcp_dev-7.14.0.dev2056}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.14.0.dev2053"
+version = "7.14.0.dev2056"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-7.14.0.dev2053 → ha_mcp_dev-7.14.0.dev2056}/src/ha_mcp/client/rest_client.py

@@ -11,6 +11,7 @@ import time
 from typing import Any
 
 import httpx
+from websockets.exceptions import WebSocketException
 
 from .._version import get_supervisor_base_url, is_running_in_addon
 from ..config import get_global_settings
@@ -133,6 +134,20 @@ class HomeAssistantCommandTimeout(HomeAssistantError):
     """
 
 
+# Exception classes that are evidence no answer came back from Home Assistant,
+# as opposed to Home Assistant answering with a rejection. ``OSError`` covers
+# ``ConnectionResetError``; ``WebSocketException`` covers the
+# ``ConnectionClosed`` family that ``send_command`` re-raises unwrapped;
+# ``HomeAssistantCommandTimeout`` covers a socket that is still open but has
+# stopped answering, which leaves a caller just as blind as a closed one.
+_NO_ANSWER_ERRORS = (
+    HomeAssistantConnectionError,
+    HomeAssistantCommandTimeout,
+    OSError,
+    WebSocketException,
+)
+
+
 class HomeAssistantClient:
     """Authenticated HTTP client for Home Assistant API."""
 
@@ -1437,6 +1452,11 @@ class HomeAssistantClient:
         retry_delay = 0.5  # seconds
 
         for attempt in range(max_retries):
+            # Whether the failure happened before a usable connection existed.
+            # Failing to obtain one is transport death whatever class the
+            # manager raises, and it raises a bare ``Exception`` when
+            # ``connect()`` returns False, so this cannot be decided by type.
+            acquiring = True
             try:
                 # Use per-client WebSocket keyed to this client's credentials
                 # (verify_ssl included so a verify_ssl=False client never
@@ -1446,6 +1466,7 @@ class HomeAssistantClient:
                     token=self.token,
                     verify_ssl=self.verify_ssl,
                 )
+                acquiring = False
 
                 # Special handling for render_template which returns an event with the actual result
                 if message.get("type") == "render_template":
@@ -1460,31 +1481,70 @@ class HomeAssistantClient:
 
             except Exception as e:
                 error_str = str(e)
-
-                # Detect transient 403 errors (rate limiting / reverse proxy throttling)
-                if "403" in error_str and "Forbidden" in error_str:
-                    if attempt < max_retries - 1:
-                        logger.warning(
-                            f"WebSocket 403 error (attempt {attempt + 1}/{max_retries}), "
-                            f"retrying after {retry_delay}s: {error_str}"
-                        )
-                        await asyncio.sleep(retry_delay)
-                        continue
-                    else:
-                        logger.error(
-                            f"WebSocket 403 error after {max_retries} attempts: {error_str}"
-                        )
-                        return {
-                            "success": False,
-                            "error": f"WebSocket request blocked (403 Forbidden): {error_str}",
-                            "error_code": getattr(e, "code", None),
-                            "suggestions": [
-                                "This may be caused by a reverse proxy or security filter",
-                                "Try simplifying the request (e.g., shorter templates, fewer parameters)",
-                                "If using complex templates, try breaking them into smaller parts",
-                                "Check if your Home Assistant is behind a reverse proxy with security rules",
-                            ],
-                        }
+                is_403 = "403" in error_str and "Forbidden" in error_str
+
+                # Transient 403 (rate limiting / reverse proxy throttling): retry
+                # before deciding anything, since the next attempt may succeed.
+                if is_403 and attempt < max_retries - 1:
+                    logger.warning(
+                        f"WebSocket 403 error (attempt {attempt + 1}/{max_retries}), "
+                        f"retrying after {retry_delay}s: {error_str}"
+                    )
+                    await asyncio.sleep(retry_delay)
+                    continue
+
+                # Phase first, type second. Failing before a client exists is
+                # evidence about the transport whatever class was raised, and
+                # the pooled manager raises a bare ``Exception`` when
+                # ``connect()`` returns False, so that case cannot be decided
+                # by type. Past acquisition only the no-answer classes count:
+                # ``send_command`` deliberately re-raises the original
+                # ``ConnectionClosed`` / ``ConnectionResetError`` from the send
+                # rather than wrapping it, to keep at-most-once semantics for
+                # write callers, so those arrive here untranslated. Anything
+                # else (a ``ValueError`` from building the message, say) is a
+                # bug rather than evidence about the connection.
+                if acquiring or isinstance(e, _NO_ANSWER_ERRORS):
+                    # One error channel for "no answer came back" (#1947): the
+                    # caller decides the policy, rather than every consumer
+                    # having to notice a marker on an otherwise ordinary
+                    # failure envelope. Callers that legitimately continue on a
+                    # missing answer catch this and say in ``warnings`` what
+                    # they skipped; callers whose output would read as a
+                    # negative finding let it propagate.
+                    logger.error(
+                        f"WebSocket transport failed ({message.get('type')}): {e}"
+                    )
+                    if isinstance(e, HomeAssistantConnectionError):
+                        # Already the right class — re-raise unchanged so
+                        # subtypes (``HomeAssistantCommandNotSent``) and the
+                        # original traceback survive.
+                        raise
+                    raise HomeAssistantConnectionError(error_str) from e
+
+                # Deliberate asymmetry (#1966 review item 8): a 403 that
+                # exhausts its retries DURING acquisition is transport death -
+                # no client was ever obtained - so it raises and loses the
+                # reverse-proxy suggestions below. The 403 text survives in the
+                # message, and returning a soft envelope there instead would
+                # put a blocked transport back on the degrade path this change
+                # exists to close. Past acquisition the socket is alive and HA
+                # (or a proxy) answered, so the tailored suggestions apply.
+                if is_403:
+                    logger.error(
+                        f"WebSocket 403 error after {max_retries} attempts: {error_str}"
+                    )
+                    return {
+                        "success": False,
+                        "error": f"WebSocket request blocked (403 Forbidden): {error_str}",
+                        "error_code": getattr(e, "code", None),
+                        "suggestions": [
+                            "This may be caused by a reverse proxy or security filter",
+                            "Try simplifying the request (e.g., shorter templates, fewer parameters)",
+                            "If using complex templates, try breaking them into smaller parts",
+                            "Check if your Home Assistant is behind a reverse proxy with security rules",
+                        ],
+                    }
 
                 # Name the command in the log line: a bare "Command failed:
                 # Unknown command." is undiagnosable from a user's log
@@ -1499,7 +1559,11 @@ class HomeAssistantClient:
                     "error_code": getattr(e, "code", None),
                 }
 
-        return {"success": False, "error": "WebSocket request failed"}
+        # Unreachable: every attempt either returns, raises, or ``continue``s,
+        # and the last attempt cannot ``continue`` (the 403 branch guards on
+        # ``attempt < max_retries - 1``). Assert rather than return a
+        # contextless failure envelope that would read as a soft error.
+        raise AssertionError("send_websocket_message loop exited without a result")
 
     async def _handle_render_template(
         self, ws_client: Any, message: dict[str, Any]
@@ -1536,12 +1600,23 @@ class HomeAssistantClient:
                 }
 
         except TimeoutError:
+            # Template-level, not transport-level: the wait budget here is the
+            # caller's own ``timeout`` (default 3s) plus two seconds, and a
+            # template that is merely slow to render leaves the socket healthy.
+            # Deliberately NOT treated as a dead transport, unlike the 30s
+            # round-trip ``HomeAssistantCommandTimeout`` in ``send_command``.
             return {
                 "success": False,
                 "error": "Event timeout - template result not received",
                 "template": message.get("template"),
             }
         except Exception as e:
+            if isinstance(e, _NO_ANSWER_ERRORS):
+                # Let the caller's classification decide. Returning an envelope
+                # here would route a transport death around the fail-loud policy
+                # in ``send_websocket_message`` — the very swallow this branch
+                # used to hide (#1947).
+                raise
             return {
                 "success": False,
                 "error": str(e),
@@ -1579,6 +1654,13 @@ class HomeAssistantClient:
                             f"Resolved script entity_id {entity_id} to storage key {unique_id}"
                         )
                     return str(unique_id)
+        except HomeAssistantConnectionError:
+            # A dead transport must not become a silent guess: the fallback
+            # below assumes the storage key equals the bare entity_id, which is
+            # exactly what a UI rename breaks. Guessing it on a write path
+            # writes a NEW object under the wrong key instead of updating the
+            # renamed one, so let the caller fail loud (#1947).
+            raise
         except Exception:
             logger.debug(
                 f"Entity registry lookup failed for {entity_id}, using bare id: {bare_id}",
@@ -1720,6 +1802,13 @@ class HomeAssistantClient:
                             f"Resolved scene entity_id {entity_id} to storage key {unique_id}"
                         )
                     return str(unique_id)
+        except HomeAssistantConnectionError:
+            # A dead transport must not become a silent guess: the fallback
+            # below assumes the storage key equals the bare entity_id, which is
+            # exactly what a UI rename breaks. Guessing it on a write path
+            # writes a NEW object under the wrong key instead of updating the
+            # renamed one, so let the caller fail loud (#1947).
+            raise
         except Exception:
             logger.debug(
                 f"Entity registry lookup failed for {entity_id}, using bare id: {bare_id}",

{ha_mcp_dev-7.14.0.dev2053 → ha_mcp_dev-7.14.0.dev2056}/src/ha_mcp/client/websocket_client.py

@@ -22,6 +22,7 @@ import websockets
 
 from ..config import get_global_settings
 from .rest_client import (
+    HomeAssistantAuthError,
     HomeAssistantCommandError,
     HomeAssistantCommandNotSent,
     HomeAssistantCommandTimeout,
@@ -368,8 +369,8 @@ class HomeAssistantWebSocketClient:
                     message_type="auth_invalid", timeout=1
                 )
                 if auth_invalid:
-                    raise Exception("Authentication failed: Invalid token")
-                raise Exception("Authentication timeout")
+                    raise HomeAssistantAuthError("Authentication failed: Invalid token")
+                raise HomeAssistantConnectionError("Authentication timeout")
 
             self._state.mark_authenticated()
             logger.info("WebSocket connected and authenticated successfully")
@@ -413,7 +414,7 @@ class HomeAssistantWebSocketClient:
     async def _send_auth(self) -> None:
         """Send authentication message."""
         if not self.websocket:
-            raise Exception("WebSocket not connected")
+            raise HomeAssistantConnectionError("WebSocket not connected")
         auth_message = {"type": "auth", "access_token": self.token}
         await self.websocket.send(json.dumps(auth_message))
 
@@ -434,7 +435,7 @@ class HomeAssistantWebSocketClient:
     async def _message_handler(self) -> None:
         """Background task to handle incoming WebSocket messages."""
         if not self.websocket:
-            raise Exception("WebSocket not connected")
+            raise HomeAssistantConnectionError("WebSocket not connected")
         # None means a clean exit (the async-for loop simply ended); the
         # except blocks below fill this in so pending futures — and the
         # log — carry *why* the connection went away instead of a bare
@@ -573,7 +574,7 @@ class HomeAssistantWebSocketClient:
 
         async with self._send_lock:
             if not self.websocket:
-                raise Exception("WebSocket not connected")
+                raise HomeAssistantConnectionError("WebSocket not connected")
             logger.debug(f"WebSocket sending: {message}")
             await self.websocket.send(json.dumps(message))
 
@@ -1204,7 +1205,7 @@ class WebSocketManager:
                 # 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(
+                raise HomeAssistantConnectionError(
                     "Failed to connect to Home Assistant WebSocket" + detail
                 )
 

{ha_mcp_dev-7.14.0.dev2053 → ha_mcp_dev-7.14.0.dev2056}/src/ha_mcp/tools/backup.py

@@ -244,9 +244,8 @@ async def _backup_prep_via_component(
     in-process read. ``None`` on capability miss, downgrade (``unknown_command``
     → invalidate the cached caps), or command error/timeout (logged) — the
     caller falls back to the legacy sequential calls. A
-    ``HomeAssistantConnectionError`` (pooled-WS drop) or the plain ``Exception``
-    ``get_websocket_client()`` raises on a failed (re)connect is caught here and
-    mapped to ``None``: the legacy probes (``_get_local_backup_agent_id`` /
+    ``HomeAssistantConnectionError`` — a pooled-WS drop, or a failed
+    (re)connect — is caught here and mapped to ``None``: the legacy probes (``_get_local_backup_agent_id`` /
     ``_get_backup_password``) run on a DEDICATED ``get_connected_ws_client`` socket
     already connected before this read, NOT this pooled one — so a wedged pooled
     socket must fall back to the legacy calls rather than fail create/restore.
@@ -265,8 +264,8 @@ async def _backup_prep_via_component(
             logger.warning("%s failed; fell back to legacy: %r", WS_BACKUP_PREP, exc)
         return None
     except Exception as exc:
-        # HomeAssistantConnectionError (pooled-WS drop) OR the plain Exception
-        # get_websocket_client() raises on a failed (re)connect. The legacy probes
+        # HomeAssistantConnectionError: a pooled-WS drop or a failed
+        # (re)connect. The legacy probes
         # ride a dedicated already-connected socket, so fall back rather than fail
         # create/restore on a wedged pooled socket.
         logger.warning(

{ha_mcp_dev-7.14.0.dev2053 → ha_mcp_dev-7.14.0.dev2056}/src/ha_mcp/tools/component_api.py

@@ -243,8 +243,8 @@ async def get_component_caps(client: Any) -> ComponentCaps | None:
       installed / upgraded mid-session (the REST client — the cache key — is not
       recreated on an HA restart) is eventually adopted instead of pinned absent.
     - ``HomeAssistantConnectionError`` / ``HomeAssistantCommandTimeout`` (WS
-      down or slow) — and the plain ``Exception`` ``get_websocket_client()`` raises
-      when ``WebSocketManager`` can't build the socket: cache a SHORT transient
+      down or slow, including the failed-connect raise from
+      ``WebSocketManager``): cache a SHORT transient
       negative (``_TRANSIENT_NEGATIVE_CACHE_TTL_S``) so repeated calls on a
       WS-broken install skip the slow connect and go straight to legacy, then
       re-probe once the window lapses (self-healing). The consuming tool's legacy
@@ -297,9 +297,8 @@ async def get_component_caps(client: Any) -> ComponentCaps | None:
             _store_transient_negative(client)
             return None
         except Exception:
-            # Includes the plain Exception get_websocket_client() raises when
-            # WebSocketManager can't build the socket — the connect-establishment
-            # failure review-5 M8 targets. Short transient cache, self-healing.
+            # Broad on purpose: the probe must never promote an unexpected
+            # fault into a tool failure. Short transient cache, self-healing.
             logger.debug("%s probe failed unexpectedly", INFO_COMMAND, exc_info=True)
             _store_transient_negative(client)
             return None

{ha_mcp_dev-7.14.0.dev2053 → ha_mcp_dev-7.14.0.dev2056}/src/ha_mcp/tools/component_config_reads.py

@@ -42,9 +42,10 @@ still completes:
 
 - ``fetch_entity_lookup_via_component``'s consumers degrade gracefully. The scene
   resolver's ``config/entity_registry/list`` dump rides
-  ``client.send_websocket_message`` — the swallowing bridge that returns
-  ``{"success": False}`` instead of raising, so the resolver walks its retry loop
-  to the naive ``scene.{id}`` fallback — and the automation resolver scans REST
+  ``client.send_websocket_message``, which answers a command HA rejected with
+  ``{"success": False}``, so the resolver walks its retry loop to the naive
+  ``scene.{id}`` fallback (a dead transport raises there instead, #1947) - and
+  the automation resolver scans REST
   ``get_states()`` and additionally catches broadly → ``None``. Its only routed
   call sites run AFTER a scene/automation upsert commits or BEFORE a REST delete,
   so an escaping transport error would report a landed write as failed / abort a
@@ -104,7 +105,7 @@ async def fetch_entity_lookup_via_component(
     ``None`` on capability miss, downgrade (``unknown_command`` → invalidate the
     cached caps), command error/timeout (logged), a connection-establishment
     failure (logged — see the module docstring: the resolvers' legacy paths ride
-    the swallowing WS bridge / REST, NOT this pooled socket, so a transport
+    the WS bridge / REST, NOT this pooled socket, so a transport
     failure must fall back rather than abort a landed write), or a shape-drift
     payload (no ``matches`` list). Same error-taxonomy and silent fallback as
     ``component_devices.fetch_device_via_component``.
@@ -125,8 +126,8 @@ async def fetch_entity_lookup_via_component(
             logger.warning("%s failed; fell back to legacy: %r", WS_ENTITY_LOOKUP, exc)
         return None
     except Exception as exc:
-        # HomeAssistantConnectionError (pooled-WS drop) OR the plain Exception
-        # get_websocket_client() raises when WebSocketManager can't (re)connect.
+        # HomeAssistantConnectionError: a pooled-WS drop or a failed
+        # (re)connect.
         # The resolvers' legacy paths do NOT die identically (see module docstring),
         # so route to legacy rather than escape.
         logger.warning(
@@ -163,11 +164,10 @@ async def fetch_reference_data_via_component(
 
     Like every component fetch helper, a transport failure routes to ``None``
     (→ legacy REST) rather than escaping; the reference validator's legacy path is
-    the REST ``get_services()`` / ``get_states()`` pair. The catch is
-    broad because ``get_websocket_client()`` raises a plain ``Exception`` (not
-    ``HomeAssistantConnectionError``) when ``WebSocketManager`` cannot build the
-    socket; letting it escape would make ``validate_config_references`` hit its
-    swallow-all fetch guard and skip ALL reference warnings even when REST is up.
+    the REST ``get_services()`` / ``get_states()`` pair. The catch stays broad
+    so no unexpected fault escapes: that would make ``validate_config_references``
+    hit its swallow-all fetch guard and skip ALL reference warnings even when
+    REST is up.
     Mirrors ``get_component_caps``' own broad-catch precedent.
     """
     caps = await get_component_caps(client)
@@ -187,10 +187,9 @@ async def fetch_reference_data_via_component(
         return None
     except Exception as exc:
         # Legacy is REST (get_services/get_states), NOT the pooled WS, so a
-        # pooled-WS drop (HomeAssistantConnectionError) OR get_websocket_client()
-        # raising a plain Exception when WebSocketManager can't (re)connect must
-        # route to the REST fetch rather than escape into the validator's
-        # swallow-all guard (which would skip every reference warning).
+        # pooled-WS drop or a failed (re)connect must route to the REST fetch
+        # rather than escape into the validator's swallow-all guard (which would
+        # skip every reference warning).
         logger.warning(
             "%s connection error; falling back to REST legacy: %r",
             WS_REFERENCE_DATA,

{ha_mcp_dev-7.14.0.dev2053 → ha_mcp_dev-7.14.0.dev2056}/src/ha_mcp/tools/component_devices.py

@@ -71,10 +71,10 @@ async def fetch_device_via_component(
     unavailable, fall back"). Falls back **silently**, mirroring
     ``ha_get_state``: the legacy path returns the byte-identical device either way
     and the ``log.warning`` preserves operator visibility. A
-    ``HomeAssistantConnectionError`` (pooled-WS drop) or the plain ``Exception``
-    ``get_websocket_client()`` raises on a failed (re)connect is caught here and
-    mapped to ``None``: the consumers' legacy paths ride the swallowing
-    ``send_websocket_message`` bridge (registry tools) or a dedicated one-shot WS
+    ``HomeAssistantConnectionError`` — a pooled-WS drop, or a failed
+    (re)connect — is caught here and mapped to ``None``: the consumers' legacy
+    paths ride the ``send_websocket_message`` bridge (registry tools) or a
+    dedicated one-shot WS
     client (the auto-backup capture) — NOT this pooled socket — so a transport
     failure must fall back rather than block a tool / a wrapped write.
 
@@ -100,10 +100,10 @@ async def fetch_device_via_component(
             logger.warning("%s failed; fell back to legacy: %r", WS_DEVICE_GET, exc)
         return None
     except Exception as exc:
-        # HomeAssistantConnectionError (pooled-WS drop) OR the plain Exception
-        # get_websocket_client() raises when WebSocketManager can't (re)connect.
-        # The legacy paths ride the swallowing send_websocket_message bridge / a
-        # dedicated capture socket, not this pooled one, so fall back to legacy.
+        # HomeAssistantConnectionError: a pooled-WS drop or a failed
+        # (re)connect. The legacy paths ride the send_websocket_message bridge /
+        # a dedicated capture socket, so fall back to legacy; if the transport
+        # itself is dead the bridge raises there in turn (#1947).
         logger.warning(
             "%s connection error; falling back to legacy: %r", WS_DEVICE_GET, exc
         )
@@ -173,7 +173,7 @@ async def fetch_device_list_via_component(client: Any) -> dict[str, Any] | None:
         return None
     except Exception as exc:
         # HomeAssistantConnectionError / plain establish Exception → legacy (the
-        # legacy device list rides the swallowing send_websocket_message bridge).
+        # legacy device list rides the send_websocket_message bridge).
         logger.warning(
             "%s connection error; falling back to legacy: %r", WS_DEVICE_LIST, exc
         )

{ha_mcp_dev-7.14.0.dev2053 → ha_mcp_dev-7.14.0.dev2056}/src/ha_mcp/tools/component_registries.py

@@ -100,14 +100,15 @@ async def fetch_registries_via_component(
     failure (logged), or a malformed response — the outer ``result`` isn't a
     dict, or a requested slice isn't its expected list/dict shape (logged; see
     ``_has_valid_shape``) — the caller falls back to its legacy WS list call(s)
-    in every case. A ``HomeAssistantConnectionError`` (pooled-WS drop) or the
-    plain ``Exception`` ``get_websocket_client()`` raises on a failed (re)connect
-    is caught here and mapped to ``None``: the auto-backup capture fetchers'
+    in every case. A ``HomeAssistantConnectionError`` — a pooled-WS drop, or a
+    failed (re)connect — is caught here and mapped to ``None``: the auto-backup capture fetchers'
     legacy ``_ws_send`` builds a DEDICATED one-shot WS client (which can succeed
     while the pooled socket is wedged) under a best-effort contract that requires
     warn-and-skip, never a blocked write; ``ha_list_floors_areas``' legacy rides
-    the swallowing ``send_websocket_message`` bridge. Neither dies identically on
-    a pooled-WS drop, so a transport failure must fall back rather than escape.
+    the ``send_websocket_message`` bridge, which is the SAME pooled connection
+    and raises on a dead transport (#1947) rather than degrading. Only the
+    capture path's dedicated socket survives a wedged pool, so a
+    component-side fault must fall back rather than escape.
     """
     caps = await get_component_caps(client)
     if not component_supports(caps, "registries"):
@@ -125,8 +126,8 @@ async def fetch_registries_via_component(
             logger.warning("%s failed; fell back to legacy: %r", WS_REGISTRIES, exc)
         return None
     except Exception as exc:
-        # HomeAssistantConnectionError (pooled-WS drop) OR the plain Exception
-        # get_websocket_client() raises on a failed (re)connect. The capture
+        # HomeAssistantConnectionError: a pooled-WS drop or a failed
+        # (re)connect. The capture
         # fetchers use a dedicated one-shot socket and forbid a blocked write, so
         # this must fall back to legacy rather than escape into the write path.
         logger.warning(

{ha_mcp_dev-7.14.0.dev2053 → ha_mcp_dev-7.14.0.dev2056}/src/ha_mcp/tools/component_registry_lookup.py

@@ -32,14 +32,15 @@ on any component error — lives in one place (the pattern ``component_devices``
 established for the ``device_get`` / ``device_list`` capabilities). Both helpers
 return ``None`` to mean "component unavailable — use the legacy path"; a component
 that answers returns its payload. Per the uniform transport-fallback taxonomy, a
-``HomeAssistantConnectionError`` (pooled-WS drop) and the plain ``Exception``
-``get_websocket_client()`` raises on a failed (re)connect are caught and mapped to
-``None`` so the legacy path runs: the consumers' legacy reads (the whole-registry
+``HomeAssistantConnectionError`` — a pooled-WS drop, or a failed (re)connect —
+is caught and mapped to ``None`` so the legacy path runs: the consumers' legacy reads (the whole-registry
 ``config/entity_registry/list`` dump and the per-id ``config/entity_registry/get``
-retry loop) ride the swallowing ``send_websocket_message`` bridge, which returns
-``{"success": False}`` rather than raising — so they do NOT die identically on a
-pooled-WS drop, and letting a transport failure escape would skip the
-``resolve_entities_via_component`` consumer's legacy retry loop entirely.
+retry loop) ride the ``send_websocket_message`` bridge, which answers a
+command HA rejected with ``{"success": False}`` - so a component-side fault
+does not kill them, and letting it escape would skip the
+``resolve_entities_via_component`` consumer's legacy retry loop entirely. The
+bridge uses the SAME pooled connection, so a dead transport raises there too
+(#1947) rather than degrading.
 """
 
 from __future__ import annotations
@@ -96,7 +97,7 @@ async def fetch_entities_for_config_entry_via_component(
         return None
     except Exception as exc:
         # HomeAssistantConnectionError / plain establish Exception → legacy (the
-        # legacy entity_registry/list dump rides the swallowing bridge; see module
+        # legacy entity_registry/list dump rides the bridge; see module
         # docstring). Never propagate a transport failure out of the read.
         logger.warning(
             "%s connection error; falling back to legacy: %r", WS_REGISTRY_LOOKUP, exc

ha_mcp_dev-7.14.0.dev2056/src/ha_mcp/tools/smart_search/_base.py

@@ -0,0 +1,51 @@
+"""Shared base for the smart-search feature mixins.
+
+``_SearchBase`` declares the instance attributes that
+``SmartSearchTools.__init__`` sets, so each feature mixin type-checks in
+isolation, and hosts the registry-list helper shared by the overview and
+entity/area search mixins.
+"""
+
+import logging
+from typing import Any
+
+from ...client.rest_client import HomeAssistantClient
+
+logger = logging.getLogger(__name__)
+
+
+class _SearchBase:
+    """Attributes set by ``SmartSearchTools.__init__`` plus shared helpers."""
+
+    client: HomeAssistantClient
+    fuzzy_searcher: Any
+    settings: Any
+
+    @staticmethod
+    def _extract_registry_list(
+        result: Any, label: str, warnings: list[str] | None = None
+    ) -> list[dict[str, Any]]:
+        """Unwrap a WS registry-list result, returning ``[]`` on error/failure.
+
+        Every caller treats missing registry data as non-fatal rather than
+        raising: the overview degrades its area enrichment, and the area
+        search degrades to "no match found". Degrading is fine; degrading
+        silently is not — a caller that passes ``warnings`` gets a line
+        naming what was unavailable and why, so a thinner answer is
+        distinguishable from a genuinely empty registry (#1947).
+        """
+        cause: str | None = None
+        registry: list[dict[str, Any]] = []
+        if isinstance(result, Exception):
+            logger.debug(f"Could not fetch {label}: {result}")
+            cause = str(result) or type(result).__name__
+        elif isinstance(result, dict) and result.get("success"):
+            registry = result.get("result", [])
+        elif isinstance(result, dict):
+            cause = str(result.get("error") or "request failed")
+        else:
+            cause = f"unexpected response type: {type(result).__name__}"
+
+        if cause is not None and warnings is not None:
+            warnings.append(f"{label} unavailable: {cause}")
+        return registry

{ha_mcp_dev-7.14.0.dev2053 → ha_mcp_dev-7.14.0.dev2056}/src/ha_mcp/tools/smart_search/_entities.py

@@ -457,9 +457,15 @@ class EntitySearchMixin(_SearchBase):
             visibility_hidden, visibility_warnings = await load_hidden_set(
                 results[2], results[0], self.client, results[3]
             )
-            area_registry = self._parse_area_registry(results[1])
-            entity_reg_map = self._parse_entity_reg_map(results[2])
-            device_area_map = self._parse_device_area_map(results[3])
+            # Registry failures still fail open, but each names itself: an area
+            # search that answers "no match found" because the area registry
+            # never arrived must not look like a search that genuinely found
+            # nothing (#1947).
+            registry_warnings: list[str] = []
+            area_registry = self._parse_area_registry(results[1], registry_warnings)
+            entity_reg_map = self._parse_entity_reg_map(results[2], registry_warnings)
+            device_area_map = self._parse_device_area_map(results[3], registry_warnings)
+            degraded_warnings = registry_warnings + visibility_warnings
 
             area_query_lower = area_query.lower().strip()
             matched_area_ids = self._match_area_ids(area_registry, area_query_lower)
@@ -476,7 +482,7 @@ class EntitySearchMixin(_SearchBase):
                             for aid, ainfo in area_registry.items()
                         ],
                     },
-                    visibility_warnings,
+                    degraded_warnings,
                 )
 
             entity_area_resolved, hidden_entity_ids = self._resolve_entity_areas(
@@ -499,7 +505,7 @@ class EntitySearchMixin(_SearchBase):
                     "total_entities": total_entities,
                     "areas": formatted_areas,
                 },
-                visibility_warnings,
+                degraded_warnings,
             )
 
         except Exception as e:
@@ -519,20 +525,24 @@ class EntitySearchMixin(_SearchBase):
             raise
 
     @classmethod
-    def _parse_area_registry(cls, result: Any) -> dict[str, dict[str, Any]]:
+    def _parse_area_registry(
+        cls, result: Any, warnings: list[str] | None = None
+    ) -> dict[str, dict[str, Any]]:
         """Parse the area registry into ``area_id -> area info``."""
         area_registry: dict[str, dict[str, Any]] = {}
-        for area in cls._extract_registry_list(result, "area registry"):
+        for area in cls._extract_registry_list(result, "area registry", warnings):
             area_id = area.get("area_id", "")
             if area_id:
                 area_registry[area_id] = area
         return area_registry
 
     @classmethod
-    def _parse_entity_reg_map(cls, result: Any) -> dict[str, dict[str, str | None]]:
+    def _parse_entity_reg_map(
+        cls, result: Any, warnings: list[str] | None = None
+    ) -> dict[str, dict[str, str | None]]:
         """Parse the entity registry into ``entity_id -> {area_id, device_id, hidden_by}``."""
         entity_reg_map: dict[str, dict[str, str | None]] = {}
-        for entry in cls._extract_registry_list(result, "entity registry"):
+        for entry in cls._extract_registry_list(result, "entity registry", warnings):
             entity_id = entry.get("entity_id")
             if entity_id:
                 entity_reg_map[entity_id] = {
@@ -543,10 +553,12 @@ class EntitySearchMixin(_SearchBase):
         return entity_reg_map
 
     @classmethod
-    def _parse_device_area_map(cls, result: Any) -> dict[str, str | None]:
+    def _parse_device_area_map(
+        cls, result: Any, warnings: list[str] | None = None
+    ) -> dict[str, str | None]:
         """Parse the device registry into ``device_id -> area_id``."""
         device_area_map: dict[str, str | None] = {}
-        for device in cls._extract_registry_list(result, "device registry"):
+        for device in cls._extract_registry_list(result, "device registry", warnings):
             device_id = device.get("id", "")
             if device_id:
                 device_area_map[device_id] = device.get("area_id")