ha-mcp-dev 8.6.0.dev2865__tar.gz → 8.6.0.dev2866__tar.gz

{ha_mcp_dev-8.6.0.dev2865 → ha_mcp_dev-8.6.0.dev2866}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2865
+Version: 8.6.0.dev2866
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien
@@ -407,7 +407,7 @@ Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA app). The full catal
 
 | Tool | Purpose |
 |------|---------|
-| `ha_search_tools` | BM25 keyword search across all tools. Returns name, description, parameters, and annotations (`readOnlyHint` / `destructiveHint`) so the agent can pick the right one. |
+| `ha_search_tools` | BM25 English-keyword search across all tools, pinned ones included. Hidden tools return name, description, parameters, and annotations (`readOnlyHint` / `destructiveHint`) so the agent can pick the right one; a pinned tool returns a name-only stub (`pinned: true`) pointing back at the tool list, and does not use up a result slot. |
 | `ha_call_read_tool` | Execute a `readOnlyHint` tool by name. Safe — clients can auto-approve. |
 | `ha_call_write_tool` | Execute a write tool that creates or updates data. |
 | `ha_call_delete_tool` | Execute a tool that removes / deletes data. |
@@ -419,7 +419,7 @@ A `ha_manage_*` tool combines several operations, so it is reachable from more t
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (tools deferred behind on-demand search). |
-| `TOOL_SEARCH_MAX_RESULTS` | `5` | Max results returned by `ha_search_tools` (range 2–10). |
+| `TOOL_SEARCH_MAX_RESULTS` | `5` | Max hidden tools returned per `ha_search_tools` call (range 2–10); a pinned tool that ranks inside that top count is added as a name-only stub on top of it. |
 | `PINNED_TOOLS` | empty | Comma-separated tool names to keep always visible. The web settings UI is the primary way to manage this. |
 
 ### When to enable

{ha_mcp_dev-8.6.0.dev2865 → ha_mcp_dev-8.6.0.dev2866}/README.md

@@ -347,7 +347,7 @@ Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA app). The full catal
 
 | Tool | Purpose |
 |------|---------|
-| `ha_search_tools` | BM25 keyword search across all tools. Returns name, description, parameters, and annotations (`readOnlyHint` / `destructiveHint`) so the agent can pick the right one. |
+| `ha_search_tools` | BM25 English-keyword search across all tools, pinned ones included. Hidden tools return name, description, parameters, and annotations (`readOnlyHint` / `destructiveHint`) so the agent can pick the right one; a pinned tool returns a name-only stub (`pinned: true`) pointing back at the tool list, and does not use up a result slot. |
 | `ha_call_read_tool` | Execute a `readOnlyHint` tool by name. Safe — clients can auto-approve. |
 | `ha_call_write_tool` | Execute a write tool that creates or updates data. |
 | `ha_call_delete_tool` | Execute a tool that removes / deletes data. |
@@ -359,7 +359,7 @@ A `ha_manage_*` tool combines several operations, so it is reachable from more t
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (tools deferred behind on-demand search). |
-| `TOOL_SEARCH_MAX_RESULTS` | `5` | Max results returned by `ha_search_tools` (range 2–10). |
+| `TOOL_SEARCH_MAX_RESULTS` | `5` | Max hidden tools returned per `ha_search_tools` call (range 2–10); a pinned tool that ranks inside that top count is added as a name-only stub on top of it. |
 | `PINNED_TOOLS` | empty | Comma-separated tool names to keep always visible. The web settings UI is the primary way to manage this. |
 
 ### When to enable

{ha_mcp_dev-8.6.0.dev2865 → ha_mcp_dev-8.6.0.dev2866}/pyproject.toml

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

{ha_mcp_dev-8.6.0.dev2865 → ha_mcp_dev-8.6.0.dev2866}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2865"
+version = "8.6.0.dev2866"
 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.6.0.dev2865 → ha_mcp_dev-8.6.0.dev2866}/src/ha_mcp/server.py

@@ -28,6 +28,7 @@ from .server_tool_text import (
     SEARCH_KEYWORDS,
     SEARCH_TOOL_DESCRIPTION,
     SKILL_USE_BEFORE_KEYWORDS,
+    TOOL_DISCOVERY_INSTRUCTIONS,
 )
 from .tools.helpers import raise_tool_error
 from .transforms import DEFAULT_PINNED_TOOLS
@@ -456,32 +457,8 @@ class HomeAssistantSmartMCPServer:
 
         # Append tool search instructions when enabled
         if self.settings.enable_tool_search:
-            instructions += (
-                "\n\n## Tool Discovery\n"
-                "This server uses search-based tool discovery. Most tools "
-                "are NOT listed directly \u2014 use ha_search_tools to find them.\n\n"
-                "WORKFLOW:\n"
-                '1. Call ha_search_tools(query="...") to find relevant tools\n'
-                "2. Results include name, description, parameters, and "
-                "annotations (readOnlyHint/destructiveHint)\n"
-                "3. Execute the discovered tool \u2014 two options:\n"
-                "   a) DIRECT CALL (preferred): Call the tool directly by "
-                "name. All discovered tools are callable without a proxy.\n"
-                "   b) VIA PROXY: For permission-gated execution, use the "
-                "matching proxy:\n"
-                "      - ha_call_read_tool \u2014 safe, read-only operations\n"
-                "      - ha_call_write_tool \u2014 creates or modifies data\n"
-                "      - ha_call_delete_tool \u2014 removes data permanently\n\n"
-                "Once you know a tool\u2019s name, you do NOT need to search "
-                "again \u2014 call it directly.\n\n"
-                f"A few default tools are listed directly "
-                f"({', '.join(DEFAULT_PINNED_TOOLS)}) — these are the "
-                f"starting pins, and users can unpin the non-mandatory "
-                f"ones via the Tools tab in the settings UI, so the "
-                f"actual visible set may be a subset of this list. "
-                f"Everything else must be discovered via search.\n\n"
-                "DO NOT assume a capability is unavailable because you "
-                "don't see a direct tool for it. ALWAYS search first."
+            instructions += TOOL_DISCOVERY_INSTRUCTIONS.format(
+                pinned=", ".join(DEFAULT_PINNED_TOOLS)
             )
 
         return instructions

{ha_mcp_dev-8.6.0.dev2865 → ha_mcp_dev-8.6.0.dev2866}/src/ha_mcp/server_tool_text.py

@@ -9,12 +9,15 @@ from __future__ import annotations
 
 # Description for the unified search tool
 SEARCH_TOOL_DESCRIPTION = (
-    "Search ALL Home Assistant tools by keyword. Returns matching tools "
-    "with descriptions, parameters, and annotations (read/write/delete). "
-    "Categories: entities, states, automations, scripts, dashboards, "
-    "helpers, HACS, calendar, zones, labels, groups, areas, floors, "
-    "history, statistics, devices, integrations, services, backups, "
-    "todo, camera, blueprints, system, and more.\n\n"
+    "Search ALL Home Assistant tools by ENGLISH keyword. Returns matching "
+    "tools with descriptions, parameters, and annotations "
+    "(read/write/delete). Categories: entities, states, automations, "
+    "scripts, dashboards, helpers, HACS, calendar, zones, labels, groups, "
+    "areas, floors, history, statistics, devices, integrations, services, "
+    "backups, todo, camera, blueprints, system, and more.\n\n"
+    "Tools already in your tool list are callable directly \u2014 no search "
+    "needed. If one matches a search, it comes back as a name-only stub "
+    "(pinned: true); use the schema you already have.\n\n"
     "WORKFLOW:\n"
     "1. ha_search_tools(query='...') \u2014 find tools (this tool)\n"
     "2. Execute: call the tool DIRECTLY by name (preferred), or use "
@@ -32,6 +35,42 @@ SEARCH_TOOL_DESCRIPTION = (
     "Most tools are discoverable only through this search."
 )
 
+# Appended to the server instructions when tool search is on; ``{pinned}``
+# is the comma-joined DEFAULT_PINNED_TOOLS.
+TOOL_DISCOVERY_INSTRUCTIONS = (
+    "\n\n## Tool Discovery\n"
+    "Tools already in your tool list are callable directly — "
+    "do not search for them. Once you know any tool’s name, "
+    "call it directly; never search for the same tool twice.\n\n"
+    "Most other tools are NOT listed directly — use "
+    "ha_search_tools to find them.\n\n"
+    "WORKFLOW:\n"
+    '1. Call ha_search_tools(query="...") with ENGLISH keywords '
+    "naming the operation (e.g. 'get entity state'). Translate "
+    "other languages first; entity, area and device names keep "
+    "their original spelling.\n"
+    "2. Results include name, description, parameters, and "
+    "annotations (readOnlyHint/destructiveHint). A tool already "
+    "in your list comes back as a name-only stub (pinned: true) "
+    "— use the schema you already have.\n"
+    "3. Execute the discovered tool — two options:\n"
+    "   a) DIRECT CALL (preferred): Call the tool directly by "
+    "name. All discovered tools are callable without a proxy.\n"
+    "   b) VIA PROXY: For permission-gated execution, use the "
+    "matching proxy:\n"
+    "      - ha_call_read_tool — safe, read-only operations\n"
+    "      - ha_call_write_tool — creates or modifies data\n"
+    "      - ha_call_delete_tool — removes data permanently\n\n"
+    "A few default tools are listed directly "
+    "({pinned}) — these are the "
+    "starting pins, and users can unpin the non-mandatory "
+    "ones via the Tools tab in the settings UI, so the "
+    "actual visible set may be a subset of this list. "
+    "Everything else must be discovered via search.\n\n"
+    "DO NOT assume a capability is unavailable because you "
+    "don't see a direct tool for it. ALWAYS search first."
+)
+
 # Extra keywords appended to tool descriptions for BM25 ranking.
 # Applied unconditionally via SearchKeywordsTransform so they also
 # improve retrieval for Claude's native deferred-tool search on
@@ -72,8 +111,12 @@ SEARCH_KEYWORDS: dict[str, str] = {
         "counter timer input_datetime input_select"
     ),
     "ha_get_entity": ("get entity state attributes details single specific entity_id"),
+    # #2576: BM25 has no stemming, so "lights" never matched "light". No
+    # control verbs (on/off/turn) here: they would pull "turn off lights"
+    # onto this read tool.
     "ha_get_state": (
-        "get current state value single entity check status bulk multiple states"
+        "get current state value single entity check status bulk multiple states "
+        "which lights"
     ),
     "ha_config_set_automation": (
         "create update modify edit automation triggers conditions actions "

{ha_mcp_dev-8.6.0.dev2865 → ha_mcp_dev-8.6.0.dev2866}/src/ha_mcp/settings_ui/locales/en.json

@@ -132,7 +132,7 @@
     "features.enable_tool_search.label": "Enable tool search",
     "features.enable_tool_search.help": "Replace the full tool catalog with search-based discovery. Reduces idle context by roughly 90%, to about 5K tokens. ⚠️ Do NOT enable this in clients with their own built-in tool search / deferred tools (claude.ai, Claude Desktop, Claude Code) — the two search layers conflict, and the client's built-in tool search is the better choice there; leave this off. Whether tools are deferred depends on your client and model combination: use this when your setup loads the full catalog up front — models without native deferred tools (e.g. Gemini, OpenAI-compatible local models, Claude Haiku), clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI), or smaller context windows. 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. Tools are found via ha_search_tools and executed via categorized proxies (read/write/delete). Requires restart to take effect.",
     "features.tool_search_max_results.label": "Tool search max results",
-    "features.tool_search_max_results.help": "Maximum number of tools returned by ha_search_tools when tool search is enabled. Lower values (2-3) save context tokens but may miss relevant tools. Range: 2-10. Requires restart.",
+    "features.tool_search_max_results.help": "Maximum number of hidden tools returned per ha_search_tools call when tool search is enabled; a pinned tool that ranks inside that top count is added as a short name-only entry on top of it. Lower values (2-3) save context tokens but may miss relevant tools. Range: 2-10. Requires restart.",
     "features.enable_tool_security_policies.label": "Enable Tool Security Policies (advanced)",
     "features.enable_tool_security_policies.help": "Gate high-stakes tool calls (lock/alarm control, automation writes, etc.) behind user approval. When a guarded tool is called, the agent tells the user to open the Tool Security Policies tab in the web UI and click Approve before the call proceeds. Per-tool rules with optional argument conditions are configured in the Tool Security Policies tab. Off by default. Requires restart to take effect.",
     "features.read_only_mode.label": "Read Only Mode",

{ha_mcp_dev-8.6.0.dev2865 → ha_mcp_dev-8.6.0.dev2866}/src/ha_mcp/settings_ui/settings_js/05_feature_flags.js

@@ -13,7 +13,7 @@ const FEATURE_META = {
   },
   tool_search_max_results: {
     label: "Tool search max results",
-    help: "Maximum number of tools returned by ha_search_tools when tool search is enabled. Lower values (2-3) save context tokens but may miss relevant tools. Range: 2-10. Requires restart.",
+    help: "Maximum number of hidden tools returned per ha_search_tools call when tool search is enabled; a pinned tool that ranks inside that top count is added as a short name-only entry on top of it. Lower values (2-3) save context tokens but may miss relevant tools. Range: 2-10. Requires restart.",
   },
   enable_tool_security_policies: {
     label: "Enable Tool Security Policies (advanced)",

{ha_mcp_dev-8.6.0.dev2865 → ha_mcp_dev-8.6.0.dev2866}/src/ha_mcp/tools/backup.py

@@ -1667,11 +1667,11 @@ survives an agent's own mistakes.
 - List snapshots (to discover a backup_id or confirm one landed): `ha_manage_backup(scope="snapshot", action="list")`
 - Restore full snapshot: `ha_manage_backup(scope="snapshot", action="restore", backup_id="dd7550ed")`
 - Delete an old snapshot (requires `enable_snapshot_delete=true`): `ha_manage_backup(scope="snapshot", action="delete", backup_id="dd7550ed", confirm=True)`
-- On-demand entity snapshot before a manual UI edit: `ha_manage_backup(scope="edits", action="create", domain="helper_input_boolean", entity_id="kitchen_lights_active")`
-- List recent auto-backups for one automation: `ha_manage_backup(scope="edits", action="list", domain="automation", entity_id="kitchen_lights")`
-- View an auto-backup: `ha_manage_backup(scope="edits", action="view", backup_name="automation.kitchen_lights.20260521_153000.yaml")`
-- Diff an auto-backup vs current state: `ha_manage_backup(scope="edits", action="diff", backup_name="automation.kitchen_lights.20260521_153000.yaml")`
-- Restore an auto-backup: `ha_manage_backup(scope="edits", action="restore", backup_name="automation.kitchen_lights.20260521_153000.yaml")`
+- On-demand entity snapshot before a manual UI edit: `ha_manage_backup(scope="edits", action="create", domain="helper_input_boolean", entity_id="welcome_home_active")`
+- List recent auto-backups for one automation: `ha_manage_backup(scope="edits", action="list", domain="automation", entity_id="welcome_home")`
+- View an auto-backup: `ha_manage_backup(scope="edits", action="view", backup_name="automation.welcome_home.20260521_153000.yaml")`
+- Diff an auto-backup vs current state: `ha_manage_backup(scope="edits", action="diff", backup_name="automation.welcome_home.20260521_153000.yaml")`
+- Restore an auto-backup: `ha_manage_backup(scope="edits", action="restore", backup_name="automation.welcome_home.20260521_153000.yaml")`
 - Delete one auto-backup: `ha_manage_backup(scope="edits", action="delete", backup_name="...")`
 - Bulk-delete old auto-backups: `ha_manage_backup(scope="edits", action="delete", older_than_days=30)`
 """

{ha_mcp_dev-8.6.0.dev2865 → ha_mcp_dev-8.6.0.dev2866}/src/ha_mcp/transforms/categorized_search.py

@@ -92,6 +92,14 @@ DEFAULT_PINNED_TOOLS: tuple[str, ...] = (
 # Tool name patterns that indicate delete/remove operations
 _DELETE_PATTERNS = ("_remove_", "_delete_")
 
+# Ranking is plain English keyword matching (BM25, no stemming, no
+# translation), so a query in another language returns nothing (#2576).
+SEARCH_QUERY_DESCRIPTION = (
+    "English keywords naming the operation, e.g. 'get entity state' or "
+    "'create automation'. Translate other languages to English first; "
+    "entity, area and device names keep their original spelling."
+)
+
 # ``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
@@ -428,9 +436,12 @@ class CategorizedSearchTransform(BM25SearchTransform):
     three category-specific proxies, each carrying appropriate MCP
     annotations for client-side permission handling.
 
-    The unified ``ha_search_tools`` is inherited from BM25SearchTransform and
-    searches across ALL tools regardless of category. Search results include
-    each tool's full annotations so the LLM can determine which proxy to use.
+    The unified ``ha_search_tools`` searches across ALL tools regardless of
+    category, pinned ones included (issue #2576: a pinned tool vanishing
+    from search reads as "no such capability" to a small model). Hidden
+    hits carry their full definition and annotations so the LLM can pick a
+    proxy; pinned hits are rendered as a name-only stub pointing back at the
+    tool list, and never consume one of the ``max_results`` slots.
     """
 
     def __init__(
@@ -524,6 +535,48 @@ class CategorizedSearchTransform(BM25SearchTransform):
             self._delete_tools = delete
             self._last_catalog_hash = current_hash
 
+    def _make_search_tool(self) -> Tool:
+        """Search tool over the whole catalog (pinned tools included)."""
+        transform = self
+
+        async def search_tools(
+            query: Annotated[str, SEARCH_QUERY_DESCRIPTION],
+            ctx: Context = None,  # type: ignore[assignment]
+        ) -> list[dict[str, Any]]:
+            """Search for tools using English keywords.
+
+            Returns matching tool definitions ranked by relevance,
+            in the same format as list_tools.
+            """
+            catalog = await transform.get_tool_catalog(ctx)
+            results = await transform._search(catalog, query)
+            return await transform._render_results(results)
+
+        return Tool.from_function(fn=search_tools, name=self._search_tool_name)
+
+    async def _search(self, tools: Sequence[Tool], query: str) -> Sequence[Tool]:
+        """Rank ``tools``; pinned hits ride along without using a result slot.
+
+        A pinned tool is kept only when it ranks inside the first
+        ``max_results`` of the whole catalog, so a weak match on a stop word
+        does not add a stub to every page.
+        """
+        # The base call (re)builds the index for this catalog; its own top-k
+        # is discarded because pinned hits must not crowd out hidden ones.
+        await super()._search(tools, query)
+        pinned_count = sum(t.name in self._always_visible for t in tools)
+        indices = self._index.query(query, self._max_results + pinned_count)
+        slots = self._max_results
+        results: list[Tool] = []
+        for rank, tool in enumerate(self._indexed_tools[i] for i in indices):
+            if tool.name in self._always_visible:
+                if rank < self._max_results:
+                    results.append(tool)
+            elif slots:
+                results.append(tool)
+                slots -= 1
+        return results
+
     async def _render_results(self, tools: Sequence[Tool]) -> list[dict[str, Any]]:
         """Serialize search results with ``execute_via`` hints."""
         proxy_map: dict[Capability, str] = {
@@ -533,6 +586,22 @@ class CategorizedSearchTransform(BM25SearchTransform):
         }
         results = []
         for tool in tools:
+            if tool.name in self._always_visible:
+                # The client already holds this tool's full definition —
+                # repeating a 5-9KB schema here is what overflows small
+                # context windows (#2576).
+                results.append(
+                    {
+                        "name": tool.name,
+                        "pinned": True,
+                        "execute_via": (
+                            f"{tool.name} is already in your tool list — "
+                            "call it directly with the schema you have; "
+                            "no search or proxy needed."
+                        ),
+                    }
+                )
+                continue
             data = tool.to_mcp_tool().model_dump(
                 mode="json", exclude_none=True, by_alias=True
             )