ha-mcp-dev 8.4.3.dev2548__tar.gz → 8.4.3.dev2552__tar.gz

{ha_mcp_dev-8.4.3.dev2548/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.3.dev2552}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2548
+Version: 8.4.3.dev2552
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -380,6 +380,8 @@ Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA app). The full catal
 
 The proxy split lets MCP clients apply different permission policies per category (e.g. auto-approve reads, prompt for writes, confirm deletes) without parsing tool docstrings.
 
+A `ha_manage_*` tool combines several operations, so it is reachable from more than one proxy: `ha_call_write_tool` and `ha_call_delete_tool` run the whole tool, while `ha_call_read_tool` runs only the read actions Read Only Mode approves (the same per-call verdict), so a manage tool with no approved read actions is not reachable there. Search results list each proxy the tool can be reached through. In Read Only Mode only `ha_call_read_tool` is listed; the other two still answer a client that holds them in a cached tool list, and any write they carry gets the Read Only Mode error rather than `Unknown tool`.
+
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (tools deferred behind on-demand search). |
@@ -394,7 +396,7 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
 
-> 🔄 **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 app 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, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but return `Unknown tool` when called. ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a **different name**.
+> 🔄 **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 app 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, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a **different name**.
 
 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.
 

{ha_mcp_dev-8.4.3.dev2548 → ha_mcp_dev-8.4.3.dev2552}/README.md

@@ -348,6 +348,8 @@ Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA app). The full catal
 
 The proxy split lets MCP clients apply different permission policies per category (e.g. auto-approve reads, prompt for writes, confirm deletes) without parsing tool docstrings.
 
+A `ha_manage_*` tool combines several operations, so it is reachable from more than one proxy: `ha_call_write_tool` and `ha_call_delete_tool` run the whole tool, while `ha_call_read_tool` runs only the read actions Read Only Mode approves (the same per-call verdict), so a manage tool with no approved read actions is not reachable there. Search results list each proxy the tool can be reached through. In Read Only Mode only `ha_call_read_tool` is listed; the other two still answer a client that holds them in a cached tool list, and any write they carry gets the Read Only Mode error rather than `Unknown tool`.
+
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (tools deferred behind on-demand search). |
@@ -362,7 +364,7 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
 
-> 🔄 **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 app 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, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but return `Unknown tool` when called. ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a **different name**.
+> 🔄 **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 app 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, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a **different name**.
 
 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.
 

{ha_mcp_dev-8.4.3.dev2548 → ha_mcp_dev-8.4.3.dev2552}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.3.dev2548"
+version = "8.4.3.dev2552"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-8.4.3.dev2548 → ha_mcp_dev-8.4.3.dev2552}/src/ha_mcp/transforms/categorized_search.py

@@ -9,6 +9,12 @@ Tools are categorized by their existing MCP annotations:
 - readOnlyHint=True → "read" category
 - destructiveHint=True with remove/delete in name → "delete" category
 - destructiveHint=True (other) → "write" category
+
+A ``manage`` tool combines several operations behind one name, so it is
+reachable from every proxy — read-approved calls only on the read proxy,
+the whole tool on the write and delete proxies (see ``_admits``) — and
+search results point each kind of action at its own proxy. In Read Only
+Mode only the read proxy is listed.
 """
 
 from __future__ import annotations
@@ -85,6 +91,12 @@ DEFAULT_PINNED_TOOLS: tuple[str, ...] = (
 # Tool name patterns that indicate delete/remove operations
 _DELETE_PATTERNS = ("_remove_", "_delete_")
 
+# ``manage`` names one interface that intentionally combines several
+# operations (.gemini/styleguide.md, Tool Naming Convention). Such a tool is
+# categorised by its annotations like any other, but every call proxy can
+# reach it — see ``_admits``.
+_MANAGE_PATTERNS = ("_manage_",)
+
 # Capability tier a tool falls into — shared by the call-proxy routing and
 # the settings-UI capability badges. See ``categorize_capability``.
 Capability = Literal["read", "write", "delete"]
@@ -192,22 +204,26 @@ def categorize_capability(
     return "write"
 
 
+def _is_manage_tool(name: str) -> bool:
+    """Whether *name* follows the ``manage`` convention for a multi-operation tool."""
+    return any(pattern in name for pattern in _MANAGE_PATTERNS)
+
+
 def _is_read_call_on_write_tool(name: str, arguments: dict[str, Any] | None) -> bool:
     """Whether this call on a non-read-category tool is one of its read actions.
 
     A mixed read/write tool (``ha_manage_backup``, ``ha_manage_updates``,
-    ``ha_manage_blueprints``, ...) is categorised ``write`` by its annotations,
-    which is where it stays: it is advertised under the write proxy and appears
-    in no other category set. But refusing its list/get actions on the read
-    proxy would strip real read surface from a client that only holds that
-    proxy — for blueprints, folding the old read tool into the merged one would
-    otherwise have removed listing entirely (#2329).
-
-    So membership decides advertisement, and this decides admission: read-only
-    mode already enumerates, per call, which invocations of such a tool are
-    reads (``READ_ONLY_EXEMPT_TOOLS``), and the read proxy reuses that verdict
-    so the two surfaces cannot disagree about what counts as a read. A call
-    that changes state is still refused here.
+    ``ha_manage_blueprints``, ...) is categorised ``write`` by its annotations
+    and lives in that category set only. But refusing its list/get actions on
+    the read proxy would strip real read surface from a client that only holds
+    that proxy — for blueprints, folding the old read tool into the merged one
+    would otherwise have removed listing entirely (#2329).
+
+    Read-only mode already enumerates, per call, which invocations of such a
+    tool are reads (``READ_ONLY_EXEMPT_TOOLS``), and the proxies reuse that
+    verdict so the two surfaces cannot disagree about what counts as a read.
+    The verdict fails closed: a tool without an exemption entry, or a missing
+    or unknown action, is never a read.
     """
     from ..read_only import READ_ONLY_EXEMPT_TOOLS
 
@@ -215,6 +231,74 @@ def _is_read_call_on_write_tool(name: str, arguments: dict[str, Any] | None) ->
     return exemption is not None and exemption.blocked_write(arguments or {}) is None
 
 
+def _has_read_actions(name: str) -> bool:
+    """Whether a write-category tool has read actions the read proxy can approve."""
+    from ..read_only import READ_ONLY_EXEMPT_TOOLS
+
+    return name in READ_ONLY_EXEMPT_TOOLS
+
+
+def _admits(
+    transform: CategorizedSearchTransform,
+    category: Capability,
+    name: str,
+    arguments: dict[str, Any] | None,
+) -> bool:
+    """Whether the *category* proxy may dispatch this call.
+
+    Membership in the category set is the rule. A ``manage`` tool (#2358) is
+    the exception: it is reachable from every proxy. The read proxy is the
+    one hard boundary — it carries ``readOnlyHint`` — so it admits only a
+    call the read-only predicate approves. The write and delete proxies both
+    carry ``destructiveHint`` and run the whole tool: its delete actions are
+    not statically enumerable (``ha_manage_radio`` and ``ha_manage_updates``
+    take a free-form ``action``), so neither proxy pretends to carve them out.
+    """
+    if category == "read":
+        return name in transform._read_tools or (
+            name in transform._write_tools
+            and _is_read_call_on_write_tool(name, arguments)
+        )
+    if category == "write":
+        return name in transform._write_tools
+    return name in transform._delete_tools or (
+        name in transform._write_tools and _is_manage_tool(name)
+    )
+
+
+def _execute_via(proxy: str, tool_name: str) -> str:
+    """Render the call form a search result advertises for *tool_name*."""
+    return (
+        f'client.{proxy}(name="{tool_name}", arguments={{...}}) '
+        f'or {proxy}(name="{tool_name}", arguments={{...}})'
+    )
+
+
+def _read_only_mode() -> bool:
+    """Whether Read Only Mode is on — consulted per request, like its filter."""
+    from ..config import get_global_settings
+
+    return bool(get_global_settings().read_only_mode)
+
+
+def _advertised_routes(name: str, category: Capability) -> list[Capability]:
+    """Proxies a search result points at for *name*, in listing order.
+
+    A manage tool lists every proxy it is reachable through (see
+    ``_admits``); the read route exists only when the read-only predicate can
+    approve calls to it. In Read Only Mode the destructive proxies are not
+    listed, so only the read route remains. The ``["write", "delete"]`` case
+    cannot occur in that mode: ``ReadOnlyToolsTransform`` drops every
+    non-exempt write tool from the catalog before the search index is built,
+    and every exempt tool has read actions.
+    """
+    if category != "write" or not _is_manage_tool(name):
+        return [category]
+    if _has_read_actions(name):
+        return ["read"] if _read_only_mode() else ["read", "write", "delete"]
+    return ["write", "delete"]
+
+
 def _categorize_tool(tool: Tool) -> Capability:
     """Categorize a Tool as read, write, or delete based on annotations and name."""
     annotations = tool.annotations
@@ -443,11 +527,15 @@ class CategorizedSearchTransform(BM25SearchTransform):
         results = []
         for tool in tools:
             data = tool.to_mcp_tool().model_dump(mode="json", exclude_none=True)
-            proxy = proxy_map[_categorize_tool(tool)]
-            data["execute_via"] = (
-                f'client.{proxy}(name="{tool.name}", arguments={{...}}) '
-                f'or {proxy}(name="{tool.name}", arguments={{...}})'
-            )
+            routes = _advertised_routes(tool.name, _categorize_tool(tool))
+            if len(routes) == 1:
+                data["execute_via"] = _execute_via(proxy_map[routes[0]], tool.name)
+            else:
+                hint = "; ".join(
+                    f"{route} actions: {_execute_via(proxy_map[route], tool.name)}"
+                    for route in routes
+                )
+                data["execute_via"] = hint[:1].upper() + hint[1:]
             results.append(data)
         return results
 
@@ -487,14 +575,6 @@ class CategorizedSearchTransform(BM25SearchTransform):
             # needs the action its old signature never carried.
             arguments = adapt_retired_arguments(requested, arguments)
 
-            # Determine which category set to check
-            if category == "read":
-                allowed = transform._read_tools
-            elif category == "delete":
-                allowed = transform._delete_tools
-            else:
-                allowed = transform._write_tools
-
             # Detect and unwrap double-wrapped arguments where the LLM
             # accidentally nested name/arguments inside the arguments param
             # e.g. ha_call_read_tool(name="ha_call_read_tool",
@@ -540,11 +620,7 @@ class CategorizedSearchTransform(BM25SearchTransform):
                         _raise_non_object_arguments(nested, proxy_name, inner_name)
                     arguments = adapt_retired_arguments(requested_inner, nested or {})
 
-            # Membership is the advertised category; a mixed tool's read
-            # actions are additionally admitted here (see the helper).
-            if name not in allowed and not (
-                category == "read" and _is_read_call_on_write_tool(name, arguments)
-            ):
+            if not _admits(transform, category, name, arguments):
                 _raise_wrong_category_error(name, transform, proxy_name)
 
             return await ctx.fastmcp.call_tool(name, arguments)
@@ -590,6 +666,16 @@ class CategorizedSearchTransform(BM25SearchTransform):
             description=self._proxy_descs["delete"],
         )
 
+        if _read_only_mode():
+            # ReadOnlyToolsTransform runs before this one and never sees the
+            # proxies synthesised here; with every write blocked at call time
+            # the destructive proxies would only advertise dead ends. They
+            # stay resolvable by name so a client holding a stale catalog gets
+            # the proxy's own structured answer (ReadOnlyMiddleware blocks a
+            # write before the proxy is even resolved) rather than a bare
+            # not-found that ToolSearchHintMiddleware declines to explain
+            # while tool search is on.
+            return [*pinned, search_tool, call_read]
         return [*pinned, search_tool, call_read, call_write, call_delete]
 
     async def get_tool(

{ha_mcp_dev-8.4.3.dev2548 → ha_mcp_dev-8.4.3.dev2552/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2548
+Version: 8.4.3.dev2552
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -380,6 +380,8 @@ Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA app). The full catal
 
 The proxy split lets MCP clients apply different permission policies per category (e.g. auto-approve reads, prompt for writes, confirm deletes) without parsing tool docstrings.
 
+A `ha_manage_*` tool combines several operations, so it is reachable from more than one proxy: `ha_call_write_tool` and `ha_call_delete_tool` run the whole tool, while `ha_call_read_tool` runs only the read actions Read Only Mode approves (the same per-call verdict), so a manage tool with no approved read actions is not reachable there. Search results list each proxy the tool can be reached through. In Read Only Mode only `ha_call_read_tool` is listed; the other two still answer a client that holds them in a cached tool list, and any write they carry gets the Read Only Mode error rather than `Unknown tool`.
+
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (tools deferred behind on-demand search). |
@@ -394,7 +396,7 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
 
-> 🔄 **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 app 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, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but return `Unknown tool` when called. ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a **different name**.
+> 🔄 **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 app 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, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a **different name**.
 
 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.