ha-mcp-dev 7.1.0.dev289__tar.gz → 7.1.0.dev290__tar.gz

{ha_mcp_dev-7.1.0.dev289/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.1.0.dev290}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.1.0.dev289
+Version: 7.1.0.dev290
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.1.0.dev289 → ha_mcp_dev-7.1.0.dev290}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.1.0.dev289"
+version = "7.1.0.dev290"
 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.1.0.dev289 → ha_mcp_dev-7.1.0.dev290}/src/ha_mcp/config.py

@@ -15,7 +15,7 @@ except importlib.metadata.PackageNotFoundError:
     _PACKAGE_VERSION = "unknown"
 
 from dotenv import load_dotenv
-from pydantic import Field, field_validator
+from pydantic import Field, field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 project_root = Path(__file__).parent.parent.parent
@@ -94,6 +94,23 @@ class Settings(BaseSettings):
     # that don't support MCP resources natively.
     enable_skills_as_tools: bool = Field(False, alias="ENABLE_SKILLS_AS_TOOLS")
 
+    # Tool search transform — replaces the full tool catalog with a unified
+    # BM25 search tool and categorized call proxies (read/write/delete).
+    # Dramatically reduces idle context token usage for LLMs.
+    enable_tool_search: bool = Field(False, alias="ENABLE_TOOL_SEARCH")
+
+    @model_validator(mode="after")
+    def _skills_dependency(self) -> "Settings":
+        """Auto-enable skills (resources) when skills-as-tools is on.
+
+        skills_as_tools wraps ResourcesAsTools which requires skills to be
+        registered as MCP resources first. Without this, enabling
+        skills_as_tools alone would produce empty list_resources results.
+        """
+        if self.enable_skills_as_tools and not self.enable_skills:
+            self.enable_skills = True
+        return self
+
     @property
     def env_file_name(self) -> str:
         """Get the current environment file name."""

{ha_mcp_dev-7.1.0.dev289 → ha_mcp_dev-7.1.0.dev290}/src/ha_mcp/server.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 import logging
 from collections.abc import Callable, Coroutine
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 import yaml  # type: ignore[import-untyped]
 from fastmcp import FastMCP
@@ -20,6 +20,7 @@ from mcp.types import Icon
 
 from .config import _PACKAGE_VERSION, get_global_settings
 from .tools.enhanced import EnhancedToolsMixin
+from .transforms import DEFAULT_PINNED_TOOLS
 
 if TYPE_CHECKING:
     from .client.rest_client import HomeAssistantClient
@@ -138,6 +139,10 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         # Register bundled skills as MCP resources
         self._register_skills()
 
+        # Apply tool search transform (must come after all tools and
+        # ResourcesAsTools are registered so it can wrap everything)
+        self._apply_tool_search()
+
     def _get_skills_dir(self) -> Path | None:
         """Return the bundled skills directory if it exists.
 
@@ -188,7 +193,13 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         # Build the access method instruction based on config
         if self.settings.enable_skills_as_tools:
             access_method = (
-                "Use the read_resource tool with the skill's URI to load it."
+                "Read the skill via MCP resources (resources/read with the "
+                "skill:// URI) — if you can read these instructions, you "
+                "should be able to access resources as well. If for any "
+                "reason you cannot access MCP resources, use the "
+                "list_resources and read_resource tools as a fallback. "
+                "If you can access resources normally, do not waste "
+                "time or tokens on those tools."
             )
         else:
             access_method = (
@@ -208,7 +219,36 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             f"How to access: {access_method}\n"
         )
 
-        return header + "\n".join(skill_blocks)
+        instructions = header + "\n".join(skill_blocks)
+
+        # 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 critical tools are listed directly "
+                f"({', '.join(DEFAULT_PINNED_TOOLS)}). Everything else must "
+                f"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."
+            )
+
+        return instructions
 
     @staticmethod
     def _parse_skill_frontmatter(main_file: Path) -> dict | None:
@@ -264,7 +304,164 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
 
         return f"\n### Skill: {skill_name} ({uri})\n{description.strip()}"
 
+    # Tools pinned outside the search transform for individual permission gating.
+    # These are always visible in list_tools() regardless of search transform.
+    _PINNED_TOOLS: ClassVar[list[str]] = list(DEFAULT_PINNED_TOOLS)
+
+    # 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"
+        "WORKFLOW:\n"
+        "1. ha_search_tools(query='...') \u2014 find tools (this tool)\n"
+        "2. Execute: call the tool DIRECTLY by name (preferred), or use "
+        "a proxy for permission gating:\n"
+        "   - ha_call_read_tool \u2014 readOnlyHint tools (safe, no side effects)\n"
+        "   - ha_call_write_tool \u2014 destructiveHint tools that create/update\n"
+        "   - ha_call_delete_tool \u2014 destructiveHint tools that remove/delete\n"
+        "Once you know a tool name, call it directly \u2014 no need to search "
+        "again.\n\n"
+        "If using proxies, call with TWO top-level params:\n"
+        '   ha_call_read_tool(name="ha_search_entities", arguments={"query": "..."})\n'
+        "   Do NOT nest name/arguments inside the arguments param.\n"
+        "   Call proxy tools SEQUENTIALLY, not in parallel.\n\n"
+        "ALWAYS search before assuming a capability is unavailable. "
+        "Most tools are discoverable only through this search."
+    )
+
+    # Extra keywords appended to tool descriptions for BM25 ranking.
+    # Only active behind enable_tool_search — the original docstrings
+    # are unchanged; these keywords are appended by SearchKeywordsTransform.
+    _SEARCH_KEYWORDS: ClassVar[dict[str, str]] = {
+        # s02: "find entities" → ha_search_entities should outrank ha_deep_search
+        "ha_search_entities": (
+            "find entities lookup discover search lights sensors switches "
+            "covers climate fans media_player binary_sensor device_tracker "
+            "person weather automation script helper input_boolean input_number"
+        ),
+        # s07: "get/read automation" → ha_config_get_automation should outrank set
+        "ha_config_get_automation": (
+            "read inspect fetch view existing automation config triggers "
+            "conditions actions get show detail"
+        ),
+        # s09: "create helper" → ha_config_set_helper should outrank remove_helper
+        "ha_config_set_helper": (
+            "create new add helper input_boolean input_number input_text "
+            "counter timer input_datetime input_select input_button "
+            "schedule zone group min_max"
+        ),
+        # Boost tools that compete with ha_deep_search for common queries
+        "ha_config_get_script": (
+            "read inspect fetch view existing script config sequence "
+            "actions get show detail"
+        ),
+        "ha_config_list_helpers": (
+            "list all helpers input_boolean input_number input_text "
+            "counter timer input_datetime input_select"
+        ),
+        "ha_get_entity": (
+            "get entity state attributes details single specific entity_id"
+        ),
+        "ha_get_state": (
+            "get current state value single entity check status"
+        ),
+        "ha_get_states": (
+            "get all states entities bulk overview list"
+        ),
+        "ha_config_set_automation": (
+            "create update modify edit automation triggers conditions actions "
+            "new automation write save"
+        ),
+        "ha_config_set_script": (
+            "create update modify edit script sequence actions "
+            "new script write save"
+        ),
+    }
+
+    # Description overrides that REPLACE the original description for BM25.
+    # Used to narrow overly broad tools so they stop matching generic queries.
+    # Only active behind enable_tool_search via SearchKeywordsTransform.
+    _SEARCH_DESCRIPTION_OVERRIDES: ClassVar[dict[str, str]] = {
+        "ha_deep_search": (
+            "Search INSIDE automation, script, and helper YAML configurations. "
+            "Use ONLY when you need to find where a specific service call, "
+            "entity reference, or config field appears within existing "
+            "automation/script/helper definitions. "
+            "NOT for finding entities or discovering tools."
+        ),
+    }
+
+    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. ResourcesAsTools (list_resources/read_resource) are also
+        pinned when enabled.
+        """
+        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
+        pinned = list(self._PINNED_TOOLS)
 
+        # Pin ResourcesAsTools and skill guidance tools if skills-as-tools is enabled
+        if self.settings.enable_skills_as_tools:
+            pinned.extend(["list_resources", "read_resource"])
+            # Forward-compatible: pin skill guidance tools registered by #732
+            pinned.extend(getattr(self, "_skill_tool_names", []))
+
+        # When skills-as-tools is enabled, the client likely doesn't support
+        # resources or server instructions — add skills hint to the search
+        # tool description (the one place the LLM is guaranteed to see).
+        description = self._SEARCH_TOOL_DESCRIPTION
+        if self.settings.enable_skills_as_tools:
+            description += (
+                "\n\nThis server also provides best-practice skills via "
+                "skill:// resources. If your client supports MCP resources, "
+                "prefer reading them directly. Otherwise, call "
+                "list_resources and read_resource (directly, no proxy "
+                "needed) to access the relevant SKILL.md before creating "
+                "automations or configuring devices."
+            )
+
+        try:
+            # Enrich tool descriptions for BM25 ranking (innermost transform).
+            # Added first so the search transform indexes enriched descriptions.
+            # Original tool docstrings are unchanged.
+            from .transforms import SearchKeywordsTransform
+
+            self.mcp.add_transform(SearchKeywordsTransform(
+                keywords=self._SEARCH_KEYWORDS,
+                overrides=self._SEARCH_DESCRIPTION_OVERRIDES,
+            ))
+
+            self.mcp.add_transform(
+                CategorizedSearchTransform(
+                    max_results=5,
+                    always_visible=pinned,
+                    search_tool_description=description,
+                )
+            )
+            logger.info(
+                "Tool search transform applied (%d pinned tools)", len(pinned)
+            )
+        except Exception:
+            logger.exception("Failed to apply tool search transform")
 
     def _register_skills(self) -> None:
         """Register bundled HA best-practice skills as MCP resources.

{ha_mcp_dev-7.1.0.dev289 → ha_mcp_dev-7.1.0.dev290}/src/ha_mcp/tools/tools_search.py

@@ -10,7 +10,9 @@ from typing import Annotated, Any, Literal, cast
 
 from pydantic import Field
 
+from ..config import get_global_settings
 from ..errors import create_validation_error
+from ..transforms.categorized_search import DEFAULT_PINNED_TOOLS
 from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
 from .util_helpers import (
     add_timezone_metadata,
@@ -507,7 +509,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         Returns comprehensive system information at the requested detail level,
         including Home Assistant base_url, version, location, timezone, entity overview,
         and active persistent notifications (if any).
-        Use 'standard' (default) for most queries. Optionally customize entity fields and limits.
+        Default is 'minimal' — use this unless you specifically need all entities.
         """
         # Coerce boolean parameters that may come as strings from XML-style calls
         include_state_bool = coerce_bool_param(
@@ -578,7 +580,31 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                             for n in notifications
                         ]
             except Exception as e:
-                logger.debug(f"Failed to fetch notifications for overview: {e}")
+                logger.warning(f"Failed to fetch notifications for overview: {e}")
+
+        # Include tool discovery hint when search transform is active
+        settings = get_global_settings()
+        if settings.enable_tool_search:
+            result["tool_discovery"] = {
+                "hint": (
+                    "This server uses search-based tool discovery. "
+                    "Use ha_search_tools(query='...') to find tools, then "
+                    "execute the discovered tool directly by name (preferred), "
+                    "or via a proxy for permission gating: "
+                    "ha_call_read_tool, ha_call_write_tool, or "
+                    "ha_call_delete_tool. Each proxy takes name and arguments "
+                    "as separate top-level params. Call proxy tools SEQUENTIALLY "
+                    "(not in parallel) to avoid cascading cancellations. "
+                    "Do NOT assume a capability is unavailable without searching first."
+                ),
+                "pinned_tools": sorted([
+                    *DEFAULT_PINNED_TOOLS,
+                    "ha_search_tools",
+                    "ha_call_read_tool",
+                    "ha_call_write_tool",
+                    "ha_call_delete_tool",
+                ]),
+            }
 
         return result
 
@@ -629,7 +655,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         Args:
             query: Search query (can be partial, with typos)
             search_types: Types to search (list of strings, default: ["automation", "script", "helper"])
-            limit: Maximum total results to return (default: 20)
+            limit: Maximum total results to return (default: 5)
 
         Examples:
             - Find automations using a service: ha_deep_search("light.turn_on")
@@ -683,7 +709,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     )
     @log_tool_usage
     async def ha_get_state(entity_id: str) -> dict[str, Any]:
-        """Get detailed state information for a Home Assistant entity with timezone metadata."""
+        """Get current status, state, and attributes of any entity (lights, switches, sensors, climate, covers, locks, fans, etc.)."""
         try:
             result = await client.get_entity_state(entity_id)
             return await add_timezone_metadata(client, result)

ha_mcp_dev-7.1.0.dev290/src/ha_mcp/transforms/__init__.py

@@ -0,0 +1,9 @@
+"""Custom FastMCP transforms for ha-mcp."""
+
+from .categorized_search import (
+    DEFAULT_PINNED_TOOLS,
+    CategorizedSearchTransform,
+    SearchKeywordsTransform,
+)
+
+__all__ = ["CategorizedSearchTransform", "DEFAULT_PINNED_TOOLS", "SearchKeywordsTransform"]

ha_mcp_dev-7.1.0.dev290/src/ha_mcp/transforms/categorized_search.py

@@ -0,0 +1,393 @@
+"""Categorized search transform for ha-mcp.
+
+Extends FastMCP's BM25SearchTransform to provide a unified search tool
+with separate call proxies for read, write, and delete operations.
+Each proxy carries its own MCP annotations so clients can apply
+appropriate permission policies (e.g., auto-approve reads, gate writes).
+
+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
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Annotated, Any, Literal
+
+from fastmcp.exceptions import ToolError
+from fastmcp.server.context import Context
+from fastmcp.server.transforms import Transform
+from fastmcp.server.transforms.search.bm25 import BM25SearchTransform
+from fastmcp.tools import Tool
+from mcp.types import ToolAnnotations
+
+from ..errors import ErrorCode, create_error_response
+
+if TYPE_CHECKING:
+    from fastmcp.server.transforms import GetToolNext
+    from fastmcp.utilities.versions import VersionSpec
+
+logger = logging.getLogger(__name__)
+
+# Default HA tools to pin (always visible, bypass search transform)
+DEFAULT_PINNED_TOOLS: tuple[str, ...] = (
+    "ha_restart",
+    "ha_reload_core",
+    "ha_backup_create",
+    "ha_backup_restore",
+    "ha_get_overview",
+    "ha_report_issue",
+    "ha_search_entities",
+    "ha_config_get_automation",
+    "ha_config_set_automation",
+)
+
+# Tool name patterns that indicate delete/remove operations
+_DELETE_PATTERNS = ("_remove_", "_delete_")
+
+
+class SearchKeywordsTransform(Transform):
+    """Adjust BM25 search keywords in tool descriptions.
+
+    Supports two modes per tool:
+    - **keywords** (append): Extra keywords appended after the original
+      description so BM25 ranks the tool higher for common queries.
+    - **overrides** (replace): Completely replaces the description with
+      a narrower one so BM25 ranks the tool *lower* for broad queries.
+
+    The original description is preserved unless an override is applied.
+    Only active when added to the transform pipeline (i.e., behind
+    the ``enable_tool_search`` toggle).
+    """
+
+    def __init__(
+        self,
+        keywords: dict[str, str] | None = None,
+        overrides: dict[str, str] | None = None,
+    ) -> None:
+        """Initialize with optional keyword boosts and description overrides."""
+        self._keywords = keywords or {}
+        self._overrides = overrides or {}
+
+    def _enrich(self, tool: Tool) -> Tool:
+        # Overrides take priority — replace the entire description
+        override = self._overrides.get(tool.name)
+        if override is not None:
+            return tool.model_copy(update={"description": override})
+        # Otherwise append keywords if present
+        keywords = self._keywords.get(tool.name)
+        if not keywords:
+            return tool
+        enriched = f"{tool.description}\n\n{keywords}" if tool.description else keywords
+        return tool.model_copy(update={"description": enriched})
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [self._enrich(t) for t in tools]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        tool = await call_next(name, version=version)
+        return self._enrich(tool) if tool else None
+
+# Proxy description suffix (shared across all proxies)
+_PROXY_PARAMS_SUFFIX = (
+    "Params: name (str) = tool name, arguments (dict) = tool parameters. "
+    "These are separate top-level params, not nested.\n"
+    "IMPORTANT: Call this tool SEQUENTIALLY, not in parallel with other proxy calls."
+)
+
+
+def _build_proxy_descriptions(search_tool_name: str) -> dict[str, str]:
+    """Build proxy descriptions that reference the configured search tool name."""
+    return {
+        "read": (
+            f"Execute a read-only tool discovered via {search_tool_name}. "
+            f"Safe — does not modify any data or state.\n"
+            f"{_PROXY_PARAMS_SUFFIX}"
+        ),
+        "write": (
+            f"Execute a write tool discovered via {search_tool_name}. "
+            f"Creates or updates data. Use for any tool that modifies "
+            f"state but does not delete/remove resources.\n"
+            f"{_PROXY_PARAMS_SUFFIX}"
+        ),
+        "delete": (
+            f"Execute a delete/remove tool discovered via {search_tool_name}. "
+            f"Permanently removes data. Use for tools that delete or "
+            f"remove resources (areas, automations, devices, etc.).\n"
+            f"{_PROXY_PARAMS_SUFFIX}"
+        ),
+    }
+
+
+def _categorize_tool(tool: Tool) -> str:
+    """Categorize a tool as read, write, or delete based on annotations and name."""
+    annotations = tool.annotations
+    if annotations and annotations.readOnlyHint:
+        return "read"
+    # A tool is 'delete' only if it's destructive AND its name suggests deletion
+    if annotations and annotations.destructiveHint and any(
+        pattern in tool.name for pattern in _DELETE_PATTERNS
+    ):
+        return "delete"
+    return "write"
+
+
+class CategorizedSearchTransform(BM25SearchTransform):
+    """BM25 search with categorized call proxies.
+
+    Replaces the single ``call_tool`` proxy from BaseSearchTransform with
+    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.
+    """
+
+    def __init__(
+        self,
+        *,
+        max_results: int = 5,
+        always_visible: list[str] | None = None,
+        search_tool_name: str = "ha_search_tools",
+        search_tool_description: str | None = None,
+        call_read_name: str = "ha_call_read_tool",
+        call_write_name: str = "ha_call_write_tool",
+        call_delete_name: str = "ha_call_delete_tool",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            max_results=max_results,
+            always_visible=always_visible,
+            search_tool_name=search_tool_name,
+            # Placeholder call_tool_name — we override transform_tools with
+            # categorized proxies so the base class's single call proxy is
+            # never surfaced to clients.
+            call_tool_name="_base_call_proxy",
+            **kwargs,
+        )
+        self._call_read_name = call_read_name
+        self._call_write_name = call_write_name
+        self._call_delete_name = call_delete_name
+        self._search_tool_description = search_tool_description
+        self._proxy_descs = _build_proxy_descriptions(search_tool_name)
+
+        # Category caches rebuilt when the catalog hash changes,
+        # matching BM25SearchTransform's staleness detection pattern.
+        self._read_tools: set[str] = set()
+        self._write_tools: set[str] = set()
+        self._delete_tools: set[str] = set()
+        self._last_catalog_hash: str = ""
+        self._cache_lock = asyncio.Lock()
+
+    @staticmethod
+    def _catalog_hash(tools: Sequence[Tool]) -> str:
+        """Hash tool names + categories for staleness detection."""
+        key = "|".join(
+            sorted(f"{t.name}:{_categorize_tool(t)}" for t in tools)
+        )
+        return hashlib.sha256(key.encode()).hexdigest()
+
+    async def _rebuild_category_cache(self, ctx: Any) -> None:
+        """Rebuild the read/write/delete category sets if catalog changed."""
+        catalog = await self.get_tool_catalog(ctx)
+        current_hash = self._catalog_hash(catalog)
+        if current_hash == self._last_catalog_hash:
+            return
+        async with self._cache_lock:
+            # Double-check after acquiring lock
+            if current_hash == self._last_catalog_hash:
+                return
+            read: set[str] = set()
+            write: set[str] = set()
+            delete: set[str] = set()
+            for tool in catalog:
+                cat = _categorize_tool(tool)
+                if cat == "read":
+                    read.add(tool.name)
+                elif cat == "delete":
+                    delete.add(tool.name)
+                else:
+                    write.add(tool.name)
+            self._read_tools = read
+            self._write_tools = write
+            self._delete_tools = delete
+            self._last_catalog_hash = current_hash
+
+    async def _render_results(self, tools: Sequence[Tool]) -> list[dict[str, Any]]:
+        """Serialize search results with ``execute_via`` hints."""
+        proxy_map = {
+            "read": self._call_read_name,
+            "write": self._call_write_name,
+            "delete": self._call_delete_name,
+        }
+        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={{...}})'
+            )
+            results.append(data)
+        return results
+
+    def _make_categorized_proxy(
+        self,
+        proxy_name: str,
+        category: Literal["read", "write", "delete"],
+        annotations: ToolAnnotations,
+        description: str,
+    ) -> Tool:
+        """Create a call proxy that validates tool category before execution."""
+        transform = self
+
+        async def categorized_call(
+            name: Annotated[str, "The name of the tool to call"],
+            arguments: Annotated[
+                dict[str, Any] | None, "Arguments to pass to the tool"
+            ] = None,
+            ctx: Context = None,  # type: ignore[assignment]
+        ) -> Any:
+            # Rebuild category cache if catalog has changed
+            await transform._rebuild_category_cache(ctx)
+
+            # 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",
+            #   arguments={"name": "actual_tool", "arguments": {...}})
+            all_known = (
+                transform._read_tools | transform._write_tools | transform._delete_tools
+            )
+            if (
+                arguments
+                and isinstance(arguments.get("name"), str)
+                and "arguments" in arguments
+                and name in (
+                    transform._call_read_name,
+                    transform._call_write_name,
+                    transform._call_delete_name,
+                )
+                and arguments["name"] in all_known
+            ):
+                logger.warning(
+                    "Detected double-wrapped proxy call for '%s' via %s — unwrapping",
+                    arguments["name"],
+                    name,
+                )
+                name = arguments["name"]
+                arguments = arguments.get("arguments") or {}
+
+            if name not in allowed:
+                # Provide a helpful error with the correct proxy name
+                actual_category = "unknown"
+                correct_proxy = ""
+                if name in transform._read_tools:
+                    actual_category = "read"
+                    correct_proxy = transform._call_read_name
+                elif name in transform._write_tools:
+                    actual_category = "write"
+                    correct_proxy = transform._call_write_name
+                elif name in transform._delete_tools:
+                    actual_category = "delete"
+                    correct_proxy = transform._call_delete_name
+                else:
+                    raise ToolError(json.dumps(create_error_response(
+                        code=ErrorCode.RESOURCE_NOT_FOUND,
+                        message=f"Tool '{name}' not found. Use ha_search_tools to discover available tools.",
+                        context={"tool_name": name},
+                    )))
+                raise ToolError(json.dumps(create_error_response(
+                    code=ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    message=f"Tool '{name}' is a {actual_category} tool. Use {correct_proxy} instead of {proxy_name}.",
+                    suggestions=[f"Use '{correct_proxy}' for {actual_category} operations."],
+                    context={"tool_name": name, "proxy_used": proxy_name, "correct_proxy": correct_proxy},
+                )))
+
+            return await ctx.fastmcp.call_tool(name, arguments)
+
+        return Tool.from_function(
+            fn=categorized_call,
+            name=proxy_name,
+            description=description,
+            annotations=annotations,
+        )
+
+    async def transform_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Replace tool listing with search + categorized call proxies."""
+        pinned = [t for t in tools if t.name in (self._always_visible or [])]
+
+        search_tool = self._make_search_tool()
+        # Always set readOnlyHint and override description if provided
+        search_tool = search_tool.model_copy(update={
+            "description": self._search_tool_description or search_tool.description,
+            "annotations": ToolAnnotations(readOnlyHint=True),
+        })
+
+        call_read = self._make_categorized_proxy(
+            proxy_name=self._call_read_name,
+            category="read",
+            annotations=ToolAnnotations(readOnlyHint=True),
+            description=self._proxy_descs["read"],
+        )
+
+        call_write = self._make_categorized_proxy(
+            proxy_name=self._call_write_name,
+            category="write",
+            annotations=ToolAnnotations(destructiveHint=True),
+            description=self._proxy_descs["write"],
+        )
+
+        call_delete = self._make_categorized_proxy(
+            proxy_name=self._call_delete_name,
+            category="delete",
+            annotations=ToolAnnotations(destructiveHint=True),
+            description=self._proxy_descs["delete"],
+        )
+
+        return [*pinned, search_tool, call_read, call_write, call_delete]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Resolve tool by name, including categorized proxy tools.
+
+        The parent only handles _search_tool_name and _call_tool_name (unused).
+        We must also intercept our three categorized proxy names so they can
+        be found when the LLM calls them.
+        """
+        if name == self._call_read_name:
+            return self._make_categorized_proxy(
+                self._call_read_name, "read",
+                ToolAnnotations(readOnlyHint=True),
+                self._proxy_descs["read"],
+            )
+        if name == self._call_write_name:
+            return self._make_categorized_proxy(
+                self._call_write_name, "write",
+                ToolAnnotations(destructiveHint=True),
+                self._proxy_descs["write"],
+            )
+        if name == self._call_delete_name:
+            return self._make_categorized_proxy(
+                self._call_delete_name, "delete",
+                ToolAnnotations(destructiveHint=True),
+                self._proxy_descs["delete"],
+            )
+        return await super().get_tool(name, call_next, version=version)

{ha_mcp_dev-7.1.0.dev289 → ha_mcp_dev-7.1.0.dev290/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.1.0.dev289
+Version: 7.1.0.dev290
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.1.0.dev289 → ha_mcp_dev-7.1.0.dev290}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -76,6 +76,8 @@ src/ha_mcp/tools/tools_utility.py
 src/ha_mcp/tools/tools_voice_assistant.py
 src/ha_mcp/tools/tools_zones.py
 src/ha_mcp/tools/util_helpers.py
+src/ha_mcp/transforms/__init__.py
+src/ha_mcp/transforms/categorized_search.py
 src/ha_mcp/utils/__init__.py
 src/ha_mcp/utils/domain_handlers.py
 src/ha_mcp/utils/fuzzy_search.py