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

{ha_mcp_dev-9.0.1.dev3231 → 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.dev3231
+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.dev3231 → 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.dev3231"
+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.dev3231 → 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.dev3231"
+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.dev3231 → ha_mcp_dev-9.1.0.dev3236}/src/ha_mcp/backup_dashboards.py

@@ -70,6 +70,7 @@ async def fetch_dashboard(client: Any, entity_id: str) -> Any:
     """
     from ha_mcp._vendor.fastmcp.exceptions import ToolError
 
+    from .tools.dashboard_read_errors import UNKNOWN_CONFIG_PREFIX
     from .tools.tools_config_dashboards import (
         _component_dashboard_config,
         _get_dashboard_config_internal,
@@ -108,7 +109,7 @@ async def fetch_dashboard(client: Any, entity_id: str) -> Any:
             # url_path ("Unknown config specified", also the create path), or
             # a dashboard whose config was never saved, which keeps its row.
             msg = str(err).lower()
-            if "not_found" not in msg and "unknown config" not in msg:
+            if "not_found" not in msg and UNKNOWN_CONFIG_PREFIX.lower() not in msg:
                 raise
             config = None
             if row is None:
@@ -134,10 +135,12 @@ async def _save(client: Any, url_path: str, config: Any) -> Any:
 
 async def _saved(client: Any, url_path: str, config: Any) -> bool:
     """Write; ``False`` when Core has no dashboard at ``url_path``."""
+    from .tools.dashboard_read_errors import CONFIG_NOT_FOUND_CODE
+
     try:
         await _save(client, url_path, config)
     except HomeAssistantCommandError as err:
-        if err.code != "config_not_found":
+        if err.code != CONFIG_NOT_FOUND_CODE:
             raise
         return False
     return True

{ha_mcp_dev-9.0.1.dev3231 → ha_mcp_dev-9.1.0.dev3236}/src/ha_mcp/backup_manager.py

@@ -109,6 +109,7 @@ from .client.rest_client import (
     HomeAssistantConnectionError,
     HomeAssistantError,
 )
+from .storage_helper_types import SIMPLE_HELPER_TYPES
 from .utils.data_paths import get_data_dir
 from .utils.registry_update_lock import registry_update_lock
 
@@ -2730,20 +2731,7 @@ async def _restore_device(client: Any, entity_id: str, config: Any) -> Any:
 # endpoints (fetch: backup_helper_target.py). The decorator
 # constructs the domain key as ``helper_<type>`` so files group naturally.
 
-_HELPER_LIST_TYPES = {
-    "input_boolean",
-    "input_text",
-    "input_number",
-    "input_select",
-    "input_datetime",
-    "input_button",
-    "counter",
-    "timer",
-    "schedule",
-    "zone",
-    "person",
-    "tag",
-}
+_HELPER_LIST_TYPES = SIMPLE_HELPER_TYPES
 
 
 async def _restore_helper(

{ha_mcp_dev-9.0.1.dev3231 → 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.dev3231 → 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.dev3231 → 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.dev3231 → ha_mcp_dev-9.1.0.dev3236}/src/ha_mcp/dashboard_screenshot/paths.py

@@ -12,13 +12,15 @@ from typing import Any, cast
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
 
 from ..errors import ErrorCode, create_error_response
+from ..tools.dashboard_read_errors import (
+    CONFIG_NOT_FOUND_CODE,
+    NO_STORED_CONFIG_MESSAGES,
+    NO_STORED_CONFIG_NOTE,
+    UNKNOWN_CONFIG_PREFIX,
+)
 from ..tools.helpers import raise_tool_error
 from .capture import _normalize_dashboard_path
 
-_UNKNOWN_CONFIG_PREFIX = "Unknown config specified:"
-_NO_CONFIG_MESSAGES = frozenset(
-    {"No config found.", "Command failed: No config found."}
-)
 _JS_DECIMAL_NUMBER = re.compile(
     r"[+-]?(?:(?:\d+(?:\.\d*)?)|(?:\.\d+))(?:[eE][+-]?\d+)?\Z"
 )
@@ -264,8 +266,14 @@ def _fallback_view_target(
     )
 
 
-async def fetch_dashboard_render_config(client: Any, url_path: str) -> dict[str, Any]:
-    """Fetch a Lovelace dashboard config for stable view-path resolution."""
+async def fetch_dashboard_render_config(
+    client: Any, url_path: str
+) -> dict[str, Any] | None:
+    """Fetch a Lovelace dashboard config for stable view-path resolution.
+
+    ``None`` when Home Assistant holds no config for the dashboard, which the
+    frontend renders as its generated default view.
+    """
     base_path = dashboard_frontend_path(url_path)
     request: dict[str, Any] = {"type": "lovelace/config", "force": True}
     if base_path != "lovelace":
@@ -296,12 +304,13 @@ async def fetch_dashboard_render_config(client: Any, url_path: str) -> dict[str,
         else:
             error_code = ""
             message = str(error)
-        missing_dashboard = (
-            error_code == "config_not_found"
-            or message.startswith(
-                (_UNKNOWN_CONFIG_PREFIX, f"Command failed: {_UNKNOWN_CONFIG_PREFIX}")
+        if message in NO_STORED_CONFIG_MESSAGES:
+            return None
+        missing_dashboard = error_code == CONFIG_NOT_FOUND_CODE or message.startswith(
+            (
+                f"{UNKNOWN_CONFIG_PREFIX}:",
+                f"Command failed: {UNKNOWN_CONFIG_PREFIX}:",
             )
-            or message in _NO_CONFIG_MESSAGES
         )
         if missing_dashboard:
             raise_tool_error(
@@ -433,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 = (
@@ -502,14 +511,14 @@ async def _resolve_legacy_dashboard_target(
         raw_view = parts[1] if len(parts) > 1 else None
         numeric_index = _numeric_view_index(raw_view) if raw_view is not None else None
         return DashboardRenderTarget(
-            url_path="lovelace",
+            url_path=dashboard_root,
             view_path=None,
             render_path=render_path,
             view_index=numeric_index,
             stable=False,
             warnings=(
-                "Legacy built-in Lovelace routes are accepted without a stored "
-                "dashboard config; the selected view cannot be verified.",
+                "Routes of a dashboard without a stored config are accepted; "
+                "the selected view cannot be verified.",
             ),
         )
     if len(parts) == 1:
@@ -663,10 +672,29 @@ 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)
+    if config is None:
+        if view_path is not None:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    NO_STORED_CONFIG_NOTE,
+                    context={"url_path": url_path, "view_path": view_path},
+                    suggestions=["Omit view_path: there are no static views"],
+                )
+            )
+        base_path = dashboard_frontend_path(url_path)
+        return DashboardRenderTarget(
+            url_path=base_path,
+            view_path=None,
+            render_path=base_path,
+            view_index=None,
+            stable=False,
+            warnings=(NO_STORED_CONFIG_NOTE,),
+        )
     return resolve_dashboard_view(url_path, config, view_path)
 
 
@@ -718,7 +746,7 @@ async def _numeric_view_warning(
         return []
     if config is None:
         config = await fetch_dashboard_render_config(client, url_path)
-    views = config.get("views")
+    views = (config or {}).get("views")
     if not isinstance(views, list):
         return []
     view_index = index if matched_view_index is None else matched_view_index