ha-mcp-dev 7.3.0.dev395__tar.gz → 7.3.0.dev397__tar.gz

{ha_mcp_dev-7.3.0.dev395/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.3.0.dev397}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.3.0.dev395
+Version: 7.3.0.dev397
 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.3.0.dev395 → ha_mcp_dev-7.3.0.dev397}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.3.0.dev395"
+version = "7.3.0.dev397"
 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.3.0.dev395 → ha_mcp_dev-7.3.0.dev397}/src/ha_mcp/server.py

@@ -143,6 +143,13 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         # Register bundled skills as MCP resources
         self._register_skills()
 
+        # Enrich tool descriptions with BM25 keyword boosts. Runs
+        # unconditionally so Claude's native deferred-tool search
+        # (claude.ai) benefits even when ENABLE_TOOL_SEARCH is off.
+        # Must come before _apply_tool_search so CategorizedSearchTransform
+        # indexes the enriched descriptions.
+        self._apply_search_keyword_enrichment()
+
         # Apply tool search transform (must come after all tools and
         # ResourcesAsTools are registered so it can wrap everything)
         self._apply_tool_search()
@@ -336,8 +343,11 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
     )
 
     # 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.
+    # Applied unconditionally via SearchKeywordsTransform so they also
+    # improve retrieval for Claude's native deferred-tool search on
+    # claude.ai, which indexes tool names and descriptions with BM25
+    # (no semantic matching). Original tool docstrings stay unchanged;
+    # these keywords are appended by the transform at list-tools time.
     _SEARCH_KEYWORDS: ClassVar[dict[str, str]] = {
         # s02: "find entities" → ha_search_entities should outrank ha_deep_search
         "ha_search_entities": (
@@ -390,8 +400,11 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
     }
 
     # 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.
+    # Used to narrow overly broad tools so they stop matching generic queries
+    # against ha-mcp's internal BM25 search tool. Only applied when
+    # enable_tool_search=True, because they are tuned specifically for the
+    # categorized search transform and replacing the base description would
+    # unnecessarily trim context for other clients.
     _SEARCH_DESCRIPTION_OVERRIDES: ClassVar[dict[str, str]] = {
         "ha_deep_search": (
             "Search INSIDE automation, script, and helper YAML configurations. "
@@ -402,6 +415,53 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         ),
     }
 
+    def _apply_search_keyword_enrichment(self) -> None:
+        """Append BM25 keyword boosts to tool descriptions.
+
+        Applied unconditionally so Claude's native deferred-tool search
+        (claude.ai uses BM25 over tool names and descriptions) can find
+        ha-mcp tools for common natural-language queries like "create
+        automation" — the scenario in #940. The original tool docstrings
+        in ``src/ha_mcp/tools/`` are unchanged; keywords are appended at
+        list-tools time via ``SearchKeywordsTransform``.
+
+        Description overrides (``_SEARCH_DESCRIPTION_OVERRIDES``) are only
+        applied when ``enable_tool_search`` is also set, because they
+        REPLACE the original description and are tuned specifically for
+        ha-mcp's internal BM25 search tool.
+
+        Runs before ``_apply_tool_search`` so downstream transforms
+        index the enriched descriptions.
+        """
+        try:
+            from .transforms import SearchKeywordsTransform
+        except ImportError:
+            logger.warning(
+                "SearchKeywordsTransform not available; skipping description "
+                "enrichment (tool discoverability on claude.ai may be degraded)."
+            )
+            return
+
+        overrides = (
+            self._SEARCH_DESCRIPTION_OVERRIDES
+            if self.settings.enable_tool_search
+            else None
+        )
+        try:
+            self.mcp.add_transform(
+                SearchKeywordsTransform(
+                    keywords=self._SEARCH_KEYWORDS,
+                    overrides=overrides,
+                )
+            )
+            logger.info(
+                "Search keyword enrichment applied (%d boosts%s)",
+                len(self._SEARCH_KEYWORDS),
+                f", {len(overrides)} overrides" if overrides else "",
+            )
+        except Exception:
+            logger.exception("Failed to apply SearchKeywordsTransform")
+
     def _apply_tool_search(self) -> None:
         """Apply the CategorizedSearchTransform if enabled.
 
@@ -410,6 +470,10 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         remain directly visible in list_tools() for individual permission
         gating. ResourcesAsTools (list_resources/read_resource) are also
         pinned when enabled.
+
+        Note: ``_apply_search_keyword_enrichment`` already ran before this
+        method and installed ``SearchKeywordsTransform`` — the enriched
+        catalog is what the categorized transform indexes.
         """
         if not self.settings.enable_tool_search:
             return
@@ -447,18 +511,6 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             )
 
         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,
@@ -623,7 +675,9 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
                 if not f.resolve().is_relative_to(resolved_root):
                     continue
                 rel = f.relative_to(skill_dir)
-                ref_files.append({"name": str(rel), "uri": f"skill://{skill_name}/{rel}"})
+                ref_files.append(
+                    {"name": str(rel), "uri": f"skill://{skill_name}/{rel}"}
+                )
         except OSError:
             logger.warning("Error reading skill files in %s", skill_dir)
         return ref_files

ha_mcp_dev-7.3.0.dev397/src/ha_mcp/tools/reference_validator.py

@@ -0,0 +1,275 @@
+"""Reference validator for automation and script configs.
+
+Walks a config dict and extracts every literal service and entity
+reference, then cross-checks them against the live service and entity
+registries. Produces soft warnings that flow into the existing response
+alongside ``best_practice_warnings``.
+
+Intentional limits (documented, not bugs):
+
+- **Templates** (strings containing ``{{``) are counted and skipped.
+  Jinja is not rendered here; template-safe validation would need
+  ``POST /api/template`` round-trips and is a later follow-up.
+- **Blueprint automations** (``use_blueprint`` at the root) are skipped
+  wholesale. Post-substitution config is not exposed by any HA API, so
+  the effective refs cannot be ground-truthed.
+- **``device_id`` / ``area_id`` / ``label_id``** are NOT checked yet.
+  They require separate registry fetches and are planned for a later
+  pass; see #940.
+
+Background: #940 (hallucinated ``notify.mobile_app_andrew_phone`` that
+``ha_config_set_automation`` accepted silently).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, TypedDict
+
+logger = logging.getLogger(__name__)
+
+# Keys whose value (literal string) names a Home Assistant service in
+# the form ``<domain>.<service_name>``. Both legacy (``service:``) and
+# the new-style (``action:``) keys are recognized — HA accepts either
+# inside automation/script action blocks.
+_SERVICE_KEYS: frozenset[str] = frozenset({"service", "action"})
+
+# Keys whose value (string or list of strings) names an entity. These
+# appear in triggers, conditions, ``target:`` blocks, and service
+# ``data:`` blocks — the walker is depth-agnostic so the location
+# doesn't matter.
+_ENTITY_KEYS: frozenset[str] = frozenset({"entity_id"})
+
+
+class ExtractedRef(TypedDict):
+    """One reference pulled out of the config tree."""
+
+    path: str
+    value: str
+    kind: str  # "service" | "entity"
+
+
+class WalkerResult(TypedDict):
+    """Return value of :func:`extract_refs`."""
+
+    refs: list[ExtractedRef]
+    unvalidated_templates: int
+    blueprint_skipped: bool
+
+
+class ValidationWarning(TypedDict):
+    """One warning in the tool response."""
+
+    path: str
+    value: str
+    kind: str
+    reason: str
+
+
+def extract_refs(config: Any) -> WalkerResult:
+    """Pull every literal service/entity reference out of *config*.
+
+    Pure function: no network, no mutation of the input. The caller
+    decides what to do with the extracted refs.
+
+    Blueprint configs short-circuit with an empty ref list and
+    ``blueprint_skipped=True`` — the effective post-substitution config
+    is not reachable from ha-mcp, so it cannot be validated.
+    """
+    if isinstance(config, dict) and "use_blueprint" in config:
+        return {
+            "refs": [],
+            "unvalidated_templates": 0,
+            "blueprint_skipped": True,
+        }
+
+    refs: list[ExtractedRef] = []
+    # Wrapped in a single-element list so the inner closure can mutate
+    # it without a ``nonlocal`` dance.
+    unvalidated_templates = [0]
+
+    def _walk(node: Any, path: str) -> None:
+        if isinstance(node, dict):
+            for key, value in node.items():
+                sub_path = f"{path}.{key}" if path else key
+
+                if key in _SERVICE_KEYS and isinstance(value, str):
+                    if _is_template(value):
+                        unvalidated_templates[0] += 1
+                    else:
+                        refs.append(
+                            {"path": sub_path, "value": value, "kind": "service"}
+                        )
+                    continue
+
+                if key in _ENTITY_KEYS:
+                    if isinstance(value, str):
+                        if _is_template(value):
+                            unvalidated_templates[0] += 1
+                        else:
+                            refs.append(
+                                {"path": sub_path, "value": value, "kind": "entity"}
+                            )
+                        continue
+                    if isinstance(value, list):
+                        for i, item in enumerate(value):
+                            if not isinstance(item, str):
+                                continue
+                            item_path = f"{sub_path}[{i}]"
+                            if _is_template(item):
+                                unvalidated_templates[0] += 1
+                            else:
+                                refs.append(
+                                    {
+                                        "path": item_path,
+                                        "value": item,
+                                        "kind": "entity",
+                                    }
+                                )
+                        continue
+
+                # Neither a service nor an entity key: recurse so deeply
+                # nested action blocks (choose/if/parallel/repeat) still
+                # get walked.
+                _walk(value, sub_path)
+
+        elif isinstance(node, list):
+            for i, item in enumerate(node):
+                _walk(item, f"{path}[{i}]")
+        # Primitives: nothing to extract.
+
+    _walk(config, "")
+    return {
+        "refs": refs,
+        "unvalidated_templates": unvalidated_templates[0],
+        "blueprint_skipped": False,
+    }
+
+
+def _is_template(value: str) -> bool:
+    """Return True if *value* looks like a Jinja template."""
+    return "{{" in value
+
+
+def build_service_index(services_payload: Any) -> dict[str, set[str]]:
+    """Turn ``/api/services`` output into a ``{domain: {services}}`` map.
+
+    HA returns a list of ``{"domain": str, "services": {name: {...}}}``
+    objects — one per domain. Any malformed entry is skipped silently.
+    """
+    index: dict[str, set[str]] = {}
+    if not isinstance(services_payload, list):
+        return index
+    for entry in services_payload:
+        if not isinstance(entry, dict):
+            continue
+        domain = entry.get("domain")
+        services = entry.get("services")
+        if not isinstance(domain, str) or not isinstance(services, dict):
+            continue
+        index[domain] = set(services.keys())
+    return index
+
+
+def build_entity_set(states_payload: Any) -> set[str]:
+    """Turn ``/api/states`` output into a set of entity_ids."""
+    entities: set[str] = set()
+    if not isinstance(states_payload, list):
+        return entities
+    for entry in states_payload:
+        if isinstance(entry, dict):
+            entity_id = entry.get("entity_id")
+            if isinstance(entity_id, str):
+                entities.add(entity_id)
+    return entities
+
+
+def check_refs(
+    refs: list[ExtractedRef],
+    service_index: dict[str, set[str]],
+    entity_set: set[str],
+) -> list[ValidationWarning]:
+    """Return one warning per ref that isn't in the registry."""
+    warnings: list[ValidationWarning] = []
+    for ref in refs:
+        value = ref["value"]
+        if ref["kind"] == "service":
+            domain, _, service_name = value.partition(".")
+            if (
+                not service_name
+                or domain not in service_index
+                or service_name not in service_index[domain]
+            ):
+                warnings.append(
+                    {
+                        "path": ref["path"],
+                        "value": value,
+                        "kind": "service",
+                        "reason": "not found in service registry",
+                    }
+                )
+        elif ref["kind"] == "entity":
+            if value not in entity_set:
+                warnings.append(
+                    {
+                        "path": ref["path"],
+                        "value": value,
+                        "kind": "entity",
+                        "reason": "not found in entity registry",
+                    }
+                )
+    return warnings
+
+
+async def validate_config_references(
+    client: Any, config: dict[str, Any]
+) -> dict[str, Any]:
+    """Walk *config*, fetch registries, return validation metadata.
+
+    Errors from the two registry fetches are logged and swallowed so
+    validation can never break the happy path of
+    ``ha_config_set_automation`` / ``ha_config_set_script``.
+
+    Returns a dict with three keys:
+
+    - ``warnings`` - list of :class:`ValidationWarning`, empty on success
+    - ``unvalidated_templates`` - int, templated strings skipped by the
+      walker
+    - ``blueprint_skipped`` - bool, True iff the root config uses
+      ``use_blueprint``
+    """
+    walker_result = extract_refs(config)
+
+    if walker_result["blueprint_skipped"] or not walker_result["refs"]:
+        return {
+            "warnings": [],
+            "unvalidated_templates": walker_result["unvalidated_templates"],
+            "blueprint_skipped": walker_result["blueprint_skipped"],
+        }
+
+    try:
+        services_payload, states_payload = await asyncio.gather(
+            client.get_services(),
+            client.get_states(),
+        )
+    except Exception:
+        logger.exception(
+            "Reference validator: failed to fetch service/entity registries; "
+            "skipping validation for this call"
+        )
+        return {
+            "warnings": [],
+            "unvalidated_templates": walker_result["unvalidated_templates"],
+            "blueprint_skipped": False,
+        }
+
+    service_index = build_service_index(services_payload)
+    entity_set = build_entity_set(states_payload)
+    warnings = check_refs(walker_result["refs"], service_index, entity_set)
+
+    return {
+        "warnings": warnings,
+        "unvalidated_templates": walker_result["unvalidated_templates"],
+        "blueprint_skipped": False,
+    }

{ha_mcp_dev-7.3.0.dev395 → ha_mcp_dev-7.3.0.dev397}/src/ha_mcp/tools/tools_config_automations.py

@@ -37,10 +37,12 @@ from .helpers import (
     raise_tool_error,
     register_tool_methods,
 )
+from .reference_validator import validate_config_references
 from .util_helpers import (
     apply_entity_category,
     coerce_bool_param,
     fetch_entity_category,
+    merge_validation_meta,
     parse_json_param,
     wait_for_entity_registered,
     wait_for_entity_removed,
@@ -641,6 +643,13 @@ class AutomationConfigTools:
                 config_dict, skill_prefix=_get_skill_prefix()
             )
 
+            # Cross-check literal service and entity references against
+            # the live registries. Soft warnings only — the write still
+            # happens, even when references don't resolve (#940).
+            validation_meta = await validate_config_references(
+                self._client, config_dict
+            )
+
             result = await self._client.upsert_automation_config(config_dict, identifier)
 
             # If the client could not verify the entity was registered, warn but don't hard-fail.
@@ -677,6 +686,8 @@ class AutomationConfigTools:
             if bp_warnings:
                 result["best_practice_warnings"] = bp_warnings
 
+            merge_validation_meta(result, validation_meta)
+
             return {
                 "success": True,
                 **result,

{ha_mcp_dev-7.3.0.dev395 → ha_mcp_dev-7.3.0.dev397}/src/ha_mcp/tools/tools_config_scripts.py

@@ -31,10 +31,12 @@ from .helpers import (
     raise_tool_error,
     register_tool_methods,
 )
+from .reference_validator import validate_config_references
 from .util_helpers import (
     apply_entity_category,
     coerce_bool_param,
     fetch_entity_category,
+    merge_validation_meta,
     parse_json_param,
     wait_for_entity_registered,
     wait_for_entity_removed,
@@ -523,6 +525,13 @@ class ConfigScriptTools:
                 config_dict, skill_prefix=_get_skill_prefix()
             )
 
+            # Cross-check literal service and entity references against
+            # the live registries. Soft warnings only — the write still
+            # happens, even when references don't resolve (#940).
+            validation_meta = await validate_config_references(
+                self._client, config_dict
+            )
+
             result = await self._client.upsert_script_config(config_dict, script_id)
 
             # Wait for script to be queryable
@@ -545,6 +554,8 @@ class ConfigScriptTools:
             if bp_warnings:
                 result["best_practice_warnings"] = bp_warnings
 
+            merge_validation_meta(result, validation_meta)
+
             return {
                 "success": True,
                 **result,

{ha_mcp_dev-7.3.0.dev395 → ha_mcp_dev-7.3.0.dev397}/src/ha_mcp/tools/util_helpers.py

@@ -530,3 +530,34 @@ async def apply_entity_category(
         result_dict["category_warning"] = (
             f"{entity_type.capitalize()} saved but failed to set category: {e}"
         )
+
+
+def merge_validation_meta(
+    result: dict[str, Any], validation_meta: dict[str, Any]
+) -> None:
+    """Attach reference-validator output to a set-tool success ``result``.
+
+    Produces a single nested ``validation`` field when there's anything
+    worth reporting - warnings, skipped templates, or a blueprint
+    short-circuit. Keeps the happy-path response unchanged.
+
+    Shared between ``ha_config_set_automation`` and
+    ``ha_config_set_script``; see
+    :mod:`ha_mcp.tools.reference_validator` for the validator itself
+    and #940 for background.
+    """
+    warnings = validation_meta.get("warnings") or []
+    unvalidated_templates = validation_meta.get("unvalidated_templates") or 0
+    blueprint_skipped = bool(validation_meta.get("blueprint_skipped"))
+
+    if not warnings and not unvalidated_templates and not blueprint_skipped:
+        return
+
+    entry: dict[str, Any] = {}
+    if warnings:
+        entry["warnings"] = warnings
+    if unvalidated_templates:
+        entry["unvalidated_templates"] = unvalidated_templates
+    if blueprint_skipped:
+        entry["blueprint_skipped"] = True
+    result["validation"] = entry

{ha_mcp_dev-7.3.0.dev395 → ha_mcp_dev-7.3.0.dev397/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.3.0.dev395
+Version: 7.3.0.dev397
 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.3.0.dev395 → ha_mcp_dev-7.3.0.dev397}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -43,6 +43,7 @@ src/ha_mcp/tools/best_practice_checker.py
 src/ha_mcp/tools/device_control.py
 src/ha_mcp/tools/enhanced.py
 src/ha_mcp/tools/helpers.py
+src/ha_mcp/tools/reference_validator.py
 src/ha_mcp/tools/registry.py
 src/ha_mcp/tools/smart_search.py
 src/ha_mcp/tools/tools_addons.py