ha-mcp-dev 8.6.0.dev2985__tar.gz → 8.6.0.dev2990__tar.gz

{ha_mcp_dev-8.6.0.dev2985 → ha_mcp_dev-8.6.0.dev2990}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2985
+Version: 8.6.0.dev2990
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien
@@ -413,7 +413,7 @@ Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA app). The full catal
 
 | Tool | Purpose |
 |------|---------|
-| `ha_search_tools` | BM25 English-keyword search across all tools, pinned ones included. Hidden tools return name, description, parameters, and annotations (`readOnlyHint` / `destructiveHint`) so the agent can pick the right one; a pinned tool returns a name-only stub (`pinned: true`) pointing back at the tool list, and does not use up a result slot. |
+| `ha_search_tools` | BM25 English-keyword search across all tools, pinned ones included. A hidden tool comes back compact: name, one-line description (the docstring's first paragraph), a one-line `params` list (types, enum values, required) and the proxy that executes it. `ha_search_tools(tools=[...])` returns the full definition (description, input schema and annotations) of the named tools, the second hop before a call. A pinned tool returns a name-only stub (`pinned: true`) pointing back at the tool list, and does not use up a result slot. |
 | `ha_call_read_tool` | Execute a `readOnlyHint` tool by name. Safe — clients can auto-approve. |
 | `ha_call_write_tool` | Execute a write tool that creates or updates data. |
 | `ha_call_delete_tool` | Execute a tool that removes / deletes data. |

{ha_mcp_dev-8.6.0.dev2985 → ha_mcp_dev-8.6.0.dev2990}/README.md

@@ -353,7 +353,7 @@ Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA app). The full catal
 
 | Tool | Purpose |
 |------|---------|
-| `ha_search_tools` | BM25 English-keyword search across all tools, pinned ones included. Hidden tools return name, description, parameters, and annotations (`readOnlyHint` / `destructiveHint`) so the agent can pick the right one; a pinned tool returns a name-only stub (`pinned: true`) pointing back at the tool list, and does not use up a result slot. |
+| `ha_search_tools` | BM25 English-keyword search across all tools, pinned ones included. A hidden tool comes back compact: name, one-line description (the docstring's first paragraph), a one-line `params` list (types, enum values, required) and the proxy that executes it. `ha_search_tools(tools=[...])` returns the full definition (description, input schema and annotations) of the named tools, the second hop before a call. A pinned tool returns a name-only stub (`pinned: true`) pointing back at the tool list, and does not use up a result slot. |
 | `ha_call_read_tool` | Execute a `readOnlyHint` tool by name. Safe — clients can auto-approve. |
 | `ha_call_write_tool` | Execute a write tool that creates or updates data. |
 | `ha_call_delete_tool` | Execute a tool that removes / deletes data. |

{ha_mcp_dev-8.6.0.dev2985 → ha_mcp_dev-8.6.0.dev2990}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2985"
+version = "8.6.0.dev2990"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-8.6.0.dev2985 → ha_mcp_dev-8.6.0.dev2990}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2985"
+version = "8.6.0.dev2990"
 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.6.0.dev2985 → ha_mcp_dev-8.6.0.dev2990}/src/ha_mcp/errors.py

@@ -310,7 +310,8 @@ def create_error_response(
         # Include first suggestion as primary, all suggestions in list
         error_dict["suggestion"] = error_suggestions[0]
         if len(error_suggestions) > 1:
-            error_dict["suggestions"] = error_suggestions
+            # A copy: the defaults are module-level lists shared by every call.
+            error_dict["suggestions"] = list(error_suggestions)
 
     response: dict[str, Any] = {
         "success": False,

{ha_mcp_dev-8.6.0.dev2985 → ha_mcp_dev-8.6.0.dev2990}/src/ha_mcp/llm_exposure.py

@@ -15,7 +15,8 @@ axis from the global enable/disable in the settings UI:
 For embedded servers with the Home Assistant LLM API enabled, the single
 source of truth travels **in-band**: :class:`LlmExposureMiddleware` stamps
 every ``tools/list`` entry with
-``_meta.ha_mcp = {"llm_api_exposed": bool, "pinned": bool, "policy": {...}}``
+``_meta.ha_mcp = {"llm_api_exposed": bool, "pinned": bool, "params": str,
+"policy": {...}}``
 so the component (one more loopback MCP client) filters on data that can never
 drift from the server's settings, with zero extra round-trips. The ``policy``
 block reports the serving server's gating state (#1990 — see META_POLICY_KEY). Stamping re-reads the
@@ -51,6 +52,10 @@ logger = logging.getLogger(__name__)
 META_NAMESPACE = "ha_mcp"
 META_EXPOSED_KEY = "llm_api_exposed"
 META_PINNED_KEY = "pinned"
+# The one-line parameter summary the component's search hits show (#2633).
+# Rendered here so the component, which cannot import this package, carries
+# no copy of the renderer.
+META_PARAMS_KEY = "params"
 
 # Serving-server policy/identity block stamped alongside the per-tool keys
 # (#1990). A client (or a debugging agent) reading tools/list can see the
@@ -267,6 +272,8 @@ class LlmExposureMiddleware(Middleware):
         call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]],
     ) -> Sequence[Tool]:
         """Stamp ``_meta.ha_mcp`` on every tool in the list result."""
+        from .transforms.compact_params import compact_params
+
         tools = await call_next(context)
         overrides, pinned = self._current_settings()
         policy_block = self._policy_block()
@@ -279,6 +286,7 @@ class LlmExposureMiddleware(Middleware):
                 tool.name, tool.tags or set(), overrides
             )
             namespace[META_PINNED_KEY] = tool.name in pinned
+            namespace[META_PARAMS_KEY] = compact_params(tool.parameters)
             namespace[META_POLICY_KEY] = policy_block
             meta[META_NAMESPACE] = namespace
             stamped.append(tool.model_copy(update={"meta": meta}))

{ha_mcp_dev-8.6.0.dev2985 → ha_mcp_dev-8.6.0.dev2990}/src/ha_mcp/read_only.py

@@ -348,6 +348,17 @@ def read_only_visible(tool: Tool) -> bool:
 def _raise_read_only_error(
     name: str, *, blocked_operation: str | None = None, allowed: str | None = None
 ) -> NoReturn:
+    raise_tool_error(
+        read_only_error_response(
+            name, blocked_operation=blocked_operation, allowed=allowed
+        )
+    )
+
+
+def read_only_error_response(
+    name: str, *, blocked_operation: str | None = None, allowed: str | None = None
+) -> dict[str, Any]:
+    """The structured ``READ_ONLY_MODE`` error for a blocked call to *name*."""
     context: dict[str, Any] = {"tool_name": name, "read_only_mode": True}
     if blocked_operation is not None:
         context["blocked_operation"] = blocked_operation
@@ -364,17 +375,15 @@ def _raise_read_only_error(
             f"'{name}' is a write-capable tool, so the call was blocked — "
             f"no changes were made."
         )
-    raise_tool_error(
-        create_error_response(
-            ErrorCode.READ_ONLY_MODE,
-            message,
-            suggestions=[
-                "Continue with read-only tools — searching, getting, and "
-                + "listing data all remain available.",
-                read_only_remedy_hint(),
-            ],
-            context=context,
-        )
+    return create_error_response(
+        ErrorCode.READ_ONLY_MODE,
+        message,
+        suggestions=[
+            "Continue with read-only tools — searching, getting, and "
+            + "listing data all remain available.",
+            read_only_remedy_hint(),
+        ],
+        context=context,
     )
 
 

{ha_mcp_dev-8.6.0.dev2985 → ha_mcp_dev-8.6.0.dev2990}/src/ha_mcp/server_tool_text.py

@@ -9,9 +9,10 @@ from __future__ import annotations
 
 # Description for the unified search tool
 SEARCH_TOOL_DESCRIPTION = (
-    "Search ALL Home Assistant tools by ENGLISH keyword. Returns matching "
-    "tools with descriptions, parameters, and annotations "
-    "(read/write/delete). Categories: entities, states, automations, "
+    "Search ALL Home Assistant tools by ENGLISH keyword. Each hit is "
+    "compact: name, one-line description, a one-line params list (types, "
+    "enum values, required), and the proxy that executes it. Categories: "
+    "entities, states, automations, "
     "scripts, dashboards, helpers, HACS, calendar, zones, labels, groups, "
     "areas, floors, history, statistics, devices, integrations, services, "
     "backups, todo, camera, blueprints, system, and more.\n\n"
@@ -20,13 +21,17 @@ SEARCH_TOOL_DESCRIPTION = (
     "(pinned: true); use the schema you already have.\n\n"
     "WORKFLOW:\n"
     "1. ha_search_tools(query='...') \u2014 find tools (this tool)\n"
-    "2. Execute: call the tool DIRECTLY by name (preferred), or use "
+    "2. ha_search_tools(tools=['<name>']) \u2014 full description and input "
+    "schema of the tool(s) you will call. Do this BEFORE calling: the compact "
+    "hit omits usage guidance, nested fields, defaults and parameter "
+    "descriptions.\n"
+    "3. Execute: call the tool DIRECTLY by name (preferred), or use "
     "a proxy for permission gating:\n"
     "   - ha_call_read_tool \u2014 readOnlyHint tools (safe, no side effects)\n"
     "   - ha_call_write_tool \u2014 destructiveHint tools that create/update\n"
     "   - ha_call_delete_tool \u2014 destructiveHint tools that remove/delete\n"
-    "Once you know a tool name, call it directly \u2014 no need to search "
-    "again.\n\n"
+    "Once you hold a tool's full schema, call it directly \u2014 no need to "
+    "repeat the keyword search or the schema lookup.\n\n"
     "If using proxies, call with TWO top-level params:\n"
     '   ha_call_read_tool(name="ha_search", arguments={"query": "..."})\n'
     "   Do NOT nest name/arguments inside the arguments param.\n"
@@ -40,8 +45,9 @@ SEARCH_TOOL_DESCRIPTION = (
 TOOL_DISCOVERY_INSTRUCTIONS = (
     "\n\n## Tool Discovery\n"
     "Tools already in your tool list are callable directly — "
-    "do not search for them. Once you know any tool’s name, "
-    "call it directly; never search for the same tool twice.\n\n"
+    "do not search for them. Once you hold a tool’s full schema, "
+    "call it directly; repeat neither the keyword search nor the "
+    "schema lookup for the same tool.\n\n"
     "Most other tools are NOT listed directly — use "
     "ha_search_tools to find them.\n\n"
     "WORKFLOW:\n"
@@ -49,8 +55,10 @@ TOOL_DISCOVERY_INSTRUCTIONS = (
     "naming the operation (e.g. 'get entity state'). Translate "
     "other languages first; entity, area and device names keep "
     "their original spelling.\n"
-    "2. Results include name, description, parameters, and "
-    "annotations (readOnlyHint/destructiveHint). A tool already "
+    "2. Results are compact: name, one-line description, a one-line "
+    "params list and the proxy to use. Before calling, fetch the full "
+    "description and input schema with ha_search_tools(tools=['<name>']). "
+    "A tool already "
     "in your list comes back as a name-only stub (pinned: true) "
     "— use the schema you already have.\n"
     "3. Execute the discovered tool — two options:\n"

{ha_mcp_dev-8.6.0.dev2985 → ha_mcp_dev-8.6.0.dev2990}/src/ha_mcp/tools/config_helpers/update.py

@@ -78,9 +78,13 @@ async def _execute_legacy_update(
         {**body, "type": f"{helper_type}/update", f"{helper_type}_id": unique_id}
     )
     if not result.get("success"):
+        code = ws_failure_code(result)
+        if code is ErrorCode.RESOURCE_NOT_FOUND:
+            # The item vanished after _stored_item read it; report it the same way.
+            code = ErrorCode.CONFIG_NOT_FOUND
         raise_tool_error(
             create_error_response(
-                ws_failure_code(result),
+                code,
                 f"Failed to update {helper_type} config: "
                 f"{result.get('error', 'Unknown error')}",
                 context=_simple_helper_error_context(helper_type, entity_id=entity_id),

ha_mcp_dev-8.6.0.dev2990/src/ha_mcp/tools/flow_helper_lookup.py

@@ -0,0 +1,400 @@
+"""Resolve the helper behind an entity_id for ha_remove_helpers_integrations."""
+
+import logging
+from typing import Any, Literal, NoReturn
+
+from ..client.rest_client import (
+    HomeAssistantAPIError,
+    HomeAssistantAuthError,
+    HomeAssistantConnectionError,
+)
+from ..errors import ErrorCode, create_error_response
+from .config_entry_flow import FLOW_HELPER_TYPES
+from .config_helpers.schemas import SIMPLE_HELPER_TYPES
+from .helpers import raise_tool_error, ws_failure_code
+
+logger = logging.getLogger(__name__)
+
+YAML_HELPER_REMOVAL = (
+    "YAML-configured helpers must be removed by editing the configuration file."
+)
+YAML_HELPER_SUGGESTION = "Edit the YAML file and reload the relevant integration."
+
+FlowLookupReason = Literal[
+    "ok",
+    "wrong_helper_type",
+    "bare_id_not_supported",
+    "not_in_registry",
+    "not_registry_managed",
+    "no_config_entry",
+    "lookup_failed",
+]
+
+
+async def _read_registry_entry(
+    client: Any, entity_id: str, warnings: list[str] | None = None
+) -> tuple[dict[str, Any] | None, FlowLookupReason]:
+    """Read ``entity_id``'s entity-registry entry, or ``(None, reason)``.
+
+    ``reason`` is ``lookup_failed`` for an OSError/TimeoutError from the
+    WebSocket send. On Core's ``not_found`` the entity's state decides between
+    ``not_registry_managed`` and ``not_in_registry``. A ``success: false``
+    reply other than ``not_found``, and a reply without an entry, raise a
+    ToolError: neither proves the entity is absent. HomeAssistantConnectionError, HomeAssistantAuthError
+    and a non-404 HomeAssistantAPIError from the state read propagate to the
+    caller's except chain.
+    """
+    try:
+        result = await client.send_websocket_message(
+            {"type": "config/entity_registry/get", "entity_id": entity_id}
+        )
+    except (HomeAssistantConnectionError, HomeAssistantAuthError):
+        # Typed errors must reach the outer handler — do not swallow.
+        raise
+    except (OSError, TimeoutError) as e:
+        # Network / transport errors from the WS layer (ConnectionError,
+        # BrokenPipeError, TimeoutError, …). Programmer-bug-shape
+        # exceptions (KeyError, AttributeError, TypeError) intentionally
+        # propagate — the response is shape-checked at the dict guard
+        # below, and catching them here would mask the bug as a
+        # transient WEBSOCKET_DISCONNECTED.
+        logger.debug(f"entity_registry/get failed for {entity_id}: {e}")
+        if warnings is not None:
+            warnings.append(f"entity_registry/get failed for {entity_id}: {e}")
+        return None, "lookup_failed"
+
+    if not isinstance(result, dict):
+        _raise_unexpected_registry_reply(entity_id, result)
+    if not result.get("success"):
+        # Core answers an unknown entity with not_found; any other failure (a
+        # proxy block, a malformed request) is no evidence of absence.
+        if result.get("error_code") != "not_found":
+            raise_tool_error(
+                create_error_response(
+                    ws_failure_code(result),
+                    f"Reading the entity registry for {entity_id} failed: "
+                    f"{result.get('error') or 'unknown error'}",
+                    context={"entity_id": entity_id},
+                    suggestions=result.get("suggestions"),
+                )
+            )
+        return None, await _absence_reason(client, entity_id)
+
+    entry = result.get("result")
+    if not isinstance(entry, dict) or not entry:
+        _raise_unexpected_registry_reply(entity_id, entry)
+    return entry, "ok"
+
+
+def _raise_unexpected_registry_reply(entity_id: str, reply: Any) -> NoReturn:
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            (
+                f"Reading the entity registry for {entity_id} returned no "
+                f"entry ({type(reply).__name__}). Nothing was deleted."
+            ),
+            context={"entity_id": entity_id},
+        )
+    )
+
+
+async def _absence_reason(client: Any, entity_id: str) -> FlowLookupReason:
+    """Tell an entity Core keeps no registry entry for from a missing one.
+
+    Core registers only entities with a ``unique_id``; one without it (a YAML
+    template sensor without unique_id, ``zone.home``) still has a state. A
+    state read failing with a status other than 404 propagates.
+    """
+    try:
+        state = await client.get_entity_state(entity_id)
+    except HomeAssistantAPIError as e:
+        if e.status_code != 404:
+            raise
+        state = None
+    return "not_registry_managed" if state else "not_in_registry"
+
+
+def raise_unregistered_entity_error(
+    target: str, helper_type: str | None, entity_id: str
+) -> NoReturn:
+    """Refuse an entity that has a state but no entity-registry entry."""
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.RESOURCE_NOT_FOUND,
+            (
+                f"{entity_id} has a state but no entity registry entry, so it "
+                "is not managed through the registry and cannot be removed "
+                "here. Nothing was deleted."
+            ),
+            context={
+                "target": target,
+                "helper_type": helper_type,
+                "entity_id": entity_id,
+            },
+            suggestions=[
+                (
+                    "Remove it where it is defined, e.g. delete it from its "
+                    "YAML file and reload that integration."
+                ),
+                (
+                    "Entities Home Assistant builds from its core "
+                    "configuration, such as zone.home, cannot be removed."
+                ),
+            ],
+        )
+    )
+
+
+async def get_entry_id_for_flow_helper(
+    client: Any,
+    helper_type: str,
+    target: str,
+    warnings: list[str] | None = None,
+) -> tuple[str | None, FlowLookupReason]:
+    """Resolve a flow-helper target to its config_entry_id via entity_registry.
+
+    Used by ha_remove_helpers_integrations when target is an entity_id
+    (contains a '.') and helper_type is a known flow-helper type.
+
+    Args:
+        client: HomeAssistantClient instance.
+        helper_type: Flow-helper type (must be in FLOW_HELPER_TYPES).
+        target: Full entity_id, e.g. "sensor.my_meter". Bare IDs not
+            supported for flow helpers (caller must provide entity_id).
+        warnings: Optional list — appended to on WebSocket failure.
+
+    Returns:
+        Tuple of (config_entry_id, reason). On success: (entry_id, "ok").
+        On failure: (None, reason) where reason discriminates the cause so
+        the caller can produce an accurate error response without an extra
+        WebSocket round-trip.
+
+    Raises:
+        ToolError: the entity belongs to another integration than
+            helper_type, or the registry read failed for a reason other than
+            ``not_found``.
+        HomeAssistantConnectionError, HomeAssistantAuthError: propagated.
+        HomeAssistantAPIError: the state read that tells an unregistered
+            entity from a missing one failed with a status other than 404.
+    """
+    if helper_type not in FLOW_HELPER_TYPES:
+        return None, "wrong_helper_type"
+
+    if "." not in target:
+        return None, "bare_id_not_supported"
+
+    entry, reason = await _read_registry_entry(client, target, warnings)
+    if entry is None:
+        return None, reason
+
+    # A helper's entities are registered under its own integration, so a
+    # foreign platform means the config_entry_id belongs to another integration.
+    platform = entry.get("platform")
+    if platform != helper_type:
+        _raise_platform_mismatch(target, helper_type, platform)
+
+    config_entry_id = entry.get("config_entry_id")
+    if not config_entry_id:
+        return None, "no_config_entry"
+    return config_entry_id, "ok"
+
+
+def _raise_platform_mismatch(target: str, helper_type: str, platform: Any) -> NoReturn:
+    """Refuse an explicit flow-helper type that the entity's registry
+    platform contradicts, naming the platform so the caller can tell whether
+    omitting helper_type can work."""
+    if platform in SIMPLE_HELPER_TYPES or platform in FLOW_HELPER_TYPES:
+        retry = f"Pass helper_type='{platform}', or omit helper_type."
+    else:
+        retry = (
+            f"Omit helper_type only if '{platform}' is a helper integration; "
+            "otherwise use ha_remove_entity() to remove just this entity, or "
+            "pass the integration's config entry_id as target."
+        )
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            (
+                f"{target} is not a {helper_type} helper: it belongs to the "
+                f"'{platform}' integration. Nothing was deleted."
+            ),
+            context={
+                "target": target,
+                "helper_type": helper_type,
+                "platform": platform,
+            },
+            suggestions=[retry],
+        )
+    )
+
+
+def raise_flow_helper_lookup_error(
+    reason: FlowLookupReason,
+    helper_type: str | None,
+    target: str,
+    detail: str | None = None,
+) -> NoReturn:
+    """Raise the structured error for a failed flow-helper entry_id lookup.
+
+    ``reason`` discriminates the failure mode without a second WebSocket
+    round-trip. The lookup helper already queried the registry; the response
+    told us everything we need.
+    """
+    entity_id = target if "." in target else f"{helper_type}.{target}"
+    if reason == "not_registry_managed":
+        raise_unregistered_entity_error(target, helper_type, entity_id)
+    if reason == "no_config_entry":
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.RESOURCE_NOT_FOUND,
+                (
+                    f"Helper {target} is not a storage-based helper "
+                    f"(no config entry). {YAML_HELPER_REMOVAL}"
+                ),
+                context={
+                    "target": target,
+                    "helper_type": helper_type,
+                    "entity_id": entity_id,
+                },
+                suggestions=[YAML_HELPER_SUGGESTION],
+            )
+        )
+    if reason == "lookup_failed":
+        # Registry WebSocket call failed transiently. Surface as
+        # a connectivity error so the caller knows to retry,
+        # rather than chasing a non-existent entity_id.
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.WEBSOCKET_DISCONNECTED,
+                (
+                    f"Registry lookup for {entity_id} failed due to a "
+                    f"WebSocket error{f': {detail}' if detail else '.'}"
+                ),
+                context={
+                    "target": target,
+                    "helper_type": helper_type,
+                    "entity_id": entity_id,
+                },
+            )
+        )
+    # wrong_helper_type cannot occur here because the dispatcher
+    # already checked SIMPLE_HELPER_TYPES / FLOW_HELPER_TYPES; the
+    # assertion enforces that contract at runtime.
+    assert reason != "wrong_helper_type"
+    if reason == "not_in_registry":
+        # Target is absent from the entity registry and has no
+        # state. Surface as ENTITY_NOT_FOUND (entity-shaped target) so the
+        # caller learns the identifier is unusable — the typo
+        # case is the failure mode "absent → success" would
+        # silently mask. Matches the bare_id_not_supported
+        # branch below and sibling ha_remove_entity.
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.ENTITY_NOT_FOUND,
+                (
+                    f"Helper {target} not found in entity "
+                    f"registry (looked up as {entity_id}). "
+                    "May indicate it was already removed, "
+                    "never existed, or the identifier is a "
+                    "typo. Verify with ha_search() "
+                    "before retrying."
+                ),
+                context={
+                    "target": target,
+                    "helper_type": helper_type,
+                    "entity_id": entity_id,
+                },
+                suggestions=[
+                    "Use ha_search() — flow helper "
+                    "types often expose entities under a "
+                    "different domain than the helper_type "
+                    "itself (e.g. utility_meter → sensor.*, "
+                    "switch_as_x → switch.* / light.*)."
+                    if helper_type
+                    else "Find the entity_id with ha_search().",
+                ],
+            )
+        )
+    # bare_id_not_supported → caller passed a bare ID where an
+    # entity_id was required. That's a call-shape error, not
+    # missing-target; surface as ENTITY_NOT_FOUND with the
+    # search suggestion so the caller can self-correct.
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.ENTITY_NOT_FOUND,
+            (
+                f"Helper {target} not found in entity registry "
+                f"(looked up as {entity_id})."
+            ),
+            context={
+                "target": target,
+                "helper_type": helper_type,
+                "entity_id": entity_id,
+            },
+            suggestions=[
+                "For a config entry_id target, omit helper_type to delete it.",
+                (
+                    "Otherwise find the entity_id with ha_search(): flow "
+                    "helpers often use another domain (utility_meter → sensor.*)."
+                ),
+            ],
+        )
+    )
+
+
+async def resolve_helper_entity(client: Any, entity_id: str) -> tuple[str | None, str]:
+    """Return the ``(helper_type, target)`` that removes the helper behind ``entity_id``.
+
+    The registry ``platform`` names the integration that owns the entity. A
+    helper Core lists as a helper flow but not in FLOW_HELPER_TYPES (``otp``,
+    custom integrations) comes back as ``(None, config_entry_id)``: a direct
+    entry delete. An entity of any other integration is refused.
+    """
+    warnings: list[str] = []
+    entry, reason = await _read_registry_entry(client, entity_id, warnings)
+    if entry is None:
+        raise_flow_helper_lookup_error(
+            reason, None, entity_id, detail="; ".join(warnings) or None
+        )
+    platform = entry.get("platform")
+    if platform in SIMPLE_HELPER_TYPES or platform in FLOW_HELPER_TYPES:
+        return platform, entity_id
+    if platform in await _helper_flow_domains(client):
+        config_entry_id = entry.get("config_entry_id")
+        if not config_entry_id:
+            raise_flow_helper_lookup_error("no_config_entry", platform, entity_id)
+        return None, config_entry_id
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            (
+                f"{entity_id} belongs to the '{platform}' integration, which "
+                "is not a helper. Nothing was deleted."
+            ),
+            context={"target": entity_id, "platform": platform},
+            suggestions=[
+                "To remove only this entity, use ha_remove_entity().",
+                (
+                    "To delete the integration's config entry, pass its "
+                    "entry_id as target."
+                ),
+            ],
+        )
+    )
+    return None  # py/mixed-returns: explicit terminal; error handlers above always raise (NoReturn), unreachable
+
+
+async def _helper_flow_domains(client: Any) -> frozenset[str]:
+    """Core's helper flows plus custom integrations of integration_type helper."""
+    domains = await client._request(
+        "GET", "/config/config_entries/flow_handlers", params={"type": "helper"}
+    )
+    # _request answers an unparseable body with {}; an empty set would refuse
+    # every helper outside the static lists as "not a helper".
+    if not isinstance(domains, list):
+        raise HomeAssistantConnectionError(
+            "flow_handlers returned an unexpected response shape: "
+            f"{type(domains).__name__}"
+        )
+    return frozenset(domains)

{ha_mcp_dev-8.6.0.dev2985 → ha_mcp_dev-8.6.0.dev2990}/src/ha_mcp/tools/helpers.py

@@ -705,9 +705,13 @@ async def safe_progress(
 
 
 def ws_failure_code(result: dict[str, Any]) -> ErrorCode:
-    """Core answers a schema-invalid write with ``invalid_format``: the caller's input."""
-    if result.get("error_code") == "invalid_format":
+    """Map Core's WS error code: ``invalid_format`` is the caller's input,
+    ``not_found`` an item Core does not hold (e.g. a YAML-configured helper)."""
+    code = result.get("error_code")
+    if code == "invalid_format":
         return ErrorCode.VALIDATION_INVALID_PARAMETER
+    if code == "not_found":
+        return ErrorCode.RESOURCE_NOT_FOUND
     return ErrorCode.SERVICE_CALL_FAILED