ha-mcp-dev 8.6.0.dev3006__tar.gz → 8.6.0.dev3007__tar.gz

{ha_mcp_dev-8.6.0.dev3006 → ha_mcp_dev-8.6.0.dev3007}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev3006
+Version: 8.6.0.dev3007
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-8.6.0.dev3006 → ha_mcp_dev-8.6.0.dev3007}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev3006"
+version = "8.6.0.dev3007"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-8.6.0.dev3006 → ha_mcp_dev-8.6.0.dev3007}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev3006"
+version = "8.6.0.dev3007"
 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-8.6.0.dev3007/src/ha_mcp/backup_integrations.py

@@ -0,0 +1,49 @@
+"""Auto-backup handlers for integration config entries.
+
+An integration snapshot holds only the entry's metadata and its enabled state, so
+a restore re-applies that state to an entry that still exists and refuses a
+deleted one rather than sending Core a command for an entry it no longer has.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .backup_entity_ids import _manager
+
+
+async def fetch_integration(client: Any, entity_id: str) -> Any:
+    bm = _manager()
+    items = bm._require_list(
+        await bm._ws_send(client, {"type": "config_entries/get"}),
+        "config_entries/get",
+    )
+    for item in items:
+        if item.get("entry_id") == entity_id:
+            return item
+    return None
+
+
+async def restore_integration(client: Any, entity_id: str, config: Any) -> Any:
+    bm = _manager()
+    if await fetch_integration(client, entity_id) is None:
+        raise bm.BackupRestoreError(
+            f"Config entry {entity_id} ({config.get('domain')}) no longer exists. "
+            "An integration snapshot holds only the entry's metadata and enabled "
+            "state, so it cannot recreate a deleted entry. Nothing was changed; add "
+            "the integration again to recover it.",
+            reason="entry_deleted",
+            suggestions=[
+                "Add it again with ha_set_integration, or have the user add it in "
+                "the HA UI when it needs their credentials."
+            ],
+        )
+    disabled = config.get("disabled_by") is not None
+    return await bm._ws_send(
+        client,
+        {
+            "type": "config_entries/disable",
+            "entry_id": entity_id,
+            "disabled_by": "user" if disabled else None,
+        },
+    )

{ha_mcp_dev-8.6.0.dev3006 → ha_mcp_dev-8.6.0.dev3007}/src/ha_mcp/backup_manager.py

@@ -35,9 +35,9 @@ Domain handlers
 - ``fetch(client, entity_id) -> config dict``  — read pre-write state
 - ``restore(client, entity_id, config) -> result`` — re-apply the saved state
 
-One handler per backed-up domain. Helper types each register their own
-handler keyed ``helper_<type>`` since each helper type has a distinct
-WS endpoint shape.
+One handler per backed-up domain. Storage helper types each register one keyed
+``helper_<type>``; a flow helper gets one built on each lookup
+(``BackupManager.handler_for``).
 """
 
 from __future__ import annotations
@@ -64,6 +64,7 @@ from typing import Any, Literal, NotRequired, TypedDict
 import yaml  # type: ignore[import-untyped]
 
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
+from ha_mcp._vendor.websockets.exceptions import ConnectionClosed
 
 from .backup_diff import (
     _TEXT_KIND,
@@ -75,6 +76,7 @@ from .backup_diff import (
     _summarize_patch_counts,
 )
 from .backup_entity_ids import _restore_entity_ids
+from .backup_integrations import fetch_integration, restore_integration
 from .backup_tags import restore_tag, tag_snapshot
 from .client.rest_client import (
     HomeAssistantCommandError,
@@ -108,6 +110,7 @@ _CAPTURE_TRANSIENT_ERRORS: tuple[type[BaseException], ...] = (
     TimeoutError,
     asyncio.TimeoutError,
     ConnectionError,
+    ConnectionClosed,
     yaml.YAMLError,
     ToolError,
 )
@@ -140,6 +143,11 @@ class MandatoryBackupError(Exception):
         # can include configuration values even when wrapped by this class.
         self.safe_detail = safe_detail
 
+    @property
+    def safe_cause(self) -> str:
+        """The safe detail, else only the failing exception's class name."""
+        return self.safe_detail or type(self.__cause__ or self).__name__
+
 
 class BackupRestoreError(HomeAssistantError):
     """A restore outcome whose apply knowledge must survive caller mapping."""
@@ -205,16 +213,22 @@ class _FlowHelperReadError(HomeAssistantError):
         self.reason = reason
 
 
-@functools.cache
-def _flow_helper_types() -> frozenset[str]:
-    from .tools.config_entry_flow import FLOW_HELPER_TYPES
-
-    return FLOW_HELPER_TYPES
+class _FlowHelperBackupSkip(_FlowHelperReadError):
+    """Nothing to back up: no stored or disclosed options, or no helper flow Core
+    lists. Best-effort capture logs it at INFO."""
 
 
 def _is_flow_helper_domain(domain: str) -> bool:
-    """A ``helper_<type>`` snapshot of a config-entry (flow) helper."""
-    return domain.startswith("helper_") and domain[7:] in _flow_helper_types()
+    """A ``helper_<type>`` snapshot domain of a config-entry (flow) helper.
+
+    Any type that is neither a storage helper nor a config subentry counts; the
+    type itself is not checked here. The tools check it against Core's helper
+    flow list (``helper_flows.require_helper_type``; ha_config_set_helper only
+    after its auto-backup capture, which checks an uncovered type itself), as
+    does ``resolve_config_entry_backup_domain`` for an arbitrary config entry.
+    """
+    helper_type = domain[7:] if domain.startswith("helper_") else ""
+    return helper_type not in ("", *_HELPER_LIST_TYPES, "config_subentry")
 
 
 def _flow_failure_reason(step: str, error: BaseException) -> str:
@@ -506,7 +520,8 @@ def _require_restore_safety(path: Path) -> None:
     """Check the recovery file after its restore pin closes the deletion race."""
     if not path.is_file():
         raise MandatoryBackupError(
-            "The safety snapshot disappeared before restore; no changes were applied"
+            "The safety snapshot disappeared before restore; no changes were applied",
+            safe_detail="safety snapshot disappeared",
         )
 
 
@@ -625,17 +640,22 @@ class BackupManager:
         self._handlers[handler.domain] = handler
 
     def handler_for(self, domain: str) -> DomainHandler | None:
-        return self._handlers.get(domain)
+        handler = self._handlers.get(domain)
+        if handler is None and _is_flow_helper_domain(domain):
+            # Built per call, never registered: a typo stays out of supported_domains().
+            handler = _make_flow_helper_handler(domain[7:])
+        return handler
 
     def supported_domains(self) -> list[str]:
-        """Return the sorted list of registered backup-domain keys.
+        """Return the sorted registered backup-domain keys, plus a placeholder
+        for the flow helpers, whose handlers are built on use.
 
         Public accessor for callers that need to surface "what domains
         are supported?" in user-facing error messages (e.g., the
         ``ha_manage_backup(scope='edits', action='create')`` handler
         when ``domain`` is unknown). Sorted for stable output.
         """
-        return sorted(self._handlers.keys())
+        return [*sorted(self._handlers.keys()), "helper_<flow helper type>"]
 
     # ----- capture -------------------------------------------------------
 
@@ -722,8 +742,8 @@ class BackupManager:
         """Capture a snapshot for ``domain:entity_id`` if throttle elapsed.
 
         Returns the Path written or None if skipped. In the default
-        (best-effort) mode it never raises — all errors are logged at WARNING
-        and swallowed so the wrapped write can proceed regardless.
+        (best-effort) mode it never raises — errors are logged at WARNING (INFO for
+        a by-design skip) and swallowed so the wrapped write can proceed regardless.
 
         ``mandatory=True`` makes the snapshot a precondition (file/YAML writes,
         #1579): a *genuine* capture failure — an unusable backup dir, a failed
@@ -823,12 +843,11 @@ class BackupManager:
         if not entity_id:
             # Create-mode call with no ID yet — nothing to back up.
             return None
-        handler = self._handlers.get(domain)
+        handler = self.handler_for(domain)
         if handler is None:
             if mandatory:
-                raise MandatoryBackupError(
-                    f"no auto-backup handler is registered for domain {domain!r}"
-                )
+                message = f"no auto-backup handler is registered for domain {domain!r}"
+                raise MandatoryBackupError(message, safe_detail=message)
             logger.warning(
                 "Auto-backup: no handler registered for domain %r — skipping",
                 domain,
@@ -847,34 +866,33 @@ class BackupManager:
     ) -> Any:
         """Fetch the pre-write config; return ``_SNAPSHOT_SKIP`` to skip capture.
 
-        A handled transient fetch failure logs a WARNING and returns the
-        sentinel (or raises ``MandatoryBackupError`` under ``mandatory``); a
-        fetch that returns None because the entity did not exist logs a DEBUG
-        and returns the sentinel. Any other value is the config to snapshot.
+        A handled transient fetch failure logs a WARNING, a ``_FlowHelperBackupSkip``
+        an INFO; both return the sentinel (or raise ``MandatoryBackupError`` under
+        ``mandatory``). A fetch that returns None because the entity did not exist
+        logs a DEBUG and returns the sentinel. Any other value is the config.
         """
         try:
             config = await handler.fetch(self._client, entity_id)
         except _CAPTURE_TRANSIENT_ERRORS as err:
-            # Degraded fetches (a non-list WS envelope from an
-            # auth-scope change or API drift) raise rather than return
-            # None — see ``_require_list``. During auto-backup we skip
-            # the snapshot with a WARNING (operator-visible) instead of
-            # crashing the pipeline; the same error during a diff/
-            # restore propagates to the tool layer as a structured
-            # error. The warning level (vs the debug log below) is what
-            # distinguishes "fetch broke" from "entity didn't exist".
+            # Degraded fetches (a non-list WS envelope from an auth-scope change
+            # or API drift) raise rather than return None (``_require_list``).
+            # Auto-backup skips the snapshot instead of crashing the pipeline;
+            # in a diff/restore the error reaches the tool layer. WARNING marks
+            # "fetch broke", INFO a by-design skip, DEBUG "entity didn't exist".
             if mandatory:
                 raise MandatoryBackupError(
-                    f"could not read the current state of {key} to back "
-                    f"it up: {type(err).__name__}: {err}",
+                    f"could not back up {key}: {type(err).__name__}: {err}",
                     safe_detail=_flow_safe_failure_detail("capture", err),
                 ) from err
-            logger.warning(
-                "Auto-backup: fetch failed for %s — %s: %s",
-                key,
-                type(err).__name__,
-                err,
-            )
+            if isinstance(err, _FlowHelperBackupSkip):
+                logger.info("Auto-backup: not backing up %s — %s", key, err)
+            else:
+                logger.warning(
+                    "Auto-backup: fetch failed for %s — %s: %s",
+                    key,
+                    type(err).__name__,
+                    err,
+                )
             if skip_reasons is not None:
                 # Only locally authored detail: a remote error may carry values.
                 detail = _flow_safe_failure_detail("capture", err)
@@ -958,7 +976,7 @@ class BackupManager:
                     f"The new snapshot for {key} disappeared before capture completed"
                 )
                 if mandatory:
-                    raise MandatoryBackupError(message)
+                    raise MandatoryBackupError(message, safe_detail=message)
                 logger.warning("Auto-backup: %s", message)
                 return None
             self._last_snapshot[key] = now
@@ -1456,7 +1474,7 @@ class BackupManager:
         domain = data["domain"]
         entity_id = data["entity_id"]
         config = data["config"]
-        handler = self._handlers.get(domain)
+        handler = self.handler_for(domain)
         if handler is None:
             raise BackupRestoreError(
                 f"No restore handler registered for domain {domain!r}",
@@ -1494,7 +1512,9 @@ class BackupManager:
             # Commit to the absent-target branch: if an entry reappeared since
             # preflight, recreation refuses instead of editing it without safety.
             restore = (
-                handler.restore
+                functools.partial(_restore_config_subentry, recreate_only=True)
+                if domain == "helper_config_subentry" and safety_path is None
+                else handler.restore
                 if needs_safety
                 else functools.partial(
                     _recreate_flow_helper, helper_type=_flow_type(domain)
@@ -1540,29 +1560,16 @@ class BackupManager:
         return await handler.fetch(self._client, entity_id) is not None
 
     async def _capture_restore_safety(self, domain: str, entity_id: str) -> Path | None:
-        """Flow-helper restore requires a fresh recovery point for its stable entry."""
-        if domain == "helper_config_subentry":
-            # A reconfigure flow can apply partly, so the capture is forced and
-            # mandatory; a deleted subentry has nothing to capture (None).
-            return await self.maybe_snapshot(
-                domain,
-                entity_id,
-                tool_name="ha_manage_backup.restore.safety",
-                force=True,
-                mandatory=True,
-            )
-        if not _is_flow_helper_domain(domain):
-            return await self.maybe_snapshot(
-                domain, entity_id, tool_name="ha_manage_backup.restore.safety"
-            )
+        """Take a restore's recovery point; a failed capture raises and blocks it."""
+        is_flow = _is_flow_helper_domain(domain)
         path = await self.maybe_snapshot(
             domain,
             entity_id,
             tool_name="ha_manage_backup.restore.safety",
-            force=True,
+            force=is_flow or domain == "helper_config_subentry",
             mandatory=True,
         )
-        if path is None:
+        if path is None and is_flow:
             raise MandatoryBackupError(
                 f"{_flow_label(_flow_type(domain))} helper no longer exists; "
                 "restore was not attempted"
@@ -1581,7 +1588,7 @@ class BackupManager:
                 data["entity_id"], data["config"], _flow_type(domain)
             )
             data["entity_id"] = snapshot["entry_id"]
-        handler = self._handlers.get(domain)
+        handler = self.handler_for(domain)
         if handler is None:
             raise LookupError(f"No diff handler registered for domain {domain!r}")
         current = await handler.fetch(self._client, data["entity_id"])
@@ -2710,28 +2717,6 @@ async def _restore_device(client: Any, entity_id: str, config: Any) -> Any:
 # Integration enable/disable — restore re-applies the disabled flag.
 
 
-async def _fetch_integration(client: Any, entity_id: str) -> Any:
-    items = _require_list(
-        await _ws_send(client, {"type": "config_entries/get"}), "config_entries/get"
-    )
-    for item in items:
-        if item.get("entry_id") == entity_id:
-            return item
-    return None
-
-
-async def _restore_integration(client: Any, entity_id: str, config: Any) -> Any:
-    disabled = config.get("disabled_by") is not None
-    return await _ws_send(
-        client,
-        {
-            "type": "config_entries/disable",
-            "entry_id": entity_id,
-            "disabled_by": "user" if disabled else None,
-        },
-    )
-
-
 # Helpers — one handler family. Entity ID is "<helper_type>:<id>" so each
 # helper type lists/restores via its native WS endpoints. The decorator
 # constructs the domain key as ``helper_<type>`` so files group naturally.
@@ -3147,9 +3132,14 @@ def _flow_options(config: Any, helper_type: str) -> dict[str, Any]:
     from .redaction import sentinel_option_keys
 
     label = _flow_label(helper_type)
-    if not isinstance(config, dict) or not config:
+    if not isinstance(config, dict):
         raise _FlowHelperReadError(
-            f"{label} helper options must be a non-empty object", "invalid_options"
+            f"{label} helper options must be an object", "invalid_options"
+        )
+    if not config:
+        raise _FlowHelperBackupSkip(  # e.g. otp: all of it is in entry.data
+            f"{label} helper has no stored options to back up or restore",
+            "invalid_options",
         )
     # The component's resolved-!secret scrub predates the server sentinels.
     # Neither kind of placeholder is a usable recovery value.
@@ -3195,10 +3185,9 @@ async def _fetch_flow_helper(client: Any, entity_id: str, helper_type: str) -> A
         )
     covered = _require_list(result.get("covered_types"), "helpers_list.covered_types")
     if helper_type not in covered:
-        raise _FlowHelperReadError(
-            f"The component cannot authoritatively read {helper_type} helpers",
-            f"{helper_type}_read_unsupported",
-        )
+        from .tools.config_entry_backup import uncovered_flow_helper_error
+
+        raise await uncovered_flow_helper_error(client, helper_type)
     records = _require_list(result.get("helpers"), "ha_mcp_tools/helpers_list.helpers")
     entries: dict[str, dict[str, Any]] = {}
     for raw_record in records:
@@ -3224,6 +3213,12 @@ async def _fetch_flow_helper(client: Any, entity_id: str, helper_type: str) -> A
     if matches:
         record = matches[0]
         entry_id = record["entry_id"]
+        if record.get("options_withheld"):
+            raise _FlowHelperBackupSkip(
+                f"{_flow_label(helper_type)} helper belongs to a custom integration "
+                "whose options the component withholds: none to back up or restore",
+                "options_withheld",
+            )
         registry = await _entity_registry_rows(client)
         return {
             "entry_id": entry_id,
@@ -3753,7 +3748,9 @@ async def _fetch_config_subentry(client: Any, entity_id: str) -> Any:
     return _subentry_row(subentries, entry_id, subentry_id)
 
 
-async def _restore_config_subentry(client: Any, entity_id: str, config: Any) -> Any:
+async def _restore_config_subentry(
+    client: Any, entity_id: str, config: Any, *, recreate_only: bool = False
+) -> Any:
     """Restore a subentry's data through its reconfigure flow.
 
     A snapshot field none of the reconfigure forms offers must still match the
@@ -3795,6 +3792,11 @@ async def _restore_config_subentry(client: Any, entity_id: str, config: Any) ->
         return await _recreate_config_subentry(
             client, entity_id, snapshot, data, subentries
         )
+    if recreate_only:  # absent at the safety capture: nothing may be edited
+        raise BackupRestoreError(
+            "Config subentry reappeared after its safety capture; not restored",
+            reason="entry_still_exists",
+        )
     expected, keys = _subentry_expectation(snapshot, data)
     return await _apply_and_verify(
         "Config subentry",
@@ -3920,7 +3922,7 @@ def _make_helper_handler(helper_type: str) -> DomainHandler:
 
 # The storage-collection helper types, snapshotted as ``helper_<type>`` through
 # ``<type>/list`` and restored through ``<type>/update``. Flow helpers (config
-# entries) are registered separately from ``_flow_helper_types()``.
+# entries) get a handler built on each lookup (``BackupManager.handler_for``).
 _KNOWN_HELPER_TYPES = sorted(_HELPER_LIST_TYPES)
 
 
@@ -3947,7 +3949,7 @@ def register_default_handlers(mgr: BackupManager, _client: Any) -> None:
     mgr.register(DomainHandler("todo_item", _fetch_todo_item, _restore_todo_item))
     mgr.register(DomainHandler("entity", _fetch_entity_state, _restore_entity_state))
     mgr.register(DomainHandler("device", _fetch_device, _restore_device))
-    mgr.register(DomainHandler("integration", _fetch_integration, _restore_integration))
+    mgr.register(DomainHandler("integration", fetch_integration, restore_integration))
     mgr.register(DomainHandler("file", _fetch_file, _restore_file))
     mgr.register(DomainHandler("yaml", _fetch_yaml, _restore_yaml))
     # Whole-file YAML config: same fetch as "file" (read_file), but restored via
@@ -3960,8 +3962,6 @@ def register_default_handlers(mgr: BackupManager, _client: Any) -> None:
         mgr.register(_make_blueprint_handler(blueprint_domain))
     for helper_type in _KNOWN_HELPER_TYPES:
         mgr.register(_make_helper_handler(helper_type))
-    for helper_type in sorted(_flow_helper_types()):
-        mgr.register(_make_flow_helper_handler(helper_type))
     mgr.register(
         DomainHandler(
             "helper_config_subentry", _fetch_config_subentry, _restore_config_subentry

{ha_mcp_dev-8.6.0.dev3006 → ha_mcp_dev-8.6.0.dev3007}/src/ha_mcp/client/rest_client.py

@@ -628,8 +628,7 @@ class HomeAssistantClient:
     async def _request(
         self, method: str, endpoint: str, **kwargs: Any
     ) -> dict[str, Any]:
-        """
-        Make authenticated request to Home Assistant API and parse JSON body.
+        """Make authenticated request to Home Assistant API and parse JSON body.
 
         Args:
             method: HTTP method (GET, POST, etc.)
@@ -642,15 +641,17 @@ class HomeAssistantClient:
         Raises:
             HomeAssistantConnectionError: Connection failed
             HomeAssistantAuthError: Authentication failed
-            HomeAssistantAPIError: API error
+            HomeAssistantAPIError: API error, or a GET reply that is not JSON
         """
         response = await self._raw_request(method, endpoint, **kwargs)
         try:
             result: dict[str, Any] = response.json()
             return result
-        except json.JSONDecodeError:
-            # Some endpoints return empty responses
-            return {}
+        except ValueError as e:  # not JSON, or not UTF-8
+            if method != "GET" or not response.content.strip():
+                return {}  # empty body, or a write's reply: accepted, body unknown
+            # A read's {} would pass as the entity's config (e.g. in a backup).
+            raise HomeAssistantAPIError("GET reply is not JSON") from e
 
     async def get_config(self) -> dict[str, Any]:
         """Get Home Assistant configuration."""
@@ -662,7 +663,7 @@ class HomeAssistantClient:
 
         Raises ``HomeAssistantConnectionError`` when the response isn't the
         JSON array ``/states`` always returns on success -- including
-        ``_request``'s own empty-dict fallback for an unparseable body.
+        ``_request``'s own empty-dict fallback for an empty body.
         Silently returning ``[]`` here would let a genuine fetch failure
         masquerade as "this instance has zero entities", which no real,
         running Home Assistant instance produces; callers that need to
@@ -1469,8 +1470,7 @@ class HomeAssistantClient:
     # Automation Configuration Management
 
     async def _resolve_automation_id(self, identifier: str) -> str:
-        """
-        Convert entity_id to unique_id if needed, or return unique_id as-is.
+        """Convert entity_id to unique_id if needed, or return unique_id as-is.
 
         Args:
             identifier: Either entity_id (automation.xxx) or unique_id
@@ -1479,9 +1479,8 @@ class HomeAssistantClient:
             The unique_id for configuration API
 
         Raises:
-            HomeAssistantAPIError: If automation not found
+            HomeAssistantAPIError: 404 if not found; other read failures propagate
         """
-        # If it looks like an entity_id, convert to unique_id
         if identifier.startswith("automation."):
             try:
                 state = await self.get_entity_state(identifier)
@@ -1495,7 +1494,9 @@ class HomeAssistantClient:
                     f"Converted entity_id {identifier} to unique_id {unique_id}"
                 )
                 return str(unique_id)
-            except HomeAssistantError as e:
+            except HomeAssistantAPIError as e:
+                if e.status_code != 404:  # a failed read is not a missing one
+                    raise
                 raise HomeAssistantAPIError(
                     f"Failed to resolve automation {identifier}: {str(e)}",
                     status_code=404,
@@ -1505,8 +1506,7 @@ class HomeAssistantClient:
             return identifier
 
     async def get_automation_config(self, identifier: str) -> dict[str, Any]:
-        """
-        Get automation configuration by unique_id or entity_id.
+        """Get automation configuration by unique_id or entity_id.
 
         Args:
             identifier: Either automation entity_id (automation.xxx) or unique_id

{ha_mcp_dev-8.6.0.dev3006 → ha_mcp_dev-8.6.0.dev3007}/src/ha_mcp/client/websocket_client.py

@@ -27,6 +27,7 @@ import anyio
 # it in place (#2135/#2146). The private copy is immune, and CI tests
 # exactly the version production runs.
 from .._vendor import websockets
+from .._vendor.websockets.exceptions import ConnectionClosed
 from ..config import get_global_settings
 from .rest_client import (
     HomeAssistantAuthError,
@@ -580,7 +581,7 @@ class HomeAssistantWebSocketClient:
                     logger.error(f"Invalid JSON received: {e}")
                 except Exception as e:  # noqa: BLE001
                     logger.error(f"Error processing message: {e}")
-        except websockets.exceptions.ConnectionClosed as e:
+        except ConnectionClosed as e:
             # Prefer the frame we received (the peer closed on us); fall
             # back to the frame we sent (we failed the connection
             # ourselves, e.g. an over-max_size frame produces a sent
@@ -1025,16 +1026,15 @@ class HomeAssistantWebSocketClient:
 
         Exception policy (narrow, distinct log levels — Gemini #1382):
 
-        - Transport-level loss (``OSError``): subscription is implicitly
-          gone with the connection. Logged at ``debug`` so HA-mid-restart
-          cleanup doesn't spam warnings.
+        - Transport-level loss (``OSError``, ``ConnectionClosed``,
+          ``HomeAssistantConnectionError``): the socket closed during the send
+          or before the answer, and the subscription went with it. Logged at
+          ``debug`` so HA-mid-restart cleanup doesn't spam warnings.
         - HA-side rejection (``HomeAssistantCommandError``, e.g. "Subscription
-          not found" after a server-side reset): unexpected during normal
-          cleanup. Logged at ``warning`` so a real subscription leak is
-          discoverable.
-        - Everything else: propagates to the caller's ``finally`` so a
-          programming bug (TypeError, AttributeError) fails loudly instead
-          of being buried under a broad ``except``.
+          not found" after a server-side reset): logged at ``warning`` so a
+          real subscription leak is discoverable.
+        - Everything else, a timeout or a programming bug (TypeError),
+          propagates to the caller's ``finally`` instead of a broad ``except``.
         """
         if not self._state.is_ready:
             logger.debug(
@@ -1044,7 +1044,7 @@ class HomeAssistantWebSocketClient:
             return
         try:
             await self.send_command("unsubscribe_events", subscription=subscription_id)
-        except OSError as e:
+        except (OSError, ConnectionClosed, HomeAssistantConnectionError) as e:
             logger.debug(
                 "unsubscribe_events(%s): transport lost during cleanup: %s",
                 subscription_id,
@@ -1308,7 +1308,7 @@ class HomeAssistantWebSocketClient:
             (
                 HomeAssistantConnectionError,
                 HomeAssistantCommandTimeout,
-                websockets.exceptions.ConnectionClosed,
+                ConnectionClosed,
             ),
         ):
             logger.debug("Background subscription release failed: %s", error)
@@ -1354,7 +1354,7 @@ class HomeAssistantWebSocketClient:
             return
         try:
             await self.send_command(unsubscribe_type, subscription=subscription_id)
-        except OSError as e:
+        except (OSError, ConnectionClosed, HomeAssistantConnectionError) as e:
             logger.debug(
                 "unsubscribe_command(%s): transport lost during cleanup: %s",
                 subscription_id,

{ha_mcp_dev-8.6.0.dev3006 → ha_mcp_dev-8.6.0.dev3007}/src/ha_mcp/server_tool_text.py

@@ -99,7 +99,7 @@ SEARCH_KEYWORDS: dict[str, str] = {
         "conditions actions get show detail"
     ),
     # s09: "create helper" → ha_config_set_helper should outrank remove_helper
-    # Covers all 29 helper types (12 simple + 17 flow-based, unified in #967).
+    # Covers the storage types and Core's common helper flows (unified in #967).
     "ha_config_set_helper": (
         "create update new add helper "
         "input_boolean input_button input_number input_text input_datetime "

{ha_mcp_dev-8.6.0.dev3006 → ha_mcp_dev-8.6.0.dev3007}/src/ha_mcp/settings_ui/_handlers_backups.py

@@ -208,6 +208,7 @@ async def _restore_backup(
             "invalid_snapshot": ErrorCode.VALIDATION_INVALID_PARAMETER,
             "unsupported_domain": ErrorCode.VALIDATION_INVALID_PARAMETER,
             "backup_capture_failed": ErrorCode.BACKUP_CAPTURE_FAILED,
+            "entry_deleted": ErrorCode.RESOURCE_NOT_FOUND,
         }.get(err.outcome.get("reason") or "", ErrorCode.SERVICE_CALL_FAILED)
         return JSONResponse(
             create_error_response(
@@ -231,11 +232,12 @@ async def _restore_backup(
             }.get(code, 409),
         )
     except MandatoryBackupError as err:
+        logger.warning("Restore of %s blocked: %s", name, err.safe_cause)
         return JSONResponse(
             create_error_response(
                 ErrorCode.BACKUP_CAPTURE_FAILED,
-                "Restore blocked: the pre-restore safety snapshot could not "
-                "be captured. Nothing was changed.",
+                "Restore blocked: the pre-restore safety snapshot could not be "
+                f"captured ({err.safe_cause}). Nothing was changed.",
                 suggestions=err.suggestions,
                 context={
                     "data": {