ha-mcp-dev 9.1.1.dev3368__tar.gz → 9.1.1.dev3370__tar.gz

{ha_mcp_dev-9.1.1.dev3368 → ha_mcp_dev-9.1.1.dev3370}/PKG-INFO

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

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

{ha_mcp_dev-9.1.1.dev3368 → ha_mcp_dev-9.1.1.dev3370}/pyproject.toml.orig

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

@@ -0,0 +1,209 @@
+"""Auto-backup handlers for integration config entries.
+
+A snapshot holds the entry's Core row, its enabled state and, read through the
+ha_mcp_tools component, its options. Options are kept only when the component
+could scrub them and they hold no redaction placeholder; otherwise
+``options_unavailable`` says why. ``entry.data`` (credentials) is never read,
+and neither are subentries: ha_set_integration does not edit them, and Core
+has no API to put a subentry's data back under a deleted entry.
+
+A restore refuses a deleted entry rather than sending Core a command for an
+entry it no longer has. Otherwise it enables the entry first when the snapshot
+was enabled, so the options flow runs on a loaded entry, puts back options that
+differ through the options flow and reads them back, then applies the enabled
+state. Options it cannot put back (the snapshot has none, or empty ones an
+options flow cannot produce) fail the restore after the enabled state is set.
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import TYPE_CHECKING, Any
+
+from .backup_entity_ids import _manager
+
+if TYPE_CHECKING:
+    from .backup_manager import BackupRestoreError
+
+
+async def fetch_integration(client: Any, entity_id: str) -> Any:
+    from .redaction import placeholder_option_keys
+    from .tools import component_config_entries
+    from .tools.component_api import component_supports, get_component_caps
+
+    bm = _manager()
+    read = await component_config_entries.fetch_config_entries(
+        client, entry_id=entity_id
+    )
+    if read is None:
+        # An installed component whose command failed is not a missing one.
+        caps = await get_component_caps(client)
+        why = (
+            "component_read_failed"
+            if component_supports(caps, "config_entries")
+            else "component_unavailable"
+        )
+        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, "options_unavailable": why}
+        return None
+    if not read.rows:
+        return None
+    row = {key: value for key, value in read.rows[0].items() if key != "subentries"}
+    options = row.pop("options", None)
+    if not isinstance(options, dict):
+        row["options_unavailable"] = "options_missing"
+    elif read.secret_scrub_degraded:
+        row["options_unavailable"] = "secret_scrub_degraded"
+    elif placeholder_option_keys(options):
+        row["options_unavailable"] = "redacted_options"
+    else:
+        row["options"] = options
+    return row
+
+
+async def _read_options(client: Any, entry_id: str) -> Any:
+    # Options the component can no longer read safely leave the restore
+    # unverified rather than failing it as a mismatch.
+    from .client.rest_client import HomeAssistantError
+
+    row = await fetch_integration(client, entry_id)
+    if row is not None and "options" not in row:
+        raise HomeAssistantError(f"options unreadable: {row['options_unavailable']}")
+    return row
+
+
+async def _set_disabled_by(client: Any, entry_id: str, disabled_by: Any) -> Any:
+    return await _manager()._ws_send(
+        client,
+        {
+            "type": "config_entries/disable",
+            "entry_id": entry_id,
+            "disabled_by": disabled_by,
+        },
+    )
+
+
+async def restore_integration(client: Any, entity_id: str, config: Any) -> Any:
+    bm = _manager()
+    current = await fetch_integration(client, entity_id)
+    if current 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, options 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."
+            ],
+        )
+    options = config.get("options")
+    if "options" in config and not isinstance(options, dict):
+        raise bm.BackupRestoreError(
+            "The integration snapshot's options are not an object. Nothing was "
+            "changed.",
+            reason="invalid_snapshot",
+        )
+    if options is not None and "options" not in current:
+        raise bm.BackupRestoreError(
+            f"The current options of config entry {entity_id} cannot be read "
+            f"({current.get('options_unavailable')}), so the snapshot's options "
+            "cannot be checked against them. Nothing was changed.",
+            reason="options_unreadable",
+        )
+    not_restored = _options_not_restored(config, current)
+    disabled_by = None if config.get("disabled_by") is None else "user"
+    enable_first = disabled_by is None and current.get("disabled_by") is not None
+    if enable_first:
+        result = await _set_disabled_by(client, entity_id, None)
+    if (
+        not_restored is None
+        and options is not None
+        and not bm._snapshot_configs_match(options, current["options"])
+    ):
+        try:
+            await _restore_options(client, entity_id, config, current["options"])
+        except bm.BackupRestoreError as err:
+            if not enable_first:
+                raise
+            raise _enabled_then_failed(entity_id, err) from err
+    if not enable_first:
+        result = await _set_disabled_by(client, entity_id, disabled_by)
+    if not_restored is not None:
+        verification_status, why = not_restored
+        raise bm.BackupRestoreError(
+            f"The enabled state of config entry {entity_id} was restored, but "
+            f"its options were not: {why}.",
+            apply_status="applied",
+            verification_status=verification_status,
+            reason="options_not_restored",
+        )
+    return result
+
+
+def _enabled_then_failed(entity_id: str, err: BackupRestoreError) -> BackupRestoreError:
+    """``err`` from the options restore of an entry the restore enabled first."""
+    if err.outcome["apply_status"] != "not_applied":
+        detail = f"then its options restore failed: {err}"
+    elif err.outcome.get("reason"):
+        detail = f"but its options were not restored: {err}"
+    else:
+        detail = "but its options were not restored: the options flow refused them"
+    failed: BackupRestoreError = _manager().BackupRestoreError(
+        f"Config entry {entity_id} was enabled, {detail}",
+        # The enable applied; the options restore keeps its own status.
+        **{
+            **err.outcome,
+            "apply_status": "applied",
+            "options_apply_status": err.outcome["apply_status"],
+        },
+    )
+    return failed
+
+
+def _options_not_restored(
+    config: Any, current: dict[str, Any]
+) -> tuple[str, str] | None:
+    """``(verification_status, why)`` for options a restore cannot put back."""
+    if "options_unavailable" in config or "options" not in config:
+        why = config.get("options_unavailable", "taken before options were captured")
+        return ("unavailable", f"the snapshot holds none ({why})")
+    if config.get("options") == {} and current["options"]:
+        return (
+            "mismatched",
+            "the snapshot's are empty, which an options flow cannot produce",
+        )
+    return None
+
+
+async def _restore_options(
+    client: Any, entity_id: str, config: Any, current_options: dict[str, Any]
+) -> None:
+    from .tools.config_entry_flow import update_config_entry_options
+
+    bm = _manager()
+    options = config["options"]
+    await bm._apply_and_verify(
+        f"{config.get('domain')} integration",
+        partial(
+            update_config_entry_options,
+            client,
+            entity_id,
+            options,
+            expected_domain=config.get("domain"),
+            keep_current_values=False,
+            fixed_options=current_options,
+        ),
+        partial(
+            bm._verify_readback,
+            partial(_read_options, client, entity_id),
+            {"options": options},
+            ("options",),
+        ),
+    )

{ha_mcp_dev-9.1.1.dev3368 → ha_mcp_dev-9.1.1.dev3370}/src/ha_mcp/backup_manager.py

@@ -54,7 +54,7 @@ import time
 import weakref
 from collections import Counter
 from collections.abc import AsyncIterator, Awaitable, Callable
-from contextlib import asynccontextmanager, suppress
+from contextlib import asynccontextmanager, nullcontext, suppress
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from functools import cached_property, partial
@@ -275,6 +275,15 @@ class _FlowHelperBackupSkip(_FlowHelperReadError):
     lists. Best-effort capture logs it at INFO."""
 
 
+def _restore_is_flow_driven(domain: str) -> bool:
+    """A snapshot domain whose restore drives a Core flow, which can apply it
+    partly: a flow helper, a config subentry or an integration entry."""
+    return _is_flow_helper_domain(domain) or domain in (
+        "helper_config_subentry",
+        "integration",
+    )
+
+
 def _is_flow_helper_domain(domain: str) -> bool:
     """A ``helper_<type>`` snapshot domain of a config-entry (flow) helper.
 
@@ -1514,18 +1523,17 @@ class BackupManager:
                         safety_backup=None,
                     ) from err
                 data["entity_id"] = entity_id
-                async with self.config_entry_write_guard(entity_id, exclusive=True):
-                    return await self._restore_snapshot_data(
-                        name, data, take_safety_backup=take_safety_backup
-                    )
-            if data["domain"] == "entity":
-                async with restore_locks(self._client, data["config"]):
-                    return await self._restore_snapshot_data(
-                        name, data, take_safety_backup=take_safety_backup
-                    )
-            return await self._restore_snapshot_data(
-                name, data, take_safety_backup=take_safety_backup
-            )
+                guard: Any = self.config_entry_write_guard(entity_id, exclusive=True)
+            elif data["domain"] == "entity":
+                guard = restore_locks(self._client, data["config"])
+            elif data["domain"] == "integration":  # its restore drives an options flow
+                guard = self.config_entry_write_guard(data["entity_id"])
+            else:
+                guard = nullcontext()
+            async with guard:
+                return await self._restore_snapshot_data(
+                    name, data, take_safety_backup=take_safety_backup
+                )
         finally:
             self._unprotect_snapshot(name)
 
@@ -1567,11 +1575,10 @@ class BackupManager:
         step = "safety_preflight"
         try:
             needs_safety = await self._restore_needs_safety(handler, entity_id, config)
-            # Existing flow helpers and subentries always require a fresh
-            # recovery point: their flows can apply a restore partly.
-            is_flow = _is_flow_helper_domain(domain)
-            flow_driven = is_flow or domain == "helper_config_subentry"
-            if needs_safety and (flow_driven or take_safety_backup):
+            # Existing flow helpers, subentries and integration entries always
+            # require a fresh recovery point: their flows can apply a restore
+            # partly.
+            if needs_safety and (_restore_is_flow_driven(domain) or take_safety_backup):
                 step = "safety_backup"
                 safety_path = await self._capture_restore_safety(
                     domain, entity_id, outcome, config
@@ -1643,7 +1650,7 @@ class BackupManager:
     ) -> Path | None:
         """Take a restore's recovery point; a failed capture raises and blocks it."""
         is_flow = _is_flow_helper_domain(domain)
-        flow_driven = is_flow or domain == "helper_config_subentry"
+        flow_driven = _restore_is_flow_driven(domain)
         if not flow_driven and not getattr(self._settings, "enable_auto_backup", False):
             return None  # auto-backup off: no safety backup is promised
         # The restore overwrites the current state, so the throttle that a
@@ -2780,7 +2787,7 @@ def _flow_label(helper_type: str) -> str:
 
 def _flow_options(config: Any, helper_type: str) -> dict[str, Any]:
     """Require persisted flow-helper options that can safely be restored."""
-    from .redaction import sentinel_option_keys
+    from .redaction import placeholder_option_keys
 
     label = _flow_label(helper_type)
     if not isinstance(config, dict):
@@ -2792,9 +2799,9 @@ def _flow_options(config: Any, helper_type: str) -> dict[str, Any]:
             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.
-    if sentinel_option_keys(config) or _contains_redacted_leaf(config):
+    # Neither a server sentinel nor the component's scrub is a usable
+    # recovery value.
+    if placeholder_option_keys(config):
         raise _FlowHelperReadError(
             f"{label} helper options contain redacted values; capture is incomplete",
             "redacted_options",
@@ -2802,14 +2809,6 @@ def _flow_options(config: Any, helper_type: str) -> dict[str, Any]:
     return config
 
 
-def _contains_redacted_leaf(value: Any) -> bool:
-    if isinstance(value, dict):
-        return any(_contains_redacted_leaf(item) for item in value.values())
-    if isinstance(value, list):
-        return any(_contains_redacted_leaf(item) for item in value)
-    return isinstance(value, str) and value == "**redacted**"
-
-
 async def _fetch_flow_helper(client: Any, entity_id: str, helper_type: str) -> Any:
     """Read a flow helper's options through the component, without starting a flow.
 
@@ -3309,13 +3308,13 @@ def _subentry_target(entity_id: str) -> tuple[str, str]:
 
 
 def _subentry_data(data: Any) -> dict[str, Any]:
-    from .redaction import sentinel_option_keys
+    from .redaction import placeholder_option_keys
 
     if not isinstance(data, dict):
         raise _FlowHelperReadError(
             "Config subentry data must be an object", "invalid_data"
         )
-    if sentinel_option_keys(data) or _contains_redacted_leaf(data):
+    if placeholder_option_keys(data):
         raise _FlowHelperReadError(
             "Config subentry data contains redacted values; capture is incomplete",
             "redacted_data",

ha_mcp_dev-9.1.1.dev3370/src/ha_mcp/client/config_entry_read.py

@@ -0,0 +1,56 @@
+"""The read behind :meth:`HomeAssistantClient.get_config_entry`.
+
+Core's WebSocket ``config_entries/get_single`` answers ``{"config_entry":
+fragment}`` or ``not_found``. Core has no REST read for one entry, so its REST
+list is the fallback when no WebSocket answer comes back, or when the token's
+user is not an admin (``get_single`` is admin-only, the REST list is not).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from .rest_client import HomeAssistantAPIError, HomeAssistantConnectionError
+
+if TYPE_CHECKING:
+    from .rest_client import HomeAssistantClient
+
+logger = logging.getLogger(__name__)
+
+
+async def read_config_entry(
+    client: HomeAssistantClient, entry_id: str
+) -> dict[str, Any]:
+    reply: dict[str, Any] | None = None
+    try:
+        reply = await client.send_websocket_message(
+            {"type": "config_entries/get_single", "entry_id": entry_id},
+            expected_error_codes=frozenset({"not_found", "unauthorized"}),
+        )
+    except HomeAssistantConnectionError as e:
+        logger.debug(f"config_entries/get_single unanswered, using REST: {e}")
+    found: dict[str, Any] | None = None
+    if reply is None or reply.get("error_code") == "unauthorized":
+        entries = await client.list_config_entries()
+        found = next((e for e in entries if e.get("entry_id") == entry_id), None)
+    elif reply.get("success"):
+        result = reply.get("result")
+        found = result.get("config_entry") if isinstance(result, dict) else None
+        if not isinstance(found, dict):
+            # Core answered, so this is not a missing entry: no 404, no REST.
+            raise HomeAssistantAPIError(
+                f"config_entries/get_single answered without a config entry: {result!r}",
+                response_data=reply,
+            )
+    elif reply.get("error_code") != "not_found":
+        raise HomeAssistantAPIError(
+            f"config_entries/get_single failed: {reply.get('error')}",
+            response_data=reply,
+        )
+    if found is None:
+        raise HomeAssistantAPIError(
+            f"Config entry not found: {entry_id}",
+            status_code=404,
+        )
+    return found

{ha_mcp_dev-9.1.1.dev3368 → ha_mcp_dev-9.1.1.dev3370}/src/ha_mcp/client/rest_client.py

@@ -1878,14 +1878,7 @@ class HomeAssistantClient:
         return await self._list_registry("config/device_registry/list", "device")
 
     async def get_config_entry(self, entry_id: str) -> dict[str, Any]:
-        """
-        Get config entry details.
-
-        Note: Home Assistant doesn't have a direct REST API endpoint for individual
-        config entries. This method lists all entries and filters by entry_id.
-
-        Args:
-            entry_id: Config entry ID
+        """Get one config entry; see :mod:`.config_entry_read` for the routes.
 
         Returns:
             Home Assistant's config-entry fragment (``ConfigEntry.as_json_fragment``):
@@ -1893,19 +1886,11 @@ class HomeAssistantClient:
             entry's connection settings and credentials are not in it.
 
         Raises:
-            HomeAssistantAPIError: If entry not found or API error
+            HomeAssistantAPIError: 404 if not found; Core's other errors
         """
-        logger.debug(f"Getting config entry: {entry_id}")
-        entries = await self.list_config_entries()
-        found: dict[str, Any] | None = next(
-            (entry for entry in entries if entry.get("entry_id") == entry_id), None
-        )
-        if found is None:
-            raise HomeAssistantAPIError(
-                f"Config entry not found: {entry_id}",
-                status_code=404,
-            )
-        return found
+        from .config_entry_read import read_config_entry
+
+        return await read_config_entry(self, entry_id)
 
     async def delete_config_entry(self, entry_id: str) -> dict[str, Any]:
         """Delete a config entry via REST API.
@@ -1927,9 +1912,17 @@ class HomeAssistantClient:
         logger.debug(f"Deleting config entry: {entry_id}")
         return await self._request("DELETE", f"/config/config_entries/entry/{entry_id}")
 
-    async def send_websocket_message(self, message: dict[str, Any]) -> dict[str, Any]:
+    async def send_websocket_message(
+        self,
+        message: dict[str, Any],
+        *,
+        expected_error_codes: frozenset[str] = frozenset(),
+    ) -> dict[str, Any]:
         """Send message via WebSocket and wait for response.
 
+        A Home Assistant error whose code is in ``expected_error_codes`` is an
+        answer the caller handles, so it is logged at debug, not error.
+
         Uses a per-client WebSocket connection keyed to the client's own
         credentials (base_url + token). This ensures OAuth mode uses the
         real HA credentials from the token claims, not the global sentinel
@@ -2036,7 +2029,11 @@ class HomeAssistantClient:
                 # Name the command in the log line: a bare "Command failed:
                 # Unknown command." is undiagnosable from a user's log
                 # (issue #1889 took a live reproduction to attribute).
-                logger.error(f"WebSocket message failed ({message.get('type')}): {e}")
+                code = getattr(e, "code", None)
+                logger.log(
+                    logging.DEBUG if code in expected_error_codes else logging.ERROR,
+                    f"WebSocket message failed ({message.get('type')}): {e}",
+                )
                 # Preserve HA's structured error code (e.g. ``not_found``) so callers
                 # can distinguish HA's authoritative verdict from a transient failure
                 # instead of only seeing the stringified message.

{ha_mcp_dev-9.1.1.dev3368 → ha_mcp_dev-9.1.1.dev3370}/src/ha_mcp/redaction.py

@@ -14,7 +14,10 @@ surfaces stop returning operator secrets verbatim:
 2. **Integration options** (``ha_get_integration``): fields the
    options-flow schema marks with a password text selector are replaced the
    same way, on both the harvested options and the ``include_schema=True``
-   schema echo (whose ``suggested_value`` carries the live value).
+   fields (whose current value comes from the form's ``suggested_value``).
+   Stored option values are checked against the flow's first form only,
+   so a password field that only a later form declares is not detected
+   in them.
 3. **Every other tool response**: secret values seen while serving 1 and 2
    are remembered in a process-local known-secrets set, and
    :class:`RedactSecretsMiddleware` (registered just outside the
@@ -24,7 +27,8 @@ surfaces stop returning operator secrets verbatim:
 The set/empty sentinel split keeps the genuinely useful diagnostic — "is
 this credential configured at all?" — answerable without disclosing the
 value. ``ha_manage_app`` and the config-entry flow writes reject
-submitted values that are (or contain) a sentinel — unconditionally, not
+submitted values that are (or contain) a sentinel, and the flow writes also
+reject the component's ``**redacted**`` placeholder — unconditionally, not
 only while the flag is on — so a redacted marker can never be round-tripped
 into a live config (add-on writes still merge from the real, unredacted
 current options server-side).
@@ -41,7 +45,7 @@ import json
 import logging
 import re
 import threading
-from collections.abc import Iterable, Sequence
+from collections.abc import Callable, Iterable, Sequence
 from typing import Any
 
 from ha_mcp._vendor.fastmcp.server.middleware.middleware import (
@@ -397,34 +401,61 @@ def _collect_stored(value: Any, listed: frozenset[str], secret: bool) -> set[str
     return known_values_for_option_item(value) if secret else set()
 
 
-def sentinel_option_keys(options: Any, _prefix: str = "") -> list[str]:
+def sentinel_option_keys(options: Any) -> list[str]:
     """Dotted paths of submitted option values that equal a redaction sentinel.
 
     Used by ``ha_manage_app`` config mode to reject round-tripping a
     redacted read back into a live add-on config.
     """
+    return _matching_option_keys(options, carries_sentinel)
+
+
+#: What the ha_mcp_tools component writes over an option value equal to a
+#: ``secrets.yaml`` entry. Like a sentinel, it is no usable value to write.
+_COMPONENT_REDACTED = "**redacted**"
+
+
+def _is_placeholder(value: Any) -> bool:
+    return carries_sentinel(value) or value == _COMPONENT_REDACTED
+
+
+def placeholder_option_keys(options: Any) -> list[str]:
+    """Dotted paths of option values that are a redaction sentinel or the
+    component's ``**redacted**`` scrub.
+
+    For config-entry options, which the component may have served.
+    """
+    return _matching_option_keys(options, _is_placeholder)
+
+
+def _matching_option_keys(
+    options: Any, match: Callable[[Any], bool], prefix: str = ""
+) -> list[str]:
+    """Dotted paths of the values in an options dict that ``match`` accepts."""
     keys: list[str] = []
     if not isinstance(options, dict):
         return keys
     for name, value in options.items():
-        path = f"{_prefix}.{name}" if _prefix else str(name)
-        _collect_sentinel_paths(value, path, keys)
+        path = f"{prefix}.{name}" if prefix else str(name)
+        _collect_matching_paths(value, path, keys, match)
     return keys
 
 
-def _collect_sentinel_paths(value: Any, path: str, keys: list[str]) -> None:
-    """Append ``path`` (or deeper paths) for every sentinel-carrying value.
+def _collect_matching_paths(
+    value: Any, path: str, keys: list[str], match: Callable[[Any], bool]
+) -> None:
+    """Append ``path`` (or deeper paths) for every value ``match`` accepts.
 
-    Recurses through dicts AND lists at any nesting depth so a sentinel at
+    Recurses through dicts AND lists at any nesting depth so a marker at
     e.g. ``opt[0][0]`` cannot slip past the write guard.
     """
-    if carries_sentinel(value):
+    if match(value):
         keys.append(path)
     elif isinstance(value, dict):
-        keys.extend(sentinel_option_keys(value, path))
+        keys.extend(_matching_option_keys(value, match, path))
     elif isinstance(value, list):
         for idx, item in enumerate(value):
-            _collect_sentinel_paths(item, f"{path}[{idx}]", keys)
+            _collect_matching_paths(item, f"{path}[{idx}]", keys, match)
 
 
 # ---------------------------------------------------------------------------
@@ -455,7 +486,8 @@ def redact_flow_schema(data_schema: Any) -> Any:
 
     HA injects the persisted option into each field's
     ``description.suggested_value`` (and static defaults into ``default`` /
-    ``value``), so an ``include_schema=True`` echo carries the live secret.
+    ``value``), so a schema handed back to a caller (a describe's fields, a
+    form-error response) would carry the live secret.
     Harvests each replaced value into the known-secrets set first.
     """
     if not isinstance(data_schema, list):
@@ -631,6 +663,13 @@ def scrub_obj(obj: Any, secrets: Sequence[str]) -> Any:
     return obj
 
 
+def scrub_known_secrets(text: str) -> str:
+    """``text`` with every known secret value replaced, while the flag is on."""
+    if not redaction_enabled():
+        return text
+    return scrub_text(text, with_serialized_variants(known_secret_values()))
+
+
 class RedactSecretsMiddleware(Middleware):
     """Scrub known secret values from every tool response and tool error.
 

{ha_mcp_dev-9.1.1.dev3368 → ha_mcp_dev-9.1.1.dev3370}/src/ha_mcp/tools/backup.py

@@ -89,7 +89,7 @@ def register_backup_tools(
 | `edits` | `list` | List per-entity auto-backups (lightweight). Filter by `domain` and/or `entity_id`. |
 | `edits` | `view` | Read one auto-backup file by name; returns YAML and parsed `config`. |
 | `edits` | `diff` | Compare one auto-backup against the entity's current config. RFC 6902 JSON-Patch + add/remove/replace counts; bounded output. Read-only — fetches the live config, makes no changes. |
-| `edits` | `restore` | Re-apply one auto-backup. Existing flow helpers (template, group, utility_meter, …) and config subentries require a fresh per-entity backup; other domains follow auto-backup settings and may proceed without one. A deleted flow helper is recreated with a new config-entry ID and its saved entity IDs are restored if unoccupied; a deleted subentry is recreated with a new subentry ID. A deleted integration config entry cannot be recreated: its snapshot holds only metadata and the enabled state. **No HA restart.** |
+| `edits` | `restore` | Re-apply one auto-backup. Existing flow helpers (template, group, utility_meter, …), config subentries and integration config entries require a fresh per-entity backup; other domains follow auto-backup settings and may proceed without one. A deleted flow helper is recreated with a new config-entry ID and its saved entity IDs are restored if unoccupied; a deleted subentry is recreated with a new subentry ID. An integration config entry's snapshot holds its metadata, its enabled state and its options, which are kept only when the ha_mcp_tools component serves the read, its `secrets.yaml` scrub ran, and no value is a redaction placeholder; a restore re-enables the entry first when needed, then puts back differing options through its options flow, and reports options it cannot put back (none kept, or empty ones) as not restored. It holds neither the entry's data nor its subentries, so a deleted integration config entry cannot be recreated. **No HA restart.** |
 | `edits` | `delete` | Delete one auto-backup by `backup_name`, or bulk-delete by filter. |
 
 **When to use which scope:**