ha-mcp-dev 9.1.0.dev3350__tar.gz → 9.1.0.dev3352__tar.gz

{ha_mcp_dev-9.1.0.dev3350 → ha_mcp_dev-9.1.0.dev3352}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3350
+Version: 9.1.0.dev3352
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien
@@ -445,6 +445,19 @@ Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, C
 
 For the HA app, the same option is documented in [`homeassistant-addon/DOCS.md`](homeassistant-addon/DOCS.md#enable_tool_search) along with the in-app settings UI for fine-grained tool enable/disable/pin.
 
+### Per-URL tool catalog
+
+`ENABLE_TOOL_SEARCH` defaults to off, and it sets the catalog of the main endpoint only. When several clients share one server, give each the URL for the catalog it needs: a client with built-in tool search keeps the full list, a small-context client gets the search tools. The suffixes are fixed overrides that ignore `ENABLE_TOOL_SEARCH`:
+
+```text
+Main endpoint (follows ENABLE_TOOL_SEARCH):  https://example.com/private_your_secret
+Always the full catalog:                     https://example.com/private_your_secret/catalog/full
+Always the search tools:                     https://example.com/private_your_secret/catalog/search
+Read-only, search tools:                     https://example.com/private_your_secret/readonly/catalog/search
+```
+
+Each URL keeps its catalog for the life of the connection, so a client picks its catalog only by the URL it is given. Reconnect the client after changing its URL so it refreshes its tool list. Home Assistant webhook URLs accept the same suffixes, alone or after `/readonly`: `https://your-ha.example/api/webhook/<webhook-id>/catalog/search`. This needs an embedded integration or Webhook Proxy app (add-on) release that serves them, with a matching MCP server; an older one returns 404 for a suffixed URL. Stdio runs one client per server process, so set `ENABLE_TOOL_SEARCH` in that client's server environment instead.
+
 ---
 
 ### Read-only HTTP connections

{ha_mcp_dev-9.1.0.dev3350 → ha_mcp_dev-9.1.0.dev3352}/README.md

@@ -385,6 +385,19 @@ Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, C
 
 For the HA app, the same option is documented in [`homeassistant-addon/DOCS.md`](homeassistant-addon/DOCS.md#enable_tool_search) along with the in-app settings UI for fine-grained tool enable/disable/pin.
 
+### Per-URL tool catalog
+
+`ENABLE_TOOL_SEARCH` defaults to off, and it sets the catalog of the main endpoint only. When several clients share one server, give each the URL for the catalog it needs: a client with built-in tool search keeps the full list, a small-context client gets the search tools. The suffixes are fixed overrides that ignore `ENABLE_TOOL_SEARCH`:
+
+```text
+Main endpoint (follows ENABLE_TOOL_SEARCH):  https://example.com/private_your_secret
+Always the full catalog:                     https://example.com/private_your_secret/catalog/full
+Always the search tools:                     https://example.com/private_your_secret/catalog/search
+Read-only, search tools:                     https://example.com/private_your_secret/readonly/catalog/search
+```
+
+Each URL keeps its catalog for the life of the connection, so a client picks its catalog only by the URL it is given. Reconnect the client after changing its URL so it refreshes its tool list. Home Assistant webhook URLs accept the same suffixes, alone or after `/readonly`: `https://your-ha.example/api/webhook/<webhook-id>/catalog/search`. This needs an embedded integration or Webhook Proxy app (add-on) release that serves them, with a matching MCP server; an older one returns 404 for a suffixed URL. Stdio runs one client per server process, so set `ENABLE_TOOL_SEARCH` in that client's server environment instead.
+
 ---
 
 ### Read-only HTTP connections

{ha_mcp_dev-9.1.0.dev3350 → ha_mcp_dev-9.1.0.dev3352}/pyproject.toml

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

{ha_mcp_dev-9.1.0.dev3350 → ha_mcp_dev-9.1.0.dev3352}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3350"
+version = "9.1.0.dev3352"
 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-9.1.0.dev3350 → ha_mcp_dev-9.1.0.dev3352}/src/ha_mcp/http_transport.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import logging
 from collections.abc import Iterator
-from contextlib import contextmanager
+from contextlib import ExitStack, contextmanager
 from dataclasses import dataclass, field
 from threading import Lock
 from time import monotonic
@@ -19,6 +19,7 @@ from ha_mcp._vendor.fastmcp import FastMCP
 from ha_mcp._vendor.fastmcp.server.http import StarletteWithLifespan
 
 from .config import get_global_settings
+from .tool_catalog import CATALOG_MODES, CatalogMode
 
 logger = logging.getLogger(__name__)
 
@@ -90,7 +91,7 @@ class HttpTransportFastMCP(FastMCP):
     """
 
     def http_app(self, *args: Any, **kwargs: Any) -> StarletteWithLifespan:
-        """Build the app with a readonly alias and optional transport experiments."""
+        """Build the app with endpoint selectors and optional transport experiments."""
         settings = get_global_settings()
         if settings.http_json_response:
             # FastMCP accepts json_response as its third positional argument.
@@ -114,38 +115,60 @@ class HttpTransportFastMCP(FastMCP):
                 kwargs["middleware"] = middleware
         app = super().http_app(*args, **kwargs)
         if app.state.transport_type == "streamable-http":
-            app.add_middleware(ReadOnlyEndpoint, path=app.state.path)
+            app.add_middleware(EndpointSelectors, path=app.state.path)
         return app
 
 
-class ReadOnlyEndpoint:
-    """Route the exact /readonly alias through the same authenticated MCP app.
+class EndpointSelectors:
+    """Route connection-selecting suffixes through the same authenticated MCP app.
 
-    This selects read-only behavior for a configured client connection; the
-    credential still works at the normal endpoint. Settings and other HTTP
-    routes are not aliased.
+    ``/readonly`` restricts the connection to reads; ``/catalog/full`` and
+    ``/catalog/search`` fix its tool catalog. A connection may use both,
+    read-only first (``/readonly/catalog/search``). The credential
+    still works at the normal endpoint. Settings and other HTTP routes are
+    not aliased.
     """
 
     def __init__(self, app: ASGIApp, path: str) -> None:
         self.app = app
         self.path = path
-        self.readonly_path = f"{path.rstrip('/')}/readonly"
+        self.base = path.rstrip("/")
+
+    def _selectors(self, route_path: str) -> tuple[bool, CatalogMode | None] | None:
+        """``(read_only, catalog_mode)`` for a selector suffix, else None."""
+        if not route_path.startswith(self.base + "/"):
+            return None
+        parts = route_path[len(self.base) + 1 :].split("/")
+        read_only = parts[:1] == ["readonly"]
+        if read_only:
+            parts = parts[1:]
+        if not parts:
+            return (True, None) if read_only else None
+        if len(parts) == 2 and parts[0] == "catalog" and parts[1] in CATALOG_MODES:
+            return read_only, parts[1]
+        return None
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
-        if (
-            scope["type"] != "http"
-            or _get_route_path(scope).rstrip("/") != self.readonly_path
-        ):
+        if scope["type"] != "http":
             await self.app(scope, receive, send)
             return
-
         from .read_only import read_only_request
+        from .tool_catalog import catalog_endpoint
 
         route_path = _get_route_path(scope)
+        selected = self._selectors(route_path.rstrip("/"))
+        if selected is None:
+            await self.app(scope, receive, send)
+            return
+        read_only, mode = selected
         prefix = scope["path"][: -len(route_path)]
         path = prefix + self.path
         scope = {**scope, "path": path, "raw_path": path.encode("utf-8")}
-        with read_only_request():
+        with ExitStack() as stack:
+            if read_only:
+                stack.enter_context(read_only_request())
+            if mode is not None:
+                stack.enter_context(catalog_endpoint(mode))
             await self.app(scope, receive, send)
 
 

{ha_mcp_dev-9.1.0.dev3350 → ha_mcp_dev-9.1.0.dev3352}/src/ha_mcp/server.py

@@ -34,6 +34,12 @@ from .server_tool_text import (
     SKILL_TOOL_NAME,
     SKILL_USE_BEFORE_KEYWORDS,
 )
+from .tool_catalog import (
+    CATALOG_MODES,
+    default_catalog_mode,
+    install_catalog_instructions,
+    set_search_available,
+)
 from .tools.helpers import raise_tool_error
 from .tools.tool_hints import read_only_hints
 from .transforms import DEFAULT_PINNED_TOOLS
@@ -114,12 +120,18 @@ class HomeAssistantSmartMCPServer:
             server_name = self.settings.mcp_server_name
             server_version = self.settings.mcp_server_version
 
-        instructions = self._build_instructions()
+        skills = self._build_skills_instructions()
+        self._instructions = {
+            mode: compose_instructions(
+                skills, self.settings, tool_search=mode == "search"
+            )
+            for mode in CATALOG_MODES
+        }
 
         self.mcp = FastMCP(
             name=server_name,
             version=server_version,
-            instructions=instructions,
+            instructions=self._instructions[default_catalog_mode()],
             lifespan=server_lifespan,
         )
 
@@ -199,7 +211,7 @@ class HomeAssistantSmartMCPServer:
 
         # Enrich tool descriptions with BM25 keyword boosts. Runs
         # unconditionally so Claude's native deferred-tool search
-        # (claude.ai) benefits even when ENABLE_TOOL_SEARCH is off.
+        # (claude.ai) benefits on full-catalog connections too.
         # Must come before _apply_tool_search so CategorizedSearchTransform
         # indexes the enriched descriptions.
         self._apply_search_keyword_enrichment()
@@ -231,7 +243,7 @@ class HomeAssistantSmartMCPServer:
         self.mcp.add_middleware(ValidationErrorMiddleware())
 
         # Replace the opaque "Unknown tool" FastMCP raises when a client calls
-        # ha_search_tools / the ha_call_* proxies while Tool Search is off
+        # ha_search_tools / the ha_call_* proxies on a full-catalog connection
         # (stale client tool-list cache) with an actionable refresh hint.
         from .tools.tool_search_hint_middleware import ToolSearchHintMiddleware
 
@@ -321,14 +333,10 @@ class HomeAssistantSmartMCPServer:
 
         return get_skills_dir()
 
-    def _build_instructions(self) -> str:
-        """Compose the server instructions sent in the MCP initialize response."""
-        return compose_instructions(self._build_skills_instructions(), self.settings)
-
     def _build_skills_instructions(self) -> str | None:
         """The skills section of the instructions, or None without skills."""
         return build_skills_instructions(
-            self._get_skills_dir(), self.settings, skill_tool_hidden(self.settings)
+            self._get_skills_dir(), skill_tool_hidden(self.settings)
         )
 
     _parse_skill_frontmatter = staticmethod(parse_skill_frontmatter)
@@ -394,8 +402,8 @@ class HomeAssistantSmartMCPServer:
 
     # Description overrides that REPLACE the original description for BM25.
     # Used to narrow overly broad tools so they stop matching generic queries
-    # against ha-mcp's internal BM25 search tool. Only applied when
-    # enable_tool_search=True, because they are tuned specifically for the
+    # against ha-mcp's internal BM25 search tool. Only applied to
+    # search-mode connections, because they are tuned specifically for the
     # categorized search transform and replacing the base description would
     # unnecessarily trim context for other clients.
     _SEARCH_DESCRIPTION_OVERRIDES: ClassVar[dict[str, str]] = {}
@@ -480,7 +488,7 @@ class HomeAssistantSmartMCPServer:
         list-tools time via ``SearchKeywordsTransform``.
 
         Description overrides (``_SEARCH_DESCRIPTION_OVERRIDES``) are only
-        applied when ``enable_tool_search`` is also set, because they
+        applied to search-mode connections, because they
         REPLACE the original description and are tuned specifically for
         ha-mcp's internal BM25 search tool.
 
@@ -496,11 +504,7 @@ class HomeAssistantSmartMCPServer:
             )
             return
 
-        overrides = (
-            self._SEARCH_DESCRIPTION_OVERRIDES
-            if self.settings.enable_tool_search
-            else None
-        )
+        overrides = self._SEARCH_DESCRIPTION_OVERRIDES
         try:
             self.mcp.add_transform(
                 SearchKeywordsTransform(
@@ -517,32 +521,15 @@ class HomeAssistantSmartMCPServer:
             logger.exception("Failed to apply SearchKeywordsTransform")
 
     def _apply_tool_search(self) -> None:
-        """Apply the CategorizedSearchTransform if enabled.
-
-        Replaces the full tool catalog with a unified BM25 search tool and
-        three categorized call proxies (read/write/delete). Pinned tools
-        remain directly visible in list_tools() for individual permission
-        gating. The ``ha_get_skill_guide`` tool is pinned via
-        ``DEFAULT_PINNED_TOOLS`` (transforms/categorized_search.py) so the
-        bundled skill trigger-conditions stay in the catalog — no explicit
-        ``pinned.append(...)`` for it here.
-
-        Note: ``_apply_search_keyword_enrichment`` already ran before this
-        method and installed ``SearchKeywordsTransform`` — the enriched
+        """Install the CategorizedSearchTransform and per-endpoint instructions.
+
+        For endpoints in search mode (see ``tool_catalog``), replaces the full
+        catalog with a BM25 search tool and read/write/delete call proxies.
+        Pinned tools, ``ha_get_skill_guide`` among them via
+        ``DEFAULT_PINNED_TOOLS``, stay directly visible for permission gating.
+        ``_apply_search_keyword_enrichment`` already ran, so the enriched
         catalog is what the categorized transform indexes.
         """
-        if not self.settings.enable_tool_search:
-            return
-
-        try:
-            from .transforms import CategorizedSearchTransform
-        except ImportError:
-            logger.error(
-                "CategorizedSearchTransform not available but ENABLE_TOOL_SEARCH=true — "
-                "full tool catalog will be exposed. Install fastmcp>=3.1 to fix."
-            )
-            return
-
         # Build the always_visible list: defaults (minus tools the user
         # explicitly toggled to "enabled" in the Tools tab) + user pins.
         # The skill guide tool is part of DEFAULT_PINNED_TOOLS, and in
@@ -576,6 +563,8 @@ class HomeAssistantSmartMCPServer:
         )
 
         try:
+            from .transforms import CategorizedSearchTransform
+
             self.mcp.add_transform(
                 CategorizedSearchTransform(
                     max_results=self.settings.tool_search_max_results,
@@ -589,14 +578,24 @@ class HomeAssistantSmartMCPServer:
                     enable_code_mode=self.settings.enable_code_mode,
                 )
             )
-            logger.info(
-                "Tool search transform applied (%d pinned tools, max_results=%d, code_mode=%s)",
-                len(pinned),
-                self.settings.tool_search_max_results,
-                self.settings.enable_code_mode,
-            )
         except Exception:
-            logger.exception("Failed to apply tool search transform")
+            # Import or install failed: no endpoint can serve search, so every
+            # one serves, and describes, the full catalog.
+            logger.exception(
+                "Tool search transform unavailable; every endpoint serves the "
+                "full tool catalog"
+            )
+            set_search_available(False)
+            self.mcp.instructions = self._instructions["full"]
+            return
+        set_search_available(True)
+        install_catalog_instructions(self.mcp, self._instructions)
+        logger.info(
+            "Tool search transform applied (%d pinned tools, max_results=%d, code_mode=%s)",
+            len(pinned),
+            self.settings.tool_search_max_results,
+            self.settings.enable_code_mode,
+        )
 
     def _apply_tool_security_policies(self) -> None:
         """Register the tool security policies middleware (#966).

{ha_mcp_dev-9.1.0.dev3350 → ha_mcp_dev-9.1.0.dev3352}/src/ha_mcp/server_instructions.py

@@ -1,7 +1,7 @@
 """The instructions the server sends in the MCP initialize response.
 
 Sections, in order: the bundled best-practice skills with how to read them
-(plus the tool-search note when that mode is on), the Read Only Mode
+(plus the tool-search note for connections in search mode), the Read Only Mode
 warning, the issue-filing rule, and the installation owner's
 ``custom_instructions``. The skills header and access fallbacks are
 defined here; the notices come from ``server_tool_text``.
@@ -116,9 +116,7 @@ def skill_block(skill_name: str, description: str) -> str:
     return f"\n### Skill: {skill_name} ({uri})\n{description.strip()}"
 
 
-def build_skills_instructions(
-    skills_dir: Path | None, settings: Settings, tool_hidden: bool
-) -> str | None:
+def build_skills_instructions(skills_dir: Path | None, tool_hidden: bool) -> str | None:
     """Build the skills section from each bundled SKILL.md's frontmatter.
 
     The description field is authored for LLM consumption and included
@@ -134,22 +132,27 @@ def build_skills_instructions(
         _RESOURCE_ACCESS + _LOCAL_SKILLS_FALLBACK if tool_hidden else _SKILL_TOOL_ACCESS
     )
     header = _SKILLS_HEADER.format(access_method=access_method)
-    instructions = header + "\n".join(
+    return header + "\n".join(
         skill_block(name, frontmatter["description"])
         for name, _dir, frontmatter in skills
     )
 
-    if settings.enable_tool_search:
-        instructions += TOOL_DISCOVERY_INSTRUCTIONS.format(
-            pinned=", ".join(DEFAULT_PINNED_TOOLS)
-        )
-
-    return instructions
 
+def compose_instructions(
+    skills: str | None, settings: Settings, *, tool_search: bool
+) -> str:
+    """Join the skills section with the startup notices and the owner's text.
 
-def compose_instructions(skills: str | None, settings: Settings) -> str:
-    """Join the skills section with the startup notices and the owner's text."""
-    sections = [skills] if skills else []
+    ``tool_search`` is the connection's catalog mode, so one server sends
+    the discovery note only to the connections that get the search tools.
+    """
+    discovery = (
+        TOOL_DISCOVERY_INSTRUCTIONS.format(pinned=", ".join(DEFAULT_PINNED_TOOLS))
+        if tool_search
+        else ""
+    )
+    lead = (skills or "") + discovery
+    sections = [lead.lstrip("\n")] if lead else []
     # Surface Read Only Mode in the startup instructions so clients
     # that show server instructions warn the model up front. Startup
     # state only — live flips are covered by the structured

ha_mcp_dev-9.1.0.dev3352/src/ha_mcp/tool_catalog.py

@@ -0,0 +1,125 @@
+"""Per-endpoint tool catalog selection.
+
+``ENABLE_TOOL_SEARCH`` (off by default) sets the catalog of the main
+endpoint. A single ha-mcp instance is often shared by several MCP clients
+with different needs: one with its own deferred tool search wants the full
+catalog, a small-context client wants ha-mcp's search tools. Each URL
+therefore serves one fixed catalog:
+
+- ``<path>`` follows ``ENABLE_TOOL_SEARCH``;
+- ``<path>/catalog/full`` always serves the full catalog;
+- ``<path>/catalog/search`` always serves the search tools.
+
+Either suffix may follow ``/readonly``. The catalog is fixed per URL, not
+negotiated per request, because clients do not refresh their tool list
+when it changes: a client picks its catalog by the URL it is given.
+
+Stdio serves one client per process, so its environment selects the mode.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any, Literal
+
+from ha_mcp._vendor import mcp_types as mt
+from ha_mcp._vendor.fastmcp.server.middleware.middleware import (
+    CallNext,
+    Middleware,
+    MiddlewareContext,
+)
+
+from .config import get_global_settings
+
+if TYPE_CHECKING:
+    from ha_mcp._vendor.fastmcp import FastMCP
+
+CatalogMode = Literal["full", "search"]
+CATALOG_MODES: tuple[CatalogMode, ...] = ("full", "search")
+
+_endpoint_mode: ContextVar[CatalogMode | None] = ContextVar(
+    "ha_mcp_endpoint_catalog_mode", default=None
+)
+# False while the search transform cannot be installed: every endpoint then
+# serves, and describes, the full catalog. Set by each server it builds, so
+# a later server in the process (the component restarts in place) resets it.
+_search_available = True
+
+
+def set_search_available(available: bool) -> None:
+    """Record whether this process's server installed the search transform."""
+    global _search_available
+    _search_available = available
+
+
+def default_catalog_mode() -> CatalogMode:
+    """The main endpoint's mode, set by ``ENABLE_TOOL_SEARCH``."""
+    if _search_available and get_global_settings().enable_tool_search:
+        return "search"
+    return "full"
+
+
+def current_catalog_mode() -> CatalogMode:
+    """The catalog mode of the endpoint serving this request."""
+    if not _search_available:
+        return "full"
+    return _endpoint_mode.get() or default_catalog_mode()
+
+
+def tool_search_active() -> bool:
+    """Whether this request's endpoint serves search-based tool discovery."""
+    return current_catalog_mode() == "search"
+
+
+@contextmanager
+def catalog_endpoint(mode: CatalogMode) -> Iterator[None]:
+    """Select ``mode`` for this request and its nested tool calls."""
+    token = _endpoint_mode.set(mode)
+    try:
+        yield
+    finally:
+        _endpoint_mode.reset(token)
+
+
+class ToolCatalogInstructionsMiddleware(Middleware):
+    """Send each connection the server instructions for its endpoint's catalog.
+
+    ``initialize`` (protocol <= 2025-11-25) and ``server/discover``
+    (2026-07-28) both carry the instructions.
+    """
+
+    def __init__(self, instructions_for: Callable[[CatalogMode], str]) -> None:
+        self._instructions_for = instructions_for
+
+    async def on_initialize(
+        self,
+        context: MiddlewareContext[mt.InitializeRequest],
+        call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None],
+    ) -> mt.InitializeResult | None:
+        result = await call_next(context)
+        if result is None:
+            return None
+        return result.model_copy(
+            update={"instructions": self._instructions_for(current_catalog_mode())}
+        )
+
+    async def on_discover(
+        self,
+        context: MiddlewareContext[mt.DiscoverRequest],
+        call_next: CallNext[mt.DiscoverRequest, mt.DiscoverResult | dict[str, Any]],
+    ) -> mt.DiscoverResult | dict[str, Any]:
+        result = await call_next(context)
+        if not isinstance(result, mt.DiscoverResult):
+            return result
+        return result.model_copy(
+            update={"instructions": self._instructions_for(current_catalog_mode())}
+        )
+
+
+def install_catalog_instructions(
+    mcp: FastMCP, instructions: Mapping[CatalogMode, str]
+) -> None:
+    """Send each connection the instructions for its endpoint's catalog."""
+    mcp.add_middleware(ToolCatalogInstructionsMiddleware(instructions.__getitem__))

{ha_mcp_dev-9.1.0.dev3350 → ha_mcp_dev-9.1.0.dev3352}/src/ha_mcp/tools/bug_report_config.py

@@ -6,6 +6,7 @@ from typing import Any
 from ..config import Settings
 from ..settings_ui import _persistence
 from ..settings_ui._tools_meta import ignored_disabled_tools, tool_config_warnings
+from ..tool_catalog import current_catalog_mode
 
 logger = logging.getLogger(__name__)
 
@@ -46,6 +47,8 @@ def collect_config_toggles(settings: Settings) -> dict[str, Any]:
         isinstance(custom, str) and custom.strip()
     )
 
+    # The catalog this connection serves; its URL can override enable_tool_search.
+    toggles["connection_catalog"] = current_catalog_mode()
     toggles.update(_tool_config_diagnostics(settings))
     return toggles
 

ha_mcp_dev-9.1.0.dev3352/src/ha_mcp/tools/tool_search_hint_middleware.py

@@ -0,0 +1,96 @@
+"""FastMCP middleware: actionable error for stale tool-search proxy/search calls.
+
+On a connection serving the full catalog (see ``ha_mcp.tool_catalog``), the
+synthetic tool-search tools — ``ha_search_tools`` and the
+``ha_call_{read,write,delete}_tool`` proxies — do not resolve. If a
+client calls one of them anyway, FastMCP raises a bare ``NotFoundError``
+("Unknown tool: 'ha_search_tools'") with no recovery guidance.
+
+Two things cause that call: the client caches a tool list it fetched from a
+search-catalog connection, or the agent learned the names from another
+ha-mcp server it is connected to (for example a ``/catalog/search`` URL
+alongside a ``/catalog/full`` one). Restarting the app (add-on) or Home
+Assistant fixes neither: the stale list lives in the client.
+
+This middleware intercepts that one case and replaces the opaque "Unknown tool"
+with a structured error naming the connection's catalog and both causes. It
+only acts on a *top-level* resolution miss for one of those four names on a
+full-catalog connection; in every other case — including a ``NotFoundError``
+bubbling up from inside an executing tool — the original error propagates
+unchanged.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ha_mcp._vendor.fastmcp.exceptions import NotFoundError
+from ha_mcp._vendor.fastmcp.server.middleware.middleware import (
+    CallNext,
+    Middleware,
+    MiddlewareContext,
+)
+
+from ..errors import ErrorCode, create_error_response
+from ..policy.middleware import PROXY_META_TOOLS
+from ..tool_catalog import tool_search_active
+from .helpers import raise_tool_error
+
+logger = logging.getLogger(__name__)
+
+
+class ToolSearchHintMiddleware(Middleware):
+    """Turn the opaque "Unknown tool" for tool-search synthetic tools into a
+    stale-tool-list hint on a full-catalog connection."""
+
+    async def on_call_tool(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        try:
+            return await call_next(context)
+        except NotFoundError as exc:
+            name = context.message.name
+            # Only rewrite a TOP-LEVEL "Unknown tool" miss for one of the four
+            # tool-search synthetic names on a full-catalog connection:
+            #  - match the dispatch-layer message so a NotFoundError bubbling up
+            #    from INSIDE an executing tool (a different name) is never
+            #    mislabeled as a stale cache; on any wording change this simply
+            #    fails closed and re-raises the original error.
+            #  - require the full catalog (on a search connection the names
+            #    resolve, so a miss is a different, real problem to not mask).
+            top_level_miss = str(exc) == f"Unknown tool: {name!r}"
+            if top_level_miss and name in PROXY_META_TOOLS and not tool_search_active():
+                logger.info(
+                    "Stale tool-search call for %r on a full-catalog connection "
+                    "- returning refresh-your-tool-list hint",
+                    name,
+                )
+                raise_tool_error(
+                    create_error_response(
+                        code=ErrorCode.RESOURCE_NOT_FOUND,
+                        message=(
+                            f"'{name}' exists only on a connection serving the "
+                            "search catalog, and this connection serves the full "
+                            "catalog, so every tool is available directly by name. "
+                            "Either your MCP client is showing a cached tool list "
+                            "from a search-catalog connection, or the name comes "
+                            "from another ha-mcp server you are connected to (such "
+                            "as a /catalog/search URL). Restarting the app "
+                            "(add-on) or Home Assistant does not refresh the "
+                            "client's cached list."
+                        ),
+                        suggestions=[
+                            (
+                                "Call the tool you need directly by its name on "
+                                "this connection."
+                            ),
+                            (
+                                "If the client lists stale tools, reconnect or "
+                                "refresh this MCP server to reload its tool list."
+                            ),
+                        ],
+                        context={"tool_name": name, "catalog": "full"},
+                    )
+                )
+            raise

{ha_mcp_dev-9.1.0.dev3350 → ha_mcp_dev-9.1.0.dev3352}/src/ha_mcp/tools/tools_code.py

@@ -79,8 +79,8 @@ _saved_tools: dict[str, dict[str, str]] = {}
 
 # Tools that sandbox code must not call. Includes ``ha_manage_custom_tool``
 # itself (prevents recursive self-invocation) plus the four synthetics that
-# the categorized-search transform exposes when ``ENABLE_TOOL_SEARCH=true``
-# (``ha_search_tools``, ``ha_call_{read,write,delete}_tool``). Without those
+# a search-catalog connection exposes (main URL with ``ENABLE_TOOL_SEARCH``,
+# or ``/catalog/search``): ``ha_search_tools``, ``ha_call_*_tool``. Without those
 # four entries, sandbox code could "launder" a recursive call as
 # ``call_tool("ha_call_write_tool", {"name": "ha_manage_custom_tool", ...})``
 # — the proxy would then dispatch the underlying tool and the in-sandbox