ha-mcp-dev 7.13.0.dev1959__tar.gz → 7.13.0.dev1965__tar.gz

{ha_mcp_dev-7.13.0.dev1959/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.13.0.dev1965}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.13.0.dev1959
+Version: 7.13.0.dev1965
 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.13.0.dev1959 → ha_mcp_dev-7.13.0.dev1965}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.13.0.dev1959"
+version = "7.13.0.dev1965"
 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-7.13.0.dev1959 → ha_mcp_dev-7.13.0.dev1965}/src/ha_mcp/backup_manager.py

@@ -1720,12 +1720,23 @@ async def _restore_entity_state(client: Any, entity_id: str, config: Any) -> Any
 # best-effort.
 
 
-async def _fetch_device(client: Any, entity_id: str) -> Any:
+async def _fetch_device(client: Any, device_id: str) -> Any:
+    # Route the single-device capture through the component's ``device_get`` when
+    # available (one in-process read of the raw DeviceEntry) instead of dumping the
+    # whole registry — the same pre-write snapshot ``ha_set_device`` /
+    # ``ha_remove_device`` capture. Lazy import to avoid the backup_manager →
+    # tools → backup_manager cycle. ``None`` from the helper means "component
+    # unavailable"; fall back to the full-list scan.
+    from .tools.component_devices import fetch_device_via_component
+
+    result = await fetch_device_via_component(client, device_id)
+    if result is not None:
+        return result.get("device")
     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:
+        if item.get("id") == device_id:
             return item
     return None
 

{ha_mcp_dev-7.13.0.dev1959 → ha_mcp_dev-7.13.0.dev1965}/src/ha_mcp/client/rest_client.py

@@ -1445,6 +1445,7 @@ class HomeAssistantClient:
                         return {
                             "success": False,
                             "error": f"WebSocket request blocked (403 Forbidden): {error_str}",
+                            "error_code": getattr(e, "code", None),
                             "suggestions": [
                                 "This may be caused by a reverse proxy or security filter",
                                 "Try simplifying the request (e.g., shorter templates, fewer parameters)",
@@ -1457,7 +1458,14 @@ class HomeAssistantClient:
                 # Unknown command." is undiagnosable from a user's log
                 # (issue #1889 took a live reproduction to attribute).
                 logger.error(f"WebSocket message failed ({message.get('type')}): {e}")
-                return {"success": False, "error": str(e)}
+                # Preserve HA's structured error code (e.g. ``not_found``) so callers
+                # can distinguish HA's authoritative verdict from a transient failure
+                # instead of only seeing the stringified message.
+                return {
+                    "success": False,
+                    "error": str(e),
+                    "error_code": getattr(e, "code", None),
+                }
 
         return {"success": False, "error": "WebSocket request failed"}
 

ha_mcp_dev-7.13.0.dev1965/src/ha_mcp/tools/component_devices.py

@@ -0,0 +1,153 @@
+"""Shared device-registry reads over the ``ha_mcp_tools`` component gate.
+
+Several tools resolve a device the same wasteful way today — pull the ENTIRE
+device registry and filter for one entry (``ha_get_device`` single lookup,
+``ha_remove_device``'s body, the ``@with_auto_backup`` capture read, and
+``ha_manage_radio``'s ``_resolve_ieee``). When the component advertises the
+``device_get`` / ``device_list`` capabilities, that whole-registry dump becomes a
+single in-process read: ``device_get`` returns one ``DeviceEntry.dict_repr`` by
+id, ``device_list`` returns them all — each byte-identical to a
+``config/device_registry/list`` element by construction (see
+``custom_components/ha_mcp_tools/websocket_api.py``). Consumers keep their own
+transforms over that raw shape.
+
+This module owns the caps-gated fetch so the routing discipline — probe caps,
+send one frame, invalidate on ``unknown_command``, fall back to the legacy path
+on any component error — lives in one place instead of being duplicated per
+consumer (the pattern ``tools_search._fetch_states_via_component`` established
+for the ``states`` capability). Both helpers return ``None`` to mean "component
+unavailable — use the legacy path"; a component that answers authoritatively
+returns its payload (with ``device`` possibly ``None`` for "no such device").
+
+``device_get`` also carries an opt-in per-device entity join
+(:func:`fetch_device_entities_via_component`): with ``include_entities`` the
+component returns the device's ``config/entity_registry/list``-shaped rows as a
+SIBLING ``entities`` key, so a single-device lookup no longer dumps the whole
+entity registry to list one device's entities. The join is additive within
+schema_version 1, so the server tolerates its absence rather than depending on a
+version bump. An older ``device_get`` that predates the param never round-trips
+the entities half — the extra field is rejected by the command's
+``PREVENT_EXTRA`` base schema, surfacing as an error that maps to the ``None``
+miss — and, belt-and-suspenders, a response that carries the device but no
+``entities`` key is treated the same: fall back to the legacy
+``config/entity_registry/list`` for the entity half. Neither breaks the call.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..client.rest_client import (
+    HomeAssistantCommandError,
+    HomeAssistantCommandTimeout,
+)
+from ..client.websocket_client import get_websocket_client
+from .component_api import (
+    component_supports,
+    get_component_caps,
+    invalidate_caps,
+    is_unknown_command,
+)
+
+logger = logging.getLogger(__name__)
+
+WS_DEVICE_GET = "ha_mcp_tools/device_get"
+WS_DEVICE_LIST = "ha_mcp_tools/device_list"
+
+
+async def fetch_device_via_component(
+    client: Any, device_id: str, *, include_entities: bool = False
+) -> dict[str, Any] | None:
+    """One ``ha_mcp_tools/device_get`` read; ``None`` ⇒ use the legacy path.
+
+    Returns the component's ``{"device": <raw dict> | None}`` payload (the raw
+    ``DeviceEntry.dict_repr`` for the id, byte-identical to a
+    ``config/device_registry/list`` element) or ``None`` when the component lacks
+    the ``device_get`` capability, was downgraded (``unknown_command`` →
+    invalidate the cached caps), or errored (logged). A component that answers
+    with ``{"device": None}`` is authoritative — the device does not exist — so
+    the caller must distinguish that from a ``None`` return (which means "component
+    unavailable, fall back"). Falls back **silently**, mirroring
+    ``ha_get_state``: the legacy path returns the byte-identical device either way
+    and the ``log.warning`` preserves operator visibility. A
+    ``HomeAssistantConnectionError`` (WS down) is not caught here, so it
+    propagates to the caller's own error handling — the legacy path shares the
+    same socket and would fail identically.
+
+    With ``include_entities`` the payload also carries a sibling ``entities`` list
+    (the device's ``config/entity_registry/list``-shaped rows), so a single-device
+    lookup that needs the device's entities skips the whole-entity-registry dump.
+    ``include_entities`` is only sent when true, so the frames of callers that need
+    only the device (``_resolve_ieee`` / capture / remove) are unchanged.
+    """
+    caps = await get_component_caps(client)
+    if not component_supports(caps, "device_get"):
+        return None
+    kwargs: dict[str, Any] = {"device_id": device_id}
+    if include_entities:
+        kwargs["include_entities"] = True
+    try:
+        ws = await get_websocket_client(url=client.base_url, token=client.token)
+        raw = await ws.send_command(WS_DEVICE_GET, **kwargs)
+    except (HomeAssistantCommandError, HomeAssistantCommandTimeout) as exc:
+        if is_unknown_command(exc):
+            invalidate_caps(client)
+        else:
+            logger.warning("%s failed; fell back to legacy: %r", WS_DEVICE_GET, exc)
+        return None
+    result = raw.get("result")
+    if not isinstance(result, dict) or "device" not in result:
+        return None
+    return result
+
+
+async def fetch_device_entities_via_component(
+    client: Any, device_id: str
+) -> list[dict[str, Any]] | None:
+    """The device's entity rows via ``device_get(include_entities=True)``; ``None`` ⇒ legacy.
+
+    Returns the ``config/entity_registry/list``-shaped rows bound to ``device_id``
+    (disabled included) so a per-device entity lookup avoids the whole-registry
+    dump. Returns ``None`` — the caller falls back to
+    ``config/entity_registry/list`` — when the component can't serve ``device_get``
+    at all, OR when it served the device but the response carries no ``entities``
+    key (an older ``device_get`` predating ``include_entities``, or any component
+    that does not round-trip the entities half): the entity join is additive, so
+    its absence degrades to legacy rather than silently reporting zero entities.
+    An AUTHORITATIVE empty result — the component honored ``include_entities`` and
+    the device has no entities, or no such device — comes back as a present empty
+    list, kept distinct from that ``None`` miss.
+    """
+    result = await fetch_device_via_component(client, device_id, include_entities=True)
+    if result is None:
+        return None
+    entities = result.get("entities")
+    return entities if isinstance(entities, list) else None
+
+
+async def fetch_device_list_via_component(client: Any) -> dict[str, Any] | None:
+    """One ``ha_mcp_tools/device_list`` read; ``None`` ⇒ use the legacy path.
+
+    Returns the component's ``{"devices": [<raw dict>, ...]}`` payload (each a raw
+    ``DeviceEntry.dict_repr``, the in-process equivalent of
+    ``config/device_registry/list``) or ``None`` on capability miss, downgrade
+    (``unknown_command`` → invalidate caps), or error (logged) — same
+    error-taxonomy and silent fallback as :func:`fetch_device_via_component`.
+    """
+    caps = await get_component_caps(client)
+    if not component_supports(caps, "device_list"):
+        return None
+    try:
+        ws = await get_websocket_client(url=client.base_url, token=client.token)
+        raw = await ws.send_command(WS_DEVICE_LIST)
+    except (HomeAssistantCommandError, HomeAssistantCommandTimeout) as exc:
+        if is_unknown_command(exc):
+            invalidate_caps(client)
+        else:
+            logger.warning("%s failed; fell back to legacy: %r", WS_DEVICE_LIST, exc)
+        return None
+    result = raw.get("result")
+    if not isinstance(result, dict) or not isinstance(result.get("devices"), list):
+        return None
+    return result

{ha_mcp_dev-7.13.0.dev1959 → ha_mcp_dev-7.13.0.dev1965}/src/ha_mcp/tools/radio/base.py

@@ -21,6 +21,7 @@ from dataclasses import dataclass, field
 from typing import Any
 
 from ...errors import ErrorCode, create_error_response
+from ..component_devices import fetch_device_entities_via_component
 from ..helpers import raise_tool_error
 
 logger = logging.getLogger(__name__)
@@ -107,10 +108,18 @@ async def resolve_update_entity(
     Filters the ``update.*`` entities tied to ``device_id``, preferring the given
     ``platform`` (e.g. "matter", "zha", "zwave_js") when a device exposes more
     than one. Raises ENTITY_NOT_FOUND when the device exposes no update entity.
+
+    Routes the per-device entity read through the component's
+    ``device_get(include_entities=True)`` when available (the device's rows in one
+    in-process frame, ``config/entity_registry/list`` shape) instead of dumping the
+    whole entity registry; falls back to ``config/entity_registry/list`` otherwise.
+    The ``update.*`` / platform filtering stays client-side exactly as before.
     """
-    entities = await ws_call(
-        client, "config/entity_registry/list", context={"device_id": device_id}
-    )
+    entities = await fetch_device_entities_via_component(client, device_id)
+    if entities is None:
+        entities = await ws_call(
+            client, "config/entity_registry/list", context={"device_id": device_id}
+        )
     candidates = [
         e
         for e in (entities or [])

{ha_mcp_dev-7.13.0.dev1959 → ha_mcp_dev-7.13.0.dev1965}/src/ha_mcp/tools/radio/zigbee.py

@@ -19,6 +19,7 @@ from typing import Any
 from fastmcp.exceptions import ToolError
 
 from ...errors import ErrorCode, create_error_response
+from ..component_devices import fetch_device_via_component
 from ..helpers import raise_tool_error
 from .base import (
     ActionSpec,
@@ -123,17 +124,40 @@ SUPPORTED: dict[str, ActionSpec] = {
 }
 
 
+async def _resolve_ieee_devices(client: Any, device_id: Any) -> list[dict[str, Any]]:
+    """The device rows ``_resolve_ieee`` scans — component ``device_get`` or legacy.
+
+    Returns just the one matching device (``[device]``, or ``[]`` when it does not
+    exist) via ``ha_mcp_tools/device_get`` when the component serves it, else the
+    whole ``config/device_registry/list`` for the caller to filter. Only a
+    non-empty string ``device_id`` is eligible for the component read; anything
+    else takes the legacy path (and is rejected by the caller's scan).
+    """
+    if isinstance(device_id, str) and device_id:
+        result = await fetch_device_via_component(client, device_id)
+        if result is not None:
+            device = result.get("device")
+            return [device] if isinstance(device, dict) else []
+    devices = await ws_call(
+        client, "config/device_registry/list", context={"device_id": device_id}
+    )
+    return list(devices or [])
+
+
 async def _resolve_ieee(client: Any, device_id: Any) -> str:
     """Resolve a ``device_id`` to its ZHA IEEE address via the device registry.
 
     Parses the ``["zha", "<ieee>"]`` registry identifier (falling back to an
     ``("ieee", ...)`` connection). Raises VALIDATION_INVALID_PARAMETER when the
     device is not a ZHA device.
+
+    Routes the single-device lookup through the component's ``device_get`` when
+    available (one in-process read of the raw ``DeviceEntry`` shape) instead of
+    dumping the whole device registry; falls back to
+    ``config/device_registry/list`` when the component can't serve it.
     """
-    devices = await ws_call(
-        client, "config/device_registry/list", context={"device_id": device_id}
-    )
-    for device in devices or []:
+    devices = await _resolve_ieee_devices(client, device_id)
+    for device in devices:
         if device.get("id") != device_id:
             continue
         for ident in device.get("identifiers", []):

{ha_mcp_dev-7.13.0.dev1959 → ha_mcp_dev-7.13.0.dev1965}/src/ha_mcp/tools/tools_blueprints.py

@@ -12,7 +12,18 @@ from fastmcp.exceptions import ToolError
 from fastmcp.tools import tool
 from pydantic import Field
 
+from ..client.rest_client import (
+    HomeAssistantCommandError,
+    HomeAssistantCommandTimeout,
+)
+from ..client.websocket_client import get_websocket_client
 from ..errors import ErrorCode, create_error_response
+from .component_api import (
+    component_supports,
+    get_component_caps,
+    invalidate_caps,
+    is_unknown_command,
+)
 from .helpers import (
     exception_to_structured_error,
     log_tool_usage,
@@ -105,8 +116,11 @@ class BlueprintTools:
         Get blueprint information - list all blueprints or get details for a specific one.
 
         Without a path: Lists all installed blueprints for the specified domain.
-        With a path: Retrieves full blueprint configuration including inputs, triggers,
-        conditions, and actions.
+        With a path: Returns the blueprint's metadata and input definitions. The
+        full body (triggers/conditions/actions for automations, sequence for
+        scripts) is included under `config` ONLY when the ha_mcp_tools custom
+        component is installed — core's blueprint API exposes metadata alone, so
+        without the component the body cannot be read.
 
         EXAMPLES:
         - List all automation blueprints: ha_get_blueprint(domain="automation")
@@ -120,7 +134,8 @@ class BlueprintTools:
         RETURNS (when getting specific blueprint):
         - Blueprint metadata (name, description, author, source_url)
         - Input definitions with selectors and defaults
-        - Blueprint configuration (triggers, conditions, actions for automations; sequence for scripts)
+        - `config`: the full parsed blueprint body (only with the ha_mcp_tools
+          component; `!input` substitution points appear as `{"__input__": name}`)
         """
         try:
             # Validate domain
@@ -202,9 +217,11 @@ class BlueprintTools:
                 if "input" in meta:
                     result["inputs"] = meta["input"]
 
-            # Add blueprint configuration if available
-            if "blueprint" in blueprint_data:
-                result["blueprint"] = blueprint_data["blueprint"]
+            # Core's blueprint/list returns metadata only (never a body), so the
+            # full triggers/conditions/actions/sequence come from the ha_mcp_tools
+            # component when installed. Merge it additively under `config`; without
+            # the component the response stays metadata + inputs.
+            await self._merge_blueprint_config(result, domain, path)
 
             return result
 
@@ -222,6 +239,73 @@ class BlueprintTools:
             )
             return None  # unreachable: exception_to_structured_error always raises
 
+    async def _merge_blueprint_config(
+        self, result: dict[str, Any], domain: str, path: str
+    ) -> None:
+        """Fetch the component-served blueprint body and merge it into ``result``.
+
+        Adds ``config`` when the body was read, or a top-level ``warnings`` entry
+        when a present component returned an unreadable body; a metadata-only
+        outcome (no component / capability) leaves ``result`` untouched.
+        """
+        config, config_warning = await self._blueprint_config_via_component(
+            domain, path
+        )
+        if config is not None:
+            result["config"] = config
+        elif config_warning is not None:
+            result.setdefault("warnings", []).append(config_warning)
+
+    async def _blueprint_config_via_component(
+        self, domain: str, path: str
+    ) -> tuple[dict[str, Any] | None, str | None]:
+        """Fetch a blueprint's full parsed body via the component.
+
+        core's ``blueprint/list`` returns only ``{metadata}`` (no body), so
+        without the component ``ha_get_blueprint`` can serve metadata + inputs
+        only. When the component advertises ``blueprint_get`` it reads the on-disk
+        blueprint file (path-jailed, executor-offloaded) and returns the full
+        parsed body, merged additively under ``config``. Returns
+        ``(config, warning)``:
+
+        - ``(dict, None)`` — the parsed body was read.
+        - ``(None, None)`` — metadata-only is the expected outcome: the component
+          is absent / lacks the capability, was downgraded (``unknown_command`` →
+          invalidate the cached caps), or errored (logged).
+        - ``(None, warning)`` — the component is present and the server has already
+          confirmed the path is a real installed blueprint, yet it returned a null
+          ``config`` (corrupt / unparseable file, read error). Metadata-only would
+          otherwise be indistinguishable from component-not-installed, so a
+          top-level warning is surfaced instead.
+        """
+        caps = await get_component_caps(self._client)
+        if not component_supports(caps, "blueprint_get"):
+            return None, None
+        try:
+            ws = await get_websocket_client(
+                url=self._client.base_url, token=self._client.token
+            )
+            raw = await ws.send_command(
+                "ha_mcp_tools/blueprint_get", domain=domain, path=path
+            )
+        except (HomeAssistantCommandError, HomeAssistantCommandTimeout) as exc:
+            if is_unknown_command(exc):
+                invalidate_caps(self._client)
+            else:
+                logger.warning(
+                    "ha_mcp_tools/blueprint_get failed; served metadata-only: %r",
+                    exc,
+                )
+            return None, None
+        result = raw.get("result") or {}
+        config = result.get("config")
+        if isinstance(config, dict):
+            return config, None
+        return None, (
+            "Blueprint body could not be read or parsed by the ha_mcp_tools "
+            "component; returning metadata only"
+        )
+
     async def _save_blueprint(
         self,
         url: str,

{ha_mcp_dev-7.13.0.dev1959 → ha_mcp_dev-7.13.0.dev1965}/src/ha_mcp/tools/tools_entities.py

@@ -14,8 +14,19 @@ from fastmcp.exceptions import ToolError
 from fastmcp.tools import tool
 from pydantic import Field
 
+from ..client.rest_client import (
+    HomeAssistantCommandError,
+    HomeAssistantCommandTimeout,
+)
+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 (
+    component_supports,
+    get_component_caps,
+    invalidate_caps,
+    is_unknown_command,
+)
 from .helpers import (
     exception_to_structured_error,
     extract_tool_error_message,
@@ -33,6 +44,11 @@ from .util_helpers import (
 
 logger = logging.getLogger(__name__)
 
+# The ha_mcp_tools/entity_enrich WS command: resolved area/floor/label NAMES +
+# aliases per entity_id, byte-shaped like the component's registry join. Named
+# once so the routing helper and its tests stay in lockstep.
+WS_ENTITY_ENRICH = "ha_mcp_tools/entity_enrich"
+
 # Bounds the per-frame size of a bulk config/entity_registry/get_entries call
 # (extended entries, ~1KB each) so a large id list can't produce an over-cap
 # WebSocket frame. Matches the chunk size smart_search uses for the same
@@ -73,6 +89,80 @@ def _format_fetched_entity(entry: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+async def fetch_entity_enrichment_via_component(
+    client: Any, entity_ids: list[str]
+) -> dict[str, dict[str, Any]] | None:
+    """One ``ha_mcp_tools/entity_enrich`` read; ``None`` ⇒ skip enrichment (legacy).
+
+    Returns the component's ``{id: {area, floor, labels, aliases}}`` map (resolved
+    area/floor/label NAMES the raw registry entry lacks — it carries ``area_id`` /
+    label *ids*) or ``None`` when the component lacks the ``entity_enrich``
+    capability, was downgraded (``unknown_command`` → invalidate the cached caps),
+    or errored (logged). ``None`` means "no enrichment available", NOT "no such
+    entity": ``ha_get_entity``'s registry read already served the base record, so a
+    ``None`` here simply leaves the additive fields off — the enrichment is
+    strictly additive, so its absence changes nothing else. A
+    ``HomeAssistantConnectionError`` (WS down) is not caught here, so it propagates
+    to the tool's own error handling. Follows the same caps-gate discipline as
+    ``component_devices.fetch_device_via_component``.
+
+    The ids are split into ``_GET_ENTRIES_CHUNK_SIZE`` chunks (the same bound the
+    sibling ``config/entity_registry/get_entries`` read uses) so a large bulk
+    request cannot produce an over-cap WebSocket frame or stall in the optional
+    enrichment step. Enrichment stays all-or-nothing: any chunk failing or drifting
+    in shape returns ``None`` (legacy shape), never a partially-enriched response.
+    """
+    if not entity_ids:
+        return None
+    caps = await get_component_caps(client)
+    if not component_supports(caps, "entity_enrich"):
+        return None
+    ids = list(entity_ids)
+    chunks = [
+        ids[i : i + _GET_ENTRIES_CHUNK_SIZE]
+        for i in range(0, len(ids), _GET_ENTRIES_CHUNK_SIZE)
+    ]
+    merged: dict[str, dict[str, Any]] = {}
+    try:
+        ws = await get_websocket_client(url=client.base_url, token=client.token)
+        for chunk in chunks:
+            raw = await ws.send_command(WS_ENTITY_ENRICH, entity_ids=chunk)
+            result = raw.get("result")
+            if not isinstance(result, dict):
+                return None
+            entities = result.get("entities")
+            if not isinstance(entities, dict):
+                return None
+            merged.update(entities)
+    except (HomeAssistantCommandError, HomeAssistantCommandTimeout) as exc:
+        if is_unknown_command(exc):
+            invalidate_caps(client)
+        else:
+            logger.warning("%s failed; skipped enrichment: %r", WS_ENTITY_ENRICH, exc)
+        return None
+    return merged
+
+
+def _merge_entity_enrichment(
+    record: dict[str, Any], enrichment: dict[str, Any] | None
+) -> None:
+    """Additively attach resolved area/floor/label NAMES to an entity record.
+
+    The base record already carries ``area_id`` and label *ids* (``labels``); the
+    component join adds the resolved, device-inherited NAMES under non-clobbering
+    keys — ``area`` / ``floor`` / ``label_names`` — so nothing existing is
+    overwritten. ``aliases`` is already on the base record (same set — the
+    component sorts, so ordering may differ — and the base value is authoritative),
+    so it is not re-added. A ``None`` / empty enrichment is a no-op: on a capability
+    miss the fields are simply absent, leaving the legacy response shape unchanged.
+    """
+    if not enrichment:
+        return
+    record["area"] = enrichment.get("area")
+    record["floor"] = enrichment.get("floor")
+    record["label_names"] = enrichment.get("labels") or []
+
+
 def _match_registry_by_unique_id(
     entries: list[dict[str, Any]],
     unique_id: str,
@@ -1816,6 +1906,16 @@ class EntityTools:
           helper's current config (template body, group members, etc.) without
           scanning a domain list.
         - unique_id: Integration's unique identifier
+
+        Resolved-name enrichment (present only when the ha_mcp_tools component
+        advertises it; otherwise these keys are absent):
+        - area: Assigned area NAME (device-inherited when the entity has none;
+          resolves area_id above)
+        - floor: Floor NAME of the assigned area
+        - label_names: Assigned label NAMES (resolves the label ids in labels)
+        Resolved label names live under label_names HERE (this tool's base
+        `labels` already carries the label ids); ha_search result_fields and
+        ha_get_entity_exposure instead emit the resolved names under `labels`.
         """
         try:
             # Resolver mode (unique_id) is mutually exclusive with entity_id.
@@ -1870,35 +1970,43 @@ class EntityTools:
             )
             return None  # unreachable: exception_to_structured_error always raises
 
+    async def _get_single_entity(self, eid: str) -> dict[str, Any]:
+        """Look up one entity registry entry, with additive enrichment."""
+        logger.info(f"Getting entity registry entry for {eid}")
+        try:
+            result = await self._fetch_entity(eid)
+        except ValueError as e:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    f"Entity not found: {e}",
+                    context={"entity_id": eid},
+                    suggestions=[
+                        "Use ha_search() to find valid entity IDs",
+                        "Check the entity_id spelling and format (e.g., 'sensor.temperature')",
+                    ],
+                )
+            )
+        # Additive area/floor/label-name enrichment via the component when it
+        # advertises entity_enrich; a capability miss leaves the fields off
+        # (legacy shape unchanged).
+        enriched = await fetch_entity_enrichment_via_component(self._client, [eid])
+        if enriched is not None:
+            _merge_entity_enrichment(result, enriched.get(eid))
+        return {
+            "success": True,
+            "entity_id": eid,
+            "entity_entry": result,
+        }
+
     async def _get_by_entity_id(self, entity_id: str | list[str]) -> dict[str, Any]:
         """Look up entities by entity_id (single or bulk list)."""
         entity_ids, is_bulk, early_response = _parse_get_entity_ids(entity_id)
         if early_response is not None:
             return early_response
 
-        # Single entity case
         if not is_bulk:
-            eid = entity_ids[0]
-            logger.info(f"Getting entity registry entry for {eid}")
-            try:
-                result = await self._fetch_entity(eid)
-            except ValueError as e:
-                raise_tool_error(
-                    create_error_response(
-                        ErrorCode.SERVICE_CALL_FAILED,
-                        f"Entity not found: {e}",
-                        context={"entity_id": eid},
-                        suggestions=[
-                            "Use ha_search() to find valid entity IDs",
-                            "Check the entity_id spelling and format (e.g., 'sensor.temperature')",
-                        ],
-                    )
-                )
-            return {
-                "success": True,
-                "entity_id": eid,
-                "entity_entry": result,
-            }
+            return await self._get_single_entity(entity_ids[0])
 
         # Bulk case - fetch all entities in one chunked get_entries call
         # (native HA bulk command) instead of one registry get per id.
@@ -1922,6 +2030,20 @@ class EntityTools:
                     }
                 )
 
+        # Additive area/floor/label-name enrichment for the found entities via the
+        # component's entity_enrich capability; missing ⇒ fields simply absent.
+        found_ids: list[str] = [
+            e["entity_id"]
+            for e in entity_entries
+            if isinstance(e.get("entity_id"), str)
+        ]
+        enriched = await fetch_entity_enrichment_via_component(self._client, found_ids)
+        if enriched is not None:
+            for entry in entity_entries:
+                entry_id = entry.get("entity_id")
+                if isinstance(entry_id, str):
+                    _merge_entity_enrichment(entry, enriched.get(entry_id))
+
         response: dict[str, Any] = {
             "success": True,
             "count": len(entity_entries),