ha-mcp-dev 8.4.2.dev2530__tar.gz → 8.4.2.dev2534__tar.gz

{ha_mcp_dev-8.4.2.dev2530/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.2.dev2534}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.2.dev2530
+Version: 8.4.2.dev2534
 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.2.dev2530 → ha_mcp_dev-8.4.2.dev2534}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.2.dev2530"
+version = "8.4.2.dev2534"
 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.2.dev2530 → ha_mcp_dev-8.4.2.dev2534}/src/ha_mcp/tools/bulk_selector.py

@@ -13,6 +13,11 @@ from typing import Annotated, Any, NamedTuple, NotRequired, TypedDict
 from pydantic import ConfigDict, Field
 
 from ..client.rest_client import HomeAssistantClient
+from ..utils.device_registry_semantics import (
+    DeviceRegistrySnapshot,
+    build_device_registry_snapshot,
+    effective_entity_area_id,
+)
 from ..utils.domain_handlers import get_domain_handler
 from ..utils.entity_membership import normalize_member_entity_ids
 from ..visibility.resolver import VisibilityDataUnavailable, load_hidden_set
@@ -259,8 +264,10 @@ def _registry_rows(result: Any, label: str) -> list[dict[str, Any]]:
     return rows
 
 
-def _validate_device_registry_rows(device_rows: list[dict[str, Any]]) -> None:
-    """Fail closed on a device row missing ``id``.
+def _validate_device_registry_rows(
+    device_rows: list[dict[str, Any]],
+) -> DeviceRegistrySnapshot:
+    """Return a canonical snapshot or fail closed on ambiguous device evidence.
 
     ``visibility.resolver._parse_device_registry`` silently skips any device
     entry without an ``id`` even when the hidden-set resolver runs
@@ -272,11 +279,18 @@ def _validate_device_registry_rows(device_rows: list[dict[str, Any]]) -> None:
     resolver. Infrastructure-class (HA's own registry data is malformed),
     not the caller's selector to fix.
     """
-    if any(not row.get("id") for row in device_rows):
+    if any(not isinstance(row.get("id"), str) or not row["id"] for row in device_rows):
         raise BulkSelectorInfrastructureError(
             "Home Assistant device registry returned a malformed entry",
             cause=InfrastructureErrorCause.MALFORMED_DEVICE_REGISTRY,
         )
+    snapshot = build_device_registry_snapshot(device_rows)
+    if snapshot.conflicting_ids:
+        raise BulkSelectorInfrastructureError(
+            "Home Assistant device registry returned a conflicting device identity",
+            cause=InfrastructureErrorCause.MALFORMED_DEVICE_REGISTRY,
+        )
+    return snapshot
 
 
 def _string_list(selector: Mapping[str, Any], key: str) -> list[str]:
@@ -305,10 +319,7 @@ def _entity_area_id(
     entry = entity_registry.get(entity_id)
     if not entry:
         return None
-    if area_id := entry.get("area_id"):
-        return str(area_id)
-    device_id = entry.get("device_id")
-    return device_areas.get(str(device_id)) if device_id else None
+    return effective_entity_area_id(entry, device_areas)
 
 
 def _expand_entity(
@@ -686,7 +697,7 @@ async def resolve_bulk_selector(
         )
     entity_rows = _registry_rows(topology.entities, "entity registry")
     device_rows = _registry_rows(topology.devices, "device registry")
-    _validate_device_registry_rows(device_rows)
+    device_snapshot = _validate_device_registry_rows(device_rows)
     selected_areas = _select_area_ids(
         _registry_rows(topology.areas, "area registry"),
         _registry_rows(topology.floors, "floor registry"),
@@ -704,9 +715,7 @@ async def resolve_bulk_selector(
         for row in entity_rows
         if isinstance(row.get("entity_id"), str)
     }
-    device_areas = {
-        str(row["id"]): row.get("area_id") for row in device_rows if row.get("id")
-    }
+    device_areas = device_snapshot.effective_area_by_id
     hidden, visibility_warnings = await _load_hidden_entities(
         client, topology.entities, topology.states, topology.devices, entity_registry
     )

{ha_mcp_dev-8.4.2.dev2530 → ha_mcp_dev-8.4.2.dev2534}/src/ha_mcp/tools/component_api.py

@@ -56,6 +56,13 @@ UNKNOWN_COMMAND_CODE = "unknown_command"
 # routing gate can't trust command payloads shaped for a different generation.
 SUPPORTED_SCHEMA_VERSION = 1
 
+# Additive semantic capability shared by every component path whose result is
+# enriched from the device registry.  The pre-2.1.3 ``device_list``/``device_get``
+# commands (and search/overview/entity enrichment built on the same registry)
+# predate Core 2026.9 child devices.  Because component and server releases update
+# independently, command presence alone cannot authorize the newer semantics.
+DEVICE_REGISTRY_CHILD_SEMANTICS = "device_registry_child_semantics"
+
 # Negative (None) caps entries expire after this many seconds of monotonic
 # time, so a component installed / upgraded mid-session is re-probed and
 # adopted instead of being pinned to "absent" for the whole process lifetime

{ha_mcp_dev-8.4.2.dev2530 → ha_mcp_dev-8.4.2.dev2534}/src/ha_mcp/tools/component_devices.py

@@ -44,6 +44,7 @@ from ..client.rest_client import (
 )
 from ..client.websocket_client import get_websocket_client
 from .component_api import (
+    DEVICE_REGISTRY_CHILD_SEMANTICS,
     component_supports,
     get_component_caps,
     invalidate_caps,
@@ -85,7 +86,10 @@ async def fetch_device_via_component(
     only the device (``_resolve_ieee`` / capture / remove) are unchanged.
     """
     caps = await get_component_caps(client)
-    if not component_supports(caps, "device_get"):
+    if not (
+        component_supports(caps, "device_get")
+        and component_supports(caps, DEVICE_REGISTRY_CHILD_SEMANTICS)
+    ):
         return None
     kwargs: dict[str, Any] = {"device_id": device_id}
     if include_entities:
@@ -167,7 +171,10 @@ async def fetch_device_list_via_component(client: Any) -> dict[str, Any] | None:
     fallback as :func:`fetch_device_via_component`.
     """
     caps = await get_component_caps(client)
-    if not component_supports(caps, "device_list"):
+    if not (
+        component_supports(caps, "device_list")
+        and component_supports(caps, DEVICE_REGISTRY_CHILD_SEMANTICS)
+    ):
         return None
     try:
         ws = await get_websocket_client(

{ha_mcp_dev-8.4.2.dev2530 → ha_mcp_dev-8.4.2.dev2534}/src/ha_mcp/tools/smart_search/_entities.py

@@ -5,6 +5,10 @@ import logging
 from collections.abc import Mapping
 from typing import Any
 
+from ...utils.device_registry_semantics import (
+    build_device_registry_snapshot,
+    effective_entity_area_id,
+)
 from ...utils.entity_membership import normalize_member_entity_ids
 from ...utils.fuzzy_search import calculate_partial_ratio, calculate_ratio
 from ...visibility.resolver import (
@@ -651,13 +655,9 @@ class EntitySearchMixin(_SearchBase):
     def _parse_device_area_map(
         cls, result: Any, warnings: list[str] | None = None
     ) -> dict[str, str | None]:
-        """Parse the device registry into ``device_id -> area_id``."""
-        device_area_map: dict[str, str | None] = {}
-        for device in cls._extract_registry_list(result, "device registry", warnings):
-            device_id = device.get("id", "")
-            if device_id:
-                device_area_map[device_id] = device.get("area_id")
-        return device_area_map
+        """Parse devices into IDs mapped to direct-or-parent effective areas."""
+        device_rows = cls._extract_registry_list(result, "device registry", warnings)
+        return build_device_registry_snapshot(list(device_rows)).effective_area_by_id
 
     @staticmethod
     def _match_exact_registry_ids(
@@ -875,7 +875,7 @@ class EntitySearchMixin(_SearchBase):
         include_hidden: bool,
         visibility_hidden: set[str],
     ) -> tuple[dict[str, str], set[str]]:
-        """Map entity_id -> resolved area_id (entity area > device area).
+        """Map entity IDs to direct area, then device direct-or-parent effective area.
 
         Hidden entities are filtered only when include_hidden is False;
         otherwise they pass through and downstream applies the score penalty so
@@ -892,10 +892,7 @@ class EntitySearchMixin(_SearchBase):
                 continue
             if is_hidden:
                 hidden_entity_ids.add(entity_id)
-            area_id = reg_info.get("area_id")
-            device_id = reg_info.get("device_id")
-            if not area_id and device_id:
-                area_id = device_area_map.get(device_id)
+            area_id = effective_entity_area_id(reg_info, device_area_map)
             if area_id:
                 entity_area_resolved[entity_id] = area_id
         return entity_area_resolved, hidden_entity_ids

{ha_mcp_dev-8.4.2.dev2530 → ha_mcp_dev-8.4.2.dev2534}/src/ha_mcp/tools/smart_search/_overview.py

@@ -6,6 +6,10 @@ import random
 from itertools import islice
 from typing import Any
 
+from ...utils.device_registry_semantics import (
+    build_device_registry_snapshot,
+    effective_entity_area_id,
+)
 from ...visibility.resolver import load_hidden_set
 from ..helpers import exception_to_structured_error
 from ._base import _SearchBase
@@ -237,23 +241,18 @@ class SystemOverviewMixin(_SearchBase):
         entity_registry: list[dict[str, Any]],
         device_registry: list[dict[str, Any]],
     ) -> dict[str, str | None]:
-        """Map entity_id -> area_id. Priority: entity direct area_id > device area_id."""
-        device_area_map: dict[str, str | None] = {}
-        for device in device_registry:
-            device_id = device.get("id", "")
-            if device_id:
-                device_area_map[device_id] = device.get("area_id")
+        """Map entity IDs to direct area, then device direct-or-parent effective area."""
+        device_area_map = build_device_registry_snapshot(
+            list(device_registry)
+        ).effective_area_by_id
 
         entity_area_map: dict[str, str | None] = {}
         for entry in entity_registry:
             entity_id = entry.get("entity_id")
-            area_id = entry.get("area_id")
-            if not area_id:
-                device_id = entry.get("device_id")
-                if device_id:
-                    area_id = device_area_map.get(device_id)
             if entity_id:
-                entity_area_map[entity_id] = area_id
+                entity_area_map[entity_id] = effective_entity_area_id(
+                    entry, device_area_map
+                )
         return entity_area_map
 
     @staticmethod

{ha_mcp_dev-8.4.2.dev2530 → ha_mcp_dev-8.4.2.dev2534}/src/ha_mcp/tools/tools_entities.py

@@ -22,6 +22,7 @@ from ..client.websocket_client import get_websocket_client
 from ..errors import ErrorCode, create_error_response
 from .auto_backup import with_auto_backup
 from .component_api import (
+    DEVICE_REGISTRY_CHILD_SEMANTICS,
     component_supports,
     get_component_caps,
     invalidate_caps,
@@ -118,7 +119,10 @@ async def fetch_entity_enrichment_via_component(
     if not entity_ids:
         return None
     caps = await get_component_caps(client)
-    if not component_supports(caps, "entity_enrich"):
+    if not (
+        component_supports(caps, "entity_enrich")
+        and component_supports(caps, DEVICE_REGISTRY_CHILD_SEMANTICS)
+    ):
         return None
     ids = list(entity_ids)
     chunks = [

{ha_mcp_dev-8.4.2.dev2530 → ha_mcp_dev-8.4.2.dev2534}/src/ha_mcp/tools/tools_registry.py

@@ -16,6 +16,10 @@ from pydantic import Field
 
 from ..client.rest_client import HomeAssistantAPIError, HomeAssistantConnectionError
 from ..errors import ErrorCode, create_error_response
+from ..utils.device_registry_semantics import (
+    EFFECTIVE_AREA_MARKER,
+    annotate_device_rows_with_effective_area,
+)
 from .auto_backup import with_auto_backup
 from .component_devices import (
     fetch_device_list_via_component,
@@ -137,7 +141,7 @@ def _get_device_info(device: dict[str, Any]) -> dict[str, Any]:
         "manufacturer": device.get("manufacturer"),
         "model": device.get("model"),
         "sw_version": device.get("sw_version"),
-        "area_id": device.get("area_id"),
+        "area_id": device.get(EFFECTIVE_AREA_MARKER, device.get("area_id")),
         "integration_type": integration_type,
         "integration_sources": integration_sources,
         "via_device_id": device.get("via_device_id"),
@@ -158,6 +162,25 @@ def _get_device_info(device: dict[str, Any]) -> dict[str, Any]:
     return device_info
 
 
+def _device_config_entries(device: dict[str, Any]) -> list[str]:
+    """Return the exact owning config-entry IDs for a main or child row.
+
+    Ordinary ``DeviceEntry`` rows carry ``config_entries`` while Core 2026.9
+    ``ChildDeviceEntry`` rows carry one singular ``config_entry_id``. Never mix,
+    coerce, or repair malformed ownership evidence: an explicitly present plural
+    field is authoritative and must be a list of non-empty strings.
+    """
+    if "config_entries" in device:
+        raw = device.get("config_entries")
+        if not isinstance(raw, list) or not all(
+            isinstance(entry_id, str) and entry_id for entry_id in raw
+        ):
+            return []
+        return list(raw)
+    entry_id = device.get("config_entry_id")
+    return [entry_id] if isinstance(entry_id, str) and entry_id else []
+
+
 def _build_entity_maps(
     all_entities: list[dict[str, Any]], need_full: bool
 ) -> tuple[dict[str, str], dict[str, list[dict[str, Any]]]]:
@@ -251,8 +274,8 @@ async def _fetch_device_rows(client: Any) -> list[dict[str, Any]]:
     """
     result = await fetch_device_list_via_component(client)
     if result is not None:
-        return list(result.get("devices", []))
-    return await _legacy_device_rows(client)
+        return annotate_device_rows_with_effective_area(list(result.get("devices", [])))
+    return annotate_device_rows_with_effective_area(await _legacy_device_rows(client))
 
 
 # HA core replies with this error code (ERR_NOT_FOUND) from
@@ -342,6 +365,9 @@ async def _single_device_and_entities(
         device = result.get("device")
         entities = result.get("entities")
         if isinstance(device, dict) and isinstance(entities, list):
+            device = dict(device)
+            if "effective_area_id" in result:
+                device[EFFECTIVE_AREA_MARKER] = result.get("effective_area_id")
             _, device_to_entities = _build_entity_maps(entities, need_full=True)
             return [device], device_to_entities
         # Either an authoritative not-found (device is None) — fall through so the
@@ -350,7 +376,9 @@ async def _single_device_and_entities(
         # entity registries.
     # Device registry first, then entity registry — the legacy wire order,
     # which the #1297 error-contract test pins with an ordered mock.
-    all_devices = await _legacy_device_rows(client)
+    all_devices = annotate_device_rows_with_effective_area(
+        await _legacy_device_rows(client)
+    )
     all_entities = await _fetch_entity_rows(client)
     _, device_to_entities = _build_entity_maps(all_entities, need_full=True)
     return all_devices, device_to_entities
@@ -547,7 +575,7 @@ async def _get_single_device_result(
     device_info["serial_number"] = device.get("serial_number")
     device_info["disabled_by"] = device.get("disabled_by")
     device_info["labels"] = device.get("labels", [])
-    device_info["config_entries"] = device.get("config_entries", [])
+    device_info["config_entries"] = _device_config_entries(device)
     device_info["connections"] = device.get("connections", [])
     device_info["identifiers"] = device.get("identifiers", [])
 
@@ -597,7 +625,8 @@ def _filter_devices(
     named_types = ["zigbee2mqtt", "zha", "zwave_js"]
     matched: list[dict[str, Any]] = []
     for device in all_devices:
-        if area_id and device.get("area_id") != area_id:
+        effective_area = device.get(EFFECTIVE_AREA_MARKER, device.get("area_id"))
+        if area_id and effective_area != area_id:
             continue
         device_man = (device.get("manufacturer") or "").lower()
         if manufacturer_lower and manufacturer_lower not in device_man:
@@ -1134,7 +1163,7 @@ class RegistryTools:
             )
             device = await _lookup_device_for_remove(self._client, device_id)
 
-            config_entries = device.get("config_entries", [])
+            config_entries = _device_config_entries(device)
             device_name = device.get("name_by_user") or device.get("name")
             if not config_entries:
                 raise_tool_error(

{ha_mcp_dev-8.4.2.dev2530 → ha_mcp_dev-8.4.2.dev2534}/src/ha_mcp/tools/tools_search.py

@@ -25,6 +25,10 @@ from ..client.websocket_client import get_websocket_client
 from ..config import get_global_settings
 from ..errors import create_validation_error
 from ..transforms.categorized_search import DEFAULT_PINNED_TOOLS
+from ..utils.device_registry_semantics import (
+    build_device_registry_snapshot,
+    effective_entity_area_id,
+)
 from ..utils.entity_membership import normalize_member_entity_ids
 from ..utils.fuzzy_search import apply_hidden_penalty
 from ..visibility.model import VisibilityWire, wire_has_allowlist_dimensions
@@ -34,6 +38,7 @@ from ..visibility.resolver import (
     visibility_state_and_wire,
 )
 from .component_api import (
+    DEVICE_REGISTRY_CHILD_SEMANTICS,
     component_supports,
     get_component_caps,
     invalidate_caps,
@@ -869,6 +874,15 @@ def _ws_result_map(resp: Any) -> dict[str, dict[str, Any]]:
     return {}
 
 
+def _ws_registry_rows(resp: Any) -> list[Any]:
+    """Return rows from a successful registry-list response, else an empty list."""
+    if isinstance(resp, dict) and resp.get("success"):
+        result = resp.get("result")
+        if isinstance(result, list):
+            return result
+    return []
+
+
 def _ws_registry_index(resp: Any, key: str) -> dict[str, dict[str, Any]]:
     """Index a ``config/*_registry/list`` reply by its id field (area_id/floor_id/…).
 
@@ -877,10 +891,9 @@ def _ws_registry_index(resp: Any, key: str) -> dict[str, dict[str, Any]]:
     empty rather than raising.
     """
     out: dict[str, dict[str, Any]] = {}
-    if isinstance(resp, dict) and resp.get("success"):
-        for item in resp.get("result") or []:
-            if isinstance(item, dict) and item.get(key):
-                out[item[key]] = item
+    for item in _ws_registry_rows(resp):
+        if isinstance(item, dict) and item.get(key):
+            out[item[key]] = item
     return out
 
 
@@ -902,13 +915,15 @@ def _entity_enrichment_fields(
     floors: dict[str, dict[str, Any]],
     labels: dict[str, dict[str, Any]],
     devices: dict[str, dict[str, Any]],
+    device_areas: dict[str, str | None],
     requested: tuple[str, ...],
 ) -> dict[str, Any]:
     """Compute the requested enrichment fields for one entity from registry data.
 
     Mirrors the component's ``_registry_enrichment`` so the legacy and
     component-served ``result_fields`` values agree: device-inherited area/labels
-    (the entity's own value wins, else the device's), area→floor resolution, and
+    (the entity's own value wins, else the device's direct-or-parent effective
+    area), area→floor resolution, and
     label id→name (falling back to the id when a label has no name). ``aliases``
     pass through from the registry entry. Only the requested keys are returned.
 
@@ -919,13 +934,11 @@ def _entity_enrichment_fields(
     the sentinel stands for is already matched via the friendly name).
     """
     aliases = sorted(a for a in (entry.get("aliases") or []) if isinstance(a, str))
-    area_id = entry.get("area_id")
+    area_id = effective_entity_area_id(entry, device_areas)
     label_ids = set(entry.get("labels") or [])
     device_id = entry.get("device_id")
     device = devices.get(device_id) if device_id else None
     if device:
-        if area_id is None:
-            area_id = device.get("area_id")
         label_ids |= set(device.get("labels") or [])
     area = areas.get(area_id) if area_id else None
     area_name = area.get("name") if area else None
@@ -2424,9 +2437,13 @@ class SearchTools:
             and _component_serves_search_types(req)
         ):
             caps = await get_component_caps(self._client)
-            if component_supports(caps, "search") and (
-                not _requested_membership(parsed_result_fields)
-                or component_supports(caps, "search_entity_membership")
+            if (
+                component_supports(caps, "search")
+                and component_supports(caps, DEVICE_REGISTRY_CHILD_SEMANTICS)
+                and (
+                    not _requested_membership(parsed_result_fields)
+                    or component_supports(caps, "search_entity_membership")
+                )
             ):
                 (
                     route_component,
@@ -3153,10 +3170,19 @@ class SearchTools:
         areas = _ws_registry_index(names[0], "area_id") if need_names else {}
         floors = _ws_registry_index(names[1], "floor_id") if need_names else {}
         labels = _ws_registry_index(names[2], "label_id") if need_names else {}
-        devices = _ws_registry_index(names[3], "id") if need_names else {}
+        device_rows = _ws_registry_rows(names[3]) if need_names else []
+        device_snapshot = build_device_registry_snapshot(device_rows)
+        devices = device_snapshot.by_id
+        device_areas = device_snapshot.effective_area_by_id
         enrichment = {
             eid: _entity_enrichment_fields(
-                entries.get(eid) or {}, areas, floors, labels, devices, requested
+                entries.get(eid) or {},
+                areas,
+                floors,
+                labels,
+                devices,
+                device_areas,
+                requested,
             )
             for eid in entity_ids
         }
@@ -4379,7 +4405,9 @@ class SearchTools:
         applied by ``ha_get_overview`` after this, identically on both paths.
         """
         caps = await get_component_caps(self._client)
-        if component_supports(caps, "overview"):
+        if component_supports(caps, "overview") and component_supports(
+            caps, DEVICE_REGISTRY_CHILD_SEMANTICS
+        ):
             component_result = await self._overview_via_component(inputs)
             if component_result is not None:
                 return component_result

{ha_mcp_dev-8.4.2.dev2530 → ha_mcp_dev-8.4.2.dev2534}/src/ha_mcp/tools/tools_voice_assistant.py

@@ -24,6 +24,7 @@ from ..client.rest_client import (
 from ..client.websocket_client import get_websocket_client
 from ..errors import ErrorCode, create_error_response
 from .component_api import (
+    DEVICE_REGISTRY_CHILD_SEMANTICS,
     component_supports,
     get_component_caps,
     invalidate_caps,
@@ -89,7 +90,10 @@ class VoiceAssistantTools:
         ``component_devices.fetch_device_via_component``.
         """
         caps = await get_component_caps(self._client)
-        if not component_supports(caps, "exposure"):
+        if not (
+            component_supports(caps, "exposure")
+            and component_supports(caps, DEVICE_REGISTRY_CHILD_SEMANTICS)
+        ):
             return None
         kwargs: dict[str, Any] = {}
         if entity_id is not None: