ha-mcp-dev 8.4.3.dev2572__tar.gz → 8.4.3.dev2576__tar.gz

{ha_mcp_dev-8.4.3.dev2572/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.3.dev2576}/PKG-INFO

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

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2576}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.3.dev2572"
+version = "8.4.3.dev2576"
 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-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2576}/src/ha_mcp/tools/smart_search/_overview.py

@@ -21,6 +21,18 @@ logger = logging.getLogger(__name__)
 class SystemOverviewMixin(_SearchBase):
     """``get_system_overview`` and its analysis/format/paginate helpers."""
 
+    async def _fetch_legacy_overview_slices(self) -> list[Any]:
+        """Fetch broad legacy slices in parallel after states succeeds."""
+        states = await self.client.get_states()
+        optional_results = await asyncio.gather(
+            self.client.get_services(),
+            self.client.send_websocket_message({"type": "config/area_registry/list"}),
+            self.client.send_websocket_message({"type": "config/entity_registry/list"}),
+            self.client.send_websocket_message({"type": "config/device_registry/list"}),
+            return_exceptions=True,
+        )
+        return [states, *optional_results]
+
     async def get_system_overview(
         self,
         detail_level: str = "standard",
@@ -76,29 +88,10 @@ class SystemOverviewMixin(_SearchBase):
                     prefetched_slices["device_registry"],
                 ]
             else:
-                # Fetch all data in parallel. return_exceptions=True so a degraded
-                # registry/service fetch doesn't abort the whole overview.
-                results = await asyncio.gather(
-                    self.client.get_states(),
-                    self.client.get_services(),
-                    self.client.send_websocket_message(
-                        {"type": "config/area_registry/list"}
-                    ),
-                    self.client.send_websocket_message(
-                        {"type": "config/entity_registry/list"}
-                    ),
-                    self.client.send_websocket_message(
-                        {"type": "config/device_registry/list"}
-                    ),
-                    return_exceptions=True,
-                )
+                # Fetch mandatory states first, then read optional slices in
+                # parallel; optional failures degrade independently below.
+                results = await self._fetch_legacy_overview_slices()
 
-            # Entities are mandatory — surface connection/auth errors immediately.
-            # Use BaseException so a cancelled states fetch propagates instead of
-            # being assigned to `entities` and crashing downstream iteration
-            # (mirrors get_entities_by_area / _fetch_search_entities).
-            if isinstance(results[0], BaseException):
-                raise results[0]
             entities = results[0]
             # A cancelled services/registry sub-task must propagate too, not be
             # silently degraded by the fail-open handlers below.

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2576}/src/ha_mcp/tools/tools_search.py

@@ -1558,6 +1558,51 @@ class _OverviewSlices:
     repairs: dict[str, Any]
 
 
+# These disjoint sets partition every key documented by ha_get_overview's
+# fields parameter. Keep the manifest test in sync when the public schema changes.
+_OVERVIEW_INDEPENDENT_FIELDS = frozenset(
+    {
+        "success",
+        "system_info",
+        "notification_count",
+        "notifications",
+        "repair_count",
+        "dismissed_repair_count",
+        "repairs",
+        "repairs_error",
+        "tool_discovery",
+        "settings_url",
+        "settings_url_hint",
+        "read_only_mode",
+        "read_only_mode_hint",
+        "ha_mcp_update",
+    }
+)
+_OVERVIEW_NOTIFICATION_FIELDS = frozenset({"notification_count", "notifications"})
+_OVERVIEW_REPAIR_FIELDS = frozenset(
+    {
+        "repair_count",
+        "dismissed_repair_count",
+        "repairs",
+        "repairs_error",
+    }
+)
+_OVERVIEW_ENTITY_FIELDS = frozenset(
+    {
+        "system_summary",
+        "domain_stats",
+        "area_analysis",
+        "ai_insights",
+        "pagination",
+        "partial",
+        "warnings",
+        "device_types",
+        "service_availability",
+    }
+)
+_OVERVIEW_AVAILABLE_FIELDS = _OVERVIEW_INDEPENDENT_FIELDS | _OVERVIEW_ENTITY_FIELDS
+
+
 def _build_component_overview_request(inputs: _OverviewInputs) -> dict[str, Any]:
     """Translate resolved ha_get_overview inputs into an ``ha_mcp_tools/overview`` request.
 
@@ -4045,7 +4090,7 @@ class SearchTools:
                 default=None,
                 description=(
                     "Return only the specified top-level response keys to reduce "
-                    'response size (e.g. ["system_info", "domains"]). '
+                    'response size (e.g. ["system_info", "domain_stats"]). '
                     "None = full response (default). "
                     "Available keys: success, system_summary, domain_stats, "
                     "area_analysis, ai_insights, pagination, partial, warnings, "
@@ -4078,6 +4123,14 @@ class SearchTools:
         Use fields= to project the response to only the keys you need — a
         significantly smaller payload when fetching a single sub-section (e.g.
         fields=["system_info"] returns just that section instead of the full overview).
+        Requests composed only of system_info, notification, repair, or server
+        metadata fields also skip the unrelated state, service, and registry reads.
+
+        Do not use this tool to inspect a known entity or a narrow set of entities.
+        Use ha_get_state for one entity, ha_get_entity for registry metadata, or
+        ha_search with a domain or area filter. An unprojected overview collects
+        system-wide state, service, and registry data and can be expensive on large
+        Home Assistant installations.
 
         When (and only when) the ha-mcp settings-UI sidecar is running
         (stdio mode, e.g. Claude Desktop / Claude Code), the response
@@ -4126,19 +4179,32 @@ class SearchTools:
         except ValueError as exc:
             raise_tool_error(create_validation_error(str(exc), parameter="domains"))
 
-        result = await self._collect_overview(
-            _OverviewInputs(
+        requested_fields = set(parsed_fields or [])
+        recognized_fields = requested_fields & _OVERVIEW_INDEPENDENT_FIELDS
+        use_independent_collectors = (
+            parsed_fields is not None and not requested_fields & _OVERVIEW_ENTITY_FIELDS
+        )
+        if use_independent_collectors:
+            result = await self._collect_independent_overview(
+                requested_fields=recognized_fields,
                 detail_level=detail_level,
-                max_entities_per_domain=max_entities_per_domain,
-                include_state=include_state_bool,
-                include_entity_id=include_entity_id_bool,
-                domains_filter=parsed_domains,
-                limit=limit,
-                offset=offset,
                 include_notifications=include_notifications_bool,
                 include_dismissed_repairs=include_dismissed_repairs_bool,
             )
-        )
+        else:
+            result = await self._collect_overview(
+                _OverviewInputs(
+                    detail_level=detail_level,
+                    max_entities_per_domain=max_entities_per_domain,
+                    include_state=include_state_bool,
+                    include_entity_id=include_entity_id_bool,
+                    domains_filter=parsed_domains,
+                    limit=limit,
+                    offset=offset,
+                    include_notifications=include_notifications_bool,
+                    include_dismissed_repairs=include_dismissed_repairs_bool,
+                )
+            )
 
         settings = get_global_settings()
         if settings.enable_tool_search:
@@ -4170,7 +4236,11 @@ class SearchTools:
         # (issue #863).
         from ..stdio_settings_sidecar import read_sidecar_url
 
-        projected = project_fields(result, parsed_fields)
+        projected = project_fields(
+            result,
+            parsed_fields,
+            available_fields=_OVERVIEW_AVAILABLE_FIELDS,
+        )
         sidecar_url = read_sidecar_url()
         if sidecar_url:
             projected["settings_url"] = sidecar_url
@@ -4215,6 +4285,32 @@ class SearchTools:
 
         return projected
 
+    async def _collect_independent_overview(
+        self,
+        *,
+        requested_fields: set[str],
+        detail_level: str,
+        include_notifications: bool,
+        include_dismissed_repairs: bool,
+    ) -> dict[str, Any]:
+        """Collect requested independent sections with full-path error semantics."""
+        result: dict[str, Any] = {"success": True}
+        if "system_info" in requested_fields:
+            await self._fetch_system_info(result, detail_level)
+        if requested_fields & _OVERVIEW_NOTIFICATION_FIELDS:
+            if include_notifications:
+                await self._fetch_notifications(result)
+            else:
+                result.setdefault("warnings", []).append(
+                    "notifications omitted: include_notifications=False"
+                )
+        if requested_fields & _OVERVIEW_REPAIR_FIELDS:
+            await self._fetch_repairs(
+                result,
+                include_dismissed_repairs,
+            )
+        return result
+
     async def _fetch_system_info(
         self,
         result: dict[str, Any],
@@ -4222,7 +4318,7 @@ class SearchTools:
         *,
         prefetched_config: dict[str, Any] | None = None,
     ) -> None:
-        """Populate result['system_info'] from HA config; tolerates failure.
+        """Populate result['system_info'] from HA config, warning on failure.
 
         ``prefetched_config`` (the component's ``config`` slice, already the bare
         ``get_config()`` dict) is used verbatim when given, skipping the fetch.
@@ -4268,6 +4364,7 @@ class SearchTools:
             logger.warning(
                 "Failed to fetch system info for overview: %s", e, exc_info=True
             )
+            result.setdefault("warnings", []).append(f"system info unavailable: {e}")
             if "system_summary" in result:
                 result["system_summary"].setdefault("version", "unknown")
 
@@ -4277,7 +4374,7 @@ class SearchTools:
         *,
         prefetched_notifications: dict[str, Any] | None = None,
     ) -> None:
-        """Attach active persistent notifications to result.
+        """Attach active persistent notifications, warning on failure.
 
         ``prefetched_notifications`` (the component's ``notifications`` slice
         re-wrapped in the ``{success, result}`` envelope) is unwrapped by the same
@@ -4331,7 +4428,7 @@ class SearchTools:
         *,
         prefetched_repairs: dict[str, Any] | None = None,
     ) -> None:
-        """Attach active repairs issues to result.
+        """Attach active repairs issues, recording failures in repairs_error.
 
         ``prefetched_repairs`` (the component's ``repairs`` slice re-wrapped in the
         ``{success, result: {issues: [...]}}`` envelope) is unwrapped, filtered

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2576}/src/ha_mcp/tools/util_helpers.py

@@ -390,6 +390,7 @@ def project_fields(
     fields: str | list[str] | None,
     *,
     extra_always_keep: frozenset[str] | None = None,
+    available_fields: frozenset[str] | None = None,
 ) -> dict[str, Any]:
     """Apply optional field projection to a response data dict.
 
@@ -401,6 +402,10 @@ def project_fields(
     contract / diagnostic keys (e.g. the orchestrator's pagination + partial-
     state keys) without having to reimplement the projection logic.
 
+    ``available_fields`` supplies the complete response schema when *data* was
+    collected narrowly. It affects typo diagnostics only; projection still
+    returns only keys present in *data*.
+
     Typo guard: if any requested key does not exist in *data* (excluding the
     always-retained keys), a diagnostic is appended to ``result["warnings"]``
     listing the unknown keys and the available ones.  This mirrors the
@@ -417,9 +422,10 @@ def project_fields(
     result = {k: v for k, v in data.items() if k in keep}
     # Typo guard — flag any requested keys that are absent from the response.
     # Exclude the always-retained sentinels so fields=["success"] never warns.
-    unknown = sorted(set(parsed) - set(data.keys()) - always_keep)
+    known_fields = set(available_fields) if available_fields is not None else set(data)
+    unknown = sorted(set(parsed) - known_fields - always_keep)
     if unknown:
-        available = sorted(k for k in data.keys() if k not in always_keep)
+        available = sorted(k for k in known_fields if k not in always_keep)
         result.setdefault("warnings", []).append(
             f"fields {unknown!r} not found in response — available keys: {available!r}"
         )

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2576/src/ha_mcp_dev.egg-info}/PKG-INFO

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