ha-mcp-dev 9.0.0.dev3096__tar.gz → 9.0.0.dev3101__tar.gz

{ha_mcp_dev-9.0.0.dev3096 → ha_mcp_dev-9.0.0.dev3101}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.0.0.dev3096
+Version: 9.0.0.dev3101
 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.0.dev3096 → ha_mcp_dev-9.0.0.dev3101}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.0.0.dev3096"
+version = "9.0.0.dev3101"
 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.0.dev3096 → ha_mcp_dev-9.0.0.dev3101}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.0.0.dev3096"
+version = "9.0.0.dev3101"
 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.0.dev3101/src/ha_mcp/client/models.py

@@ -0,0 +1,18 @@
+"""Frozen value types shared by the client and its tool consumers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ErrorLogPage:
+    """One bounded window of the error log, plus whether older history exists.
+
+    ``has_more`` cannot be derived by the caller from ``text``: a journald
+    window that comes back full may or may not have anything behind it (see
+    ``_journald_error_log_page``), and only the fetching route knows which.
+    """
+
+    text: str
+    has_more: bool

{ha_mcp_dev-9.0.0.dev3096 → ha_mcp_dev-9.0.0.dev3101}/src/ha_mcp/client/rest_client.py

@@ -18,6 +18,7 @@ from .._vendor.websockets.exceptions import WebSocketException
 from .._version import get_supervisor_base_url, is_running_in_addon
 from ..config import get_global_settings
 from .admin_routes import is_admin_only_route
+from .models import ErrorLogPage
 from .supervisor_client import make_supervisor_httpx_client
 
 
@@ -147,19 +148,6 @@ class HomeAssistantAPIError(HomeAssistantError):
         self.response_data = response_data
 
 
-@dataclass(frozen=True)
-class ErrorLogPage:
-    """One bounded window of the error log, plus whether older history exists.
-
-    ``has_more`` cannot be derived by the caller from ``text``: a journald
-    window that comes back full may or may not have anything behind it (see
-    ``_journald_error_log_page``), and only the fetching route knows which.
-    """
-
-    text: str
-    has_more: bool
-
-
 @dataclass(frozen=True)
 class SceneResolution:
     """Outcome of resolving a scene identifier via the entity registry.
@@ -831,6 +819,7 @@ class HomeAssistantClient:
         entity_id: str | None = None,
         start_time: str | None = None,
         end_time: str | None = None,
+        context_id: str | None = None,
     ) -> list[dict[str, Any]]:
         """
         Get logbook entries.
@@ -839,12 +828,13 @@ class HomeAssistantClient:
             entity_id: Optional entity ID to filter
             start_time: Optional start time (ISO format) - used as URL path component
             end_time: Optional end time (ISO format) - used as query parameter
+            context_id: Optional context ID filter - used as query parameter
 
         Returns:
             Logbook entries
         """
         logger.debug(
-            f"Fetching logbook entries for entity: {entity_id}, start: {start_time}, end: {end_time}"
+            f"Fetching logbook entries for entity: {entity_id}, start: {start_time}, end: {end_time}, context: {context_id}"
         )
 
         # Build endpoint - start_time goes in URL path if provided
@@ -859,6 +849,8 @@ class HomeAssistantClient:
             params["entity"] = entity_id
         if end_time:
             params["end_time"] = end_time
+        if context_id:
+            params["context_id"] = context_id
 
         result = await self._request("GET", endpoint, params=params)
         if isinstance(result, list):
@@ -958,6 +950,7 @@ class HomeAssistantClient:
                 "Accept": "text/plain",
                 "Range": self._journald_range_header(lines, offset),
             },
+            params={"no_colors": "true"},
         )
         return response.text
 
@@ -1235,7 +1228,10 @@ class HomeAssistantClient:
                     "GET",
                     f"/hassio/{path}/logs",
                     headers={"Accept": "text/plain"},
-                    params={"lines": lines} if lines is not None else None,
+                    params={
+                        "no_colors": "true",
+                        **({"lines": lines} if lines is not None else {}),
+                    },
                 )
         except TimeoutError as e:
             raise HomeAssistantConnectionError(
@@ -1278,7 +1274,7 @@ class HomeAssistantClient:
 
         - ``"addons/<slug>"`` for app (add-on) container logs
         - ``"<service>"`` (where service ∈ {supervisor, host, core, dns, audio,
-          cli, multicast, observer}) for system-service logs
+          multicast}) for system-service logs
 
         ``lines`` maps to the endpoint's ``?lines=`` journald-window query
         param; omitted → Supervisor's 100-line default window. Adding
@@ -1326,13 +1322,16 @@ class HomeAssistantClient:
 
         relative_path = f"/{path}/logs"
         headers = {"Accept": "text/plain"}
-        params = {"lines": lines} if lines is not None else None
+        # Presence-triggered flag: journald output carries ANSI escapes otherwise.
+        params: dict[str, Any] = {"no_colors": "true"}
+        if lines is not None:
+            params["lines"] = lines
         if offset is not None:
             # An offset window with no size asked for falls back to the
             # smallest one the Range syntax can express.
             size = lines if lines is not None else MIN_LOG_WINDOW_LINES
             headers["Range"] = self._journald_range_header(size, offset)
-            params = None
+            params.pop("lines", None)
         logger.debug(
             "Fetching %s%s via Supervisor direct (%s)",
             get_supervisor_base_url(),
@@ -1419,11 +1418,11 @@ class HomeAssistantClient:
     ) -> str:
         """Fetch HA system-service logs.
 
-        ``service`` must be one of the eight Supervisor-managed services:
-        ``supervisor``, ``host``, ``core``, ``dns``, ``audio``, ``cli``,
-        ``multicast``, ``observer``. Caller is responsible for validating
-        ``service``; this helper performs no validation, and unsupported paths
-        are rejected by the selected direct-Supervisor or Core-proxy route.
+        ``service`` must be one of the six Supervisor-managed services:
+        ``supervisor``, ``host``, ``core``, ``dns``, ``audio``, ``multicast``.
+        Caller is responsible for validating ``service``; this helper performs
+        no validation, and unsupported paths are rejected by the selected
+        direct-Supervisor or Core-proxy route.
 
         Branch on ``is_running_in_addon()`` — mirror of ``get_addon_logs``:
         inside the app (add-on) container goes directly to Supervisor at
@@ -1433,10 +1432,9 @@ class HomeAssistantClient:
         without Supervisor, pip pointing at a normal HA URL),
         falls back to the HA Core proxy at ``/api/hassio/{service}/logs``.
 
-        All eight service slugs are whitelisted in HA Core's hassio proxy
-        (``homeassistant/components/hassio/http.py`` — ``PATHS_ADMIN``), so
-        an admin LLA is sufficient to reach any of them from outside the
-        app.
+        HA Core's hassio proxy accepts ``/cli`` and ``/observer`` too, but
+        Supervisor serves no log route for either, so those always 404; the
+        six slugs here are the ones with a real ``/<slug>/logs`` route.
         """
         if is_running_in_addon():
             return await self._supervisor_logs_get(service, lines=lines)

{ha_mcp_dev-9.0.0.dev3096 → ha_mcp_dev-9.0.0.dev3101}/src/ha_mcp/tools/log_common.py

@@ -28,12 +28,14 @@ COMPACT_LOGBOOK_FIELDS = {
 }
 
 
-# Supervisor-managed system services exposed via /<slug>/logs. Set mirrors
-# HA Core's hassio HTTP proxy ``PATHS_ADMIN`` whitelist in
-# ``homeassistant/components/hassio/http.py``. See #1116 (original 7-service
-# scope) and #1260 (cli added — proxy supported it the whole time).
+# Supervisor-managed system services exposed via /<slug>/logs. The set is
+# Supervisor's own route list (its ``_register_advanced_logs`` call sites),
+# not HA Core's hassio proxy allowlist: the proxy accepts /cli and /observer
+# but Supervisor serves no log route for either, so they always 404. See
+# #1116 (original seven-service scope, observer included) and #1260 (cli added
+# off the proxy list).
 SYSTEM_SERVICE_SLUGS = frozenset(
-    {"supervisor", "host", "core", "dns", "audio", "cli", "multicast", "observer"}
+    {"supervisor", "host", "core", "dns", "audio", "multicast"}
 )
 
 DEFAULT_LIMIT = 50
@@ -106,6 +108,8 @@ def _collect_log_warnings(
     source: str,
     level: str | None,
     entity_id: str | None,
+    device_id: str | None,
+    context_id: str | None,
     end_time: str | None,
     slug: str | None,
     order: Literal["newest", "oldest"],
@@ -117,10 +121,17 @@ def _collect_log_warnings(
             "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]):
+    if source != "logbook" and any(
+        p is not None for p in [entity_id, device_id, context_id, end_time]
+    ):
         ignored = [
             p
-            for p, v in [("entity_id", entity_id), ("end_time", end_time)]
+            for p, v in [
+                ("entity_id", entity_id),
+                ("device_id", device_id),
+                ("context_id", context_id),
+                ("end_time", end_time),
+            ]
             if v is not None
         ]
         warnings.append(

{ha_mcp_dev-9.0.0.dev3096 → ha_mcp_dev-9.0.0.dev3101}/src/ha_mcp/tools/log_sources.py

@@ -1,17 +1,17 @@
 """Log sources served by ``ha_get_logs`` from Home Assistant itself.
 
-Logbook, ``system_log``, the raw/structured error log, and the per-integration
-logger levels. Mixed into ``LogTools`` (``tools_logs``) rather than standing
-alone: every fetcher here is a thin shell around one client call, and the
-dispatch, validation and tool registration they share live with the host class.
-The Supervisor-backed sources are in ``log_sources_supervisor``.
+``system_log``, the raw/structured error log, and the per-integration logger
+levels. The logbook lives in ``log_sources_logbook``; the Supervisor-backed
+sources are in ``log_sources_supervisor``. Mixed into ``LogTools``
+(``tools_logs``) rather than standing alone: every fetcher here is a thin shell
+around one client call, and the dispatch, validation and tool registration they
+share live with the host class.
 
 Split out of ``tools_utility`` under `.gemini/styleguide.md` § Tool
 Consolidation and Module Size.
 """
 
 import logging
-from datetime import UTC, datetime, timedelta
 from typing import Any, Literal
 
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
@@ -37,9 +37,7 @@ from .log_common import (
     DEFAULT_LOG_LIMIT,
     _addon_auth_error_suggestions,
     _coerce_limit,
-    _compact_logbook_entries,
 )
-from .response_helpers import add_timezone_metadata
 from .util_helpers import normalize_log_level
 
 logger = logging.getLogger(__name__)
@@ -112,233 +110,6 @@ class CoreLogSourcesMixin:
 
     _client: Any
 
-    @staticmethod
-    def _coerce_logbook_params(
-        hours_back: int,
-        limit: int | None,
-        offset: int,
-    ) -> tuple[int, int, int]:
-        effective_limit = _coerce_limit(limit)
-        return hours_back, effective_limit, offset
-
-    @staticmethod
-    def _build_pagination_hint(
-        offset_int: int,
-        effective_limit: int,
-        total_entries: int,
-        paginated_entries: Any,
-        hours_back_int: int,
-        end_time: str | None,
-        entity_id: str | None,
-        search: str | None,
-        compact_bool: bool,
-        order: Literal["newest", "oldest"] = "newest",
-    ) -> str:
-        """Build reproducible pagination hint string for logbook results.
-
-        String values are quoted: the hint is meant to be copied back as a
-        call, and an unquoted ``search=front door`` is not one.
-        """
-        next_offset = offset_int + effective_limit
-        param_parts = [
-            f"hours_back={hours_back_int}",
-            f"limit={effective_limit}",
-            f"offset={next_offset}",
-        ]
-        if entity_id:
-            param_parts.append(f"entity_id={entity_id!r}")
-        if end_time:
-            param_parts.append(f"end_time={end_time!r}")
-        if search:
-            param_parts.append(f"search={search!r}")
-        if not compact_bool:
-            param_parts.append("compact=False")
-        if order != "newest":
-            param_parts.append(f"order={order!r}")
-        param_str = ", ".join(param_parts)
-        return (
-            f"Showing entries {offset_int + 1}-{offset_int + len(paginated_entries)} of {total_entries}. "
-            f"To get the next page, use: ha_get_logs({param_str})"
-        )
-
-    @staticmethod
-    def _filter_logbook_by_search(
-        response: Any, search: str | None
-    ) -> tuple[Any, dict[str, str]]:
-        """Filter logbook entries by search term across name/message/entity_id.
-
-        Returns the (possibly filtered) response and a filters_applied dict
-        recording which filters were used.
-        """
-        filters_applied: dict[str, str] = {}
-        if search and isinstance(response, list):
-            search_lower = search.lower()
-            response = [
-                e
-                for e in response
-                if isinstance(e, dict)
-                and (
-                    search_lower in str(e.get("name", "")).lower()
-                    or search_lower in str(e.get("message", "")).lower()
-                    or search_lower in str(e.get("entity_id", "")).lower()
-                )
-            ]
-            filters_applied["search"] = search
-        return response, filters_applied
-
-    @staticmethod
-    def _paginate_logbook_entries(
-        response: Any,
-        offset_int: int,
-        effective_limit: int,
-        order: Literal["newest", "oldest"],
-    ) -> tuple[Any, int, bool]:
-        """Slice logbook entries into the requested page.
-
-        HA's /logbook returns entries oldest-first. Takes a window from
-        the end for newest-first (default), or from the start for
-        oldest-first, with offset paging deeper in the chosen order.
-        """
-        total_entries = len(response) if isinstance(response, list) else 1
-
-        if isinstance(response, list):
-            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
-
-        return paginated_entries, total_entries, has_more
-
-    @staticmethod
-    def _logbook_error_suggestions(error_str: str) -> list[str]:
-        """Build remediation suggestions for a logbook fetch failure.
-
-        Adds server-crash-specific guidance when the error indicates a 500
-        (heavy query causing HA to fail) on top of the general tips.
-        """
-        if "500" in error_str:
-            return [
-                "The query returned too many results causing a server error (500).",
-                "This often happens with very active entities or long time periods.",
-                "Try reducing 'hours_back' parameter (e.g., from 24 to 1 hour)",
-                "Add a specific 'entity_id' filter to narrow down results",
-                "If debugging an automation, filter by that automation's entity_id",
-                "Use ha_report_issue to check Home Assistant logs for crash details",
-            ]
-        return [
-            "Try reducing 'hours_back' parameter (e.g., from 24 to 1 hour)",
-            "Add a specific 'entity_id' filter to narrow down results",
-        ]
-
-    async def _get_logbook(
-        self,
-        hours_back: int = 1,
-        entity_id: str | None = None,
-        end_time: str | None = None,
-        limit: int | None = None,
-        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(
-            hours_back, limit, offset
-        )
-
-        if end_time:
-            try:
-                end_dt = datetime.fromisoformat(end_time.replace("Z", "+00:00"))
-            except ValueError:
-                # Outside the fetch try-block below, so without this guard the
-                # raw ValueError would bypass the structured ToolError shape.
-                raise_tool_error(
-                    create_error_response(
-                        ErrorCode.VALIDATION_INVALID_PARAMETER,
-                        f"Invalid end_time '{end_time}': not an ISO 8601 timestamp",
-                        suggestions=[
-                            "Use ISO format, e.g. end_time='2026-08-28T01:00:00Z'"
-                        ],
-                    )
-                )
-        else:
-            end_dt = datetime.now(UTC)
-
-        start_dt = end_dt - timedelta(hours=hours_back_int)
-        start_timestamp = start_dt.isoformat()
-
-        try:
-            response = await self._client.get_logbook(
-                entity_id=entity_id, start_time=start_timestamp, end_time=end_time
-            )
-
-            response, filters_applied = self._filter_logbook_by_search(response, search)
-
-            paginated_entries, total_entries, has_more = self._paginate_logbook_entries(
-                response, offset_int, effective_limit, order
-            )
-
-            # In compact mode, strip entries to essential fields only.
-            # This prevents full attribute dictionaries from exhausting
-            # the LLM context window during debugging workflows.
-            if compact and isinstance(paginated_entries, list):
-                paginated_entries = _compact_logbook_entries(paginated_entries)
-
-            logbook_data: dict[str, Any] = {
-                "success": True,
-                "source": "logbook",
-                "entries": paginated_entries,
-                "period": f"{hours_back_int} hours back from {end_dt.isoformat()}",
-                "start_time": start_timestamp,
-                "end_time": end_dt.isoformat(),
-                "entity_filter": entity_id,
-                "total_entries": total_entries,
-                "returned_entries": len(paginated_entries)
-                if isinstance(paginated_entries, list)
-                else 1,
-                "limit": effective_limit,
-                "offset": offset_int,
-                "order": order,
-                "has_more": has_more,
-            }
-            if filters_applied:
-                logbook_data["filters_applied"] = filters_applied
-            if has_more:
-                logbook_data["pagination_hint"] = self._build_pagination_hint(
-                    offset_int,
-                    effective_limit,
-                    total_entries,
-                    paginated_entries,
-                    hours_back_int,
-                    end_time,
-                    entity_id,
-                    search,
-                    compact,
-                    order,
-                )
-
-            return await add_timezone_metadata(self._client, logbook_data)
-
-        except ToolError:
-            raise
-        except Exception as e:
-            exception_to_structured_error(
-                e,
-                context={
-                    "period": f"{hours_back_int} hours back from {end_dt.isoformat()}",
-                },
-                suggestions=self._logbook_error_suggestions(str(e)),
-            )
-            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.