ha-mcp-dev 7.8.0.dev709__tar.gz → 7.8.0.dev711__tar.gz

{ha_mcp_dev-7.8.0.dev709/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.8.0.dev711}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.0.dev709
+Version: 7.8.0.dev711
 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.8.0.dev709 → ha_mcp_dev-7.8.0.dev711}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.8.0.dev709"
+version = "7.8.0.dev711"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.8.0.dev709 → ha_mcp_dev-7.8.0.dev711}/src/ha_mcp/backup_manager.py

@@ -991,19 +991,46 @@ async def _fetch_dashboard(client: Any, entity_id: str) -> Any:
     """
     from fastmcp.exceptions import ToolError
 
-    from .tools.tools_config_dashboards import _get_dashboard_config_internal
+    from .tools.tools_config_dashboards import (
+        _get_dashboard_config_internal,
+        _resolve_dashboard,
+    )
+
+    # The set/delete tools accept BOTH the canonical hyphenated url_path
+    # AND HA's internal (underscored) dashboard id, eagerly resolving the
+    # latter before writing. ``_get_dashboard_config_internal`` does NOT
+    # lazy-resolve, so an internal-id identifier 404s with "Unknown config
+    # specified" and the pre-write snapshot is silently skipped. Pre-resolve
+    # to the canonical url_path so capture works for whichever form the
+    # caller passed (matching the form the write tool ultimately targets).
+    fetch_path = entity_id
+    try:
+        match, _ = await _resolve_dashboard(client, entity_id)
+        if match and match.get("url_path"):
+            fetch_path = match["url_path"]
+    except (HomeAssistantError, ToolError) as err:
+        # Resolver failure (transport/shape) — fall through with the
+        # original identifier; the canonical form is often already correct.
+        logger.debug(
+            "Auto-backup: dashboard resolve failed for %r: %s — using as-is",
+            entity_id,
+            err,
+        )
 
     try:
-        config, _config_hash = await _get_dashboard_config_internal(client, entity_id)
+        config, _config_hash = await _get_dashboard_config_internal(client, fetch_path)
     except ToolError as err:
-        # ToolError carries the structured failure payload; treat
-        # missing-dashboard responses as "entity doesn't exist yet".
+        # ToolError carries the structured failure payload; treat a
+        # missing/unknown dashboard as "nothing to back up" (also covers a
+        # brand-new dashboard on the create path). "Unknown config
+        # specified" is HA's message for an unresolved url_path.
         msg = str(err).lower()
-        if "not_found" in msg or "config_not_found" in msg:
+        if "not_found" in msg or "config_not_found" in msg or "unknown config" in msg:
             return None
         raise
     except HomeAssistantError as err:
-        if "not_found" in str(err).lower() or "config_not_found" in str(err).lower():
+        msg = str(err).lower()
+        if "not_found" in msg or "config_not_found" in msg or "unknown config" in msg:
             return None
         raise
     return config
@@ -1305,8 +1332,11 @@ async def _restore_area_or_floor(client: Any, entity_id: str, config: Any) -> An
 
 
 async def _fetch_todo_item(client: Any, entity_id: str) -> Any:
-    cal, _, uid = entity_id.partition("::")
-    if not cal or not uid:
+    # The second segment is whatever the tool's ``item`` param carried.
+    # ha_set_todo_item / ha_remove_todo_item accept EITHER the item uid OR
+    # its exact summary/name, so this can be either form.
+    cal, _, item_ref = entity_id.partition("::")
+    if not cal or not item_ref:
         return None
     payload = {
         "type": "execute_script",
@@ -1332,7 +1362,11 @@ async def _fetch_todo_item(client: Any, entity_id: str) -> Any:
     result = _require_dict(result, "execute_script")
     items = result.get("response", {}).get("items", {}).get(cal, {}).get("items", [])
     for item in items:
-        if item.get("uid") == uid:
+        # Match either form. Matching only on uid silently skipped the
+        # snapshot whenever the caller passed the human-readable summary
+        # (the documented/common case, e.g. ha_remove_todo_item(list, "Buy
+        # milk")) — uid != summary, so the loop found nothing -> None.
+        if item.get("uid") == item_ref or item.get("summary") == item_ref:
             return {"todo_entity_id": cal, **item}
     return None
 
@@ -1366,6 +1400,42 @@ async def _restore_entity_state(client: Any, entity_id: str, config: Any) -> Any
     return await _rest_post(client, f"states/{entity_id}", payload)
 
 
+# Devices — config/device_registry/{list,update}. ``ha_set_device`` mutates
+# the user-editable registry fields (name_by_user / area_id / disabled_by /
+# labels); restore re-applies exactly those. A device deleted by
+# ``ha_remove_device`` cannot be recreated through the registry, so for that
+# path the snapshot is an informational pre-delete record and restore is
+# best-effort.
+
+
+async def _fetch_device(client: Any, entity_id: str) -> Any:
+    items = await _ws_send(client, {"type": "config/device_registry/list"})
+    if not isinstance(items, list):
+        return None
+    for item in items:
+        if item.get("id") == entity_id:
+            return item
+    return None
+
+
+async def _restore_device(client: Any, entity_id: str, config: Any) -> Any:
+    # Re-apply the captured registry state. Uses the same field NAMES as
+    # ``_update_device_internal`` but, unlike that partial-update path, always
+    # sends all four — restore reverts the device to the snapshot, so a
+    # captured ``None`` area/name is intentionally re-applied (cleared).
+    return await _ws_send(
+        client,
+        {
+            "type": "config/device_registry/update",
+            "device_id": entity_id,
+            "name_by_user": config.get("name_by_user"),
+            "area_id": config.get("area_id"),
+            "disabled_by": config.get("disabled_by"),
+            "labels": config.get("labels", []),
+        },
+    )
+
+
 # Integration enable/disable — restore re-applies the disabled flag.
 
 
@@ -1435,6 +1505,34 @@ async def _fetch_helper(client: Any, entity_id: str, helper_type: str) -> Any:
     for item in items:
         if item.get("id") == object_id or item.get("id") == entity_id:
             return item
+    # Fallback for renamed helpers: after an entity_id rename the object_id
+    # no longer equals the storage collection id (which stays the original
+    # create-time id == the registry unique_id), so the direct match above
+    # misses and the snapshot was silently skipped. Resolve the unique_id
+    # via the entity registry and match on that — the same key the helper
+    # update tool itself resolves to.
+    eid = entity_id if "." in entity_id else f"{helper_type}.{entity_id}"
+    try:
+        entry = await _ws_send(
+            client, {"type": "config/entity_registry/get", "entity_id": eid}
+        )
+    except HomeAssistantError as err:
+        # Only a genuine "entity not found" means there's nothing to back up;
+        # transport/auth/5xx errors must propagate so maybe_snapshot logs a
+        # WARNING rather than silently skipping. Same POLICY as _fetch_automation,
+        # but matched on the message substring because config/entity_registry/get
+        # failures arrive as a WS command error with no status_code to switch on.
+        # Best-effort: if HA's not-found wording ever changes, a real miss
+        # degrades to a WARNING + skip (never a swallowed fatal error).
+        msg = str(err).lower()
+        if "not_found" in msg or "not found" in msg:
+            return None
+        raise
+    unique_id = entry.get("unique_id") if isinstance(entry, dict) else None
+    if unique_id:
+        for item in items:
+            if str(item.get("id")) == str(unique_id):
+                return item
     return None
 
 
@@ -1505,6 +1603,7 @@ def register_default_handlers(mgr: BackupManager, _client: Any) -> None:
     )
     mgr.register(DomainHandler("todo_item", _fetch_todo_item, _restore_todo_item))
     mgr.register(DomainHandler("entity", _fetch_entity_state, _restore_entity_state))
+    mgr.register(DomainHandler("device", _fetch_device, _restore_device))
     mgr.register(DomainHandler("integration", _fetch_integration, _restore_integration))
     for helper_type in _KNOWN_HELPER_TYPES:
         mgr.register(_make_helper_handler(helper_type))

{ha_mcp_dev-7.8.0.dev709 → ha_mcp_dev-7.8.0.dev711}/src/ha_mcp/tools/auto_backup.py

@@ -75,17 +75,20 @@ def automation_backup_target(kw: dict[str, Any]) -> str:
         config_id = config.get("id")
         if config_id:
             return str(config_id)
-    identifier = _resolve_str(kw.get("identifier"))
-    # Strip the leading ``automation.`` prefix when the caller passed an
-    # entity_id form (typical for ``python_transform`` calls that don't
-    # carry a config body). Without this, snapshot files duplicate the
-    # domain segment as ``automation.automation.<slug>.<ts>.yaml`` — the
-    # body's entity_id keeps the prefix, only the filename / list key
-    # tighten up. HA's automation upsert accepts either form for the
-    # ``identifier`` param, so restore is unaffected.
-    if identifier.startswith("automation."):
-        identifier = identifier[len("automation.") :]
-    return identifier
+    # Return the identifier UNCHANGED — do NOT strip the ``automation.``
+    # prefix. Capture and restore resolve the target through
+    # ``client.get_automation_config`` -> ``_resolve_automation_id``, which
+    # converts an entity_id ("automation.<slug>") to the real numeric
+    # ``unique_id`` via a state lookup ONLY when the prefix is present;
+    # otherwise it assumes the string already IS a unique_id. Stripping the
+    # prefix produced a bare object_id slug that the resolver mis-treats as
+    # a unique_id -> GET /config/automation/config/<slug> 404s -> the
+    # pre-write snapshot is silently skipped (and, had it resolved, restore
+    # would POST to the wrong key and create a stray automation). The
+    # doubled domain segment in the snapshot filename
+    # ("automation.automation.<slug>.<ts>.yaml") is purely cosmetic and is
+    # exactly what the remove path (id_param="identifier") already produces.
+    return _resolve_str(kw.get("identifier"))
 
 
 def with_auto_backup(

{ha_mcp_dev-7.8.0.dev709 → ha_mcp_dev-7.8.0.dev711}/src/ha_mcp/tools/tools_entities.py

@@ -1316,6 +1316,7 @@ def register_entity_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             "title": "Remove Entity",
         },
     )
+    @with_auto_backup(domain="entity", id_param="entity_id", client=client)
     @log_tool_usage
     async def ha_remove_entity(
         entity_id: Annotated[

{ha_mcp_dev-7.8.0.dev709 → ha_mcp_dev-7.8.0.dev711}/src/ha_mcp/tools/tools_registry.py

@@ -14,6 +14,7 @@ from pydantic import Field
 
 from ..client.rest_client import HomeAssistantAPIError, HomeAssistantConnectionError
 from ..errors import ErrorCode, create_error_response
+from .auto_backup import with_auto_backup
 from .helpers import (
     exception_to_structured_error,
     log_tool_usage,
@@ -599,6 +600,7 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         tags={"Device Registry"},
         annotations={"destructiveHint": True, "title": "Set Device"},
     )
+    @with_auto_backup(domain="device", id_param="device_id", client=client)
     @log_tool_usage
     async def ha_set_device(
         device_id: Annotated[
@@ -700,6 +702,7 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             "title": "Remove Device",
         },
     )
+    @with_auto_backup(domain="device", id_param="device_id", client=client)
     @log_tool_usage
     async def ha_remove_device(
         device_id: Annotated[

{ha_mcp_dev-7.8.0.dev709 → ha_mcp_dev-7.8.0.dev711}/src/ha_mcp/tools/tools_utility.py

@@ -122,8 +122,14 @@ class UtilityTools:
         entity_id: str | None,
         end_time: str | None,
         slug: str | None,
+        order: Literal["newest", "oldest"],
     ) -> list[str]:
         warnings: list[str] = []
+        if source == "logger" and order != "newest":
+            warnings.append(
+                "Parameter 'order' does not apply to source='logger' "
+                "(entries are sorted by integration name); ignored"
+            )
         if source != "logbook" and any(p is not None for p in [entity_id, end_time]):
             ignored = [
                 p
@@ -200,6 +206,7 @@ class UtilityTools:
         compact: bool,
         level: str | None,
         slug: str | None,
+        order: Literal["newest", "oldest"],
     ) -> dict[str, Any]:
         if source == "logbook":
             return await self._get_logbook(
@@ -210,20 +217,29 @@ class UtilityTools:
                 offset=offset,
                 search=search,
                 compact=compact,
+                order=order,
             )
         if source == "system":
-            return await self._get_system_log(limit=limit, search=search, level=level)
+            return await self._get_system_log(
+                limit=limit, search=search, level=level, order=order
+            )
         if source == "error_log":
-            return await self._get_error_log(limit=limit, search=search, level=level)
+            return await self._get_error_log(
+                limit=limit, search=search, level=level, order=order
+            )
         if source == "logger":
+            # logger reports per-integration levels, not time-ordered events;
+            # 'order' does not apply (a warning is emitted upstream).
             return await self._get_logger_info(limit=limit, search=search)
         if source == "system_service":
             assert slug is not None  # guaranteed by _validate_log_slug
             return await self._get_system_service_log(
-                service=slug, limit=limit, search=search
+                service=slug, limit=limit, search=search, order=order
             )
         assert slug is not None  # guaranteed by _validate_log_slug
-        return await self._get_supervisor_log(slug=slug, limit=limit, search=search)
+        return await self._get_supervisor_log(
+            slug=slug, limit=limit, search=search, order=order
+        )
 
     async def get_logs(
         self,
@@ -237,9 +253,12 @@ class UtilityTools:
         compact: bool,
         level: str | None,
         slug: str | None,
+        order: Literal["newest", "oldest"] = "newest",
     ) -> dict[str, Any]:
         level = self._validate_log_level(level)
-        warnings = self._collect_log_warnings(source, level, entity_id, end_time, slug)
+        warnings = self._collect_log_warnings(
+            source, level, entity_id, end_time, slug, order
+        )
         self._validate_log_slug(source, slug)
         result = await self._fetch_log_source(
             source,
@@ -252,6 +271,7 @@ class UtilityTools:
             compact,
             level,
             slug,
+            order,
         )
         if warnings:
             result["warnings"] = warnings
@@ -277,6 +297,7 @@ class UtilityTools:
         entity_id: str | None,
         search: str | None,
         compact_bool: bool,
+        order: Literal["newest", "oldest"] = "newest",
     ) -> str:
         """Build reproducible pagination hint string for logbook results."""
         next_offset = offset_int + effective_limit
@@ -293,6 +314,8 @@ class UtilityTools:
             param_parts.append(f"search={search}")
         if not compact_bool:
             param_parts.append("compact=False")
+        if order != "newest":
+            param_parts.append(f"order={order}")
         param_str = ", ".join(param_parts)
         return (
             f"Showing entries {offset_int + 1}-{offset_int + len(paginated_entries)} of {total_entries}. "
@@ -308,6 +331,7 @@ class UtilityTools:
         offset: int = 0,
         search: str | None = None,
         compact: bool = True,
+        order: Literal["newest", "oldest"] = "newest",
     ) -> dict[str, Any]:
         """Fetch logbook entries with search and pagination."""
         hours_back_int, effective_limit, offset_int = self._coerce_logbook_params(
@@ -342,8 +366,20 @@ class UtilityTools:
             total_entries = len(response) if isinstance(response, list) else 1
 
             if isinstance(response, list):
-                paginated_entries = response[offset_int : offset_int + effective_limit]
-                has_more = (offset_int + effective_limit) < total_entries
+                # HA's /logbook returns entries oldest-first. Take a window from
+                # the end for newest-first (default), or from the start for
+                # oldest-first, with offset paging deeper in the chosen order.
+                if order == "newest":
+                    end = total_entries - offset_int
+                    start = max(end - effective_limit, 0)
+                    paginated_entries = (
+                        list(reversed(response[start:end])) if end > 0 else []
+                    )
+                else:
+                    paginated_entries = response[
+                        offset_int : offset_int + effective_limit
+                    ]
+                has_more = offset_int + len(paginated_entries) < total_entries
             else:
                 paginated_entries = response
                 has_more = False
@@ -368,6 +404,7 @@ class UtilityTools:
                 else 1,
                 "limit": effective_limit,
                 "offset": offset_int,
+                "order": order,
                 "has_more": has_more,
             }
             if filters_applied:
@@ -383,6 +420,7 @@ class UtilityTools:
                     entity_id,
                     search,
                     compact,
+                    order,
                 )
 
             return await add_timezone_metadata(self._client, logbook_data)
@@ -416,11 +454,28 @@ class UtilityTools:
             )
             raise  # unreachable: exception_to_structured_error always raises
 
+    @staticmethod
+    def _system_log_sort_key(entry: Any) -> float:
+        """Total-order-safe sort key for system_log entries.
+
+        ``system_log/list`` does not guarantee a numeric ``timestamp`` on every
+        record. Coerce a missing / non-numeric / non-dict entry to ``0.0`` so
+        sorting never raises a cross-type ``TypeError`` (bools are excluded so
+        a stray ``True`` doesn't read as ``1.0``).
+        """
+        if not isinstance(entry, dict):
+            return 0.0
+        ts = entry.get("timestamp")
+        if isinstance(ts, bool) or not isinstance(ts, (int, float)):
+            return 0.0
+        return float(ts)
+
     async def _get_system_log(
         self,
         limit: int | None = None,
         search: str | None = None,
         level: str | None = None,
+        order: Literal["newest", "oldest"] = "newest",
     ) -> dict[str, Any]:
         """Fetch structured system log entries via system_log/list."""
         effective_limit = self._coerce_limit(limit)
@@ -461,6 +516,17 @@ class UtilityTools:
                 ]
                 filters_applied["search"] = search
 
+            # system_log/list entries carry a 'timestamp' (epoch float, last
+            # occurrence), but HA does not guarantee it on every record. Sort
+            # with a total-order-safe key so 'order' is deterministic regardless
+            # of HA's native ordering (newest-first by default) and a missing /
+            # non-numeric / non-dict entry can never raise a cross-type
+            # TypeError out of this method's narrow except clause.
+            entries.sort(
+                key=self._system_log_sort_key,
+                reverse=(order == "newest"),
+            )
+
             total_entries = len(entries)
             entries = entries[:effective_limit]
 
@@ -471,6 +537,7 @@ class UtilityTools:
                 "total_entries": total_entries,
                 "returned_entries": len(entries),
                 "limit": effective_limit,
+                "order": order,
             }
             if filters_applied:
                 data["filters_applied"] = filters_applied
@@ -500,6 +567,7 @@ class UtilityTools:
         limit: int | None = None,
         search: str | None = None,
         level: str | None = None,
+        order: Literal["newest", "oldest"] = "newest",
     ) -> dict[str, Any]:
         """Fetch raw error log text from home-assistant.log."""
         effective_limit = self._coerce_limit(
@@ -527,8 +595,11 @@ class UtilityTools:
                 filters_applied["search"] = search
 
             total_lines = len(lines)
-            # Return the LAST N lines (most recent)
+            # Always take the most-recent window (the tail of the chronological
+            # file); 'order' controls only the display direction of that window.
             lines = lines[-effective_limit:]
+            if order == "newest":
+                lines = list(reversed(lines))
 
             data: dict[str, Any] = {
                 "success": True,
@@ -537,6 +608,7 @@ class UtilityTools:
                 "total_lines": total_lines,
                 "returned_lines": len(lines),
                 "limit": effective_limit,
+                "order": order,
                 "note": "Returned the most recent log lines matching filters",
             }
             if filters_applied:
@@ -665,6 +737,7 @@ class UtilityTools:
         slug: str,
         limit: int | None = None,
         search: str | None = None,
+        order: Literal["newest", "oldest"] = "newest",
     ) -> dict[str, Any]:
         """Fetch add-on container logs.
 
@@ -692,8 +765,11 @@ class UtilityTools:
                 filters_applied["search"] = search
 
             total_lines = len(lines)
-            # Return the LAST N lines (most recent)
+            # Always take the most-recent window (the tail); 'order' controls
+            # only the display direction of that window.
             lines = lines[-effective_limit:]
+            if order == "newest":
+                lines = list(reversed(lines))
 
             data: dict[str, Any] = {
                 "success": True,
@@ -703,6 +779,7 @@ class UtilityTools:
                 "total_lines": total_lines,
                 "returned_lines": len(lines),
                 "limit": effective_limit,
+                "order": order,
             }
             if filters_applied:
                 data["filters_applied"] = filters_applied
@@ -797,6 +874,7 @@ class UtilityTools:
         service: str,
         limit: int | None = None,
         search: str | None = None,
+        order: Literal["newest", "oldest"] = "newest",
     ) -> dict[str, Any]:
         """Fetch HA system-service logs from Supervisor's per-service endpoint.
 
@@ -826,8 +904,11 @@ class UtilityTools:
                 filters_applied["search"] = search
 
             total_lines = len(lines)
-            # Return the LAST N lines (most recent)
+            # Always take the most-recent window (the tail); 'order' controls
+            # only the display direction of that window.
             lines = lines[-effective_limit:]
+            if order == "newest":
+                lines = list(reversed(lines))
 
             data: dict[str, Any] = {
                 "success": True,
@@ -837,6 +918,7 @@ class UtilityTools:
                 "total_lines": total_lines,
                 "returned_lines": len(lines),
                 "limit": effective_limit,
+                "order": order,
             }
             if filters_applied:
                 data["filters_applied"] = filters_applied
@@ -1035,6 +1117,17 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         # Shared parameters
         limit: int | None = None,
         search: str | None = None,
+        order: Annotated[
+            Literal["newest", "oldest"],
+            Field(
+                description=(
+                    "Sort order for time-ordered sources (logbook, system, "
+                    "error_log, supervisor, system_service): 'newest' (default) "
+                    "returns most-recent first; 'oldest' returns chronological-"
+                    "first. Ignored for source='logger'."
+                )
+            ),
+        ] = "newest",
         # Logbook-specific (ignored for other sources)
         hours_back: Annotated[int, Field(ge=1)] = 1,
         entity_id: str | None = None,
@@ -1059,6 +1152,7 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         - "logger": Effective log level per integration via logger/log_info (confirms logger.set_level changes took effect)
 
         **Shared params:** limit, search (keyword filter on entries/lines; matches integration domain for source='logger')
+        **Order:** order='newest' (default) returns most-recent first; order='oldest' returns chronological-first. Applies to all time-ordered sources (logbook, system, error_log, supervisor, system_service); ignored for source='logger'. For raw-text sources (error_log, supervisor, system_service) it sets the read direction of the most-recent window.
         **Logbook params:** hours_back, entity_id, end_time, offset, compact (default True — strips attribute dicts to save context)
         **System/error_log params:** level (ERROR, WARNING, INFO, DEBUG)
         **Supervisor params:** slug = add-on slug, e.g. "core_mosquitto" (use
@@ -1078,6 +1172,7 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             compact=compact,
             level=level,
             slug=slug,
+            order=order,
         )
 
     @mcp.tool(

{ha_mcp_dev-7.8.0.dev709 → ha_mcp_dev-7.8.0.dev711/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.0.dev709
+Version: 7.8.0.dev711
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT