ha-mcp-dev 9.2.0.dev3460__tar.gz → 9.2.0.dev3463__tar.gz

{ha_mcp_dev-9.2.0.dev3460 → ha_mcp_dev-9.2.0.dev3463}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.2.0.dev3460
+Version: 9.2.0.dev3463
 Summary: Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants.
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.2.0.dev3460 → ha_mcp_dev-9.2.0.dev3463}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.2.0.dev3460"
+version = "9.2.0.dev3463"
 description = "Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants."
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.2.0.dev3460 → ha_mcp_dev-9.2.0.dev3463}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.2.0.dev3460"
+version = "9.2.0.dev3463"
 description = "Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants."
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-9.2.0.dev3460 → ha_mcp_dev-9.2.0.dev3463}/src/ha_mcp/tools/component_api.py

@@ -71,6 +71,11 @@ SUPPORTED_SCHEMA_VERSION = 1
 # independently, command presence alone cannot authorize the newer semantics.
 DEVICE_REGISTRY_CHILD_SEMANTICS = "device_registry_child_semantics"
 
+# Additive flag on search and overview: entity rows carry the name Core
+# composes, and search matches on it. A component without it serves the legacy
+# friendly_name alone, and the server says so where that changes the answer.
+ENTITY_COMPOSED_NAME = "entity_composed_name"
+
 # 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-9.2.0.dev3460 → ha_mcp_dev-9.2.0.dev3463}/src/ha_mcp/tools/search/component.py

@@ -28,6 +28,7 @@ from ..component_api import (
 from ..smart_search import DEFAULT_CONCURRENCY_LIMIT, DeepSearchMixin
 from ..util_helpers import merge_visibility_warnings
 from .entities import (
+    _COMPOSED_NAME_FIELD,
     _ENTITY_RECORD_KEYS,
     _requested_enrichment,
     _requested_membership,
@@ -578,19 +579,22 @@ def _shape_component_search_response(
 
     if req.registry_eligible:
         parsed_result_fields = _parse_component_result_fields(req.result_fields)
-        # Base records contain the six documented keys. Requested enrichment
-        # fields retain the component's area/floor/labels/aliases registry join;
-        # requested membership fields append its opt-in state-derived metadata.
-        # With neither class requested, the default six-key shape is unchanged.
+        # Base records contain the six documented keys plus Core's composed
+        # name where the component sends one (an older component does not).
+        # Requested enrichment fields retain the component's
+        # area/floor/labels/aliases registry join; requested membership fields
+        # append its opt-in state-derived metadata.
+        membership = _requested_membership(parsed_result_fields)
         record_keys = (
             *_ENTITY_RECORD_KEYS,
+            _COMPOSED_NAME_FIELD,
             *_requested_enrichment(parsed_result_fields),
-            *_requested_membership(parsed_result_fields),
+            *membership,
         )
-        conditional_keys = set(_requested_membership(parsed_result_fields))
+        conditional_keys = {_COMPOSED_NAME_FIELD, *membership}
         entities = [
             {
-                key: rec[key] if key in conditional_keys else rec.get(key)
+                key: rec.get(key)
                 for key in record_keys
                 if key not in conditional_keys or key in rec
             }
@@ -715,9 +719,12 @@ class ComponentSearchMixin(LegacySearchMixin):
         *,
         visibility: VisibilityWire | None = None,
         caps: Any = None,
-    ) -> dict[str, Any] | None:
+    ) -> tuple[dict[str, Any] | None, bool]:
         """Serve ha_search from the component; ``None`` ⇒ run the legacy path.
 
+        The flag says whether the component answered: it is false for a
+        response the failure fallback took from the legacy path.
+
         ``visibility`` is the serialized hide config passed to a
         ``search_visibility``-capable component so it applies the entity-
         visibility filter in-process (``None`` ⇒ no filter / not supported ⇒ the
@@ -733,17 +740,17 @@ class ComponentSearchMixin(LegacySearchMixin):
         """
         if _dashboard_split_requested(req):
             if not _dashboard_split_serviceable(req, caps):
-                return None
+                return None, False
             return await self._component_search_with_dashboards(
                 req, ctx, visibility=visibility
             )
         try:
             raw = await self._send_component_search(req, visibility)
         except Exception as exc:  # noqa: BLE001
-            return await self._component_search_fallback(req, ctx, exc)
+            return await self._component_search_fallback(req, ctx, exc), False
         response = _shape_component_search_response(req, raw.get("result") or {})
         await _scrub_component_config_buckets(response, self._client)
-        return response
+        return response, True
 
     async def _component_search_fallback(
         self, req: _ResolvedSearch, ctx: Context | None, exc: Exception
@@ -795,7 +802,7 @@ class ComponentSearchMixin(LegacySearchMixin):
         ctx: Context | None,
         *,
         visibility: VisibilityWire | None,
-    ) -> dict[str, Any] | None:
+    ) -> tuple[dict[str, Any] | None, bool]:
         """Serve a ``dashboard``-including request from both legs (issue #2289).
 
         The two legs run concurrently: the dashboards leg is a second frame on
@@ -825,7 +832,7 @@ class ComponentSearchMixin(LegacySearchMixin):
             # search uncancellably.
             dashboard_task.cancel()
             await asyncio.wait([dashboard_task])
-            return await self._component_search_fallback(req, ctx, exc)
+            return await self._component_search_fallback(req, ctx, exc), False
         except BaseException:
             # Cancellation / shutdown of THIS coroutine: settle the leg before
             # propagating, so no cancelled task outlives the call, then
@@ -858,7 +865,7 @@ class ComponentSearchMixin(LegacySearchMixin):
             ),
         )
         await _scrub_component_config_buckets(response, self._client)
-        return response
+        return response, True
 
     async def _search_dashboards_leg(self, req: _ResolvedSearch) -> _DashboardLeg:
         """The dashboards bucket for a merged component search.

{ha_mcp_dev-9.2.0.dev3460 → ha_mcp_dev-9.2.0.dev3463}/src/ha_mcp/tools/search/entities.py

@@ -7,7 +7,7 @@ entity search, and the enrichment methods of the search tool class.
 import asyncio
 import logging
 from collections.abc import Mapping
-from typing import Any
+from typing import Any, Literal
 
 from ...errors import create_validation_error
 from ...utils.device_registry_semantics import (
@@ -62,6 +62,69 @@ _ENRICHMENT_FIELDS: tuple[str, ...] = ("area", "floor", "labels", "aliases")
 _MEMBERSHIP_FIELDS: tuple[str, ...] = ("is_group", "member_entity_ids")
 
 
+# The name Home Assistant shows for the entity, composed by Core from the
+# parent device, device and entity names (friendly_name is the legacy state
+# attribute). Only the component can ask Core for it, so a record carries it
+# on the component path alone.
+_COMPOSED_NAME_FIELD = "name"
+# A search without a current component sees less (an entity only by its id,
+# legacy friendly_name and aliases), so a search that finds nothing may be one
+# the component would have answered.
+_NO_COMPONENT_EMPTY_SEARCH_HINT = (
+    "No ha_mcp_tools component detected; for full search functionality, "
+    "install it via HACS (the Marketplace on Home Assistant 2026.11+)."
+)
+_OLD_COMPONENT_EMPTY_SEARCH_HINT = (
+    "The installed ha_mcp_tools component is out of date; for full search "
+    "functionality, update it."
+)
+_COMPOSED_NAME_UNAVAILABLE = (
+    "name was requested, but the ha_mcp_tools component did not serve this "
+    "search and only it can ask Home Assistant for an entity's composed name; "
+    "the records carry friendly_name, the legacy name"
+)
+_COMPOSED_NAME_NEEDS_UPDATE = (
+    "name was requested, but the installed ha_mcp_tools component predates "
+    "composed names; update it. The records carry friendly_name, the legacy name"
+)
+
+
+ComponentNaming = Literal["absent", "outdated", "current"]
+
+
+def _composed_name_notes(
+    *,
+    name_served: bool,
+    component: ComponentNaming,
+    name_requested: bool,
+    nothing_found: bool,
+) -> list[str]:
+    """Warnings for a search that ran without a current component.
+
+    ``name_served`` is true when a component that composes names answered;
+    nothing is missing then. Otherwise a requested ``name`` and a search that
+    found nothing each say what is in the way: no component (or none that
+    answered), or one that is out of date. A search the legacy path served
+    while a current component is installed carries no hint.
+    """
+    if name_served:
+        return []
+    notes: list[str] = []
+    if name_requested:
+        notes.append(
+            _COMPOSED_NAME_NEEDS_UPDATE
+            if component == "outdated"
+            else _COMPOSED_NAME_UNAVAILABLE
+        )
+    if nothing_found and component != "current":
+        notes.append(
+            _OLD_COMPONENT_EMPTY_SEARCH_HINT
+            if component == "outdated"
+            else _NO_COMPONENT_EMPTY_SEARCH_HINT
+        )
+    return notes
+
+
 # Every field name result_fields= accepts — base record keys plus opt-in
 # enrichment and membership keys. Unknown names are rejected up front rather
 # than silently projecting to empty records.
@@ -69,6 +132,7 @@ _ALLOWED_RESULT_FIELDS: frozenset[str] = (
     frozenset(_ENTITY_RECORD_KEYS)
     | frozenset(_ENRICHMENT_FIELDS)
     | frozenset(_MEMBERSHIP_FIELDS)
+    | {_COMPOSED_NAME_FIELD}
 )
 
 

{ha_mcp_dev-9.2.0.dev3460 → ha_mcp_dev-9.2.0.dev3463}/src/ha_mcp/tools/smart_search/_overview.py

@@ -144,6 +144,7 @@ class SystemOverviewMixin(_SearchBase):
             entity_area_map = self._build_entity_area_map(
                 entity_registry, device_registry
             )
+            entity_names = self._build_entity_name_map(entity_registry)
 
             (
                 max_entities_per_domain,
@@ -169,6 +170,7 @@ class SystemOverviewMixin(_SearchBase):
                 domains_filter_set,
                 area_stats,
                 entity_area_map,
+                entity_names,
                 include_state,
                 include_entity_id,
             )
@@ -248,6 +250,21 @@ class SystemOverviewMixin(_SearchBase):
                 )
         return entity_area_map
 
+    @staticmethod
+    def _build_entity_name_map(
+        entity_registry: list[dict[str, Any]],
+    ) -> dict[str, str]:
+        """Map entity IDs to the name Core composes for them.
+
+        Only the component's registry rows carry it (``full_name``); Core's own
+        registry list does not, so the map is empty without the component.
+        """
+        return {
+            entry["entity_id"]: entry["full_name"]
+            for entry in entity_registry
+            if entry.get("entity_id") and entry.get("full_name")
+        }
+
     @staticmethod
     def _resolve_overview_display_opts(
         detail_level: str,
@@ -314,6 +331,7 @@ class SystemOverviewMixin(_SearchBase):
         domains_filter_set: set[str] | None,
         area_stats: dict[str, dict[str, Any]],
         entity_area_map: dict[str, str | None],
+        entity_names: dict[str, str],
         include_state: bool,
         include_entity_id: bool,
     ) -> tuple[dict[str, dict[str, Any]], dict[str, int]]:
@@ -336,9 +354,13 @@ class SystemOverviewMixin(_SearchBase):
             stats["count"] += 1
             stats["states_summary"][state] = stats["states_summary"].get(state, 0) + 1
 
-            entity_data: dict[str, Any] = {
-                "friendly_name": attributes.get("friendly_name", entity_id),
-            }
+            friendly_name = attributes.get("friendly_name", entity_id)
+            entity_data: dict[str, Any] = {"friendly_name": friendly_name}
+            # Most entities carry one name; a second key on every row of a
+            # whole-house listing would repeat it.
+            name = entity_names.get(entity_id)
+            if name and name != friendly_name:
+                entity_data["name"] = name
             if include_entity_id:
                 entity_data["entity_id"] = entity_id
             if include_state:

{ha_mcp_dev-9.2.0.dev3460 → ha_mcp_dev-9.2.0.dev3463}/src/ha_mcp/tools/tools_search.py

@@ -17,6 +17,7 @@ from ..transforms.categorized_search import DEFAULT_PINNED_TOOLS
 from .coercion import JSON_STRING_COERCION, parse_string_list_param
 from .component_api import (
     DEVICE_REGISTRY_CHILD_SEMANTICS,
+    ENTITY_COMPOSED_NAME,
     component_supports,
     get_component_caps,
 )
@@ -27,7 +28,13 @@ from .helpers import (
 )
 from .response_helpers import project_fields
 from .search.component import ComponentSearchMixin, _component_serves_search_types
-from .search.entities import _requested_membership, _validate_result_field_names
+from .search.entities import (
+    _COMPOSED_NAME_FIELD,
+    ComponentNaming,
+    _composed_name_notes,
+    _requested_membership,
+    _validate_result_field_names,
+)
 from .search.overview import (
     _OVERVIEW_AVAILABLE_FIELDS,
     _OVERVIEW_ENTITY_FIELDS,
@@ -203,7 +210,11 @@ class SearchTools(ComponentSearchMixin, OverviewMixin, StateMixin):
                     "Project each entity-registry record to only the specified "
                     'keys (e.g. ["entity_id", "state"]). None = full records. '
                     "Base keys: entity_id, friendly_name, domain, state, score, "
-                    "match_type. Opt-in enrichment/membership keys (computed on request): "
+                    "match_type, name. name is the name Home Assistant shows, "
+                    "composed from the parent device, device and entity names "
+                    "(served by a current ha_mcp_tools component); friendly_name "
+                    "is the legacy state attribute and can differ from it. "
+                    "Opt-in enrichment/membership keys (computed on request): "
                     "area, floor, labels, aliases, is_group, member_entity_ids. "
                     "Membership is recognized only when HA explicitly exposes a "
                     "valid group_entities or legacy entity_id collection; "
@@ -395,32 +406,60 @@ class SearchTools(ComponentSearchMixin, OverviewMixin, StateMixin):
         # components serve queryless listings, locations, and complete windows.
         # Visibility and membership gates still apply before any entity data is
         # returned; schema hiding never changes old-client invocation support.
-        if _component_serves_search_types(req):
-            caps = await get_component_caps(self._client)
-            mode_supported = component_supports(caps, "search_unified") or (
-                bool(req.query_text) and not (req.area_filter or "").strip()
+        if not _component_serves_search_types(req):
+            return _omit_empty_warnings(await self._legacy_ha_search(req, ctx))
+
+        caps = await get_component_caps(self._client)
+        naming: ComponentNaming = "absent"
+        if caps is not None:
+            naming = (
+                "current"
+                if component_supports(caps, ENTITY_COMPOSED_NAME)
+                else "outdated"
             )
-            if (
-                mode_supported
-                and 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")
-                )
-            ):
+        component_response: dict[str, Any] | None = None
+        component_answered = False
+        mode_supported = component_supports(caps, "search_unified") or (
+            bool(req.query_text) and not (req.area_filter or "").strip()
+        )
+        if (
+            mode_supported
+            and 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,
+                visibility,
+            ) = await self._resolve_component_search_visibility(caps)
+            if route_component:
                 (
-                    route_component,
-                    visibility,
-                ) = await self._resolve_component_search_visibility(caps)
-                if route_component:
-                    component_response = await self._ha_search_via_component(
-                        req, ctx, visibility=visibility, caps=caps
-                    )
-                    if component_response is not None:
-                        return _omit_empty_warnings(component_response)
-
-        return _omit_empty_warnings(await self._legacy_ha_search(req, ctx))
+                    component_response,
+                    component_answered,
+                ) = await self._ha_search_via_component(
+                    req, ctx, visibility=visibility, caps=caps
+                )
+
+        response = (
+            component_response
+            if component_response is not None
+            else await self._legacy_ha_search(req, ctx)
+        )
+        notes = _composed_name_notes(
+            name_served=component_answered and naming == "current",
+            component=naming,
+            name_requested=_COMPOSED_NAME_FIELD in (parsed_result_fields or ()),
+            nothing_found=bool(req.query_text)
+            and not response.get("count")
+            and not response.get("entity_total_matches")
+            and not response.get("config_total_matches"),
+        )
+        if notes:
+            response.setdefault("warnings", []).extend(notes)
+        return _omit_empty_warnings(response)
 
     @tool(
         name="ha_get_overview",
@@ -541,6 +580,11 @@ class SearchTools(ComponentSearchMixin, OverviewMixin, StateMixin):
         Use 'minimal' (default) for most queries. Domain counts and states_summary
         are always complete regardless of entity pagination.
 
+        Entities are listed by friendly_name, the legacy state attribute. A row
+        also carries name where Home Assistant shows a different one, composed
+        from the parent device, device and entity names (served by a current
+        ha_mcp_tools component).
+
         Requests whose fields= are composed only of system_info, notification,
         repair, or server metadata fields skip the unrelated state, service, and
         registry reads.