ha-mcp-dev 8.4.0.dev2482__tar.gz → 8.4.0.dev2485__tar.gz

{ha_mcp_dev-8.4.0.dev2482/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.0.dev2485}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.0.dev2482
+Version: 8.4.0.dev2485
 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.0.dev2482 → ha_mcp_dev-8.4.0.dev2485}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.0.dev2482"
+version = "8.4.0.dev2485"
 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.0.dev2482 → ha_mcp_dev-8.4.0.dev2485}/src/ha_mcp/__init__.py

@@ -24,6 +24,7 @@ from .errors import (
     create_config_error,
     create_connection_error,
     create_entity_not_found_error,
+    create_entity_unavailable_after_dispatch_error,
     create_error_response,
     create_service_error,
     create_timeout_error,
@@ -45,6 +46,7 @@ __all__ = [
     "create_connection_error",
     "create_auth_error",
     "create_entity_not_found_error",
+    "create_entity_unavailable_after_dispatch_error",
     "create_service_error",
     "create_validation_error",
     "create_config_error",

{ha_mcp_dev-8.4.0.dev2482 → ha_mcp_dev-8.4.0.dev2485}/src/ha_mcp/errors.py

@@ -405,6 +405,36 @@ def create_entity_not_found_error(
     )
 
 
+def create_entity_unavailable_after_dispatch_error(entity_id: str) -> dict[str, Any]:
+    """Create an ENTITY_UNAVAILABLE error for a target whose command already dispatched.
+
+    Distinct from a bare "unavailable" report: by the time this fires, the
+    confirmation wait has already lapsed, which only happens AFTER the
+    service call reached Home Assistant. The caller must not read this as
+    "the command never went out" and blindly retry a non-idempotent service
+    (e.g. ``toggle``) — that would double-apply a write that may have already
+    landed. ``context["dispatched"]`` makes that explicit for a caller that
+    only inspects structured fields rather than the message.
+    """
+    return create_error_response(
+        ErrorCode.ENTITY_UNAVAILABLE,
+        f"Entity '{entity_id}' exists but is currently unavailable",
+        details=(
+            f"The service call for '{entity_id}' was already dispatched to Home "
+            "Assistant -- it may have taken effect even though the entity's "
+            "state could not be confirmed within the timeout."
+        ),
+        suggestions=[
+            "The command was already sent -- check the entity's current state "
+            + "with ha_get_state before retrying",
+            "Avoid re-issuing a non-idempotent service (e.g. toggle) that could "
+            + "double-apply if the original command did land",
+            "Check if the device is powered on and connected",
+        ],
+        context={"entity_id": entity_id, "dispatched": True},
+    )
+
+
 def create_service_error(
     domain: str,
     service: str,

{ha_mcp_dev-8.4.0.dev2482 → ha_mcp_dev-8.4.0.dev2485}/src/ha_mcp/server.py

@@ -655,6 +655,19 @@ class HomeAssistantSmartMCPServer:
             "ssh samba grafana influxdb deconz motioneye compile validate upload "
             "deploy firmware ota flash yaml device logs flows events stats"
         ),
+        # #2322: the Energy Dashboard's tariffs live in .storage/energy, not
+        # in the state machine, so an agent hunting for electricity prices
+        # searches entities, finds none, and invents input_number helpers.
+        # The docstring says "cost tariffs" but never "price", "peak" or
+        # "kWh" — the words agents actually query with — and the title reads
+        # write-only ("Manage ..."), so lead the boost with the read verbs.
+        "ha_manage_energy_prefs": (
+            "read get inspect energy dashboard preferences prefs "
+            "electricity price prices pricing tariff tariffs rate rates "
+            "cost costs kwh peak off-peak offpeak contract utility bill "
+            "grid solar battery gas water consumption "
+            "number_energy_price entity_energy_price stat_energy_from"
+        ),
         # Old tool names from before #1134 consolidation. BM25 retrieval
         # on agents that still know the previous catalog ("call
         # ha_list_resources", "use ha_get_skill_home_assistant_best_practices")

{ha_mcp_dev-8.4.0.dev2482 → ha_mcp_dev-8.4.0.dev2485}/src/ha_mcp/tools/device_control.py

@@ -23,7 +23,11 @@ from ..client.rest_client import (
 from ..client.websocket_client import get_websocket_client
 from ..client.websocket_listener import start_websocket_listener
 from ..config import get_global_settings
-from ..errors import ErrorCode, create_error_response
+from ..errors import (
+    ErrorCode,
+    create_entity_unavailable_after_dispatch_error,
+    create_error_response,
+)
 from ..utils.domain_handlers import get_domain_handler
 from ..utils.operation_manager import (
     fail_pending_operation,
@@ -43,7 +47,7 @@ from .helpers import (
     safe_progress,
 )
 from .tools_service import BulkControlOperation
-from .util_helpers import _SERVICE_TO_STATE
+from .util_helpers import _SERVICE_TO_STATE, is_single_entity_target
 
 logger = logging.getLogger(__name__)
 
@@ -1016,9 +1020,18 @@ class DeviceControlTools:
         by ``_build_bulk_response`` exactly as the legacy dispatch result is; an op
         whose ``async_call`` raised under the batch (``error`` set / not dispatched)
         maps to a structured ``SERVICE_CALL_FAILED`` error and is NOT re-dispatched
-        (D9). When ``validate_first`` (the default) is set and the target's captured
-        pre-state is null (the entity does not exist), the op maps to a structured
-        ``ENTITY_NOT_FOUND`` failure — parity with the legacy per-op validation.
+        (D9). When ``validate_first`` (the default) is set and ``entity_id`` is a
+        single literal entity ID (see ``is_single_entity_target`` — a comma-joined
+        multi-target or magic broadcast target like ``"all"`` is skipped entirely,
+        since its transition row proves nothing about whether the possibly-
+        successful dispatch landed), a captured pre-state that is null (the entity
+        does not exist) maps to a structured ``ENTITY_NOT_FOUND`` failure — parity
+        with the legacy per-op validation. A captured pre-state of ``"unavailable"``
+        maps to a distinct ``ENTITY_UNAVAILABLE`` failure, but only once BOTH the op
+        is unconfirmed AND the post-dispatch state still shows unavailable — unlike
+        the not-found branch, an unavailable target can legitimately reconnect and
+        confirm mid-dispatch, so this check is doubly gated rather than symmetric
+        with it.
         """
         service_call = {
             "domain": row["domain"],
@@ -1039,31 +1052,78 @@ class DeviceControlTools:
         # exist (HA no-ops the dispatch, then the wait stalls to partial). The legacy
         # path returns a structured ENTITY_NOT_FOUND per-op failure — match it from
         # the pre-state already in the transition (no extra hops), rather than
-        # counting a phantom entity as a successful command. Reachability is
-        # drift-bounded: a missing transition row from a length-drifted batch now routes
-        # to the ambiguous path (I2) before reaching here, so a null old_state here
-        # means a genuinely absent entity, not a dropped row.
-        if op.get("validate_first", True) and row.get("entity_ids"):
-            old_state = next(
+        # counting a phantom entity as a successful command. I2 (length-drift)
+        # guards the BATCH-level op-count, not this: an individual op can still
+        # legitimately carry an EMPTY transitions list (dispatched, but post-
+        # dispatch formatting raised — see _dispatched_unconfirmed_bulk_result) at
+        # the correct array length, and that proves nothing about existence. So
+        # look for a transition row at all first; only a present row with a null
+        # old_state means a genuinely absent entity.
+        if (
+            op.get("validate_first", True)
+            and row.get("entity_ids")
+            and is_single_entity_target(entity_id)
+        ):
+            transition = next(
                 (
-                    t.get("old_state")
+                    t
                     for t in transitions
                     if isinstance(t, dict) and t.get("entity_id") == entity_id
                 ),
                 None,
             )
-            if old_state is None:
-                err = create_error_response(
-                    ErrorCode.ENTITY_NOT_FOUND,
-                    f"Entity not found: {entity_id}",
-                    suggestions=[
-                        "Use ha_search to find the correct entity",
-                        "Check the entity is not disabled in Home Assistant",
-                    ],
-                    context={"entity_id": entity_id, "action": action},
-                )
-                err["service_call"] = service_call
-                return err
+            if transition is not None:
+                old_state = transition.get("old_state")
+                if old_state is None:
+                    err = create_error_response(
+                        ErrorCode.ENTITY_NOT_FOUND,
+                        f"Entity not found: {entity_id}",
+                        suggestions=[
+                            "Use ha_search to find the correct entity",
+                            "Check the entity is not disabled in Home Assistant",
+                        ],
+                        context={"entity_id": entity_id, "action": action},
+                    )
+                    err["service_call"] = service_call
+                    return err
+                if (
+                    isinstance(old_state, dict)
+                    and old_state.get("state") == "unavailable"
+                ):
+                    new_state = transition.get("new_state")
+                    if new_state is None and not component_op.get("confirmed"):
+                        # Removed during the dispatch -- a more specific outcome
+                        # than "still unavailable", which would falsely assert it
+                        # still exists.
+                        err = create_error_response(
+                            ErrorCode.ENTITY_NOT_FOUND,
+                            f"Entity not found: {entity_id}",
+                            suggestions=[
+                                "Use ha_search to find the correct entity",
+                                "Check the entity is not disabled in Home Assistant",
+                            ],
+                            context={"entity_id": entity_id, "action": action},
+                        )
+                        err["service_call"] = service_call
+                        return err
+                    if (
+                        not component_op.get("confirmed")
+                        and isinstance(new_state, dict)
+                        and new_state.get("state") == "unavailable"
+                    ):
+                        # Gated on NOT confirmed AND still unavailable per the
+                        # best-available post-dispatch read: unlike a nonexistent
+                        # entity, an "unavailable" one legitimately stays in the
+                        # component's confirmation wait and can reconnect and
+                        # transition mid-dispatch (see _confirmable_entity_ids) —
+                        # a confirmed op, or one whose new_state shows it
+                        # reconnected to some OTHER state (just not the expected
+                        # hint), must never be reported as this failure just
+                        # because its PRE-state was unavailable.
+                        err = create_entity_unavailable_after_dispatch_error(entity_id)
+                        err["action"] = action
+                        err["service_call"] = service_call
+                        return err
         final_state = next(
             (
                 t["new_state"].get("state")

{ha_mcp_dev-8.4.0.dev2482 → ha_mcp_dev-8.4.0.dev2485}/src/ha_mcp/tools/tools_service.py

@@ -14,6 +14,7 @@ from fastmcp.tools import tool
 from pydantic import ConfigDict, Field, SkipValidation, TypeAdapter, ValidationError
 
 from ..client.rest_client import (
+    HomeAssistantAPIError,
     HomeAssistantClient,
     HomeAssistantCommandError,
     HomeAssistantCommandNotSent,
@@ -23,6 +24,8 @@ from ..client.websocket_client import get_websocket_client
 from ..errors import (
     ErrorCode,
     create_connection_error,
+    create_entity_not_found_error,
+    create_entity_unavailable_after_dispatch_error,
     create_error_response,
     create_validation_error,
 )
@@ -53,6 +56,7 @@ from .util_helpers import (
     BLOCKED_WS_WRITE_COMMANDS,
     JSON_STRING_COERCION,
     compact_service_result,
+    is_single_entity_target,
     parse_json_param,
     parse_string_list_param,
     project_entity_record,
@@ -924,8 +928,8 @@ class ServiceTools:
             response["warnings"].append(_COMPONENT_RESPONSE_UNCONFIRMED_WARNING)
         return response
 
-    async def _capture_initial_state(self, entity_id: str | None) -> str | None:
-        """Capture the current state of an entity before a service call.
+    async def _validate_entity_before_wait(self, entity_id: str | None) -> str | None:
+        """Fetch entity_id's pre-call state, failing fast on a settled bad target.
 
         ``entity_id`` stays optional in the signature to match the caller's
         own ``str | None`` (a service call may target zero entities); the
@@ -936,18 +940,54 @@ class ServiceTools:
         not in a form the type checker can see through. Narrowing here
         instead of trusting the caller keeps ``get_entity_state`` (which
         genuinely requires a ``str``) honestly typed.
+
+        A clean 404 (the entity does not exist) settles the question with
+        certainty before any service dispatch or 10s state-change wait, so
+        raise immediately instead of silently degrading into a wait that can
+        never confirm. Any other fetch failure is NOT conclusive -- it
+        returns ``None`` and lets the call proceed as before, since the
+        entity may well exist and this could be a transient blip.
+
+        Deliberately NOT fast-failed here: a fetched ``"unavailable"``
+        state. Unlike a 404, it does not prove the target can never respond
+        -- dispatching the service is exactly what can reconnect it (e.g. a
+        device that wakes on the very command being sent), and failing here
+        would mean that command never reaches Home Assistant at all. The
+        entity's initial state is still returned so ``_verify_state_change``
+        can classify a genuine confirmation lapse as ENTITY_UNAVAILABLE only
+        if a live re-check shows it is STILL unavailable afterward -- mirrors
+        the component path's post-dispatch-state check.
+
+        A comma-separated ``entity_id`` ("light.a,light.b") or a Home
+        Assistant magic broadcast target (``entity_id="all"`` /
+        ``ENTITY_MATCH_ALL``, or ``"none"``) is a valid target for the
+        service-call payload, but the single-entity ``/api/states/<id>``
+        endpoint has no way to resolve either -- a 404 there proves nothing
+        about whether the underlying call can succeed, so the fast-fail is
+        skipped entirely for one (see ``is_single_entity_target``; matches
+        the component route's own comma exclusion in
+        ``_maybe_component_call_service``).
         """
         if entity_id is None:
             return None
+        is_single_target = is_single_entity_target(entity_id)
         try:
             state_data = await self._client.get_entity_state(entity_id)
-            return state_data.get("state") if state_data else None
+        except HomeAssistantAPIError as e:
+            if is_single_target and e.status_code == 404:
+                raise_tool_error(create_entity_not_found_error(entity_id))
+            logger.debug(
+                f"Could not fetch initial state for {entity_id}: {e} — state verification may be degraded"
+            )
+            return None
         except Exception as e:
             logger.debug(
                 f"Could not fetch initial state for {entity_id}: {e} — state verification may be degraded"
             )
             return None
 
+        return state_data.get("state") if state_data else None
+
     async def _verify_state_change(
         self,
         entity_id: str,
@@ -955,7 +995,17 @@ class ServiceTools:
         initial_state: str | None,
         response: dict[str, Any],
     ) -> None:
-        """Wait for and verify entity state change after a service call, updating response in place."""
+        """Wait for and verify entity state change after a service call, updating response in place.
+
+        An entity that was ``"unavailable"`` at dispatch time was NOT failed
+        fast (see ``_validate_entity_before_wait``) -- it may have reconnected
+        once the command actually reached it. Only once the wait genuinely
+        lapses does a fresh live re-check decide whether it's still
+        unavailable (report the precise ``ENTITY_UNAVAILABLE``) or reconnected
+        to some state other than the hint (leave the existing generic
+        partial/timeout wording) -- mirrors the component path's
+        post-dispatch-state check.
+        """
         try:
             expected = _SERVICE_TO_STATE.get(service)
             new_state = await wait_for_state_change(
@@ -967,15 +1017,58 @@ class ServiceTools:
             )
             if new_state:
                 response["verified_state"] = new_state.get("state")
-            else:
-                response.setdefault("warnings", []).append(
-                    "Service executed but state change could not be verified within timeout."
+                return
+            if initial_state == "unavailable" and await self._still_unavailable(
+                entity_id
+            ):
+                raise_tool_error(
+                    create_entity_unavailable_after_dispatch_error(entity_id)
                 )
+            response.setdefault("warnings", []).append(
+                "Service executed but state change could not be verified within timeout."
+            )
+        except ToolError:
+            raise
         except Exception as e:
             response.setdefault("warnings", []).append(
                 f"Service executed but state verification failed: {e}"
             )
 
+    async def _still_unavailable(self, entity_id: str) -> bool:
+        """Live re-check: True only when a successful fetch explicitly shows
+        ``"unavailable"``.
+
+        A 404 here means the entity was REMOVED since the initial fetch — a
+        more specific outcome than "still unavailable", so it raises
+        ENTITY_NOT_FOUND directly rather than being folded into it. Any other
+        fetch failure (network blip, an expired token surfacing as
+        ``HomeAssistantAuthError`` -- a sibling of ``HomeAssistantAPIError``,
+        not a subclass, so it lands in the generic branch below) or a
+        response with no usable ``state`` is inconclusive, not proof either
+        way, so it returns ``False`` and lets the caller fall through to the
+        generic verification-failed wording instead of confidently asserting
+        an unproven "still unavailable". Logged at WARNING (matching the
+        sibling re-check in ``_validate_entity_before_wait`` and
+        ``wait_for_state_change`` in util_helpers.py) so an operational
+        failure here -- an expired token, in particular -- leaves a
+        server-side trace instead of silently reading as a generic timeout.
+        """
+        try:
+            current = await self._client.get_entity_state(entity_id)
+        except HomeAssistantAPIError as e:
+            if e.status_code == 404:
+                raise_tool_error(create_entity_not_found_error(entity_id))
+            logger.warning(
+                f"Post-timeout unavailable re-check for {entity_id} failed: {e} — treating as inconclusive"
+            )
+            return False
+        except Exception as e:
+            logger.warning(
+                f"Post-timeout unavailable re-check for {entity_id} failed: {e} — treating as inconclusive"
+            )
+            return False
+        return isinstance(current, dict) and current.get("state") == "unavailable"
+
     @staticmethod
     def _split_return_response_envelope(
         result: Any, *, return_response: bool
@@ -1465,6 +1558,81 @@ class ServiceTools:
                     return new_state.get("state")
         return None
 
+    @staticmethod
+    def _raise_for_missing_or_unavailable_target(
+        transitions: list[Any], entity_id: str
+    ) -> None:
+        """Report why a confirmation never landed, once it's certain it never will.
+
+        Only reached when the component result was NOT confirmed. No-op
+        (returns) unless ``entity_id`` is a single literal entity ID (see
+        ``is_single_entity_target``): a comma-joined multi-target or a Home
+        Assistant magic broadcast target (``"all"`` / ``"none"``) is never a
+        literal entity in the state machine, so its transition row carries a
+        null ``old_state`` unconditionally -- that proves nothing about
+        whether the (possibly successful) broadcast landed, unlike a genuine
+        single-entity miss.
+
+        For a real single-entity target: the transition's ``old_state`` is
+        ``None`` for an entity absent from the state machine at pre-dispatch
+        time — the component excludes it from the wait entirely (it
+        structurally cannot ever confirm), so an unconfirmed result with a
+        null ``old_state`` is unambiguous: raise ENTITY_NOT_FOUND immediately.
+        A real state dict whose ``state`` is ``"unavailable"`` stayed IN the
+        component's confirmation wait (unlike a nonexistent target, it can
+        legitimately reconnect and transition mid-dispatch — the caller only
+        reaches this branch after that chance has already lapsed); what
+        happened to it by ``new_state`` (the best-available POST-dispatch
+        read: ``_post_state`` re-reads live if the listener's exact
+        expected-state event never arrived) then decides the outcome:
+
+        * ``new_state`` is ``None`` — the entity was REMOVED during the
+          dispatch, a more specific outcome than "still unavailable" (which
+          would falsely assert it still exists), so raise ENTITY_NOT_FOUND.
+        * ``new_state`` still shows ``"unavailable"`` — raise
+          ENTITY_UNAVAILABLE.
+        * ``new_state`` shows anything else — the target reconnected but
+          settled on some state other than the hint (e.g. a lock that
+          reached "locking", not yet "locked"), demonstrably no longer
+          unavailable even though this op never confirmed. Reporting it as
+          ENTITY_UNAVAILABLE from the stale pre-state alone would discard
+          that real result, so no-op instead.
+
+        No-op also for any other unconfirmed target — a real, available
+        entity whose confirming event simply never arrived, OR no transition
+        row at all (``_dispatched_unconfirmed_result``'s empty
+        ``transitions`` after a post-dispatch formatting failure — the write
+        already landed, so an absent row proves nothing about existence) —
+        leaving the caller's existing generic partial/timeout wording for
+        those genuine-ambiguity cases.
+        """
+        if not is_single_entity_target(entity_id):
+            return
+        transition = next(
+            (
+                t
+                for t in transitions
+                if isinstance(t, dict) and t.get("entity_id") == entity_id
+            ),
+            None,
+        )
+        if transition is None:
+            return
+        old_state = transition.get("old_state")
+        if old_state is None:
+            raise_tool_error(create_entity_not_found_error(entity_id))
+        if not (
+            isinstance(old_state, dict) and old_state.get("state") == "unavailable"
+        ):
+            return
+        new_state = transition.get("new_state")
+        if new_state is None:
+            # Removed during the dispatch -- a more specific outcome than
+            # "still unavailable", which would falsely assert it still exists.
+            raise_tool_error(create_entity_not_found_error(entity_id))
+        if isinstance(new_state, dict) and new_state.get("state") == "unavailable":
+            raise_tool_error(create_entity_unavailable_after_dispatch_error(entity_id))
+
     def _build_component_call_response(
         self,
         component_result: dict[str, Any],
@@ -1492,6 +1660,21 @@ class ServiceTools:
         timeout path produces (``_build_timeout_response``).
         """
         transitions = component_result.get("transitions") or []
+        # A nonexistent target's pre-dispatch read excludes it from the wait
+        # entirely, so it can never reach ``confirmed``; an "unavailable" one
+        # stays eligible and CAN reach it (a genuine reconnect-and-confirm) —
+        # only an UNCONFIRMED result is checked here, before building a generic
+        # partial/timeout response, using the same ``old_state``/``new_state``
+        # signal ``device_control.py``'s bulk-op mapping already reads from
+        # this identical transitions shape. A genuine confirmation lapse on a
+        # real, available target (old_state present, not "unavailable") falls
+        # through unchanged to the existing partial-success wording below.
+        if (
+            should_wait
+            and entity_id is not None
+            and not component_result.get("confirmed")
+        ):
+            self._raise_for_missing_or_unavailable_target(transitions, entity_id)
         # The transition new_states are State.as_dict() records — the same shape the
         # legacy REST POST returns — so the existing projection helpers apply
         # unchanged (compact filters to the target, drops metadata / heavy lists).
@@ -1538,9 +1721,13 @@ class ServiceTools:
                 )
         if should_wait:
             if component_result.get("partial"):
-                # Dispatched, but the confirming state_changed did not arrive within
-                # the wait — the same partial-success contract the legacy timeout
-                # path reports (success stays True; verification is never a failure).
+                # Reached only when _raise_for_missing_or_unavailable_target above
+                # did NOT raise -- i.e. a genuine confirmation lapse on a real,
+                # available target whose confirming state_changed simply never
+                # arrived within the wait. success stays True here (the same
+                # partial-success contract the legacy timeout path reports);
+                # unlike this generic case, a target proven nonexistent or still
+                # unavailable is a raised ToolError, not a partial success.
                 response["partial"] = True
                 response.setdefault("warnings", []).append(
                     "Service executed but state change could not be verified "
@@ -1819,10 +2006,16 @@ class ServiceTools:
                 return component_response
 
             # Legacy REST path (component absent, or it never dispatched): capture
-            # initial state before the call for the WS-subscribe verification.
+            # initial state before the call for the WS-subscribe verification. A
+            # settled 404 (single-entity target definitely does not exist) raises
+            # here, BEFORE the dispatch below, so a known-invalid call never
+            # reaches the service POST or the 10s confirmation wait. An
+            # "unavailable" target is NOT fast-failed here -- dispatching is
+            # exactly what might reconnect it; see _verify_state_change for its
+            # post-dispatch classification instead.
             initial_state = None
             if should_wait:
-                initial_state = await self._capture_initial_state(entity_id)
+                initial_state = await self._validate_entity_before_wait(entity_id)
 
             result = await self._client.call_service(
                 domain, service, service_data, return_response=return_response_bool

{ha_mcp_dev-8.4.0.dev2482 → ha_mcp_dev-8.4.0.dev2485}/src/ha_mcp/tools/util_helpers.py

@@ -53,6 +53,30 @@ _SERVICE_TO_STATE: dict[str, str] = {
 }
 
 
+def is_single_entity_target(entity_id: str | None) -> bool:
+    """True when ``entity_id`` looks like exactly one real, literal entity ID.
+
+    False for two shapes a not-found/unavailable lookup miss cannot settle
+    anything about:
+
+    * A comma-separated multi-target list ("light.a,light.b") — a valid
+      service-call payload the single-entity ``/api/states/<id>`` endpoint
+      has no syntax for, so its 404 on the literal joined string proves
+      nothing about the individual targets.
+    * A Home Assistant magic broadcast target — ``ENTITY_MATCH_ALL`` ("all")
+      or ``ENTITY_MATCH_NONE`` ("none"), both defined in
+      ``homeassistant/const.py`` and neither a literal entity in the state
+      machine, so a states-endpoint miss for either is expected and proves
+      nothing about whether the underlying service call can succeed.
+
+    A normal entity ID always has a ``domain.object_id`` shape (contains a
+    dot); the absence of one is the general, defensive signal used here
+    rather than hardcoding just "all"/"none" by name, so any other future
+    magic target is covered the same way.
+    """
+    return entity_id is not None and "," not in entity_id and "." in entity_id
+
+
 def websocket_error_message(error: Any) -> str:
     """Extract a readable message from a Home Assistant websocket error."""
     if isinstance(error, dict):

{ha_mcp_dev-8.4.0.dev2482 → ha_mcp_dev-8.4.0.dev2485}/src/ha_mcp/transforms/categorized_search.py

@@ -100,8 +100,10 @@ class SearchKeywordsTransform(Transform):
       a narrower one so BM25 ranks the tool *lower* for broad queries.
 
     The original description is preserved unless an override is applied.
-    Only active when added to the transform pipeline (i.e., behind
-    the ``enable_tool_search`` toggle).
+
+    Added to the transform pipeline unconditionally (#940), so ``keywords``
+    reach every client regardless of ``enable_tool_search``; only
+    ``overrides`` are gated behind that toggle.
     """
 
     def __init__(

{ha_mcp_dev-8.4.0.dev2482 → ha_mcp_dev-8.4.0.dev2485/src/ha_mcp_dev.egg-info}/PKG-INFO

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