ha-mcp-dev 7.6.0.dev645__tar.gz → 7.6.0.dev647__tar.gz

{ha_mcp_dev-7.6.0.dev645/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.6.0.dev647}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.6.0.dev645
+Version: 7.6.0.dev647
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -25,7 +25,7 @@ Requires-Dist: python-dotenv==1.2.2
 Requires-Dist: truststore==0.10.4
 Requires-Dist: websockets==16.0
 Requires-Dist: cryptography==48.0.0
-Requires-Dist: pydantic-monty==0.0.17
+Requires-Dist: pydantic-monty==0.0.18
 Dynamic: license-file
 
 > **Breaking change (v7.3.0):** `ha_config_set_yaml` has been moved to [beta](docs/beta.md).
@@ -219,6 +219,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Blueprints** | `ha_get_blueprint`, `ha_import_blueprint` |
 | **Calendar** | `ha_config_get_calendar_events`, `ha_config_remove_calendar_event`, `ha_config_set_calendar_event` |
 | **Camera** | `ha_get_camera_image` |
+| **Dashboard** | `ha_get_dashboard_screenshot` *(beta)* |
 | **Dashboards** | `ha_config_delete_dashboard_resource`, `ha_config_delete_dashboard`, `ha_config_get_dashboard`, `ha_config_list_dashboard_resources`, `ha_config_set_dashboard_resource`, `ha_config_set_dashboard` |
 | **Device Registry** | `ha_get_device`, `ha_remove_device`, `ha_set_device` |
 | **Energy** | `ha_manage_energy_prefs` |
@@ -234,7 +235,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Scripts** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` |
 | **Search & Discovery** | `ha_deep_search`, `ha_get_overview`, `ha_get_state`, `ha_search_entities` |
 | **Service & Device Control** | `ha_bulk_control`, `ha_call_event`, `ha_call_service`, `ha_get_operation_status`, `ha_list_services` |
-| **System** | `ha_check_config`, `ha_config_set_yaml` *(beta)*, `ha_get_updates`, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_reload_core`, `ha_restart` |
+| **System** | `ha_config_set_yaml` *(beta)*, `ha_get_updates`, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_reload_core`, `ha_restart` |
 | **Todo Lists** | `ha_get_todo`, `ha_remove_todo_item`, `ha_set_todo_item` |
 | **Utilities** | `ha_eval_template`, `ha_install_mcp_tools` *(beta)*, `ha_report_issue` |
 | **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |

{ha_mcp_dev-7.6.0.dev645 → ha_mcp_dev-7.6.0.dev647}/README.md

@@ -189,6 +189,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Blueprints** | `ha_get_blueprint`, `ha_import_blueprint` |
 | **Calendar** | `ha_config_get_calendar_events`, `ha_config_remove_calendar_event`, `ha_config_set_calendar_event` |
 | **Camera** | `ha_get_camera_image` |
+| **Dashboard** | `ha_get_dashboard_screenshot` *(beta)* |
 | **Dashboards** | `ha_config_delete_dashboard_resource`, `ha_config_delete_dashboard`, `ha_config_get_dashboard`, `ha_config_list_dashboard_resources`, `ha_config_set_dashboard_resource`, `ha_config_set_dashboard` |
 | **Device Registry** | `ha_get_device`, `ha_remove_device`, `ha_set_device` |
 | **Energy** | `ha_manage_energy_prefs` |
@@ -204,7 +205,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Scripts** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` |
 | **Search & Discovery** | `ha_deep_search`, `ha_get_overview`, `ha_get_state`, `ha_search_entities` |
 | **Service & Device Control** | `ha_bulk_control`, `ha_call_event`, `ha_call_service`, `ha_get_operation_status`, `ha_list_services` |
-| **System** | `ha_check_config`, `ha_config_set_yaml` *(beta)*, `ha_get_updates`, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_reload_core`, `ha_restart` |
+| **System** | `ha_config_set_yaml` *(beta)*, `ha_get_updates`, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_reload_core`, `ha_restart` |
 | **Todo Lists** | `ha_get_todo`, `ha_remove_todo_item`, `ha_set_todo_item` |
 | **Utilities** | `ha_eval_template`, `ha_install_mcp_tools` *(beta)*, `ha_report_issue` |
 | **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |

{ha_mcp_dev-7.6.0.dev645 → ha_mcp_dev-7.6.0.dev647}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.6.0.dev645"
+version = "7.6.0.dev647"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -31,7 +31,7 @@ dependencies = [
     "truststore==0.10.4",
     "websockets==16.0",
     "cryptography==48.0.0",
-    "pydantic-monty==0.0.17",
+    "pydantic-monty==0.0.18",
 ]
 
 [project.urls]

{ha_mcp_dev-7.6.0.dev645 → ha_mcp_dev-7.6.0.dev647}/src/ha_mcp/client/websocket_client.py

@@ -536,7 +536,12 @@ class HomeAssistantWebSocketClient:
 
         Args:
             command_type: Type of command to send
-            **kwargs: Command parameters
+            _wait_timeout: Seconds to wait for the response (consumed from
+                ``kwargs``, not forwarded to Home Assistant). Defaults to 30s,
+                which suits fast commands; long-running ones (e.g. a
+                ``supervisor/api`` add-on install) must raise this so the
+                client doesn't give up before Home Assistant replies.
+            **kwargs: Command parameters (merged into the outgoing message)
 
         Returns:
             Response from Home Assistant
@@ -544,6 +549,14 @@ class HomeAssistantWebSocketClient:
         if not self._state.is_ready:
             raise HomeAssistantConnectionError("WebSocket not authenticated")
 
+        # Pull the wait timeout out of kwargs rather than making it a positional
+        # parameter: callers unpack a ``dict[str, object]`` via
+        # ``send_command(cmd, **message)``, and a typed positional param would
+        # break that call shape under mypy. The leading underscore keeps it out
+        # of the HA message namespace — HA WebSocket fields never start with
+        # one — so it can never shadow a real command field when popped.
+        wait_timeout: float = kwargs.pop("_wait_timeout", 30.0)
+
         message_id = self.get_next_message_id()
         message = {"id": message_id, "type": command_type, **kwargs}
 
@@ -556,9 +569,9 @@ class HomeAssistantWebSocketClient:
             self.cancel_pending_response(message_id)
             raise
 
-        # Wait for response outside the lock (30 second timeout)
+        # Wait for response outside the lock.
         try:
-            response = await asyncio.wait_for(future, timeout=30.0)
+            response = await asyncio.wait_for(future, timeout=wait_timeout)
             logger.debug(f"WebSocket response for id {message_id}: {response}")
 
             # Process standard Home Assistant WebSocket response

{ha_mcp_dev-7.6.0.dev645 → ha_mcp_dev-7.6.0.dev647}/src/ha_mcp/config.py

@@ -193,6 +193,25 @@ class Settings(BaseSettings):
         False, alias="HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION"
     )
 
+    # Dashboard screenshot mode — the ``ha_get_dashboard_screenshot`` tool
+    # plus the ``include_screenshot`` / ``return_screenshot`` params on the
+    # dashboard get/set tools. Renders a Lovelace view to a PNG 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.
+    enable_dashboard_screenshot: bool = Field(
+        False, alias="HAMCP_ENABLE_DASHBOARD_SCREENSHOT"
+    )
+
+    # 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 intentionally absent from FEATURE_FLAG_FIELDS. Left blank, the
+    # provisioner auto-discovers the Puppet add-on via the Supervisor in
+    # HA OS / Supervised mode; Container / Core users set it explicitly.
+    dashboard_screenshot_engine_url: str = Field(
+        "", alias="HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL"
+    )
+
     # Code Mode — sandboxed Python execution via pydantic-monty.
     # Provides an "escape hatch" tool (ha_manage_custom_tool) that lets LLMs write
     # custom one-off Python code when no existing tool covers the request.
@@ -265,6 +284,7 @@ class Settings(BaseSettings):
     @field_validator(
         "enable_filesystem_tools",
         "enable_custom_component_integration",
+        "enable_dashboard_screenshot",
         mode="before",
     )
     @classmethod
@@ -289,6 +309,23 @@ class Settings(BaseSettings):
             raise ValueError("Home Assistant URL must start with http:// or https://")
         return v.rstrip("/")  # Remove trailing slash
 
+    @field_validator("dashboard_screenshot_engine_url")
+    @classmethod
+    def validate_dashboard_screenshot_engine_url(cls, v: str) -> str:
+        """Validate the optional screenshot-engine URL (env/.env only).
+
+        Blank = auto-discover the engine add-on via the Supervisor. When set
+        (the Docker/Container sidecar path) it must be an http(s) URL, so a
+        typo fails loudly at startup instead of silently 0-byte-failing later.
+        """
+        if not v:
+            return v
+        if not v.startswith(("http://", "https://")):
+            raise ValueError(
+                "Screenshot engine URL must start with http:// or https://"
+            )
+        return v.rstrip("/")
+
     @field_validator("homeassistant_token")
     @classmethod
     def validate_homeassistant_token(cls, v: str) -> str:
@@ -478,6 +515,11 @@ FEATURE_FLAG_FIELDS: tuple[FeatureFlagField, ...] = (
     # the web UI Server Settings tab) can write the flag. Without this
     # entry, the UI save logic would have nowhere to land the value.
     FeatureFlagField("enable_code_mode", "ENABLE_CODE_MODE", bool),
+    FeatureFlagField(
+        "enable_dashboard_screenshot",
+        "HAMCP_ENABLE_DASHBOARD_SCREENSHOT",
+        bool,
+    ),
 )
 
 # Override-file location is the same data dir that holds tool_config.json
@@ -517,6 +559,7 @@ BETA_FEATURE_FIELDS: tuple[str, ...] = (
     "enable_custom_component_integration",
     "enable_code_mode",
     "enable_lite_docstrings",
+    "enable_dashboard_screenshot",
 )
 
 # ===== Advanced settings panel registry =====

ha_mcp_dev-7.6.0.dev647/src/ha_mcp/dashboard_screenshot/__init__.py

@@ -0,0 +1,28 @@
+"""Dashboard screenshot support (opt-in, beta).
+
+Renders a Home Assistant Lovelace dashboard view to a PNG via a separate,
+single-purpose headless-Chromium screenshot engine (balloob's Puppet add-on,
+or a docker-compose 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
+default ha-mcp install stays lightweight unless the user opts in.
+"""
+
+from __future__ import annotations
+
+from .capture import (
+    DEFAULT_HEIGHT,
+    DEFAULT_WAIT_MS,
+    DEFAULT_WIDTH,
+    capture_dashboard_png,
+)
+from .provision import resolve_engine_url
+
+__all__ = [
+    "DEFAULT_HEIGHT",
+    "DEFAULT_WAIT_MS",
+    "DEFAULT_WIDTH",
+    "capture_dashboard_png",
+    "resolve_engine_url",
+]

ha_mcp_dev-7.6.0.dev647/src/ha_mcp/dashboard_screenshot/capture.py

@@ -0,0 +1,183 @@
+"""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 — no HA token
+ever flows through ha-mcp or the LLM for screenshots.
+"""
+
+from __future__ import annotations
+
+import logging
+from urllib.parse import quote
+
+import httpx
+
+from ..errors import ErrorCode, create_error_response
+from ..tools.helpers import raise_tool_error
+from .provision import TOKEN_HINT, resolve_engine_url
+
+logger = logging.getLogger(__name__)
+
+# Shared Field-description clause for the ``full_page`` screenshot param, reused
+# across ha_get_dashboard_screenshot and the get/set screenshot options so the
+# wording stays in one place instead of being copy-pasted per tool.
+FULL_PAGE_PARAM_DESC = (
+    "capture the whole scrollable dashboard instead of just the viewport "
+    "(use when content runs below the fold)"
+)
+
+DEFAULT_WIDTH = 1280
+DEFAULT_HEIGHT = 800
+# Cold-start render-settle. The engine waits this long after the dashboard
+# reports loaded so canvas/chart cards (history-graph, ApexCharts,
+# mini-graph) have time to paint. Heavy custom chart cards may need more —
+# exposed as a per-request parameter on the tools so the caller can raise it.
+DEFAULT_WAIT_MS = 2500
+_REQUEST_TIMEOUT_S = 60.0
+
+# full_page render height. The Puppet engine clips to the requested viewport
+# height (it has no native full-page mode), so capturing a whole scrollable
+# dashboard means asking for a tall viewport. This is the engine's max useful
+# height; dashboards taller than this still clip, and shorter ones get trailing
+# whitespace. Once the engine gains a native fullPage param (upstream), prefer
+# that instead — it auto-sizes to content with no cap and no whitespace.
+FULL_PAGE_HEIGHT = 4096
+
+# Characters/sequences that would let an LLM-supplied path escape the
+# dashboard route and reshape the engine request (scheme, authority,
+# query/fragment, traversal, backslash). The engine renders whatever path it
+# is handed with a full-HA credential, so the path must stay a plain
+# frontend route segment.
+_FORBIDDEN_PATH_BITS = ("://", "//", "..", "@", "\\", "?", "#")
+
+
+def _validate_dashboard_path(dashboard_path: str) -> str:
+    """Return a safe, stripped dashboard path or raise ToolError.
+
+    Rejects anything that isn't a plain Lovelace frontend route — no scheme,
+    authority, query, fragment, traversal, or backslash — so the caller can't
+    point the credentialed engine at arbitrary URLs or admin routes.
+    """
+    raw = (dashboard_path or "").strip()
+    if not raw:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_MISSING_PARAMETER,
+                "dashboard_path is required (e.g. 'lovelace/0' or 'my-dashboard').",
+                suggestions=["Pass a Lovelace path such as 'lovelace/0'"],
+            )
+        )
+    if any(bit in raw for bit in _FORBIDDEN_PATH_BITS) or any(
+        ord(c) < 0x20 for c in raw
+    ):
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"Invalid dashboard_path {dashboard_path!r}: pass a plain "
+                "Lovelace path like 'lovelace/0' or 'my-dashboard/kitchen'.",
+                details="Path may not contain URLs, query strings, fragments, "
+                "'..' segments, backslashes, or control characters.",
+                context={"dashboard_path": dashboard_path},
+            )
+        )
+    # Percent-encode each surviving segment so only the explicit query params
+    # (set in capture_dashboard_png) ever reach the engine — defense in depth
+    # on top of the rejection above.
+    segments = [seg for seg in raw.strip("/").split("/") if seg not in ("", ".")]
+    if not segments:
+        # e.g. "/" or "/." — the engine would serve its config/UI HTML for the
+        # root path, not a dashboard PNG, which would be a confusing silent
+        # failure. Require a concrete view path.
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"Invalid dashboard_path {dashboard_path!r}: cannot be empty or "
+                "the root path.",
+                details="Pass a specific Lovelace view, e.g. 'lovelace/0'.",
+                context={"dashboard_path": dashboard_path},
+            )
+        )
+    return "/".join(quote(seg, safe="") for seg in segments)
+
+
+async def capture_dashboard_png(
+    dashboard_path: str,
+    *,
+    width: int = DEFAULT_WIDTH,
+    height: int = DEFAULT_HEIGHT,
+    zoom: float = 1.0,
+    wait_ms: int = DEFAULT_WAIT_MS,
+    full_page: bool = False,
+) -> bytes:
+    """Render ``dashboard_path`` to PNG bytes via the screenshot engine.
+
+    With ``full_page=True`` the whole scrollable dashboard is captured rather
+    than just the viewport: the engine clips to the requested height, so we ask
+    for a tall viewport (``FULL_PAGE_HEIGHT``). ``height`` is ignored in that
+    case. See ``FULL_PAGE_HEIGHT`` for the interim caveats (cap + whitespace).
+
+    Raises :class:`ToolError` if the engine is unreachable or returns an error.
+    """
+    path = _validate_dashboard_path(dashboard_path)
+    engine = await resolve_engine_url()
+    effective_height = FULL_PAGE_HEIGHT if full_page else int(height)
+    params: dict[str, str] = {
+        "viewport": f"{int(width)}x{effective_height}",
+        "zoom": str(zoom),
+        "wait": str(int(wait_ms)),
+        "format": "png",
+    }
+    url = f"{engine}/{path}"
+
+    try:
+        async with httpx.AsyncClient(timeout=httpx.Timeout(_REQUEST_TIMEOUT_S)) as h:
+            resp = await h.get(url, params=params)
+    except httpx.HTTPError as e:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.CONNECTION_FAILED,
+                f"Could not reach the dashboard screenshot engine at {engine}.",
+                details=str(e),
+                context={"engine_url": engine},
+                suggestions=[
+                    "Ensure the Puppet screenshot add-on (or sidecar) is "
+                    "installed and running",
+                    # Puppet restarts itself when navigation fails, so a
+                    # missing/invalid token shows up as a dropped connection
+                    # rather than an HTTP error.
+                    f"If it is running, its access token is likely missing or "
+                    f"invalid — {TOKEN_HINT}",
+                    "Check HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL on "
+                    "Docker/Container deployments",
+                ],
+            )
+        )
+
+    if resp.status_code >= 400:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                f"Screenshot engine returned HTTP {resp.status_code} for "
+                f"dashboard '{path}'.",
+                details=resp.text[:300],
+                context={"status_code": resp.status_code, "path": path},
+                suggestions=[
+                    "Verify the dashboard path exists",
+                    f"If the engine landed on the login page, its access token "
+                    f"is missing/invalid — {TOKEN_HINT}",
+                    "Increase wait_ms for heavy chart cards",
+                ],
+            )
+        )
+    if not resp.content:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                f"Screenshot engine returned an empty image for '{path}'.",
+                details="The dashboard path may be invalid, or the engine's "
+                "access token may be missing/expired.",
+                context={"path": path},
+            )
+        )
+    return resp.content

ha_mcp_dev-7.6.0.dev647/src/ha_mcp/dashboard_screenshot/provision.py

@@ -0,0 +1,187 @@
+"""Locate the dashboard screenshot engine for the current deployment.
+
+The engine is balloob's **Puppet** add-on (https://github.com/balloob/
+home-assistant-addons), a headless-Chromium renderer. ha-mcp does not vendor
+it — the user installs it themselves.
+
+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. The Puppet
+   add-on (slug ``*_puppet``) is discovered via the Supervisor REST API and
+   reached on the internal network by its hostname. The user must have
+   installed + started it themselves (add balloob's add-on repository, then
+   install "Puppet") — 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
+
+import httpx
+from fastmcp.exceptions import ToolError
+
+from ..errors import ErrorCode, create_error_response
+from ..tools.helpers import raise_tool_error
+
+logger = logging.getLogger(__name__)
+
+ENGINE_PORT = 10000
+# The Supervisor slug is ``<repo-hash>_puppet`` for balloob's Puppet add-on;
+# ``_ha_mcp_screenshot`` is the legacy vendored engine, still accepted so a
+# mid-migration install keeps working. ``str.endswith`` takes this tuple.
+ENGINE_SLUG_SUFFIXES = ("_puppet", "_ha_mcp_screenshot")
+
+_REPO_URL = "https://github.com/balloob/home-assistant-addons"
+
+# The single source of truth for the "configure the access 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 add-on's 'access_token' option 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 the Puppet screenshot engine "
+    "add-on is not installed. On HA OS / Supervised: (1) add balloob's add-on "
+    f"repository ({_REPO_URL}) under Settings > Add-ons > Add-on Store > "
+    "Repositories, then install the 'Puppet' add-on; and (2) it REQUIRES a "
+    f"token — {TOKEN_HINT}. Without a token the engine only serves a "
+    "configuration-instructions page. On Docker / Container, run the Puppet "
+    "image as a sidecar (with its access_token set) and point ha-mcp at it via "
+    "HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL (e.g. http://puppet:10000)."
+)
+
+_NOT_STARTED_HELP = (
+    "The Puppet screenshot engine add-on is installed but not started. Open "
+    f"Settings > Add-ons > Puppet, {TOKEN_HINT} (enable 'Start on boot' to keep "
+    "it available)."
+)
+
+_STDIO_HELP = (
+    "Dashboard screenshot mode needs either HA OS / Supervised (add balloob's "
+    "add-on repository and install the 'Puppet' add-on) or a Puppet sidecar "
+    "reachable via HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL. This deployment "
+    "(stdio / standalone) can host neither — see docs/beta.md."
+)
+
+
+async def resolve_engine_url() -> str:
+    """Return the base URL of the screenshot engine, 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 explicit.rstrip("/")
+
+    if os.environ.get("SUPERVISOR_TOKEN"):
+        return await _discover_engine_url_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 add-on",
+                "Or run the engine as a sidecar and set "
+                "HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL",
+            ],
+        )
+    )
+
+
+async def _discover_engine_url_via_supervisor() -> str:
+    """Find the Puppet add-on via the Supervisor and return its internal URL.
+
+    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 the engine is missing or stopped.
+    """
+    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 = listing.json().get("data", {}).get("addons", [])
+
+            matches = [
+                a
+                for a in addons
+                if str(a.get("slug", "")).endswith(ENGINE_SLUG_SUFFIXES)
+            ]
+            if not matches:
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.RESOURCE_NOT_FOUND,
+                        "The Puppet screenshot engine add-on is not installed.",
+                        details=_INSTALL_HELP,
+                    )
+                )
+
+            # The /addons list is only reliable for slug discovery (the
+            # repo-hash prefix is not known ahead of time). Per-addon ``state``
+            # and ``hostname`` are authoritative on /addons/<slug>/info — the
+            # same source ha_manage_addon trusts. The list can report a
+            # stale/absent ``state`` for a freshly-started add-on, so read state
+            # from /info. With more than one match (e.g. the legacy vendored
+            # engine alongside Puppet), prefer whichever is started.
+            last_slug: str | None = None
+            last_state: str | None = None
+            for match in matches:
+                slug = str(match["slug"])
+                info = await sup.get(f"/addons/{slug}/info")
+                info.raise_for_status()
+                data = info.json().get("data", {})
+                last_slug, last_state = slug, data.get("state")
+                if data.get("state") != "started":
+                    continue
+                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 add-on '{slug}' is started but "
+                            "the Supervisor returned no hostname/ip_address.",
+                            context={"slug": slug},
+                        )
+                    )
+                return f"http://{hostname}:{ENGINE_PORT}"
+
+            # Matched an installed engine, but none was started.
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    "The Puppet screenshot engine add-on is installed but not started.",
+                    details=_NOT_STARTED_HELP,
+                    context={"slug": last_slug, "state": last_state},
+                )
+            )
+    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 Puppet "
+                "screenshot engine add-on.",
+                details=str(e),
+                suggestions=[
+                    "Verify the Puppet add-on is installed and started",
+                    "Or set HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL explicitly",
+                ],
+            )
+        )

{ha_mcp_dev-7.6.0.dev645 → ha_mcp_dev-7.6.0.dev647}/src/ha_mcp/settings.js

@@ -1088,9 +1088,13 @@ const FEATURE_META = {
     label: "Enable lite tool docstrings (beta)",
     help: "Beta feature — disabled by default. Replaces the docstrings on a handful of heavy ha-mcp tools (automations, scripts, scenes, helpers, dashboards, ha_call_service, ha_config_set_yaml) with shorter variants that defer schema and example detail to the ha_get_skill_guide tool (or its skill:// resource). WARNING: this reduces idle token usage, but may degrade LLM performance — the trimmed descriptions rely on the LLM actually calling the skill tool or reading the skill resource for detail, which is not guaranteed (some models will skip the extra tool call and end up with less guidance than they had before). Best paired with a client that supports MCP resources or with enable_tool_search. Requires restart to take effect.",
   },
+  enable_dashboard_screenshot: {
+    label: "Enable dashboard screenshot mode (beta)",
+    help: "Beta feature — disabled by default. Adds the ha_get_dashboard_screenshot tool plus include_screenshot / return_screenshot options on the dashboard get/set tools, so AI assistants can see a rendered PNG of a Lovelace dashboard (e.g. to verify one they just created). Rendering runs in a separate, opt-in engine — balloob's \"Puppet\" add-on (headless Chromium) — which you install once (add balloob's add-on repository, then install \"Puppet\") and give a long-lived access token; on Docker/Container deployments you run that engine as a sidecar and set HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL. Nothing heavy is installed unless you both enable this and install the engine. Requires restart to take effect. REQUIRES the master \"Enable beta features\" toggle above (and in the web UI) to be on — otherwise this sub-flag is ignored at runtime regardless of its value here.",
+  },
 };
 
-// The 5 beta sub-flag fields gated by the master beta toggle. Populated
+// The beta sub-flag fields gated by the master beta toggle. Populated
 // from the ``beta_sub_flags`` array in the /api/settings/features
 // response so the JS stays in sync with Python's
 // ``config.BETA_FEATURE_FIELDS`` without duplicating the name list here.