ha-mcp-dev 7.14.2.dev2093__tar.gz → 7.14.2.dev2098__tar.gz

{ha_mcp_dev-7.14.2.dev2093/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.14.2.dev2098}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.14.2.dev2093
+Version: 7.14.2.dev2098
 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.14.2.dev2093 → ha_mcp_dev-7.14.2.dev2098}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.14.2.dev2093"
+version = "7.14.2.dev2098"
 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.14.2.dev2093 → ha_mcp_dev-7.14.2.dev2098}/src/ha_mcp/backup_manager.py

@@ -766,16 +766,18 @@ class BackupManager:
 
     # ----- legacy store (pre-#1579 .ha_mcp_tools_backups/) ---------------
 
-    async def list_legacy(self) -> list[dict[str, Any]]:
+    async def list_legacy(self) -> tuple[list[dict[str, Any]], str | None]:
         """List pre-#1579 ``.bak`` backups via the component service.
 
         Each entry is normalized to a synthetic ``name`` (``legacy:<file>``)
         plus ``source="legacy"`` and the decode hints (``file_path`` /
         ``path_ambiguous``) so the caller can route view/diff/restore and warn
-        on un-restorable (ambiguous) names. Returns ``[]`` when the component
-        is too old to expose the service, so ``list`` still works.
+        on un-restorable (ambiguous) names. Returns ``(entries,
+        unavailable_reason)``: entries is ``[]`` when the component is too
+        old, unconfigured, or absent — ``list`` still works — and the reason
+        (when set) lets the caller flag the omission.
         """
-        backups = await _list_legacy_backups(self._client)
+        backups, unavailable_reason = await _list_legacy_backups(self._client)
         out: list[dict[str, Any]] = []
         for b in backups:
             filename = b.get("filename")
@@ -792,7 +794,7 @@ class BackupManager:
                     "path_ambiguous": b.get("path_ambiguous", True),
                 }
             )
-        return out
+        return out, unavailable_reason
 
     async def read_legacy(self, filename: str) -> dict[str, Any]:
         """Read one legacy ``.bak`` (raw content + decode hints).
@@ -815,7 +817,7 @@ class BackupManager:
         domain: str | None = None,
         entity_id: str | None = None,
         limit: int | None = None,
-    ) -> list[dict[str, Any]]:
+    ) -> tuple[list[dict[str, Any]], list[str]]:
         """Edits-store snapshots plus pre-#1579 legacy ``.bak`` entries (#1579).
 
         ``list_snapshots`` is sync (dir glob, run off-thread); the legacy store
@@ -828,9 +830,22 @@ class BackupManager:
         Legacy entries get reserved room within ``limit`` so a full edits store
         (>= ``limit`` snapshots) can't truncate the few historical legacy
         entries out of the listing — surfacing them is the whole point.
+
+        Returns ``(entries, warnings)``: when the legacy sub-fetch was
+        suppressed (tools entry not set up / component too old), ``warnings``
+        says so, so the tool response doesn't read as a clean, complete list
+        with the ``.bak`` history silently missing (#1996).
         """
         want_legacy = domain in (None, "yaml_file") and entity_id is None
-        legacy = await self.list_legacy() if want_legacy else []
+        legacy: list[dict[str, Any]] = []
+        warnings: list[str] = []
+        if want_legacy:
+            legacy, unavailable_reason = await self.list_legacy()
+            if unavailable_reason:
+                warnings.append(
+                    "Legacy .bak backups could not be listed and are omitted: "
+                    f"{unavailable_reason}"
+                )
         edits_limit = max(1, limit - len(legacy)) if limit and legacy else limit
         entries = await asyncio.to_thread(
             self.list_snapshots, domain=domain, entity_id=entity_id, limit=edits_limit
@@ -838,7 +853,7 @@ class BackupManager:
         entries.extend(legacy)
         if limit:
             entries = entries[:limit]
-        return entries
+        return entries, warnings
 
     async def _diff_legacy(self, filename: str) -> DiffResponseText:
         info = await self.read_legacy(filename)
@@ -2173,30 +2188,37 @@ async def _restore_yaml_file(client: Any, entity_id: str, config: Any) -> Any:
     return result
 
 
-async def _list_legacy_backups(client: Any) -> list[dict[str, Any]]:
+async def _list_legacy_backups(client: Any) -> tuple[list[dict[str, Any]], str | None]:
     """Fetch pre-#1579 ``.bak`` backups via the component list_legacy_backups
     service.
 
-    Returns ``[]`` (logged at debug) when the component predates the service —
-    a service-unavailable rejection surfaces either as a ``success: False``
-    response or a ``HomeAssistantError`` — so the edits ``list`` still works
-    against an older standalone component. Genuine programming errors propagate.
+    Returns ``(backups, unavailable_reason)``. The legacy store is
+    best-effort: when the component predates the service, isn't configured
+    (tools entry not set up), or is missing entirely, the entry list is ``[]``
+    and ``unavailable_reason`` carries the human-readable cause — a
+    ``HomeAssistantError`` or any ``ToolError`` out of
+    ``call_mcp_tools_service`` (all its caller-token gates included) lands
+    here (also logged at debug), so the edits ``list`` still works and the
+    caller can surface the degradation as a warning. A ``success: False``
+    service response degrades silently as before. Genuine programming errors
+    propagate.
     """
+    from .tools.helpers import extract_structured_error_reason
     from .tools.tools_filesystem import call_mcp_tools_service
     from .tools.util_helpers import unwrap_service_response
 
     try:
         result = await call_mcp_tools_service(client, "list_legacy_backups", {})
-    except HomeAssistantError as err:
+    except (HomeAssistantError, ToolError) as err:
         logger.debug("legacy backup list unavailable: %s", err)
-        return []
+        return [], extract_structured_error_reason(err) or str(err)
     if not isinstance(result, dict):
-        return []
+        return [], None
     result = unwrap_service_response(result)
     if not result.get("success", False):
-        return []
+        return [], None
     backups = result.get("backups")
-    return backups if isinstance(backups, list) else []
+    return (backups, None) if isinstance(backups, list) else ([], None)
 
 
 async def _read_legacy_backup(client: Any, filename: str) -> dict[str, Any]:
@@ -2204,9 +2226,11 @@ async def _read_legacy_backup(client: Any, filename: str) -> dict[str, Any]:
 
     Returns the unwrapped service response (carries ``success`` / ``content`` /
     ``file_path`` / ``path_ambiguous`` / ``timestamp``). A service-unavailable
-    ``HomeAssistantError`` is mapped to a ``success: False`` dict so the caller
-    surfaces a not-found rather than crashing.
+    ``HomeAssistantError`` — or a ``ToolError`` from the caller-token gates —
+    is mapped to a ``success: False`` dict so the caller surfaces a not-found
+    rather than crashing.
     """
+    from .tools.helpers import extract_structured_error_reason
     from .tools.tools_filesystem import call_mcp_tools_service
     from .tools.util_helpers import unwrap_service_response
 
@@ -2214,8 +2238,15 @@ async def _read_legacy_backup(client: Any, filename: str) -> dict[str, Any]:
         result = await call_mcp_tools_service(
             client, "read_legacy_backup", {"filename": filename}
         )
-    except HomeAssistantError as err:
-        return {"success": False, "error": str(err)}
+    except (HomeAssistantError, ToolError) as err:
+        # The human reason, not str(err) verbatim: a ToolError's string is
+        # the whole JSON envelope, which would reach the tool layer as an
+        # unreadable JSON-in-JSON message (#1996's original symptom).
+        logger.debug("legacy backup read unavailable: %s", err)
+        return {
+            "success": False,
+            "error": extract_structured_error_reason(err) or str(err),
+        }
     if not isinstance(result, dict):
         return {"success": False, "error": f"no response for {filename!r}"}
     return unwrap_service_response(result)

{ha_mcp_dev-7.14.2.dev2093 → ha_mcp_dev-7.14.2.dev2098}/src/ha_mcp/dashboard_screenshot/paths.py

@@ -347,42 +347,28 @@ async def fetch_dashboard_render_config(
     return cast(dict[str, Any], config)
 
 
-def resolve_dashboard_view(
+def match_dashboard_view(
     dashboard_url_path: str,
     config: dict[str, Any],
-    view_path: str | None,
-) -> DashboardRenderTarget:
-    """Resolve one named Lovelace view to a canonical frontend route."""
-    base_path = dashboard_frontend_path(dashboard_url_path)
-    if view_path is None:
-        views = config.get("views")
-        has_static_views = isinstance(views, list) and bool(views)
-        if "strategy" in config:
-            warning = (
-                "No view_path was supplied; this strategy dashboard generates "
-                "its views at runtime, so only the base route is available."
-            )
-        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."
-            )
-        else:
-            warning = (
-                "No view_path was supplied and the dashboard has no static views; "
-                "only the base route is available."
-            )
-        return DashboardRenderTarget(
-            dashboard_url_path=base_path,
-            view_path=None,
-            render_path=base_path,
-            view_index=None,
-            stable=False,
-            warnings=(warning,),
-        )
-
-    cleaned_view_path = view_path
-    if not cleaned_view_path.strip():
+    view_path: str,
+    *,
+    strategy_suggestions: tuple[str, ...] = (
+        "Use dashboard_path with the frontend route instead",
+    ),
+) -> tuple[int, dict[str, Any]]:
+    """Match one named Lovelace view by its configured ``views[].path``.
+
+    Shared by screenshot view resolution and get-mode view scoping so both
+    honour identical semantics: exact match on the configured path, with
+    structured errors for an empty path, a strategy dashboard (no static
+    views to match), and a missing/ambiguous path (the not-found error lists
+    the available paths). Returns ``(view_index, view)``.
+
+    ``strategy_suggestions`` lets each caller phrase the strategy-dashboard
+    remediation in its own vocabulary (the screenshot tools have a
+    ``dashboard_path`` route parameter; config scoping does not).
+    """
+    if not view_path.strip():
         raise_tool_error(
             create_error_response(
                 ErrorCode.VALIDATION_INVALID_PARAMETER,
@@ -397,9 +383,9 @@ def resolve_dashboard_view(
                 "Strategy dashboards do not expose static named view paths.",
                 context={
                     "dashboard_url_path": dashboard_url_path,
-                    "view_path": cleaned_view_path,
+                    "view_path": view_path,
                 },
-                suggestions=["Use dashboard_path with the frontend route instead"],
+                suggestions=list(strategy_suggestions),
             )
         )
     views = config.get("views")
@@ -408,7 +394,7 @@ def resolve_dashboard_view(
     matches = [
         (index, view)
         for index, view in enumerate(views)
-        if _configured_view_path(view) == cleaned_view_path
+        if _configured_view_path(view) == view_path
     ]
     if len(matches) != 1:
         available = [
@@ -420,17 +406,57 @@ def resolve_dashboard_view(
         raise_tool_error(
             create_error_response(
                 ErrorCode.RESOURCE_NOT_FOUND,
-                f"Dashboard view path '{cleaned_view_path}' is {reason}.",
+                f"Dashboard view path '{view_path}' is {reason}.",
                 context={
                     "dashboard_url_path": dashboard_url_path,
-                    "view_path": cleaned_view_path,
+                    "view_path": view_path,
                     "available_view_paths": available,
                 },
                 suggestions=["Use a view_path returned by ha_config_get_dashboard"],
             )
         )
+    return matches[0]
+
 
-    view_index, _ = matches[0]
+def resolve_dashboard_view(
+    dashboard_url_path: str,
+    config: dict[str, Any],
+    view_path: str | None,
+) -> DashboardRenderTarget:
+    """Resolve one named Lovelace view to a canonical frontend route."""
+    base_path = dashboard_frontend_path(dashboard_url_path)
+    if view_path is None:
+        views = config.get("views")
+        has_static_views = isinstance(views, list) and bool(views)
+        if "strategy" in config:
+            warning = (
+                "No view_path was supplied; this strategy dashboard generates "
+                "its views at runtime, so only the base route is available."
+            )
+        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."
+            )
+        else:
+            warning = (
+                "No view_path was supplied and the dashboard has no static views; "
+                "only the base route is available."
+            )
+        return DashboardRenderTarget(
+            dashboard_url_path=base_path,
+            view_path=None,
+            render_path=base_path,
+            view_index=None,
+            stable=False,
+            warnings=(warning,),
+        )
+
+    view_index, _ = match_dashboard_view(dashboard_url_path, config, view_path)
+    cleaned_view_path = view_path
+    views = config.get("views")
+    if not isinstance(views, list):
+        views = []
     render_path = _safe_named_render_path(base_path, cleaned_view_path)
     if render_path is None:
         return _fallback_view_target(

{ha_mcp_dev-7.14.2.dev2093 → ha_mcp_dev-7.14.2.dev2098}/src/ha_mcp/settings_ui/_handlers_fs.py

@@ -25,6 +25,20 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _component_error_reason(exc: Exception) -> str | None:
+    """Extract the human message from a structured ``ToolError``, else None.
+
+    ``raise_tool_error`` serializes the whole error envelope into the
+    exception string, so rendering ``str(exc)`` verbatim shows the settings
+    UI a raw JSON blob behind a misleading "could not reach" prefix — the
+    hard-to-read surface from #1996. Thin seam over the shared extractor
+    (imported lazily like the other tools imports in this module).
+    """
+    from ..tools.helpers import extract_structured_error_reason
+
+    return extract_structured_error_reason(exc)
+
+
 async def _fs_custom_paths_call(
     server: HomeAssistantSmartMCPServer | None, service: str, data: dict[str, Any]
 ) -> Any:
@@ -90,7 +104,10 @@ async def _get_fs_custom_paths(
         result = await _fs_custom_paths_call(server, "get_allowed_paths", {})
     except Exception as exc:
         logger.warning("fs-custom-paths GET could not reach ha_mcp_tools: %s", exc)
-        return _unavailable(f"Could not reach the ha_mcp_tools component: {exc}")
+        return _unavailable(
+            _component_error_reason(exc)
+            or f"Could not reach the ha_mcp_tools component: {exc}"
+        )
 
     data = unwrap_service_response(result) if isinstance(result, dict) else {}
     if not isinstance(data, dict) or not data.get("success", False):
@@ -163,7 +180,8 @@ async def _save_fs_custom_paths(
         return JSONResponse(
             create_error_response(
                 ErrorCode.SERVICE_CALL_FAILED,
-                f"Could not reach the ha_mcp_tools component: {exc}",
+                _component_error_reason(exc)
+                or f"Could not reach the ha_mcp_tools component: {exc}",
             ),
             status_code=502,
         )

{ha_mcp_dev-7.14.2.dev2093 → ha_mcp_dev-7.14.2.dev2098}/src/ha_mcp/tools/backup.py

@@ -1908,12 +1908,12 @@ async def _edits_list(
     # Edits-store snapshots + pre-#1579 legacy .bak entries (#1579).
     # The manager owns the merge (sync dir-glob off-thread + async
     # legacy service call) so this layer stays source-agnostic.
-    entries = await mgr.list_edits_and_legacy(
+    entries, warnings = await mgr.list_edits_and_legacy(
         domain=domain,
         entity_id=entity_id,
         limit=limit,
     )
-    return {
+    response: dict[str, Any] = {
         "success": True,
         "data": {
             "backups": entries,
@@ -1924,6 +1924,9 @@ async def _edits_list(
             "retain_per_entity": settings.auto_backup_retain_per_entity,
         },
     }
+    if warnings:
+        response["warnings"] = warnings
+    return response
 
 
 async def _edits_view(

{ha_mcp_dev-7.14.2.dev2093 → ha_mcp_dev-7.14.2.dev2098}/src/ha_mcp/tools/helpers.py

@@ -78,6 +78,41 @@ def extract_tool_error_message(te: ToolError) -> str:
         return str(te)
 
 
+def extract_structured_error_reason(exc: BaseException) -> str | None:
+    """Extract "message" + first actionable suggestion from a structured error.
+
+    Like ``extract_tool_error_message`` but for surfaces that show the reason
+    to a human (settings UI, degraded-result warnings): it appends the first
+    suggestion when one exists, and returns ``None`` — instead of the raw
+    ``str(exc)`` JSON envelope — when the payload is not a structured error
+    or carries no usable message, so callers pick their own fallback.
+    ``create_error_response`` emits only the singular ``suggestion`` key for
+    one-suggestion errors (the plural ``suggestions`` list needs two or
+    more), so both keys are honored.
+    """
+    try:
+        payload = json.loads(str(exc))
+    except (TypeError, ValueError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    error = payload.get("error")
+    if not isinstance(error, dict):
+        return None
+    message = error.get("message")
+    if not isinstance(message, str) or not message:
+        return None
+    suggestions = error.get("suggestions")
+    first = (
+        suggestions[0]
+        if isinstance(suggestions, list) and suggestions
+        else error.get("suggestion")
+    )
+    if isinstance(first, str) and first:
+        return f"{message} {first}"
+    return message
+
+
 def validate_identifier_not_empty(
     value: str | None,
     param_name: str,