ha-mcp-dev 7.7.0.dev694__tar.gz → 7.7.0.dev695__tar.gz

{ha_mcp_dev-7.7.0.dev694/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.7.0.dev695}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.7.0.dev694
+Version: 7.7.0.dev695
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -349,6 +349,8 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.
 
+> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the add-on or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop). If you skip this, tools shown as available will return `Unknown tool` when called.
+
 For the HA add-on, the same option is documented in [`homeassistant-addon/DOCS.md`](homeassistant-addon/DOCS.md#enable_tool_search) along with the in-add-on settings UI for fine-grained tool enable/disable/pin.
 
 ---

{ha_mcp_dev-7.7.0.dev694 → ha_mcp_dev-7.7.0.dev695}/README.md

@@ -319,6 +319,8 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.
 
+> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the add-on or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop). If you skip this, tools shown as available will return `Unknown tool` when called.
+
 For the HA add-on, the same option is documented in [`homeassistant-addon/DOCS.md`](homeassistant-addon/DOCS.md#enable_tool_search) along with the in-add-on settings UI for fine-grained tool enable/disable/pin.
 
 ---

{ha_mcp_dev-7.7.0.dev694 → ha_mcp_dev-7.7.0.dev695}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.7.0.dev694"
+version = "7.7.0.dev695"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.7.0.dev694 → ha_mcp_dev-7.7.0.dev695}/src/ha_mcp/server.py

@@ -236,6 +236,13 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
 
         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
+        # (stale client tool-list cache) with an actionable refresh hint.
+        from .tools.tool_search_hint_middleware import ToolSearchHintMiddleware
+
+        self.mcp.add_middleware(ToolSearchHintMiddleware())
+
         # Read Only Mode write blocker (discussion #1569) — always
         # installed, consults the live flag per call. Before
         # PolicyMiddleware so a write blocked by Read Only Mode never

{ha_mcp_dev-7.7.0.dev694 → ha_mcp_dev-7.7.0.dev695}/src/ha_mcp/settings_ui.py

@@ -812,6 +812,10 @@ _SETTINGS_HTML = (
   <span class="restart-notice-text" id="restartNoticeText">
     ⚠ Changes saved. Restart ha-mcp for them to take effect — disabled
     tools will be fully removed from the MCP tool list on next startup.
+    Then reconnect or refresh the MCP server in your AI client (e.g.
+    re-add/refresh the connector in ChatGPT, or close and reopen Claude
+    Desktop) so it reloads the tool list — restarting the add-on or Home
+    Assistant does NOT refresh your client's cached tool list.
   </span>
   <button class="restart-btn" id="restartBtn" style="display:none">Restart Add-on</button>
 </div>
@@ -857,8 +861,10 @@ _SETTINGS_HTML = (
 </div>
 <div class="panel" id="panel-server">
   <div class="features-sub">
-    Tool Search, advanced settings. Changes require an MCP-host restart
-    to take effect (close + reopen Claude Desktop, restart the add-on, etc.).
+    Tool Search, advanced settings. Changes take effect only after you
+    restart the add-on (applies the change server-side) AND reconnect or
+    refresh the MCP server in your AI client (reloads the tool list) — e.g.
+    re-add/refresh the connector in ChatGPT, or close + reopen Claude Desktop.
   </div>
 
   <!-- Two-step note + top Save button. The Save +

ha_mcp_dev-7.7.0.dev695/src/ha_mcp/tools/tool_search_hint_middleware.py

@@ -0,0 +1,99 @@
+"""FastMCP middleware: actionable error for stale tool-search proxy/search calls.
+
+When ``enable_tool_search`` is off, the synthetic tool-search tools —
+``ha_search_tools`` and the ``ha_call_{read,write,delete}_tool`` proxies — are
+never registered (the ``CategorizedSearchTransform`` is not installed). If a
+client calls one of them anyway, FastMCP raises a bare ``NotFoundError``
+("Unknown tool: 'ha_search_tools'") with no recovery guidance.
+
+That is exactly what happens when an MCP client that caches its tool list is
+still advertising one captured from a previous session when Tool Search was on:
+the client shows ``ha_search_tools`` as available, calls it, and the live
+server — now in Tool-Search-off mode — rejects it. Restarting the add-on or
+Home Assistant does not help because the stale list lives in the client, not
+the server.
+
+This middleware intercepts that one case and replaces the opaque "Unknown tool"
+with a structured error that tells the user their tool list is stale and to
+reconnect/refresh the MCP server. It only acts on a *top-level* resolution miss
+for one of those four names while Tool Search is off; 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 fastmcp.exceptions import NotFoundError
+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
+
+from ..config import get_global_settings
+from ..errors import ErrorCode, create_error_response
+from ..policy.middleware import PROXY_META_TOOLS
+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 when Tool Search is disabled."""
+
+    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 while Tool Search is off:
+            #  - 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 Tool Search to be off (when on, the names resolve, so a
+            #    miss would be a different, real problem we must not mask).
+            top_level_miss = str(exc) == f"Unknown tool: {name!r}"
+            if (
+                top_level_miss
+                and name in PROXY_META_TOOLS
+                and not get_global_settings().enable_tool_search
+            ):
+                logger.info(
+                    "Stale tool-search call for %r while enable_tool_search is off "
+                    "- returning refresh-your-tool-list hint",
+                    name,
+                )
+                raise_tool_error(
+                    create_error_response(
+                        code=ErrorCode.RESOURCE_NOT_FOUND,
+                        message=(
+                            f"'{name}' only exists when Tool Search is enabled, and "
+                            "Tool Search is currently OFF on this ha-mcp server. Your "
+                            "MCP client is showing a cached tool list from when Tool "
+                            "Search was on. After changing any ha-mcp setting (Tool "
+                            "Search, pinned/disabled tools, etc.) the client must "
+                            "reconnect or refresh the MCP server to re-fetch the "
+                            "current tools — restarting the add-on or Home Assistant "
+                            "does not refresh the client's cached list. With Tool "
+                            f"Search off, every tool is available directly by name, "
+                            f"so {name} is not needed."
+                        ),
+                        suggestions=[
+                            (
+                                "Reconnect or refresh the ha-mcp MCP server in your "
+                                "client to reload the current tool list."
+                            ),
+                            (
+                                "Then call the tool you need directly by its name "
+                                "(with Tool Search off, ha_search_tools and the "
+                                "ha_call_* proxies do not exist)."
+                            ),
+                        ],
+                        context={"tool_name": name, "enable_tool_search": False},
+                    )
+                )
+            raise

{ha_mcp_dev-7.7.0.dev694 → ha_mcp_dev-7.7.0.dev695/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.7.0.dev694
+Version: 7.7.0.dev695
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -349,6 +349,8 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.
 
+> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the add-on or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop). If you skip this, tools shown as available will return `Unknown tool` when called.
+
 For the HA add-on, the same option is documented in [`homeassistant-addon/DOCS.md`](homeassistant-addon/DOCS.md#enable_tool_search) along with the in-add-on settings UI for fine-grained tool enable/disable/pin.
 
 ---

{ha_mcp_dev-7.7.0.dev694 → ha_mcp_dev-7.7.0.dev695}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -68,6 +68,7 @@ src/ha_mcp/tools/enhanced.py
 src/ha_mcp/tools/helpers.py
 src/ha_mcp/tools/reference_validator.py
 src/ha_mcp/tools/registry.py
+src/ha_mcp/tools/tool_search_hint_middleware.py
 src/ha_mcp/tools/tools_addons.py
 src/ha_mcp/tools/tools_areas.py
 src/ha_mcp/tools/tools_blueprints.py