ha-mcp-dev 7.5.0.dev520__tar.gz → 7.5.0.dev521__tar.gz

{ha_mcp_dev-7.5.0.dev520/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev521}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.5.0.dev520
+Version: 7.5.0.dev521
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -264,6 +264,43 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ---
 
+## 🔍 Tool Discovery for AI Agents
+
+By default, the full tool catalog (~86 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus,) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
+
+For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing 86 tools eats ~46K tokens of idle context. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+
+### Enable search-based discovery
+
+Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA add-on). The full catalog is replaced in the tool list with four entry points plus a small set of always-visible "pinned" tools (ha_search_entities, ha_get_overview, ha_restart, etc.). All tools remain callable directly by name once discovered:
+
+| 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_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. |
+
+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.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (~46K → ~5K idle tokens). |
+| `TOOL_SEARCH_MAX_RESULTS` | `5` | Max results returned by `ha_search_tools` (range 2–10). |
+| `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
+
+- **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
+- MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 86.
+- **Cost-sensitive deployments** — fewer idle tokens per turn.
+
+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.
+
+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.
+
+---
+
 ## 🧪 Dev Channel
 
 Want early access to new features and fixes? Dev releases (`.devN`) are published on every push to master.

{ha_mcp_dev-7.5.0.dev520 → ha_mcp_dev-7.5.0.dev521}/README.md

@@ -234,6 +234,43 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ---
 
+## 🔍 Tool Discovery for AI Agents
+
+By default, the full tool catalog (~86 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus,) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
+
+For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing 86 tools eats ~46K tokens of idle context. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+
+### Enable search-based discovery
+
+Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA add-on). The full catalog is replaced in the tool list with four entry points plus a small set of always-visible "pinned" tools (ha_search_entities, ha_get_overview, ha_restart, etc.). All tools remain callable directly by name once discovered:
+
+| 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_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. |
+
+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.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (~46K → ~5K idle tokens). |
+| `TOOL_SEARCH_MAX_RESULTS` | `5` | Max results returned by `ha_search_tools` (range 2–10). |
+| `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
+
+- **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
+- MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 86.
+- **Cost-sensitive deployments** — fewer idle tokens per turn.
+
+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.
+
+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.
+
+---
+
 ## 🧪 Dev Channel
 
 Want early access to new features and fixes? Dev releases (`.devN`) are published on every push to master.

{ha_mcp_dev-7.5.0.dev520 → ha_mcp_dev-7.5.0.dev521}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev520"
+version = "7.5.0.dev521"
 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.5.0.dev520 → ha_mcp_dev-7.5.0.dev521}/src/ha_mcp/tools/tools_search.py

@@ -22,7 +22,9 @@ from .util_helpers import (
     build_pagination_metadata,
     coerce_bool_param,
     coerce_int_param,
+    filter_active_repairs,
     parse_string_list_param,
+    project_repair_fields,
     public_fields,
 )
 
@@ -852,6 +854,16 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 description="Include active persistent notifications (default: True). Set False to skip.",
             ),
         ] = True,
+        include_dismissed_repairs: Annotated[
+            bool | str | None,
+            Field(
+                default=False,
+                description=(
+                    "Include user-dismissed/ignored repairs (default: False). "
+                    "Matches the HA Repairs UI which hides dismissed items by default."
+                ),
+            ),
+        ] = False,
     ) -> dict[str, Any]:
         """Get AI-friendly system overview with intelligent categorization.
 
@@ -873,6 +885,13 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         include_notifications_bool = coerce_bool_param(
             include_notifications, "include_notifications", default=True
         )
+        include_dismissed_repairs_bool = bool(
+            coerce_bool_param(
+                include_dismissed_repairs,
+                "include_dismissed_repairs",
+                default=False,
+            )
+        )
 
         # Parse domains filter
         parsed_domains = parse_string_list_param(domains, "domains", allow_csv=True)
@@ -951,25 +970,39 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             except Exception as e:
                 logger.warning(f"Failed to fetch notifications for overview: {e}")
 
-        # Include active repair issues
+        # Active repairs only by default — matches the HA Repairs UI so agents
+        # don't chase problems the user already dismissed.
         result["repair_count"] = 0
         try:
             repairs_result = await client.send_websocket_message(
                 {"type": "repairs/list_issues"}
             )
             if repairs_result.get("success"):
-                issues = repairs_result.get("result", {}).get("issues", [])
-                result["repair_count"] = len(issues)
-                if issues:
+                all_issues = repairs_result.get("result", {}).get("issues", [])
+                visible_issues = filter_active_repairs(
+                    all_issues,
+                    include_dismissed=include_dismissed_repairs_bool,
+                )
+                result["repair_count"] = len(visible_issues)
+                if not include_dismissed_repairs_bool:
+                    dismissed_count = len(all_issues) - len(visible_issues)
+                    if dismissed_count:
+                        result["dismissed_repair_count"] = dismissed_count
+                if visible_issues:
                     result["repairs"] = [
-                        {
-                            "issue_id": r.get("issue_id"),
-                            "domain": r.get("domain"),
-                            "severity": r.get("severity"),
-                            "translation_key": r.get("translation_key"),
-                        }
-                        for r in issues
+                        project_repair_fields(r) for r in visible_issues
                     ]
+            else:
+                err = repairs_result.get("error") or {}
+                err_msg = (
+                    err.get("message")
+                    if isinstance(err, dict)
+                    else str(err)
+                ) or "unknown error"
+                logger.warning(
+                    "repairs/list_issues returned success=false: %s", err_msg
+                )
+                result["repairs_error"] = f"Could not fetch repairs: {err_msg}"
         except Exception as e:
             logger.warning("Failed to fetch repairs for overview: %s", e)
             result["repairs_error"] = f"Could not fetch repairs: {e}"

{ha_mcp_dev-7.5.0.dev520 → ha_mcp_dev-7.5.0.dev521}/src/ha_mcp/tools/tools_system.py

@@ -21,7 +21,7 @@ from .helpers import (
     raise_tool_error,
     register_tool_methods,
 )
-from .util_helpers import coerce_bool_param
+from .util_helpers import coerce_bool_param, filter_active_repairs
 
 logger = logging.getLogger(__name__)
 
@@ -339,6 +339,7 @@ class SystemTools:
     async def ha_get_system_health(
         self,
         include: str | None = None,
+        include_dismissed_repairs: bool | str | None = False,
     ) -> dict[str, Any]:
         """
         Get Home Assistant system health, including Zigbee (ZHA) and Z-Wave JS network diagnostics.
@@ -348,13 +349,21 @@ class SystemTools:
 
         **Parameters:**
         - include: Optional comma-separated list of additional data to include.
-          - "repairs": Repair items from Settings > System > Repairs
+          - "repairs": Repair items from Settings > System > Repairs (active only by default; pass `include_dismissed_repairs=True` for all)
           - "zha_network": ZHA Zigbee devices with radio signal summary (name, LQI, RSSI)
           - "zha_network_full": ZHA Zigbee devices with all device details (can be large on 100+ device networks; prefer "zha_network" for summary)
           - "zwave_network": Z-Wave JS network status and node summary (status, security, routing)
           - Example: include="repairs,zha_network,zwave_network"
+        - include_dismissed_repairs: Include user-dismissed/ignored repairs (default: False). Only meaningful when "repairs" is in `include`.
         """
         includes = self._parse_includes(include)
+        include_dismissed_repairs_bool = bool(
+            coerce_bool_param(
+                include_dismissed_repairs,
+                "include_dismissed_repairs",
+                default=False,
+            )
+        )
 
         ws_client = None
 
@@ -369,7 +378,10 @@ class SystemTools:
 
             # Fetch optional sections
             if "repairs" in includes:
-                result["repairs"] = await self._fetch_repairs(ws_client)
+                result["repairs"] = await self._fetch_repairs(
+                    ws_client,
+                    include_dismissed=include_dismissed_repairs_bool,
+                )
 
             zha_full = "zha_network_full" in includes
             zha_summary = "zha_network" in includes
@@ -454,17 +466,42 @@ class SystemTools:
 
 
     @staticmethod
-    async def _fetch_repairs(ws_client: Any) -> dict[str, Any]:
-        """Fetch repair issues from Home Assistant."""
+    async def _fetch_repairs(
+        ws_client: Any, *, include_dismissed: bool = False
+    ) -> dict[str, Any]:
+        """Fetch repair issues from Home Assistant.
+
+        Filters out user-dismissed ("ignored") repairs by default to match the
+        HA Repairs UI. Pass ``include_dismissed=True`` to return all issues
+        and report the dismissed count alongside the active count.
+        """
         repairs: dict[str, Any] = {"issues": [], "count": 0}
         try:
             repairs_result = await ws_client.send_command("repairs/list_issues")
             if repairs_result.get("success"):
-                repairs_list = repairs_result.get("result", {}).get("issues", [])
+                all_issues = repairs_result.get("result", {}).get("issues", [])
+                visible_issues = filter_active_repairs(
+                    all_issues, include_dismissed=include_dismissed
+                )
                 repairs = {
-                    "issues": repairs_list,
-                    "count": len(repairs_list),
+                    "issues": visible_issues,
+                    "count": len(visible_issues),
                 }
+                if not include_dismissed:
+                    dismissed_count = len(all_issues) - len(visible_issues)
+                    if dismissed_count:
+                        repairs["dismissed_count"] = dismissed_count
+            else:
+                err = repairs_result.get("error") or {}
+                err_msg = (
+                    err.get("message")
+                    if isinstance(err, dict)
+                    else str(err)
+                ) or "unknown error"
+                logger.warning(
+                    "repairs/list_issues returned success=false: %s", err_msg
+                )
+                repairs["error"] = f"Repairs data not available: {err_msg}"
         except Exception as e:
             logger.warning("Failed to fetch repairs: %s", e)
             repairs["error"] = f"Repairs data not available: {e}"

{ha_mcp_dev-7.5.0.dev520 → ha_mcp_dev-7.5.0.dev521}/src/ha_mcp/tools/util_helpers.py

@@ -315,6 +315,47 @@ def unwrap_service_response(result: dict[str, Any]) -> dict[str, Any]:
     return sr if isinstance(sr, dict) else result
 
 
+# Fields surfaced from each repair issue. Includes `ignored` / `dismissed_version`
+# so callers can distinguish active vs. user-dismissed repairs when both are
+# returned (e.g., `include_dismissed_repairs=True`).
+_REPAIR_PROJECTION_FIELDS = (
+    "issue_id",
+    "domain",
+    "severity",
+    "translation_key",
+    "ignored",
+    "dismissed_version",
+    "is_fixable",
+    "breaks_in_ha_version",
+    "created",
+    "issue_domain",
+)
+
+
+def filter_active_repairs(
+    issues: list[dict[str, Any]], *, include_dismissed: bool = False
+) -> list[dict[str, Any]]:
+    """Drop user-dismissed repairs unless ``include_dismissed`` is set.
+
+    HA's `repairs/list_issues` returns both active and ignored repairs (the
+    Repairs UI hides ignored ones by default). Mirror that UI default so
+    overview / system-health responses don't surface repairs the user has
+    already dismissed.
+    """
+    if include_dismissed:
+        return list(issues)
+    return [r for r in issues if not r.get("ignored")]
+
+
+def project_repair_fields(issue: dict[str, Any]) -> dict[str, Any]:
+    """Project a repair issue dict to the public-facing field subset.
+
+    Drops verbose fields (`translation_placeholders`, `learn_more_url`) to
+    keep overview payloads compact.
+    """
+    return {k: issue[k] for k in _REPAIR_PROJECTION_FIELDS if k in issue}
+
+
 # Python logging numeric-level → canonical level name.
 # Mirrors the values in HA's LOGSEVERITY constant (components/logger/const.py).
 _LOG_LEVEL_NAMES: dict[int, str] = {

{ha_mcp_dev-7.5.0.dev520 → ha_mcp_dev-7.5.0.dev521/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.5.0.dev520
+Version: 7.5.0.dev521
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -264,6 +264,43 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ---
 
+## 🔍 Tool Discovery for AI Agents
+
+By default, the full tool catalog (~86 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus,) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
+
+For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing 86 tools eats ~46K tokens of idle context. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+
+### Enable search-based discovery
+
+Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA add-on). The full catalog is replaced in the tool list with four entry points plus a small set of always-visible "pinned" tools (ha_search_entities, ha_get_overview, ha_restart, etc.). All tools remain callable directly by name once discovered:
+
+| 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_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. |
+
+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.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (~46K → ~5K idle tokens). |
+| `TOOL_SEARCH_MAX_RESULTS` | `5` | Max results returned by `ha_search_tools` (range 2–10). |
+| `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
+
+- **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
+- MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 86.
+- **Cost-sensitive deployments** — fewer idle tokens per turn.
+
+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.
+
+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.
+
+---
+
 ## 🧪 Dev Channel
 
 Want early access to new features and fixes? Dev releases (`.devN`) are published on every push to master.