ha-mcp-dev 7.13.0.dev1977__tar.gz → 7.13.0.dev1983__tar.gz

{ha_mcp_dev-7.13.0.dev1977/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.13.0.dev1983}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.13.0.dev1977"
+version = "7.13.0.dev1983"
 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.13.0.dev1977 → ha_mcp_dev-7.13.0.dev1983}/src/ha_mcp/config.py

@@ -836,7 +836,7 @@ ADVANCED_SETTINGS_FIELDS: tuple[AdvancedField, ...] = (
     AdvancedField("enable_websocket", "ENABLE_WEBSOCKET", bool, "operations", True),
     # Dashboard-screenshot engine URL (#1538): docker/.env users could set
     # HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL, but add-on users had no path to
-    # it. It is resolved live per capture (resolve_engine_url), so unlike the
+    # it. It is resolved live per capture (resolve_engine), so unlike the
     # time budgets it takes effect without a restart. Blank = auto-discover
     # the Puppet add-on via the Supervisor.
     AdvancedField(

{ha_mcp_dev-7.13.0.dev1977 → ha_mcp_dev-7.13.0.dev1983}/src/ha_mcp/dashboard_screenshot/__init__.py

@@ -19,7 +19,8 @@ from .capture import (
     DashboardImageCapture,
     capture_dashboard_images,
 )
-from .provision import resolve_engine_url
+from .provision import EngineTarget, resolve_engine
+from .theme_guard import EngineCredential, ThemeGuard
 
 __all__ = [
     "DEFAULT_HEIGHT",
@@ -27,6 +28,9 @@ __all__ = [
     "DEFAULT_WAIT_MS",
     "DEFAULT_WIDTH",
     "DashboardImageCapture",
+    "EngineCredential",
+    "EngineTarget",
+    "ThemeGuard",
     "capture_dashboard_images",
-    "resolve_engine_url",
+    "resolve_engine",
 ]

{ha_mcp_dev-7.13.0.dev1977 → ha_mcp_dev-7.13.0.dev1983}/src/ha_mcp/dashboard_screenshot/capture.py

@@ -2,8 +2,11 @@
 
 The engine (balloob's Puppet add-on, or a docker-compose sidecar)
 authenticates to Home Assistant with its OWN configured long-lived token, so
-this client passes only the dashboard path + render parameters — no HA token
-ever flows through ha-mcp or the LLM for screenshots.
+this client passes only the dashboard path + render parameters to the engine
+— no HA token is ever sent to the engine or exposed to the LLM. The
+:mod:`theme_guard` bracket around each capture batch may hold the engine's
+token in server memory to restore the engine user's saved theme (issue
+#1909); see that module's docstring for the containment rules.
 """
 
 from __future__ import annotations
@@ -20,7 +23,8 @@ from fastmcp.exceptions import ToolError
 
 from ..errors import ErrorCode, create_error_response
 from ..tools.helpers import raise_tool_error
-from .provision import TOKEN_HINT, resolve_engine_url
+from .provision import TOKEN_HINT, resolve_engine
+from .theme_guard import ThemeGuard
 
 logger = logging.getLogger(__name__)
 
@@ -757,9 +761,30 @@ async def _request_or_collect_failure(
         return None
 
 
+def _viewport_params(
+    options: _CaptureOptions, viewport: _ViewportRequest
+) -> dict[str, str]:
+    """Build one viewport's engine query parameters."""
+    params: dict[str, str] = {
+        "viewport": f"{viewport.width}x{viewport.height}",
+        "zoom": str(options.zoom),
+        "wait": str(options.wait_ms),
+        "format": options.image_format,
+    }
+    if options.theme is not None:
+        params["theme"] = options.theme
+    if options.dark_mode:
+        # Puppet checks only for query-key presence.
+        params["dark"] = ""
+    if options.language is not None:
+        params["lang"] = options.language
+    return params
+
+
 def _complete_capture_batch(
     captures: list[DashboardImageCapture],
     partial_failures: list[dict[str, Any]] | None,
+    guard_warnings: list[str],
 ) -> list[DashboardImageCapture]:
     """Return partial successes, but raise when every requested capture failed."""
     if not captures and partial_failures:
@@ -769,10 +794,41 @@ def _complete_capture_batch(
             "failure_count": len(partial_failures),
             "screenshot_failures": partial_failures,
         }
+        if guard_warnings:
+            aggregate_failure["warnings"] = [
+                *aggregate_failure.get("warnings", []),
+                *guard_warnings,
+            ]
         raise_tool_error(aggregate_failure)
     return captures
 
 
+def _reraise_with_guard_warnings(error: ToolError, warnings: list[str]) -> NoReturn:
+    """Re-raise a capture ToolError with the theme guard's warnings attached.
+
+    A batch that raises may already have rendered (and clobbered the engine
+    user's theme) before failing, so a failed restore must stay visible on
+    the error path too — otherwise the tool contract ("an attempted but
+    failed restore surfaces as a warning") silently breaks exactly when the
+    theme is most likely left flipped.
+    """
+    if not warnings:
+        raise error
+    try:
+        payload = json.loads(str(error))
+    except (json.JSONDecodeError, TypeError):
+        payload = None
+    if not isinstance(payload, dict):
+        raise error
+    existing = payload.get("warnings")
+    payload["warnings"] = [
+        *(existing if isinstance(existing, list) else []),
+        *warnings,
+    ]
+    raise_tool_error(payload)
+    raise AssertionError("unreachable: raise_tool_error always raises")
+
+
 async def capture_dashboard_images(
     dashboard_path: str,
     *,
@@ -789,6 +845,8 @@ async def capture_dashboard_images(
     image_format: ScreenshotFormat = "png",
     render_timeout_seconds: float = DEFAULT_RENDER_TIMEOUT_SECONDS,
     partial_failures: list[dict[str, Any]] | None = None,
+    client: Any | None = None,
+    capture_warnings: list[str] | None = None,
 ) -> list[DashboardImageCapture]:
     """Render one or more ordered dashboard images via the screenshot engine.
 
@@ -796,6 +854,12 @@ async def capture_dashboard_images(
     preset or custom dimensions when needed; omitting it preserves each
     preset's native orientation. ``full_page`` is a compatibility alias for
     requesting the engine's native ``WIDTHxauto`` viewport.
+
+    The batch is bracketed by a :class:`ThemeGuard` that restores the engine
+    user's saved frontend theme if rendering changed it (issue #1909).
+    ``client`` supplies the guard's non-add-on credential fallback and
+    ``capture_warnings`` collects the guard's non-fatal warnings; both are
+    optional and never affect the captures themselves.
     """
     path = _validate_dashboard_path(dashboard_path)
     options = validate_capture_parameters(
@@ -814,94 +878,102 @@ async def capture_dashboard_images(
     )
     viewports = _capture_viewports(options)
 
-    engine = await resolve_engine_url()
+    engine_target = await resolve_engine()
+    engine = engine_target.url
     url = f"{engine}/{path}"
     mime_type = _MIME_TYPES[options.image_format]
     captures: list[DashboardImageCapture] = []
 
-    async with httpx.AsyncClient(
-        timeout=httpx.Timeout(options.render_timeout_seconds)
-    ) as http_client:
-        for capture_index, viewport in enumerate(viewports):
-            params: dict[str, str] = {
-                "viewport": f"{viewport.width}x{viewport.height}",
-                "zoom": str(options.zoom),
-                "wait": str(options.wait_ms),
-                "format": options.image_format,
-            }
-            if options.theme is not None:
-                params["theme"] = options.theme
-            if options.dark_mode:
-                # Puppet checks only for query-key presence.
-                params["dark"] = ""
-            if options.language is not None:
-                params["lang"] = options.language
-
-            request_context = {
-                "path": path,
-                "preset": viewport.preset,
-                "width": viewport.width,
-                "height": viewport.height,
-                "requested_format": options.image_format,
-                "capture_index": capture_index,
-                "capture_count": len(viewports),
-                "completed_count": len(captures),
-            }
-            aggregate_bytes = sum(capture.size_bytes for capture in captures)
-            remaining_batch_bytes = MAX_BATCH_PAYLOAD_BYTES - aggregate_bytes
-            if remaining_batch_bytes <= 0:
-                assert partial_failures is not None
-                partial_failures.append(
-                    create_error_response(
-                        ErrorCode.IMAGE_PAYLOAD_TOO_LARGE,
-                        "Screenshot image batch reached the server's safe "
-                        "inline-image limit.",
-                        context={
-                            **request_context,
-                            "aggregate_bytes_before_capture": aggregate_bytes,
-                            "limit_kind": "batch",
-                            "limit_bytes": MAX_BATCH_PAYLOAD_BYTES,
-                        },
+    # The engine dispatches a theme write into the authenticated frontend on
+    # cold renders, which Home Assistant persists to the engine user's real
+    # profile (issue #1909). Snapshot before, restore after — including when
+    # the batch fails, since the engine may already have rendered (and
+    # written) before the failure.
+    guard = ThemeGuard.for_capture(engine_target.addon_credential, client)
+    await guard.take_snapshot()
+    batch_error: ToolError | None = None
+    try:
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(options.render_timeout_seconds)
+        ) as http_client:
+            for capture_index, viewport in enumerate(viewports):
+                params = _viewport_params(options, viewport)
+
+                request_context = {
+                    "path": path,
+                    "preset": viewport.preset,
+                    "width": viewport.width,
+                    "height": viewport.height,
+                    "requested_format": options.image_format,
+                    "capture_index": capture_index,
+                    "capture_count": len(viewports),
+                    "completed_count": len(captures),
+                }
+                aggregate_bytes = sum(capture.size_bytes for capture in captures)
+                remaining_batch_bytes = MAX_BATCH_PAYLOAD_BYTES - aggregate_bytes
+                if remaining_batch_bytes <= 0:
+                    assert partial_failures is not None
+                    partial_failures.append(
+                        create_error_response(
+                            ErrorCode.IMAGE_PAYLOAD_TOO_LARGE,
+                            "Screenshot image batch reached the server's safe "
+                            "inline-image limit.",
+                            context={
+                                **request_context,
+                                "aggregate_bytes_before_capture": aggregate_bytes,
+                                "limit_kind": "batch",
+                                "limit_bytes": MAX_BATCH_PAYLOAD_BYTES,
+                            },
+                        )
                     )
-                )
-                break
-
-            outcome = await _request_or_collect_failure(
-                http_client,
-                url=url,
-                path=path,
-                engine=engine,
-                params=params,
-                options=options,
-                viewport=viewport,
-                mime_type=mime_type,
-                request_context=request_context,
-                aggregate_bytes=aggregate_bytes,
-                remaining_batch_bytes=remaining_batch_bytes,
-                partial_failures=partial_failures,
-            )
-            if outcome is None:
-                if (
-                    partial_failures
-                    and partial_failures[-1].get("limit_kind") == "batch"
-                ):
                     break
-                continue
-            image_data, capture_height, fallback_used = outcome
-
-            captures.append(
-                DashboardImageCapture(
-                    data=image_data,
-                    width=viewport.width,
-                    height=capture_height,
-                    preset=viewport.preset,
-                    orientation=viewport.orientation,
-                    image_format=options.image_format,
-                    mime_type=mime_type,
-                    size_bytes=len(image_data),
+
+                outcome = await _request_or_collect_failure(
+                    http_client,
+                    url=url,
+                    path=path,
+                    engine=engine,
+                    params=params,
                     options=options,
-                    legacy_full_page_fallback=fallback_used,
+                    viewport=viewport,
+                    mime_type=mime_type,
+                    request_context=request_context,
+                    aggregate_bytes=aggregate_bytes,
+                    remaining_batch_bytes=remaining_batch_bytes,
+                    partial_failures=partial_failures,
                 )
-            )
-
-    return _complete_capture_batch(captures, partial_failures)
+                if outcome is None:
+                    if (
+                        partial_failures
+                        and partial_failures[-1].get("limit_kind") == "batch"
+                    ):
+                        break
+                    continue
+                image_data, capture_height, fallback_used = outcome
+
+                captures.append(
+                    DashboardImageCapture(
+                        data=image_data,
+                        width=viewport.width,
+                        height=capture_height,
+                        preset=viewport.preset,
+                        orientation=viewport.orientation,
+                        image_format=options.image_format,
+                        mime_type=mime_type,
+                        size_bytes=len(image_data),
+                        options=options,
+                        legacy_full_page_fallback=fallback_used,
+                    )
+                )
+    except ToolError as exc:
+        # Held (not re-raised here) so the restore in ``finally`` runs first
+        # and its outcome can be attached to the error payload below.
+        batch_error = exc
+    finally:
+        await guard.restore()
+        if capture_warnings is not None:
+            capture_warnings.extend(guard.warnings)
+
+    if batch_error is not None:
+        _reraise_with_guard_warnings(batch_error, guard.warnings)
+    return _complete_capture_batch(captures, partial_failures, guard.warnings)

{ha_mcp_dev-7.13.0.dev1977 → ha_mcp_dev-7.13.0.dev1983}/src/ha_mcp/dashboard_screenshot/provision.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 import logging
 import os
+from dataclasses import dataclass
 from typing import Any
 
 import httpx
@@ -30,9 +31,27 @@ from fastmcp.exceptions import ToolError
 
 from ..errors import ErrorCode, create_error_response
 from ..tools.helpers import raise_tool_error
+from .theme_guard import EngineCredential, addon_credential_from_options
 
 logger = logging.getLogger(__name__)
 
+
+@dataclass(frozen=True, slots=True)
+class EngineTarget:
+    """A resolved screenshot engine endpoint.
+
+    ``addon_credential`` authenticates as the engine's user (extracted from
+    the Puppet add-on's Supervisor options during discovery, so the theme
+    guard needs no second round-trip and the raw secret-bearing options
+    dict never leaves this module). It is ``None`` for an explicitly
+    configured engine URL. The token inside never leaves the server process
+    — it must not be logged or surfaced in responses.
+    """
+
+    url: str
+    addon_credential: EngineCredential | None = None
+
+
 ENGINE_PORT = 10000
 # The Supervisor slug is ``<repo-hash>_puppet`` for balloob's Puppet add-on.
 # ``str.endswith`` accepts a tuple, kept as one for easy future extension.
@@ -146,8 +165,8 @@ def _supervisor_addon_listing(payload: Any) -> list[dict[str, Any]]:
     return addons
 
 
-async def resolve_engine_url() -> str:
-    """Return the base URL of the screenshot engine, or raise ToolError.
+async def resolve_engine() -> EngineTarget:
+    """Resolve the screenshot engine endpoint, or raise ToolError.
 
     See module docstring for the three-mode resolution order.
     """
@@ -155,10 +174,13 @@ async def resolve_engine_url() -> str:
 
     explicit = (get_global_settings().dashboard_screenshot_engine_url or "").strip()
     if explicit:
-        return explicit.rstrip("/")
+        return EngineTarget(
+            url=explicit.rstrip("/"),
+            addon_credential=await _addon_credential_best_effort(),
+        )
 
     if os.environ.get("SUPERVISOR_TOKEN"):
-        return await _discover_engine_url_via_supervisor()
+        return await _discover_engine_via_supervisor()
 
     raise_tool_error(
         create_error_response(
@@ -178,8 +200,35 @@ async def resolve_engine_url() -> str:
     raise AssertionError("unreachable: raise_tool_error always raises")
 
 
-async def _discover_engine_url_via_supervisor() -> str:
-    """Find the Puppet add-on via the Supervisor and return its internal URL.
+async def _addon_credential_best_effort() -> EngineCredential | None:
+    """Best-effort theme-guard credential for an explicitly configured URL.
+
+    HA OS / Supervised users may set ``HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL``
+    to override auto-discovery while still running the Puppet add-on; without
+    its token the theme guard would go inactive exactly where the add-on
+    credential exists (``_client_credential`` refuses Supervisor-proxy auth).
+    Any failure — no Supervisor, no verified add-on, not started — simply
+    means "no credential": the explicit URL may point at a non-add-on
+    engine, so this must never raise. If the explicit URL targets a
+    different engine than the discovered add-on, the guard still only ever
+    writes back a value that the discovered add-on's own user changed
+    mid-capture, which only that add-on's renders would do — a safe no-op.
+    """
+    if not os.environ.get("SUPERVISOR_TOKEN"):
+        return None
+    try:
+        return (await _discover_engine_via_supervisor()).addon_credential
+    except Exception:
+        logger.debug(
+            "No Supervisor-discoverable engine credential for the explicit "
+            "engine URL; the theme guard stays inactive.",
+            exc_info=True,
+        )
+        return None
+
+
+async def _discover_engine_via_supervisor() -> EngineTarget:
+    """Find the Puppet add-on via the Supervisor and return its endpoint.
 
     Requires the ha-mcp add-on's ``manager`` role (already declared) for the
     read-only ``/addons`` + ``/addons/<slug>/info`` endpoints. Raises a
@@ -229,7 +278,13 @@ async def _discover_engine_url_via_supervisor() -> str:
                         context={"slug": slug},
                     )
                 )
-            return f"http://{hostname}:{ENGINE_PORT}"
+            options = data.get("options")
+            return EngineTarget(
+                url=f"http://{hostname}:{ENGINE_PORT}",
+                addon_credential=addon_credential_from_options(
+                    options if isinstance(options, dict) else None
+                ),
+            )
     except ToolError:
         raise
     except (httpx.HTTPError, KeyError, ValueError) as e: