homeassistant-ai
diff --git a/‎custom_components/ha_mcp_tools/const.py‎
Lines changed: 1 addition & 1 deletion b/‎custom_components/ha_mcp_tools/const.py‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎custom_components/ha_mcp_tools/manifest.json‎
Lines changed: 1 addition & 1 deletion b/‎custom_components/ha_mcp_tools/manifest.json‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎custom_components/ha_mcp_tools/websocket_api.py‎
Lines changed: 702 additions & 15 deletions b/‎custom_components/ha_mcp_tools/websocket_api.py‎
Lines changed: 702 additions & 15 deletions
diff --git a/‎src/ha_mcp/backup_manager.py‎
Lines changed: 13 additions & 2 deletions b/‎src/ha_mcp/backup_manager.py‎
Lines changed: 13 additions & 2 deletions
diff --git a/‎src/ha_mcp/client/rest_client.py‎
Lines changed: 9 additions & 1 deletion b/‎src/ha_mcp/client/rest_client.py‎
Lines changed: 9 additions & 1 deletion
diff --git a/‎src/ha_mcp/tools/component_devices.py‎
Lines changed: 153 additions & 0 deletions b/‎src/ha_mcp/tools/component_devices.py‎
Lines changed: 153 additions & 0 deletions
diff --git a/‎src/ha_mcp/tools/radio/base.py‎
Lines changed: 12 additions & 3 deletions b/‎src/ha_mcp/tools/radio/base.py‎
Lines changed: 12 additions & 3 deletions
diff --git a/‎src/ha_mcp/tools/radio/zigbee.py‎
Lines changed: 28 additions & 4 deletions b/‎src/ha_mcp/tools/radio/zigbee.py‎
Lines changed: 28 additions & 4 deletions
@@ -24,7 +24,7 @@
 # manifest bump that forgets this constant (or vice-versa) fails in CI. The
 # capability negotiation — not this version — gates each WS command (see
 # ``websocket_api.CAPABILITIES``).
-COMPONENT_VERSION = "1.1.0"
+COMPONENT_VERSION = "1.1.1"
 
 # Config-entry discriminator (``entry.data[CONF_ENTRY_TYPE]``). A missing value
 # means "tools" so the pre-existing services entry keeps working across the
 
@@ -19,5 +19,5 @@
     "requirements": [
         "ruamel.yaml>=0.18.0"
     ],
-    "version": "1.1.0"
+    "version": "1.1.1"
 }
@@ -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
 
 
@@ -1445,6 +1445,7 @@ async def send_websocket_message(self, message: dict[str, Any]) -> dict[str, Any
                         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 @@ async def send_websocket_message(self, message: dict[str, Any]) -> dict[str, Any
                 # 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"}
 
 
@@ -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
@@ -21,6 +21,7 @@
 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 [])
 
@@ -19,6 +19,7 @@
 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 @@
 }
 
 
+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", []):
Original file line number	Diff line number	Diff line change
`@@ -19,5 +19,5 @@`
`19`	`19`	`"requirements": [`
`20`	`20`	`"ruamel.yaml>=0.18.0"`
`21`	`21`	`],`
`22`		`- "version": "1.1.0"`
	`22`	`+ "version": "1.1.1"`
`23`	`23`	`}`