ha-mcp-dev 7.14.2.dev2095__tar.gz → 7.14.2.dev2098__tar.gz

{ha_mcp_dev-7.14.2.dev2095/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.14.2.dev2098}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.14.2.dev2095
+Version: 7.14.2.dev2098
 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.14.2.dev2095 → ha_mcp_dev-7.14.2.dev2098}/pyproject.toml

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

@@ -766,16 +766,18 @@ class BackupManager:
 
     # ----- legacy store (pre-#1579 .ha_mcp_tools_backups/) ---------------
 
-    async def list_legacy(self) -> list[dict[str, Any]]:
+    async def list_legacy(self) -> tuple[list[dict[str, Any]], str | None]:
         """List pre-#1579 ``.bak`` backups via the component service.
 
         Each entry is normalized to a synthetic ``name`` (``legacy:<file>``)
         plus ``source="legacy"`` and the decode hints (``file_path`` /
         ``path_ambiguous``) so the caller can route view/diff/restore and warn
-        on un-restorable (ambiguous) names. Returns ``[]`` when the component
-        is too old to expose the service, so ``list`` still works.
+        on un-restorable (ambiguous) names. Returns ``(entries,
+        unavailable_reason)``: entries is ``[]`` when the component is too
+        old, unconfigured, or absent — ``list`` still works — and the reason
+        (when set) lets the caller flag the omission.
         """
-        backups = await _list_legacy_backups(self._client)
+        backups, unavailable_reason = await _list_legacy_backups(self._client)
         out: list[dict[str, Any]] = []
         for b in backups:
             filename = b.get("filename")
@@ -792,7 +794,7 @@ class BackupManager:
                     "path_ambiguous": b.get("path_ambiguous", True),
                 }
             )
-        return out
+        return out, unavailable_reason
 
     async def read_legacy(self, filename: str) -> dict[str, Any]:
         """Read one legacy ``.bak`` (raw content + decode hints).
@@ -815,7 +817,7 @@ class BackupManager:
         domain: str | None = None,
         entity_id: str | None = None,
         limit: int | None = None,
-    ) -> list[dict[str, Any]]:
+    ) -> tuple[list[dict[str, Any]], list[str]]:
         """Edits-store snapshots plus pre-#1579 legacy ``.bak`` entries (#1579).
 
         ``list_snapshots`` is sync (dir glob, run off-thread); the legacy store
@@ -828,9 +830,22 @@ class BackupManager:
         Legacy entries get reserved room within ``limit`` so a full edits store
         (>= ``limit`` snapshots) can't truncate the few historical legacy
         entries out of the listing — surfacing them is the whole point.
+
+        Returns ``(entries, warnings)``: when the legacy sub-fetch was
+        suppressed (tools entry not set up / component too old), ``warnings``
+        says so, so the tool response doesn't read as a clean, complete list
+        with the ``.bak`` history silently missing (#1996).
         """
         want_legacy = domain in (None, "yaml_file") and entity_id is None
-        legacy = await self.list_legacy() if want_legacy else []
+        legacy: list[dict[str, Any]] = []
+        warnings: list[str] = []
+        if want_legacy:
+            legacy, unavailable_reason = await self.list_legacy()
+            if unavailable_reason:
+                warnings.append(
+                    "Legacy .bak backups could not be listed and are omitted: "
+                    f"{unavailable_reason}"
+                )
         edits_limit = max(1, limit - len(legacy)) if limit and legacy else limit
         entries = await asyncio.to_thread(
             self.list_snapshots, domain=domain, entity_id=entity_id, limit=edits_limit
@@ -838,7 +853,7 @@ class BackupManager:
         entries.extend(legacy)
         if limit:
             entries = entries[:limit]
-        return entries
+        return entries, warnings
 
     async def _diff_legacy(self, filename: str) -> DiffResponseText:
         info = await self.read_legacy(filename)
@@ -2173,30 +2188,37 @@ async def _restore_yaml_file(client: Any, entity_id: str, config: Any) -> Any:
     return result
 
 
-async def _list_legacy_backups(client: Any) -> list[dict[str, Any]]:
+async def _list_legacy_backups(client: Any) -> tuple[list[dict[str, Any]], str | None]:
     """Fetch pre-#1579 ``.bak`` backups via the component list_legacy_backups
     service.
 
-    Returns ``[]`` (logged at debug) when the component predates the service —
-    a service-unavailable rejection surfaces either as a ``success: False``
-    response or a ``HomeAssistantError`` — so the edits ``list`` still works
-    against an older standalone component. Genuine programming errors propagate.
+    Returns ``(backups, unavailable_reason)``. The legacy store is
+    best-effort: when the component predates the service, isn't configured
+    (tools entry not set up), or is missing entirely, the entry list is ``[]``
+    and ``unavailable_reason`` carries the human-readable cause — a
+    ``HomeAssistantError`` or any ``ToolError`` out of
+    ``call_mcp_tools_service`` (all its caller-token gates included) lands
+    here (also logged at debug), so the edits ``list`` still works and the
+    caller can surface the degradation as a warning. A ``success: False``
+    service response degrades silently as before. Genuine programming errors
+    propagate.
     """
+    from .tools.helpers import extract_structured_error_reason
     from .tools.tools_filesystem import call_mcp_tools_service
     from .tools.util_helpers import unwrap_service_response
 
     try:
         result = await call_mcp_tools_service(client, "list_legacy_backups", {})
-    except HomeAssistantError as err:
+    except (HomeAssistantError, ToolError) as err:
         logger.debug("legacy backup list unavailable: %s", err)
-        return []
+        return [], extract_structured_error_reason(err) or str(err)
     if not isinstance(result, dict):
-        return []
+        return [], None
     result = unwrap_service_response(result)
     if not result.get("success", False):
-        return []
+        return [], None
     backups = result.get("backups")
-    return backups if isinstance(backups, list) else []
+    return (backups, None) if isinstance(backups, list) else ([], None)
 
 
 async def _read_legacy_backup(client: Any, filename: str) -> dict[str, Any]:
@@ -2204,9 +2226,11 @@ async def _read_legacy_backup(client: Any, filename: str) -> dict[str, Any]:
 
     Returns the unwrapped service response (carries ``success`` / ``content`` /
     ``file_path`` / ``path_ambiguous`` / ``timestamp``). A service-unavailable
-    ``HomeAssistantError`` is mapped to a ``success: False`` dict so the caller
-    surfaces a not-found rather than crashing.
+    ``HomeAssistantError`` — or a ``ToolError`` from the caller-token gates —
+    is mapped to a ``success: False`` dict so the caller surfaces a not-found
+    rather than crashing.
     """
+    from .tools.helpers import extract_structured_error_reason
     from .tools.tools_filesystem import call_mcp_tools_service
     from .tools.util_helpers import unwrap_service_response
 
@@ -2214,8 +2238,15 @@ async def _read_legacy_backup(client: Any, filename: str) -> dict[str, Any]:
         result = await call_mcp_tools_service(
             client, "read_legacy_backup", {"filename": filename}
         )
-    except HomeAssistantError as err:
-        return {"success": False, "error": str(err)}
+    except (HomeAssistantError, ToolError) as err:
+        # The human reason, not str(err) verbatim: a ToolError's string is
+        # the whole JSON envelope, which would reach the tool layer as an
+        # unreadable JSON-in-JSON message (#1996's original symptom).
+        logger.debug("legacy backup read unavailable: %s", err)
+        return {
+            "success": False,
+            "error": extract_structured_error_reason(err) or str(err),
+        }
     if not isinstance(result, dict):
         return {"success": False, "error": f"no response for {filename!r}"}
     return unwrap_service_response(result)

{ha_mcp_dev-7.14.2.dev2095 → ha_mcp_dev-7.14.2.dev2098}/src/ha_mcp/settings_ui/_handlers_fs.py

@@ -25,6 +25,20 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _component_error_reason(exc: Exception) -> str | None:
+    """Extract the human message from a structured ``ToolError``, else None.
+
+    ``raise_tool_error`` serializes the whole error envelope into the
+    exception string, so rendering ``str(exc)`` verbatim shows the settings
+    UI a raw JSON blob behind a misleading "could not reach" prefix — the
+    hard-to-read surface from #1996. Thin seam over the shared extractor
+    (imported lazily like the other tools imports in this module).
+    """
+    from ..tools.helpers import extract_structured_error_reason
+
+    return extract_structured_error_reason(exc)
+
+
 async def _fs_custom_paths_call(
     server: HomeAssistantSmartMCPServer | None, service: str, data: dict[str, Any]
 ) -> Any:
@@ -90,7 +104,10 @@ async def _get_fs_custom_paths(
         result = await _fs_custom_paths_call(server, "get_allowed_paths", {})
     except Exception as exc:
         logger.warning("fs-custom-paths GET could not reach ha_mcp_tools: %s", exc)
-        return _unavailable(f"Could not reach the ha_mcp_tools component: {exc}")
+        return _unavailable(
+            _component_error_reason(exc)
+            or f"Could not reach the ha_mcp_tools component: {exc}"
+        )
 
     data = unwrap_service_response(result) if isinstance(result, dict) else {}
     if not isinstance(data, dict) or not data.get("success", False):
@@ -163,7 +180,8 @@ async def _save_fs_custom_paths(
         return JSONResponse(
             create_error_response(
                 ErrorCode.SERVICE_CALL_FAILED,
-                f"Could not reach the ha_mcp_tools component: {exc}",
+                _component_error_reason(exc)
+                or f"Could not reach the ha_mcp_tools component: {exc}",
             ),
             status_code=502,
         )

{ha_mcp_dev-7.14.2.dev2095 → ha_mcp_dev-7.14.2.dev2098}/src/ha_mcp/tools/backup.py

@@ -1908,12 +1908,12 @@ async def _edits_list(
     # Edits-store snapshots + pre-#1579 legacy .bak entries (#1579).
     # The manager owns the merge (sync dir-glob off-thread + async
     # legacy service call) so this layer stays source-agnostic.
-    entries = await mgr.list_edits_and_legacy(
+    entries, warnings = await mgr.list_edits_and_legacy(
         domain=domain,
         entity_id=entity_id,
         limit=limit,
     )
-    return {
+    response: dict[str, Any] = {
         "success": True,
         "data": {
             "backups": entries,
@@ -1924,6 +1924,9 @@ async def _edits_list(
             "retain_per_entity": settings.auto_backup_retain_per_entity,
         },
     }
+    if warnings:
+        response["warnings"] = warnings
+    return response
 
 
 async def _edits_view(

{ha_mcp_dev-7.14.2.dev2095 → ha_mcp_dev-7.14.2.dev2098}/src/ha_mcp/tools/helpers.py

@@ -78,6 +78,41 @@ def extract_tool_error_message(te: ToolError) -> str:
         return str(te)
 
 
+def extract_structured_error_reason(exc: BaseException) -> str | None:
+    """Extract "message" + first actionable suggestion from a structured error.
+
+    Like ``extract_tool_error_message`` but for surfaces that show the reason
+    to a human (settings UI, degraded-result warnings): it appends the first
+    suggestion when one exists, and returns ``None`` — instead of the raw
+    ``str(exc)`` JSON envelope — when the payload is not a structured error
+    or carries no usable message, so callers pick their own fallback.
+    ``create_error_response`` emits only the singular ``suggestion`` key for
+    one-suggestion errors (the plural ``suggestions`` list needs two or
+    more), so both keys are honored.
+    """
+    try:
+        payload = json.loads(str(exc))
+    except (TypeError, ValueError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    error = payload.get("error")
+    if not isinstance(error, dict):
+        return None
+    message = error.get("message")
+    if not isinstance(message, str) or not message:
+        return None
+    suggestions = error.get("suggestions")
+    first = (
+        suggestions[0]
+        if isinstance(suggestions, list) and suggestions
+        else error.get("suggestion")
+    )
+    if isinstance(first, str) and first:
+        return f"{message} {first}"
+    return message
+
+
 def validate_identifier_not_empty(
     value: str | None,
     param_name: str,

{ha_mcp_dev-7.14.2.dev2095 → ha_mcp_dev-7.14.2.dev2098}/src/ha_mcp/tools/tools_bug_report.py

@@ -556,6 +556,49 @@ async def _fetch_core_error_log(client: Any) -> str:
     return sanitized
 
 
+def _format_tools_entry_value(diagnostic_info: dict[str, Any]) -> str:
+    """Render the File & YAML Tools entry status for the report templates."""
+    return diagnostic_info.get("tools_entry_status") or "unknown (probe failed)"
+
+
+def _format_server_entry_value(diagnostic_info: dict[str, Any]) -> str:
+    """Render the in-process server entry status for the report templates."""
+    return diagnostic_info.get("server_entry_status") or "unknown (probe failed)"
+
+
+# Entry titles assigned by the component's config flow (config_flow.py /
+# const.py in custom_components/ha_mcp_tools) — the server code cannot import
+# the separately-shipped component package, so the defaults are mirrored here.
+# "HA MCP Tools" is the pre-#1853 tools-entry title an unloaded legacy entry
+# may still carry. A user-renamed entry lands in the "unrecognized" bucket
+# rather than being misclassified.
+_SERVER_ENTRY_TITLE = "HA-MCP Server"
+_TOOLS_ENTRY_TITLES = frozenset({"HA-MCP File & YAML Tools", "HA MCP Tools"})
+
+
+def _classify_component_entries(
+    entries: list[Any],
+) -> tuple[list[str], list[str]]:
+    """Split ha_mcp_tools config entries into server-entry and unrecognized.
+
+    Tools-entry titles are dropped: their functional state comes from the
+    services probe (``_detect_tools_entry_status``), which sees whether the
+    entry actually serves, not just whether it exists.
+    """
+    server: list[str] = []
+    unrecognized: list[str] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        title = str(entry.get("title") or "untitled")
+        state = str(entry.get("state") or "unknown state")
+        if title == _SERVER_ENTRY_TITLE:
+            server.append(f"added ({state})")
+        elif title not in _TOOLS_ENTRY_TITLES:
+            unrecognized.append(f'"{title}" ({state})')
+    return server, unrecognized
+
+
 def _build_formatted_report(
     diagnostic_info: dict[str, Any],
     mcp_transport: str,
@@ -574,6 +617,8 @@ def _build_formatted_report(
         "",
         f"ha-mcp Version: {_format_version_value(diagnostic_info)}",
         f"Custom Component: {diagnostic_info.get('component_version') or 'not detected (not installed, or probe failed)'}",
+        f"File & YAML Tools entry: {_format_tools_entry_value(diagnostic_info)}",
+        f"In-process Server entry: {_format_server_entry_value(diagnostic_info)}",
         f"Installation Method: {diagnostic_info['installation_method']}",
         f"MCP Transport: {mcp_transport}",
         f"MCP Client: {_format_client_info_for_template(client_info)}",
@@ -649,6 +694,70 @@ class BugReportTools:
             logger.info("Component version probe failed: %s", e)
             return None
 
+    async def _detect_tools_entry_status(self) -> str | None:
+        """Describe the File & YAML Tools entry state for the report, best-effort.
+
+        The ``ha_mcp_tools`` services register only in that entry's setup, so
+        the service registry distinguishes "entry set up" from the #1996
+        state — integration installed but the second entry never added —
+        which the component version alone cannot show. Returns None when the
+        probe fails; the report path must never break on it.
+        """
+        from .tools_filesystem import _bootstrap_service_state
+
+        try:
+            domain_registered, bootstrap_registered = await _bootstrap_service_state(
+                self._client
+            )
+        except Exception as e:
+            logger.info("Tools-entry status probe failed: %s", e)
+            return None
+        if not domain_registered:
+            return (
+                "not set up — no ha_mcp_tools services registered; add the "
+                '"HA-MCP File & YAML Tools" entry via "Add entry" on the '
+                "HA-MCP Custom Component integration (or install the "
+                "component first)"
+            )
+        if not bootstrap_registered:
+            return "set up, but the component is pre-0.5.0 (update via HACS)"
+        return "set up (ha_mcp_tools services registered)"
+
+    async def _detect_server_entry_status(self) -> str | None:
+        """Describe the in-process "HA-MCP Server" entry state, best-effort.
+
+        Both parts of the custom component ship under the single
+        ``ha_mcp_tools`` domain, so "the component is installed" says nothing
+        about WHICH part is set up. The File & YAML tools part is covered by
+        the services probe; this one classifies the domain's config entries by
+        their flow-assigned titles to show whether the in-process server entry
+        exists — e.g. an add-on install that erroneously also added it (a
+        second, redundant server) becomes visible next to Installation Method.
+        Returns None when the probe fails; the report must never break on it.
+        """
+        try:
+            response = await self._client.send_websocket_message(
+                {"type": "config_entries/get", "domain": "ha_mcp_tools"}
+            )
+            if not isinstance(response, dict) or not response.get("success"):
+                return None
+            result = response.get("result")
+            if not isinstance(result, list):
+                return None
+        except Exception as e:
+            logger.info("Server-entry status probe failed: %s", e)
+            return None
+        server, unrecognized = _classify_component_entries(result)
+        if server:
+            return ", ".join(server)
+        if unrecognized:
+            # A renamed entry cannot be classified by title — report it
+            # rather than claiming the server entry is absent.
+            return "not identified — unrecognized ha_mcp_tools entries: " + ", ".join(
+                unrecognized
+            )
+        return "not added"
+
     @tool(
         name="ha_report_issue",
         tags={"Utilities"},
@@ -760,6 +869,8 @@ class BugReportTools:
         client_info = _extract_client_info(ctx)
         installed_version = await asyncio.to_thread(_detect_installed_version)
         component_version = await self._detect_component_version()
+        tools_entry_status = await self._detect_tools_entry_status()
+        server_entry_status = await self._detect_server_entry_status()
 
         diagnostic_info: dict[str, Any] = {
             "ha_mcp_version": __version__,
@@ -768,6 +879,8 @@ class BugReportTools:
                 installed_version and installed_version != __version__
             ),
             "component_version": component_version,
+            "tools_entry_status": tools_entry_status,
+            "server_entry_status": server_entry_status,
             "instance": _instance_identity(),
             "installation_method": install_method,
             "platform": platform_info,
@@ -1278,6 +1391,8 @@ ha_call_service(domain="light", service="turn_on", entity_id="light.example")
 
 - **ha-mcp Version:** {_format_version_value(diagnostic_info)}
 - **Custom Component:** {diagnostic_info.get("component_version") or "not detected (not installed, or probe failed)"}
+- **File & YAML Tools entry:** {_format_tools_entry_value(diagnostic_info)}
+- **In-process Server entry:** {_format_server_entry_value(diagnostic_info)}
 - **Installation Method:** {diagnostic_info.get("installation_method", "Unknown")}
 - **MCP Transport:** {mcp_transport} _(auto-detected — correct if wrong)_
 - **MCP Client:** {_format_client_info_for_template(client_info)} _(auto-detected from the MCP `initialize` handshake)_
@@ -1443,6 +1558,8 @@ def _generate_agent_behavior_template(
 
 - **ha-mcp Version:** {_format_version_value(diagnostic_info)}
 - **Custom Component:** {diagnostic_info.get("component_version") or "not detected (not installed, or probe failed)"}
+- **File & YAML Tools entry:** {_format_tools_entry_value(diagnostic_info)}
+- **In-process Server entry:** {_format_server_entry_value(diagnostic_info)}
 - **Installation Method:** {diagnostic_info.get("installation_method", "Unknown")}
 - **MCP Transport:** {mcp_transport} _(auto-detected — correct if wrong)_
 - **MCP Client:** {_format_client_info_for_template(client_info)} _(auto-detected from the MCP `initialize` handshake)_

{ha_mcp_dev-7.14.2.dev2095 → ha_mcp_dev-7.14.2.dev2098}/src/ha_mcp/tools/tools_filesystem.py

@@ -122,11 +122,23 @@ def _get_token_lock(client: Any) -> asyncio.Lock:
     return lock
 
 
-async def _is_bootstrap_service_registered(client: Any) -> bool:
-    """Returns True if ha_mcp_tools.get_caller_token is present in HA's
-    service registry. Old (<0.5.0) versions of the custom component
-    didn't ship this service; the bootstrap call would otherwise fail
-    with an opaque 400 from HA."""
+async def _bootstrap_service_state(client: Any) -> tuple[bool, bool]:
+    """Return ``(domain_registered, bootstrap_registered)`` from HA's service
+    registry.
+
+    The two flags distinguish the two very different ways the
+    ``get_caller_token`` bootstrap can be missing (#1996):
+
+    - No ``ha_mcp_tools`` services at all — the component's "HA-MCP File &
+      YAML Tools" config entry was never added (the services register only in
+      that entry's setup), or the component isn't installed. A HACS update
+      cannot fix this.
+    - Domain services present but no ``get_caller_token`` — a genuinely old
+      (<0.5.0) component that pre-dates the bootstrap service; the call would
+      otherwise fail with an opaque 400 from HA. This one IS fixed by updating.
+    """
+    # HA /api/services returns a list of {"domain": str, "services": {...}}
+    # objects — stable across all supported HA versions.
     services = await client.get_services()
     for entry in services:
         if not isinstance(entry, dict):
@@ -134,8 +146,42 @@ async def _is_bootstrap_service_registered(client: Any) -> bool:
         if entry.get("domain") != MCP_TOOLS_DOMAIN:
             continue
         domain_services = entry.get("services") or {}
-        return CALLER_TOKEN_BOOTSTRAP_SERVICE in domain_services
-    return False
+        return True, CALLER_TOKEN_BOOTSTRAP_SERVICE in domain_services
+    return False, False
+
+
+def _raise_tools_entry_not_set_up() -> NoReturn:
+    """Actionable error for the no-services state (#1996).
+
+    Installing the HA-MCP integration is not enough for the file / YAML
+    tools: they need the separate "HA-MCP File & YAML Tools" config entry,
+    which users routinely miss. Lead with the "Add entry" step; the full
+    HACS install is the fallback for a component that isn't there at all.
+    """
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.COMPONENT_NOT_INSTALLED,
+            'The optional "HA-MCP File & YAML Tools" entry is not set up in '
+            "Home Assistant, so the file and YAML tools are unavailable. "
+            "Installing the HA-MCP integration alone is not enough — this "
+            "second entry must be added to it.",
+            suggestions=[
+                "In Home Assistant: Settings → Devices & Services → "
+                + 'HA-MCP Custom Component → "Add entry" → choose '
+                + '"HA-MCP File & YAML Tools" (NOT '
+                + '"HA-MCP Server", which starts a second in-process server '
+                + "this ha-mcp server does not need)",
+                "If the HA-MCP integration is not listed there, install it "
+                + 'first: ha_manage_hacs(action="add_repository", '
+                + 'repository="homeassistant-ai/ha-mcp-integration", '
+                + 'category="integration"), then ha_manage_hacs('
+                + 'action="download", '
+                + 'repository_id="homeassistant-ai/ha-mcp-integration"), '
+                + "then restart Home Assistant (ha_restart)",
+                "Then retry the operation",
+            ],
+        )
+    )
 
 
 def _raise_component_too_old(detail: str) -> NoReturn:
@@ -158,12 +204,17 @@ def _raise_component_too_old(detail: str) -> NoReturn:
 async def _fetch_caller_token(client: Any) -> str:
     """Call the bootstrap service and cache the returned token.
 
-    Two version gates:
+    Three gates, pre-flighted via ``_bootstrap_service_state``:
 
-    1. ``_is_bootstrap_service_registered`` — pre-0.5.0 components don't
-       ship ``get_caller_token`` at all. Surface an actionable "update"
+    1. No ``ha_mcp_tools`` services registered at all — the "HA-MCP File &
+       YAML Tools" config entry was never added (or the component isn't
+       installed). Surface the "add the entry" error, NOT an update prompt:
+       a current component in this state misled users into fruitless HACS
+       updates when the old code lumped it in with "too old" (#1996).
+    2. Domain present but no ``get_caller_token`` — pre-0.5.0 components
+       don't ship the bootstrap service. Surface an actionable "update"
        error instead of letting HA return an opaque 400 to the caller.
-    2. ``MIN_COMPONENT_VERSION`` — even when the bootstrap service is
+    3. ``MIN_COMPONENT_VERSION`` — even when the bootstrap service is
        present, the response now carries the component's manifest
        version. ha-mcp releases that depend on newer custom-component
        behavior (e.g. a new accepted yaml_path key, a new schema field)
@@ -176,7 +227,10 @@ async def _fetch_caller_token(client: Any) -> str:
     reason: the absence of the field IS the signal that the component
     doesn't yet know how to report its capabilities to ha-mcp.
     """
-    if not await _is_bootstrap_service_registered(client):
+    domain_registered, bootstrap_registered = await _bootstrap_service_state(client)
+    if not domain_registered:
+        _raise_tools_entry_not_set_up()
+    if not bootstrap_registered:
         _raise_component_too_old(
             "the get_caller_token bootstrap service is not registered (pre-0.5.0)"
         )
@@ -312,17 +366,16 @@ def is_filesystem_tools_enabled() -> bool:
 
 
 async def _is_mcp_tools_available(client: Any) -> bool:
-    """Return True if the ha_mcp_tools custom component is registered in HA services.
+    """Return True if any ha_mcp_tools services are registered in HA.
 
-    Raises if the services API call fails — callers handle API errors via
-    their own exception_to_structured_error blocks.
+    No services means the File & YAML Tools entry is not set up (or the
+    component is absent entirely — indistinguishable from here, see
+    ``_bootstrap_service_state``). Raises if the services API call fails —
+    callers handle API errors via their own exception_to_structured_error
+    blocks.
     """
-    # HA /api/services returns a list of {"domain": str, "services": {...}} objects.
-    # This format has been stable since before HA 0.7 (the first public release).
-    services = await client.get_services()
-    return any(
-        isinstance(s, dict) and s.get("domain") == MCP_TOOLS_DOMAIN for s in services
-    )
+    domain_registered, _ = await _bootstrap_service_state(client)
+    return domain_registered
 
 
 def _assert_caps_version_ok(caps: ComponentCaps) -> None:
@@ -352,7 +405,10 @@ async def _assert_mcp_tools_available(client: Any) -> None:
     ``caps.component_version`` (info shipped in 1.1.0, already past the floor).
     Legacy fallback: caps is None for a component in the 0.11.0-1.1.0 band
     (services, no info command) or an absent one, so fall back to the per-call
-    ``get_services()`` existence probe.
+    ``get_services()`` existence probe. A no-services verdict raises the
+    "File & YAML Tools entry not set up" error
+    (``_raise_tools_entry_not_set_up``), not an install-the-component prompt —
+    the entry-not-added state is the common cause (#1996).
 
     Must be called within a try block that handles API errors via
     exception_to_structured_error, so connection failures are classified
@@ -365,22 +421,7 @@ async def _assert_mcp_tools_available(client: Any) -> None:
         _assert_caps_version_ok(caps)
         return
     if not await _is_mcp_tools_available(client):
-        raise_tool_error(
-            create_error_response(
-                ErrorCode.COMPONENT_NOT_INSTALLED,
-                f"The {MCP_TOOLS_DOMAIN} custom component is not installed.",
-                suggestions=[
-                    'Add the repository to HACS: ha_manage_hacs(action="add_repository",'
-                    + ' repository="homeassistant-ai/ha-mcp-integration", category="integration")',
-                    'Download the component: ha_manage_hacs(action="download",'
-                    + ' repository_id="homeassistant-ai/ha-mcp-integration")',
-                    "Restart Home Assistant (ha_restart) so the integration loads",
-                    'In HA, add the "HA-MCP Custom Component" integration and choose the'
-                    + ' "HA-MCP File & YAML Tools" entry — NOT "HA-MCP Server", which starts'
-                    + " a second in-process server this ha-mcp server does not need",
-                ],
-            )
-        )
+        _raise_tools_entry_not_set_up()
 
 
 class FilesystemTools:

{ha_mcp_dev-7.14.2.dev2095 → ha_mcp_dev-7.14.2.dev2098/src/ha_mcp_dev.egg-info}/PKG-INFO

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