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

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

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

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

@@ -65,8 +65,8 @@ class OAuthProxyClient:
         self._oauth_clients: dict[str, HomeAssistantClient] = {}
         self._lock = threading.Lock()
 
-    def _get_oauth_client(self) -> "HomeAssistantClient":
-        """Get the OAuth client for the current request context."""
+    def current_client(self) -> "HomeAssistantClient":
+        """The requesting user's client; per-user caches key on it, not the proxy."""
         from ha_mcp._vendor.fastmcp.server.dependencies import get_access_token
         from ha_mcp.client.rest_client import (
             HomeAssistantAuthError,
@@ -116,7 +116,7 @@ class OAuthProxyClient:
 
     def __getattr__(self, name: str) -> Any:
         """Forward all attribute access to the OAuth client."""
-        client = self._get_oauth_client()
+        client = self.current_client()
         return getattr(client, name)
 
 

ha_mcp_dev-9.1.1.dev3374/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.dev3374}/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.dev3374/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.dev3374}/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.