ha-mcp-dev 7.6.0.dev615__tar.gz → 7.6.0.dev616__tar.gz

{ha_mcp_dev-7.6.0.dev615/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.6.0.dev616}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.6.0.dev615
+Version: 7.6.0.dev616
 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.6.0.dev615 → ha_mcp_dev-7.6.0.dev616}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.6.0.dev615"
+version = "7.6.0.dev616"
 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.6.0.dev615 → ha_mcp_dev-7.6.0.dev616}/src/ha_mcp/tools/smart_search.py

@@ -6,6 +6,7 @@ import asyncio
 import logging
 import os
 import random
+import re
 import time
 from typing import Any
 
@@ -23,6 +24,8 @@ from ..utils.fuzzy_search import (
 )
 from .helpers import exception_to_structured_error, safe_info, safe_progress
 from .tools_config_dashboards import fetch_dashboards_list
+from .tools_config_entry_flow import FLOW_HELPER_TYPES
+from .tools_integrations import fetch_entry_options
 
 logger = logging.getLogger(__name__)
 
@@ -1755,6 +1758,22 @@ class SmartSearchTools:
                     elif isinstance(result, Exception):
                         logger.debug(f"Helper list fetch failed: {result}")
 
+                # Flow-based helpers (template, group, utility_meter,
+                # derivative, ...) are config entries, not storage records,
+                # and have no `<type>/list` WebSocket endpoint. Pull them via
+                # the standard /config/config_entries/entry REST surface and
+                # probe each entry's options flow so the helper's current
+                # config (template body, group members, source entity, ...)
+                # is searchable alongside the input_* helpers above.
+                results["helpers"].extend(
+                    await self._search_flow_helpers(
+                        query_lower,
+                        exact_match,
+                        semaphore,
+                        include_config=include_config,
+                    )
+                )
+
                 phase_done += 1
                 await safe_progress(
                     ctx,
@@ -1969,6 +1988,138 @@ class SmartSearchTools:
                 },
             )
 
+    async def _search_flow_helpers(
+        self,
+        query_lower: str,
+        exact_match: bool,
+        semaphore: asyncio.Semaphore,
+        *,
+        include_config: bool,
+    ) -> list[dict[str, Any]]:
+        """Search UI-created flow-based helpers (template, group, …).
+
+        Flow-helpers live as config entries (not storage records) and have
+        no ``<type>/list`` endpoint. Lists them via the standard config
+        entries REST endpoint, then probes each entry's options flow so the
+        helper's current config — template body, group members, source
+        entity, etc. — is searchable.
+
+        Cost: 1 REST call + one options-flow probe per flow-helper config
+        entry, parallelised under ``semaphore``. The probe is skipped when
+        the title alone already scores the maximum (a deeper config match can
+        only raise the total, never lower it); any title that leaves headroom
+        is still probed for accurate scoring and ``match_in_config``.
+        """
+        try:
+            response = await self.client._request("GET", "/config/config_entries/entry")
+        except Exception as exc:
+            logger.debug(f"flow-helper search: list_entries failed: {exc}")
+            return []
+
+        if not isinstance(response, list):
+            return []
+
+        flow_entries = [
+            e
+            for e in response
+            if isinstance(e, dict)
+            and e.get("domain") in FLOW_HELPER_TYPES
+            and e.get("supports_options")
+        ]
+        if not flow_entries:
+            return []
+
+        async def score_entry(entry: dict[str, Any]) -> dict[str, Any] | None:
+            entry_id = entry.get("entry_id")
+            if not isinstance(entry_id, str):
+                return None
+            domain = entry.get("domain", "")
+            title = entry.get("title") or entry_id
+
+            # Score the name against a title-derived slug, never the opaque
+            # config-entry ULID: a random ULID substring would otherwise
+            # produce false-positive name matches (e.g. a 3-char query that
+            # happens to occur inside the base32 id). The slug mirrors the
+            # storage-helper path, which scores a name-derived id rather than
+            # an opaque key. entry_id is still returned to the caller; it just
+            # isn't a search target.
+            title_slug = re.sub(r"[^a-z0-9]+", "_", title.lower()).strip("_")
+            title_pseudo_eid = f"{domain}.{title_slug}" if title_slug else domain
+            name_score = self.fuzzy_searcher._calculate_entity_score(
+                title_pseudo_eid, title, domain, query_lower
+            )
+
+            options: dict[str, Any] = {}
+            # Only a perfect title match (score 100) makes the deeper options
+            # probe redundant — the probe can only raise the total, never lower
+            # it, so anything below 100 is worth probing (in both exact and
+            # fuzzy modes) for accurate scoring and ``match_in_config``.
+            need_probe = include_config or (
+                self._score_deep_match(
+                    title_pseudo_eid,
+                    title,
+                    name_score,
+                    0,
+                    query_lower,
+                    exact_match,
+                )[0]
+                < 100
+            )
+            if need_probe:
+                async with semaphore:
+                    options = await fetch_entry_options(
+                        self.client, entry_id, quiet=True
+                    )
+
+            # Search the title, domain, and probed options — but not the opaque
+            # entry_id (it would match random ULID substrings; it is returned
+            # in the result for the caller regardless).
+            haystack: dict[str, Any] = {
+                "title": title,
+                "domain": domain,
+                "options": options,
+            }
+            config_score = self._search_in_dict(haystack, query_lower, exact_match)
+            total_score, threshold, match_in_name = self._score_deep_match(
+                title_pseudo_eid,
+                title,
+                name_score,
+                config_score,
+                query_lower,
+                exact_match,
+            )
+            if total_score < threshold:
+                return None
+
+            result: dict[str, Any] = {
+                "entry_id": entry_id,
+                "helper_type": domain,
+                "name": title,
+                "score": total_score,
+                "match_in_name": match_in_name,
+                "match_in_config": config_score >= threshold,
+            }
+            if include_config:
+                result["config"] = options
+            return result
+
+        scored = await asyncio.gather(
+            *(score_entry(e) for e in flow_entries),
+            return_exceptions=True,
+        )
+        out: list[dict[str, Any]] = []
+        for item in scored:
+            if isinstance(item, dict):
+                out.append(item)
+            elif isinstance(item, Exception):
+                # The probe swallows its own transient/API errors, so anything
+                # reaching here is a scoring/extraction bug (e.g. a shape
+                # assumption breaking on a future HA version). Log at warning so
+                # it's discoverable — one bad entry must not sink the whole
+                # multi-source deep_search, so we drop it and keep going.
+                logger.warning(f"flow-helper scoring failed: {item!r}")
+        return out
+
     def _score_deep_match(
         self,
         entity_id: str,

{ha_mcp_dev-7.6.0.dev615 → ha_mcp_dev-7.6.0.dev616}/src/ha_mcp/tools/tools_entities.py

@@ -1189,6 +1189,12 @@ def register_entity_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
           via the ha_set_entity(expose_to=...) parameter, not the options dict.
         - platform: Integration platform (e.g., "hue", "zwave_js")
         - device_id: Associated device ID (null if standalone)
+        - config_entry_id: Parent config entry's ID (null for YAML-only
+          entities). When non-null — e.g. for UI-created template/group/
+          utility_meter/derivative/... helpers — pass it to
+          ``ha_get_integration(entry_id=..., include_options=True)`` to read the
+          helper's current config (template body, group members, etc.) without
+          scanning a domain list.
         - unique_id: Integration's unique identifier
         """
         try:
@@ -1254,6 +1260,7 @@ def register_entity_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     "options": entry.get("options", {}),
                     "platform": entry.get("platform"),
                     "device_id": entry.get("device_id"),
+                    "config_entry_id": entry.get("config_entry_id"),
                     "unique_id": entry.get("unique_id"),
                 }
 

{ha_mcp_dev-7.6.0.dev615 → ha_mcp_dev-7.6.0.dev616}/src/ha_mcp/tools/tools_integrations.py

@@ -101,6 +101,98 @@ assert set(get_args(HelperTypeLiteral)) == (
 )
 
 
+def options_from_form_flow(flow: dict[str, Any]) -> dict[str, Any]:
+    """Extract ``{field_name: current_value}`` from a form-type OptionsFlow.
+
+    Reads each ``data_schema`` entry's ``default`` key, falling back to
+    ``value`` (constant-type fields ship ``value`` instead of ``default``)
+    and then ``description.suggested_value`` (UI-created template, group,
+    utility_meter, and other flow-based helpers stash the current value
+    there — voluptuous renders ``suggested_value=...`` into the
+    ``description`` sub-object, not as a top-level field key). Fields with
+    a missing or ``None`` value are skipped.
+    """
+    out: dict[str, Any] = {}
+    # Defensive: HA should always return a list of dict fields, but guard
+    # against malformed shapes so a bad response degrades to {} instead of
+    # raising AttributeError (e.g. a string data_schema would iterate chars).
+    data_schema = flow.get("data_schema")
+    if not isinstance(data_schema, list):
+        return out
+    for field in data_schema:
+        if not isinstance(field, dict):
+            continue
+        name = field.get("name")
+        if name is None:
+            continue
+        value = field.get("default", field.get("value"))
+        if value is None:
+            description = field.get("description")
+            if isinstance(description, dict):
+                value = description.get("suggested_value")
+        if value is not None:
+            out[name] = value
+    return out
+
+
+async def fetch_entry_options(
+    client: Any, entry_id: str, *, quiet: bool = False
+) -> dict[str, Any]:
+    """Read the current ``options`` for a config entry via its OptionsFlow.
+
+    Home Assistant does not expose ``ConfigEntry.options`` through any
+    read-only REST or WebSocket endpoint — ``/api/config/config_entries/entry``
+    deliberately omits the field. The closest approximation that the HA UI
+    itself uses is the ``default`` values populated into the OptionsFlow's
+    first-step ``data_schema``: integrations build that schema from the
+    existing options dict, so the defaults match the persisted state.
+
+    Starts the flow, harvests ``{name: default}`` from the first step, and
+    aborts the flow in ``finally`` so it doesn't sit half-open.
+
+    Returns ``{}`` on any failure (unsupported entry, non-form first step
+    such as a menu, init/abort errors) so callers can treat the return as
+    the canonical "options" field without further checks.
+
+    Probe failures log at ``warning`` (so breakage of a deliberate
+    single-entry probe is discoverable) unless ``quiet=True``, which demotes
+    them to ``debug`` for bulk fan-out callers (e.g. ``smart_search`` probes
+    one entry per flow-helper on every ``ha_deep_search``; a per-entry
+    warning there would spam the log on routine searches).
+
+    Exposed at module level (not as a method) so non-class callers such as
+    ``smart_search._search_flow_helpers`` can probe flow-helper config
+    without instantiating ``IntegrationTools``.
+    """
+    log_probe_failure = logger.debug if quiet else logger.warning
+    flow_id: str | None = None
+    try:
+        flow = await client.start_options_flow(entry_id)
+        flow_id = flow.get("flow_id")
+        flow_type = flow.get("type")
+        if flow_type != "form":
+            log_probe_failure(
+                f"OptionsFlow for {entry_id} returned type={flow_type!r}, "
+                f"not a form — cannot extract option defaults"
+            )
+            return {}
+        return options_from_form_flow(flow)
+    except Exception as exc:
+        log_probe_failure(
+            f"Failed to fetch options for {entry_id}: {type(exc).__name__}: {exc}"
+        )
+        return {}
+    finally:
+        if flow_id:
+            try:
+                await client.abort_options_flow(flow_id)
+            except Exception as abort_err:
+                log_probe_failure(
+                    f"Failed to abort options flow {flow_id}: "
+                    f"{type(abort_err).__name__}: {abort_err}"
+                )
+
+
 async def _get_entry_id_for_flow_helper(
     client: Any,
     helper_type: str,
@@ -213,7 +305,13 @@ class IntegrationTools:
             Field(
                 description="Include the options object for each entry. "
                 "Automatically enabled when domain filter is set. "
-                "Useful for auditing template definitions and helper configurations.",
+                "For UI-created flow-based helpers (template, group, "
+                "utility_meter, derivative, ...), the current config — "
+                "template body, group members, source entity, etc. — is "
+                "surfaced here by probing the options flow. Prefer this over "
+                "include_schema when you only need to read the current values; "
+                "use include_schema when you also need the field types or "
+                "selector metadata.",
                 default=False,
             ),
         ] = False,
@@ -614,7 +712,7 @@ class IntegrationTools:
 
             # Surface `options` on every per-entry response (HA's REST endpoint
             # omits the field). For entries with supports_options=True we probe
-            # via OptionsFlow — see `_fetch_entry_options`. When include_schema
+            # via OptionsFlow — see `fetch_entry_options`. When include_schema
             # is also requested, `_fetch_options_schema` below populates options
             # from the same flow init so we don't pay for two round-trips.
             if isinstance(result, dict):
@@ -758,68 +856,17 @@ class IntegrationTools:
 
     @staticmethod
     def _options_from_form_flow(flow: dict[str, Any]) -> dict[str, Any]:
-        """Extract ``{field_name: current_value}`` from a form-type OptionsFlow.
-
-        Reads each ``data_schema`` entry's ``default`` key, falling back to
-        ``value`` only when the ``default`` key is absent (constant-type
-        fields ship ``value`` instead of ``default``). Fields with a missing
-        or ``None`` value are skipped.
-        """
-        out: dict[str, Any] = {}
-        for field in flow.get("data_schema") or []:
-            name = field.get("name")
-            if name is None:
-                continue
-            value = field.get("default", field.get("value"))
-            if value is not None:
-                out[name] = value
-        return out
+        """Class-method alias for :func:`options_from_form_flow`."""
+        return options_from_form_flow(flow)
 
     async def _fetch_entry_options(self, entry_id: str) -> dict[str, Any]:
-        """Read the current ``options`` for a config entry via its OptionsFlow.
-
-        Home Assistant does not expose ``ConfigEntry.options`` through any
-        read-only REST or WebSocket endpoint — ``/api/config/config_entries/entry``
-        deliberately omits the field. The closest approximation that the HA UI
-        itself uses is the ``default`` values populated into the OptionsFlow's
-        first-step ``data_schema``: integrations build that schema from the
-        existing options dict, so the defaults match the persisted state.
-
-        Starts the flow, harvests ``{name: default}`` from the first step,
-        and aborts the flow in ``finally`` so it doesn't sit half-open.
-
-        Returns ``{}`` on any failure (unsupported entry, non-form first step
-        such as a menu, init/abort errors) so callers can treat the return as
-        the canonical "options" field without further checks. Unexpected
-        exception types are logged at ``warning`` so probe breakage is
-        discoverable.
+        """Instance wrapper around :func:`fetch_entry_options`.
+
+        Kept so existing call sites (and the ``include_schema`` path) read
+        naturally as ``self._fetch_entry_options(...)``; the probe logic and
+        full rationale live on the module-level function.
         """
-        flow_id: str | None = None
-        try:
-            flow = await self._client.start_options_flow(entry_id)
-            flow_id = flow.get("flow_id")
-            flow_type = flow.get("type")
-            if flow_type != "form":
-                logger.debug(
-                    f"OptionsFlow for {entry_id} returned type={flow_type!r}, "
-                    f"not a form — cannot extract option defaults"
-                )
-                return {}
-            return self._options_from_form_flow(flow)
-        except Exception as exc:
-            logger.warning(
-                f"Failed to fetch options for {entry_id}: {type(exc).__name__}: {exc}"
-            )
-            return {}
-        finally:
-            if flow_id:
-                try:
-                    await self._client.abort_options_flow(flow_id)
-                except Exception as abort_err:
-                    logger.warning(
-                        f"Failed to abort options flow {flow_id}: "
-                        f"{type(abort_err).__name__}: {abort_err}"
-                    )
+        return await fetch_entry_options(self._client, entry_id)
 
     async def _fetch_options_schema(self, entry_id: str, resp: dict[str, Any]) -> None:
         """Start an options flow to read the schema, then abort it.
@@ -899,7 +946,7 @@ class IntegrationTools:
 
         # `_format_entry` is sync and cannot probe the OptionsFlow; options
         # are filled in by a second async pass below for entries that
-        # advertise supports_options=True. See `_fetch_entry_options`.
+        # advertise supports_options=True. See `fetch_entry_options`.
         formatted_entries = [
             self._format_entry(entry, include_opts, logger_levels) for entry in entries
         ]

{ha_mcp_dev-7.6.0.dev615 → ha_mcp_dev-7.6.0.dev616}/src/ha_mcp/tools/tools_search.py

@@ -1473,6 +1473,13 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         **NOTE:** Dashboards and badges are NOT searched by default. Add 'dashboard' to
         search_types to include them.
 
+        The 'helper' search covers both input_* helpers (input_boolean, input_number, ...)
+        and UI-created flow-based helpers (template, group, utility_meter, derivative, ...).
+        For flow-helpers, results carry the parent config entry id under ``entry_id``.
+        When ``include_config=False`` (the default), pair with
+        ``ha_get_integration(entry_id=..., include_options=True)`` to retrieve the full
+        config; set ``include_config=True`` to get it inline in one call.
+
         Args:
             query: Search query (exact substring by default, or fuzzy with exact_match=False)
             search_types: Types to search (default: ["automation", "script", "scene", "helper"])

{ha_mcp_dev-7.6.0.dev615 → ha_mcp_dev-7.6.0.dev616/src/ha_mcp_dev.egg-info}/PKG-INFO

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