ha-mcp-dev 9.0.1.dev3235__tar.gz → 9.1.0.dev3236__tar.gz

{ha_mcp_dev-9.0.1.dev3235 → ha_mcp_dev-9.1.0.dev3236}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.0.1.dev3235
+Version: 9.1.0.dev3236
 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.0.1.dev3235 → ha_mcp_dev-9.1.0.dev3236}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.0.1.dev3235"
+version = "9.1.0.dev3236"
 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.0.1.dev3235 → ha_mcp_dev-9.1.0.dev3236}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.0.1.dev3235"
+version = "9.1.0.dev3236"
 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.0.1.dev3235 → ha_mcp_dev-9.1.0.dev3236}/src/ha_mcp/config_settings.py

@@ -250,11 +250,11 @@ class Settings(BaseSettings):
         Setting(surface="advanced", section="operations", restart_required=True),
     ] = Field(True, alias="ENABLE_WEBSOCKET")
 
-    # Base URL of the screenshot engine (e.g. ``http://puppet:10000`` or a
-    # docker-compose sidecar). A connection string, NOT a beta toggle, so
-    # it is not a feature flag. Left blank, the
-    # provisioner auto-discovers the Puppet add-on via the Supervisor in
-    # HA OS / Supervised mode; Container / Core users set it explicitly.
+    # Base URL of the screenshot engine (e.g. ``http://puppet:10000``,
+    # ``http://wpe-screenshot-engine:8080`` or a docker-compose sidecar). A
+    # connection string, NOT a beta toggle, so it is not a feature flag. Left
+    # blank, the provisioner auto-discovers supported apps via the Supervisor
+    # in HA OS / Supervised mode; Container / Core users set it explicitly.
     # Resolved live per capture (resolve_engine), so unlike the time
     # budgets it takes effect without a restart (#1538).
     dashboard_screenshot_engine_url: Annotated[
@@ -670,9 +670,9 @@ class Settings(BaseSettings):
     # Dashboard screenshot mode — the ``ha_get_dashboard_screenshot`` tool
     # plus the ``include_screenshot`` / ``return_screenshot`` params on the
     # dashboard get/set tools. Renders responsive Lovelace images via a
-    # separate, opt-in headless-Chromium screenshot add-on (balloob's Puppet
-    # add-on, or a docker-compose sidecar). Off by default; nothing heavy is
-    # pulled unless the user enables it AND installs the engine.
+    # separate, opt-in screenshot engine app (Puppet, WPE Screenshot Engine,
+    # or a docker-compose sidecar). Off by default; nothing heavy is pulled
+    # unless the user enables it AND installs the engine.
     enable_dashboard_screenshot: Annotated[
         bool, Setting(surface="feature", beta=True, app=_DEV_FLAVOR)
     ] = Field(False, alias="HAMCP_ENABLE_DASHBOARD_SCREENSHOT")

{ha_mcp_dev-9.0.1.dev3235 → ha_mcp_dev-9.1.0.dev3236}/src/ha_mcp/dashboard_screenshot/__init__.py

@@ -1,8 +1,7 @@
 """Dashboard screenshot support (opt-in, beta).
 
-Renders Home Assistant Lovelace dashboard views via a separate,
-single-purpose headless-Chromium screenshot engine (balloob's Puppet add-on,
-or a docker-compose sidecar).
+Renders Home Assistant Lovelace dashboard views via a separate screenshot
+engine (balloob's Puppet app, WPE Screenshot Engine, or a sidecar).
 
 The heavy browser runtime lives entirely in that separate engine — this
 package is a thin async HTTP client plus deployment-mode discovery, so the

{ha_mcp_dev-9.0.1.dev3235 → ha_mcp_dev-9.1.0.dev3236}/src/ha_mcp/dashboard_screenshot/capture.py

@@ -1,8 +1,8 @@
 """Thin async HTTP client to the dashboard screenshot engine.
 
-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 to the engine
+The engine (Puppet, WPE Screenshot Engine, or a sidecar)
+authenticates to Home Assistant with its own configured long-lived token, so
+this client passes only the dashboard path and 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
@@ -24,7 +24,8 @@ from ha_mcp._vendor.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
+from .engine_compat import is_legacy_puppet
+from .provision import TOKEN_HINT, EngineKind, resolve_engine
 from .theme_guard import ThemeGuard
 
 logger = logging.getLogger(__name__)
@@ -97,9 +98,9 @@ _FORBIDDEN_PATH_BITS = ("://", "//", "..", "@", "\\", "?", "#")
 class DashboardImageCapture:
     """Image bytes plus metadata describing the render request.
 
-    Puppet returns only an image and its content type. Viewport and frontend
-    context values here therefore describe what ha-mcp requested, not values
-    independently confirmed by the rendered Home Assistant frontend.
+    Screenshot engines return only an image and its content type. Viewport and
+    frontend context values here therefore describe what ha-mcp requested, not
+    values independently confirmed by the rendered Home Assistant frontend.
     """
 
     data: bytes
@@ -536,7 +537,7 @@ async def _read_image_response(
                     "received_content_type": response_mime_type or None,
                 },
                 suggestions=[
-                    "Verify the URL points to the Puppet screenshot engine",
+                    "Verify the URL points to a supported screenshot engine",
                     "Check that the screenshot engine supports the "
                     + f"requested {image_format} format",
                 ],
@@ -601,7 +602,7 @@ async def _read_image_response(
                     "received_signature_hex": image_data[:12].hex(),
                 },
                 suggestions=[
-                    "Verify the URL points to the Puppet screenshot engine",
+                    "Verify the URL points to a supported screenshot engine",
                     "Check whether an authentication or proxy page was returned "
                     + "with an incorrect image Content-Type",
                 ],
@@ -615,7 +616,9 @@ async def _request_viewport_image(
     *,
     url: str,
     path: str,
-    engine: str,
+    engine_url: str,
+    engine_kind: EngineKind | None,
+    engine_version: str | None,
     params: dict[str, str],
     options: _CaptureOptions,
     viewport: _ViewportRequest,
@@ -641,13 +644,13 @@ async def _request_viewport_image(
                         and viewport.height == "auto"
                         and not fallback_used
                     ):
-                        # Puppet <2.5.0 does not understand WIDTHxauto.
-                        fallback_used = True
-                        capture_height = MAX_VIEWPORT_DIMENSION
-                        params["viewport"] = (
-                            f"{viewport.width}x{MAX_VIEWPORT_DIMENSION}"
-                        )
-                        continue
+                        if is_legacy_puppet(engine_kind, engine_version):
+                            fallback_used = True
+                            capture_height = MAX_VIEWPORT_DIMENSION
+                            params["viewport"] = (
+                                f"{viewport.width}x{MAX_VIEWPORT_DIMENSION}"
+                            )
+                            continue
                     raise_tool_error(
                         create_error_response(
                             ErrorCode.SERVICE_CALL_FAILED,
@@ -657,6 +660,8 @@ async def _request_viewport_image(
                             context={
                                 **request_context,
                                 "status_code": response.status_code,
+                                "engine_kind": engine_kind or "unknown",
+                                "engine_version": engine_version,
                                 "legacy_full_page_fallback_attempted": fallback_used,
                             },
                             suggestions=[
@@ -684,7 +689,7 @@ async def _request_viewport_image(
                     details=str(exc),
                     context={
                         **request_context,
-                        "engine_url": engine,
+                        "engine_url": engine_url,
                         "render_timeout_seconds": options.render_timeout_seconds,
                     },
                     suggestions=[
@@ -698,16 +703,14 @@ async def _request_viewport_image(
             raise_tool_error(
                 create_error_response(
                     ErrorCode.CONNECTION_FAILED,
-                    f"Could not reach the dashboard screenshot engine at {engine}.",
+                    f"Could not reach the dashboard screenshot engine at {engine_url}.",
                     details=str(exc),
-                    context={**request_context, "engine_url": engine},
+                    context={**request_context, "engine_url": engine_url},
                     suggestions=[
-                        "Ensure the Puppet screenshot add-on (or sidecar) "
-                        + "is installed and running",
+                        "Ensure the screenshot engine app or sidecar is installed and running",
                         "If it is running, its access token is likely "
                         + f"missing or invalid — {TOKEN_HINT}",
-                        "Check HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL on "
-                        + "Docker/Container deployments",
+                        "Check HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL for Docker/Container deployments",
                     ],
                 )
             )
@@ -719,7 +722,9 @@ async def _request_or_collect_failure(
     *,
     url: str,
     path: str,
-    engine: str,
+    engine_url: str,
+    engine_kind: EngineKind | None,
+    engine_version: str | None,
     params: dict[str, str],
     options: _CaptureOptions,
     viewport: _ViewportRequest,
@@ -735,7 +740,9 @@ async def _request_or_collect_failure(
             http_client,
             url=url,
             path=path,
-            engine=engine,
+            engine_url=engine_url,
+            engine_kind=engine_kind,
+            engine_version=engine_version,
             params=params,
             options=options,
             viewport=viewport,
@@ -775,7 +782,7 @@ def _viewport_params(
     if options.theme is not None:
         params["theme"] = options.theme
     if options.dark_mode:
-        # Puppet checks only for query-key presence.
+        # Both supported engines interpret an empty `dark` value as true.
         params["dark"] = ""
     if options.language is not None:
         params["lang"] = options.language
@@ -881,8 +888,8 @@ async def capture_dashboard_images(
     viewports = _capture_viewports(options)
 
     engine_target = await resolve_engine()
-    engine = engine_target.url
-    url = f"{engine}/{path}"
+    engine_url = engine_target.url
+    url = f"{engine_url}/{path}"
     mime_type = _MIME_TYPES[options.image_format]
     captures: list[DashboardImageCapture] = []
 
@@ -935,7 +942,9 @@ async def capture_dashboard_images(
                     http_client,
                     url=url,
                     path=path,
-                    engine=engine,
+                    engine_url=engine_url,
+                    engine_kind=engine_target.engine_kind,
+                    engine_version=engine_target.engine_version,
                     params=params,
                     options=options,
                     viewport=viewport,

ha_mcp_dev-9.1.0.dev3236/src/ha_mcp/dashboard_screenshot/engine_compat.py

@@ -0,0 +1,17 @@
+"""Compatibility checks for screenshot-engine API differences."""
+
+from __future__ import annotations
+
+from packaging.version import InvalidVersion, Version
+
+from .provision import EngineKind
+
+
+def is_legacy_puppet(engine_kind: EngineKind | None, version: str | None) -> bool:
+    """Return whether a verified Puppet version predates WIDTHxauto support."""
+    if engine_kind != "puppet" or not version:
+        return False
+    try:
+        return Version(version) < Version("2.5.0")
+    except InvalidVersion:
+        return False

{ha_mcp_dev-9.0.1.dev3235 → ha_mcp_dev-9.1.0.dev3236}/src/ha_mcp/dashboard_screenshot/paths.py

@@ -442,7 +442,7 @@ def resolve_dashboard_view(
         elif has_static_views:
             warning = (
                 "No view_path was supplied; the dashboard base route renders "
-                "the first view visible to Puppet's Home Assistant user."
+                "the first view visible to the screenshot engine's Home Assistant user."
             )
         else:
             warning = (
@@ -672,7 +672,7 @@ async def resolve_dashboard_render_target(
             stable=False,
             warnings=(
                 "No named view path was supplied; the built-in dashboard base route "
-                "renders the first view visible to Puppet's Home Assistant user.",
+                "renders the first view visible to the screenshot engine's Home Assistant user.",
             ),
         )
     config = await fetch_dashboard_render_config(client, url_path)

ha_mcp_dev-9.1.0.dev3236/src/ha_mcp/dashboard_screenshot/provision.py

@@ -0,0 +1,387 @@
+"""Locate a supported dashboard screenshot engine for this deployment.
+
+The supported engines are balloob's **Puppet** app and the **WPE Screenshot
+Engine** app. ha-mcp does not vendor either engine — the user installs them.
+
+Three deployment modes, resolved lazily on first tool use (never at
+startup, never silently installed):
+
+1. **Explicit** — ``HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL`` is set. Used
+   verbatim. This is the Docker / Container path (a docker-compose
+   sidecar), and also lets HA OS users override auto-discovery.
+2. **HA OS / Supervised** — ``SUPERVISOR_TOKEN`` is present. A supported app
+   (slug ``*_puppet`` or ``*_wpe_screenshot_engine``) is verified through the
+   Supervisor REST API and reached on the internal network by its hostname.
+   The user must install and start the app themselves — we never auto-install.
+3. **Neither** (stdio / standalone) — a clear :class:`ToolError` explaining
+   how to enable it.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import httpx
+
+from ha_mcp._vendor.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__)
+
+EngineKind = Literal["puppet", "wpe"]
+
+
+@dataclass(frozen=True, slots=True)
+class EngineTarget:
+    """A resolved screenshot engine endpoint.
+
+    ``addon_credential`` authenticates as Puppet's user (extracted from its
+    Supervisor options during discovery, so the theme guard needs no second
+    round-trip and the raw secret-bearing options dict never leaves this
+    module). ``engine_kind`` and ``engine_version`` are populated only when
+    Supervisor verifies the selected app. An explicit URL does not prove which
+    engine or version it targets. WPE temporarily applies frontend preferences
+    and does not need the guard credential. An explicit URL may still carry
+    Puppet's credential when Supervisor discovery finds it. The token never
+    leaves the server process — it must not be logged or surfaced in responses.
+    """
+
+    url: str
+    engine_kind: EngineKind | None = None
+    engine_version: str | None = None
+    addon_credential: EngineCredential | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class _EngineProfile:
+    """Supervisor identity and network details for a supported renderer."""
+
+    name: str
+    kind: EngineKind
+    slug_suffix: str
+    port: int
+    required_schema_options: frozenset[str]
+    has_persistent_theme_override: bool = False
+
+
+_PUPPET = _EngineProfile(
+    name="Puppet",
+    kind="puppet",
+    slug_suffix="_puppet",
+    port=10000,
+    required_schema_options=frozenset(
+        {"access_token", "home_assistant_url", "keep_browser_open"}
+    ),
+    has_persistent_theme_override=True,
+)
+_WPE = _EngineProfile(
+    name="WPE Screenshot Engine",
+    kind="wpe",
+    slug_suffix="_wpe_screenshot_engine",
+    port=8080,
+    required_schema_options=frozenset(
+        {"home_assistant_url", "home_assistant_token", "dashboard_path"}
+    ),
+)
+_SUPPORTED_ENGINES = (_PUPPET, _WPE)
+
+_PUPPET_REPO_URL = "https://github.com/balloob/home-assistant-addons"
+_WPE_REPO_URL = "https://github.com/Nischay-Pro/ha-wpe-screenshot-engine"
+
+# The single source of truth for the "configure the engine token" instruction,
+# reused across every engine-troubleshooting message here and in capture.py so
+# a copy edit only has to happen once.
+TOKEN_HINT = (
+    "set the engine's token option ('access_token' for "
+    "Puppet or 'home_assistant_token' for WPE Screenshot Engine) to a "
+    "Home Assistant long-lived access token (create one in Profile > Security, "
+    "ideally for a dedicated low-privilege user) and (re)start it"
+)
+
+_INSTALL_HELP = (
+    "Dashboard screenshot mode is enabled, but no supported screenshot "
+    "engine app is installed. On HA OS / Supervised, add either balloob's "
+    f"repository ({_PUPPET_REPO_URL}) or WPE Screenshot Engine's repository "
+    f"({_WPE_REPO_URL}) under Settings > Apps > Install app > ⋮ > Repositories "
+    "(Settings > Add-ons > Add-on store before Home Assistant 2026.2), then "
+    "install and start Puppet or WPE Screenshot Engine. "
+    f"{TOKEN_HINT}. On Docker / Container, run "
+    "one of these engines as a sidecar and set "
+    "HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL to its reachable URL."
+)
+
+_NOT_STARTED_HELP = (
+    "The supported screenshot engine app is installed but not started. Open "
+    "Settings > Apps > the selected engine (Settings > Add-ons before Home "
+    f"Assistant 2026.2), {TOKEN_HINT}. "
+    "Enable 'Start on boot' to keep it available."
+)
+
+_STDIO_HELP = (
+    "Dashboard screenshot mode needs either HA OS / Supervised with a "
+    "supported screenshot engine app installed, or a screenshot-engine "
+    "sidecar reachable via HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL. This "
+    "deployment (stdio / standalone) can host neither — see docs/beta.md."
+)
+
+
+def _verified_engine_profile(
+    slug: str, info: dict[str, Any], profiles: tuple[_EngineProfile, ...]
+) -> _EngineProfile | None:
+    """Return the profile whose slug, app name and schema all match."""
+    schema = info.get("schema")
+    schema_names = {
+        str(item.get("name"))
+        for item in schema or []
+        if isinstance(item, dict) and item.get("name") is not None
+    }
+    for profile in profiles:
+        if (
+            slug.endswith(profile.slug_suffix)
+            and info.get("name") == profile.name
+            and profile.required_schema_options <= schema_names
+        ):
+            return profile
+    return None
+
+
+def _select_started_verified_engine(
+    addon_infos: list[tuple[str, dict[str, Any]]],
+    profiles: tuple[_EngineProfile, ...] = _SUPPORTED_ENGINES,
+) -> tuple[str, dict[str, Any], _EngineProfile]:
+    """Select one started app that exactly matches a supported engine."""
+    verified: list[tuple[str, dict[str, Any], _EngineProfile]] = []
+    for slug, info in addon_infos:
+        profile = _verified_engine_profile(slug, info, profiles)
+        if profile is not None:
+            verified.append((slug, info, profile))
+    if not verified:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.CONFIG_VALIDATION_FAILED,
+                "Installed screenshot engine apps did not match a supported "
+                "engine's expected identity and schema.",
+                context={"matched_slugs": [slug for slug, _ in addon_infos]},
+                suggestions=[
+                    "Verify the app is Puppet or WPE Screenshot Engine and "
+                    "matches its repository configuration"
+                ],
+            )
+        )
+    started = [item for item in verified if item[1].get("state") == "started"]
+    if not started:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                "The schema-verified screenshot engine app is not started.",
+                details=_NOT_STARTED_HELP,
+                context={"matched_slugs": [slug for slug, _, _ in verified]},
+            )
+        )
+    if len(started) > 1:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.CONFIG_VALIDATION_FAILED,
+                "Multiple started screenshot engine apps matched supported "
+                "schemas; "
+                "refusing an ambiguous target.",
+                context={"matched_slugs": [slug for slug, _, _ in started]},
+            )
+        )
+    return started[0]
+
+
+def _supervisor_response_data(payload: Any, endpoint: str) -> dict[str, Any]:
+    """Return a Supervisor response's object-shaped data payload."""
+    if not isinstance(payload, dict):
+        raise ValueError(f"Supervisor {endpoint} returned a non-object payload")
+    data = payload.get("data")
+    if not isinstance(data, dict):
+        raise ValueError(f"Supervisor {endpoint} returned invalid data")
+    return data
+
+
+def _supervisor_addon_listing(payload: Any) -> list[dict[str, Any]]:
+    """Return the validated add-on objects from a Supervisor list response."""
+    addons = _supervisor_response_data(payload, "/addons").get("addons")
+    if not isinstance(addons, list) or not all(
+        isinstance(addon, dict) for addon in addons
+    ):
+        raise ValueError("Supervisor /addons returned an invalid addons list")
+    return addons
+
+
+async def resolve_engine() -> EngineTarget:
+    """Resolve the screenshot engine endpoint, or raise ToolError.
+
+    See module docstring for the three-mode resolution order.
+    """
+    from ..config import get_global_settings
+
+    explicit = (get_global_settings().dashboard_screenshot_engine_url or "").strip()
+    if explicit:
+        return EngineTarget(
+            url=explicit.rstrip("/"),
+            addon_credential=await _addon_credential_best_effort(),
+        )
+
+    if os.environ.get("SUPERVISOR_TOKEN"):
+        return await _discover_engine_via_supervisor()
+
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            "Dashboard screenshot mode is not available in this deployment.",
+            details=_STDIO_HELP,
+            suggestions=[
+                "Use HA OS / Supervised and install the screenshot engine app",
+                "Or run the engine as a sidecar and set "
+                + "HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL",
+            ],
+        )
+    )
+    # raise_tool_error is typed -> NoReturn, but CodeQL cannot see that, so it
+    # reports py/mixed-returns for the implicit None fall-through past it. Keep
+    # this terminal statement to suppress that false positive (repo convention).
+    raise AssertionError("unreachable: raise_tool_error always raises")
+
+
+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 Puppet; without its token
+    the theme guard would go inactive exactly where the app 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:
+        # The theme guard is specific to Puppet, whose current renderer writes
+        # theme changes to the Home Assistant user profile. WPE applies these
+        # options temporarily and suppresses the corresponding user-data write.
+        return (
+            await _discover_engine_via_supervisor(preferred_engine="Puppet")
+        ).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(
+    *, preferred_engine: str | None = None
+) -> EngineTarget:
+    """Find one supported app through 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
+    ToolError with actionable guidance when no matching engine is available.
+    ``preferred_engine`` is used only for the best-effort Puppet theme guard
+    when the operator configured an explicit URL.
+    """
+    from ..client.supervisor_client import make_supervisor_httpx_client
+
+    try:
+        async with make_supervisor_httpx_client(timeout=15.0, verify=True) as sup:
+            listing = await sup.get("/addons")
+            listing.raise_for_status()
+            addons = _supervisor_addon_listing(listing.json())
+
+            profiles = tuple(
+                profile
+                for profile in _SUPPORTED_ENGINES
+                if preferred_engine is None or profile.name == preferred_engine
+            )
+            matches = [
+                a
+                for a in addons
+                if str(a.get("slug", "")).endswith(
+                    tuple(profile.slug_suffix for profile in profiles)
+                )
+            ]
+            if not matches:
+                engine_names = (
+                    [preferred_engine]
+                    if preferred_engine
+                    else [profile.name for profile in _SUPPORTED_ENGINES]
+                )
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.RESOURCE_NOT_FOUND,
+                        "A supported screenshot engine app is not installed.",
+                        context={"supported_engines": engine_names},
+                        details=_INSTALL_HELP,
+                    )
+                )
+
+            # The /addons list is only reliable for slug discovery (the
+            # repo-hash prefix is not known ahead of time). Per-addon details
+            # are authoritative on /addons/<slug>/info — the same source
+            # ha_manage_app trusts.
+            addon_infos: list[tuple[str, dict[str, Any]]] = []
+            for match in matches:
+                slug = str(match["slug"])
+                info = await sup.get(f"/addons/{slug}/info")
+                info.raise_for_status()
+                data = _supervisor_response_data(info.json(), f"/addons/{slug}/info")
+                addon_infos.append((slug, data))
+            slug, data, profile = _select_started_verified_engine(addon_infos, profiles)
+            hostname = data.get("hostname") or data.get("ip_address")
+            if not hostname:
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.SERVICE_CALL_FAILED,
+                        f"Screenshot engine app '{slug}' is started but "
+                        "the Supervisor returned no hostname/ip_address.",
+                        context={"slug": slug},
+                    )
+                )
+            options = data.get("options")
+            app_version = data.get("version")
+            return EngineTarget(
+                url=f"http://{hostname}:{profile.port}",
+                engine_kind=profile.kind,
+                engine_version=(
+                    app_version.strip()
+                    if isinstance(app_version, str) and app_version.strip()
+                    else None
+                ),
+                addon_credential=(
+                    addon_credential_from_options(
+                        options if isinstance(options, dict) else None
+                    )
+                    if profile.has_persistent_theme_override
+                    else None
+                ),
+            )
+    except ToolError:
+        raise
+    except (httpx.HTTPError, KeyError, ValueError) as e:
+        logger.warning("Screenshot engine discovery via Supervisor failed: %s", e)
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.CONNECTION_FAILED,
+                "Could not query the Supervisor to locate the screenshot engine app.",
+                details=str(e),
+                suggestions=[
+                    "Verify the screenshot engine app is installed and started",
+                    "Or set HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL explicitly",
+                ],
+            )
+        )