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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.7.0.dev694
+Version: 7.7.0.dev696
 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.dev696}/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.dev696}/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.dev696"
 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.dev696}/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.dev696}/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.dev696/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.dev696}/src/ha_mcp/tools/tools_config_helpers.py

@@ -737,12 +737,15 @@ def _validate_applicable_params(
 
     if helper_type in FLOW_HELPER_TYPES:
         # Flow types accept `config` (handled before this call) plus
-        # cross-cutting params (name/helper_id/area_id/labels/category/wait).
-        # Any simple-helper-typed param passed here is inapplicable.
+        # cross-cutting params (name/helper_id/area_id/labels/category/icon/wait).
+        # `icon` is applied to the resulting entity(ies) via the entity registry
+        # (like area_id/labels), so it is allowed even though the config-flow
+        # form has no icon field. Any other simple-helper-typed param passed
+        # here is inapplicable.
         inapplicable.extend(
             param_name
             for param_name in _ALL_TYPED_PARAMS
-            if passed.get(param_name) is not None
+            if param_name != "icon" and passed.get(param_name) is not None
         )
     else:
         applicable = _TYPE_TYPED_PARAMS.get(helper_type, frozenset())
@@ -760,7 +763,7 @@ def _validate_applicable_params(
     if helper_type in FLOW_HELPER_TYPES:
         applicable_msg = (
             "config (see data_schema on a validation error for the field set), "
-            "name, helper_id, area_id, labels, category, wait"
+            "name, helper_id, area_id, labels, category, icon, wait"
         )
     else:
         type_specific = sorted(_TYPE_TYPED_PARAMS.get(helper_type, frozenset()))
@@ -1453,7 +1456,11 @@ async def _get_entities_for_config_entry(
 
 
 async def _entity_registry_update_coro(
-    client: Any, entity_id: str, area_id: str | None, labels: list[str] | None
+    client: Any,
+    entity_id: str,
+    area_id: str | None,
+    labels: list[str] | None,
+    icon: str | None = None,
 ) -> Any:
     """Build and send a config/entity_registry/update WS message."""
     update_message: dict[str, Any] = {
@@ -1464,6 +1471,8 @@ async def _entity_registry_update_coro(
         update_message["area_id"] = area_id if area_id else None
     if labels is not None:
         update_message["labels"] = labels
+    if icon is not None:
+        update_message["icon"] = icon if icon else None
     return await client.send_websocket_message(update_message)
 
 
@@ -1482,6 +1491,7 @@ def _process_reg_update_result(
     reg_result: Any,
     area_id: str | None,
     labels: list[str] | None,
+    icon: str | None,
     applied: dict[str, Any],
     entity_id: str,
     warnings: list[str],
@@ -1495,9 +1505,21 @@ def _process_reg_update_result(
                 applied["area_id"] = area_id if area_id else None
             if labels is not None:
                 applied["labels"] = labels
+            if icon is not None:
+                applied["icon"] = icon if icon else None
         else:
+            # area_id/labels/icon share one WS message, so a rejection of any
+            # one sinks the others. Name the batched fields so the caller can
+            # tell which touchups didn't land instead of guessing.
+            sent_fields = [
+                f
+                for f, v in (("area_id", area_id), ("labels", labels), ("icon", icon))
+                if v is not None
+            ]
+            field_note = f" (fields: {', '.join(sent_fields)})" if sent_fields else ""
             warnings.append(
-                f"{entity_id}: entity registry update failed: {_ws_error_msg(reg_result)}"
+                f"{entity_id}: entity registry update failed{field_note}: "
+                f"{_ws_error_msg(reg_result)}"
             )
 
 
@@ -1523,9 +1545,10 @@ async def _apply_registry_updates_to_entity(
     area_id: str | None,
     labels: list[str] | None,
     category: str | None,
+    icon: str | None,
     warnings: list[str],
 ) -> dict[str, Any]:
-    """Apply area_id/labels (single WS call) and category (shared helper) to one entity.
+    """Apply area_id/labels/icon (single WS call) and category (shared helper) to one entity.
 
     Appends human-readable warning strings to `warnings` on any failure.
     Returns a small dict summarizing what was applied (for result building).
@@ -1536,13 +1559,13 @@ async def _apply_registry_updates_to_entity(
     # `is not None` distinguishes "not provided" from "explicit clear" (empty
     # string / empty list). A transient raise on either call is captured via
     # return_exceptions so a multi-entity flow helper can still report partial success.
-    needs_registry = area_id is not None or labels is not None
+    needs_registry = area_id is not None or labels is not None or icon is not None
     needs_category = bool(category)
     if not (needs_registry or needs_category):
         return applied
 
     reg_task = (
-        _entity_registry_update_coro(client, entity_id, area_id, labels)
+        _entity_registry_update_coro(client, entity_id, area_id, labels, icon)
         if needs_registry
         else None
     )
@@ -1557,7 +1580,7 @@ async def _apply_registry_updates_to_entity(
     cat_result = raw_results.pop(0) if needs_category else None
 
     _process_reg_update_result(
-        reg_result, area_id, labels, applied, entity_id, warnings
+        reg_result, area_id, labels, icon, applied, entity_id, warnings
     )
     _process_cat_apply_result(cat_result, entity_id, applied, warnings)
     return applied
@@ -1772,31 +1795,45 @@ async def _apply_flow_registry_updates(
     area_id: str | None,
     labels_list: list[str] | None,
     category: str | None,
+    icon: str | None,
     extras: dict[str, Any],
     warnings: list[str],
 ) -> None:
-    """Apply area/labels/category to every entity from a flow helper, in parallel."""
+    """Apply area/labels/category/icon to every entity from a flow helper, in parallel."""
     if not (
         entity_ids
-        and (area_id is not None or labels_list is not None or category is not None)
+        and (
+            area_id is not None
+            or labels_list is not None
+            or category is not None
+            or icon is not None
+        )
     ):
         return
     applied_per_entity = list(
         await asyncio.gather(
             *(
                 _apply_registry_updates_to_entity(
-                    client, eid, area_id, labels_list, category, warnings
+                    client, eid, area_id, labels_list, category, icon, warnings
                 )
                 for eid in entity_ids
             )
         )
     )
-    if area_id is not None:
+    # Echo a top-level convenience key only when it was actually applied to at
+    # least one entity. The per-entity ``applied`` dicts are the source of
+    # truth — a failed entity_registry/update leaves its key out and records a
+    # warning instead — so echoing straight from the inputs would assert
+    # success that the accompanying warnings contradict.
+    applied_keys = {k for entry in applied_per_entity for k in entry}
+    if area_id is not None and "area_id" in applied_keys:
         extras["area_id"] = area_id if area_id else None
-    if labels_list is not None:
+    if labels_list is not None and "labels" in applied_keys:
         extras["labels"] = labels_list
-    if category:
+    if category and "category" in applied_keys:
         extras["category"] = category
+    if icon is not None and "icon" in applied_keys:
+        extras["icon"] = icon if icon else None
     extras["applied"] = applied_per_entity
 
 
@@ -1810,16 +1847,17 @@ async def _handle_flow_helper(
     labels: str | list[str] | None,
     category: str | None,
     wait: bool,
+    icon: str | None = None,
     action: str | None = None,
 ) -> dict[str, Any]:
     """Create or update a flow-based helper and apply registry updates to all entities.
 
     Routes between create_flow_helper and update_flow_helper based on helper_id,
     then resolves the resulting config_entry_id to its entity(ies) and applies
-    area_id / labels / category across the full set.
+    area_id / labels / category / icon across the full set.
 
-    For utility_meter with tariffs, this means the same label/area is applied
-    to every tariff sensor (and the select entity) uniformly.
+    For utility_meter with tariffs, this means the same label/area/icon is
+    applied to every tariff sensor (and the select entity) uniformly.
 
     `action` may be passed by the caller (Bug 11 explicit-intent path) — when
     None, falls back to the legacy implicit discriminator (presence of
@@ -1903,7 +1941,7 @@ async def _handle_flow_helper(
         extras["updated"] = True
 
     await _apply_flow_registry_updates(
-        client, entity_ids, area_id, labels_list, category, extras, warnings
+        client, entity_ids, area_id, labels_list, category, icon, extras, warnings
     )
 
     return _helper_response(
@@ -3886,7 +3924,8 @@ class HelperConfigTools:
                     labels,
                     category,
                     wait,
-                    action,
+                    icon=icon,
+                    action=action,
                 )
                 _attach_helper_skill(flow_response, MandatoryBPS)
                 return flow_response

{ha_mcp_dev-7.7.0.dev694 → ha_mcp_dev-7.7.0.dev696/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.dev696
 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.dev696}/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