ha-mcp-dev 9.1.2.dev3397__tar.gz → 9.1.2.dev3399__tar.gz

{ha_mcp_dev-9.1.2.dev3397 → ha_mcp_dev-9.1.2.dev3399}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.2.dev3397
+Version: 9.1.2.dev3399
 Summary: Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants.
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.1.2.dev3397 → ha_mcp_dev-9.1.2.dev3399}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.2.dev3397"
+version = "9.1.2.dev3399"
 description = "Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants."
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.2.dev3397 → ha_mcp_dev-9.1.2.dev3399}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.2.dev3397"
+version = "9.1.2.dev3399"
 description = "Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants."
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

ha_mcp_dev-9.1.2.dev3399/src/ha_mcp/tools/component_config_reads.py

@@ -0,0 +1,228 @@
+"""Config-resolution + reference reads over the ``ha_mcp_tools`` component gate.
+
+Two consumers in the automation/script/scene family read through the
+component:
+
+- Entity resolution maps storage keys to live registry entity IDs.
+  ``entity_registration.resolve_entity_id_after_write`` polls after scene/script
+  writes against one deadline. ``_resolve_scene_entity_id`` uses a single retry
+  before scene removal. The component's ``entity_lookup`` returns only matching
+  rows instead of a full registry/state listing. A hit is authoritative at once,
+  but an empty read can precede HA's asynchronous entity registration even when
+  performed in-process, so post-write callers must continue polling.
+- The reference validator (``validate_config_references``) asks the
+  component's ``ha_mcp_tools/config_references`` for Core's own verdict on a
+  proposed config's references; Core serves nothing like it for an unsaved
+  config, so there is no legacy path and an absent component is reported.
+
+This module owns the caps-gated fetches so the routing discipline — probe caps,
+send one frame, invalidate on ``unknown_command`` — lives in one place instead
+of being duplicated per consumer (the pattern ``component_devices`` established
+for the ``device_get`` / ``device_list`` capabilities).
+``fetch_entity_lookup_via_component`` returns ``None`` to mean "component
+unavailable — use the legacy path"; a component that answers authoritatively
+returns its payload (an EMPTY ``matches`` list is authoritative — "no registry
+entry with that unique_id" — kept distinct from the ``None`` miss). It maps a
+transport failure (``HomeAssistantConnectionError`` off ``send_command`` or from
+a failed (re)build of the pooled socket, or ``HomeAssistantAuthError``) to
+``None`` too, NEVER propagating it: its consumers fall back to the legacy
+WebSocket registry bridge or REST state reads, which an escaping error would
+skip. The post-write resolver catches known API/transport failures and retains
+a best-effort entity ID; later wait and category operations report any
+verification or assignment failure. Removal resolvers retain their own error
+policies.
+
+**GET-path invariant:** the automation/script/scene *config-get* tools never
+read the config body through the component — its in-process ``raw_config``
+freshness lags the config file between a write and the next completed reload,
+so the body always comes from Core's REST config endpoint. The script and scene
+resolvers gate the whole component branch (caps probe included) behind
+``allow_component`` for removals, and the dedicated post-write resolver is never
+called from a config-get. The automation tools resolve through
+``component_automation.automation_lookup`` instead, which reads the registry,
+never the body.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..client.rest_client import (
+    HomeAssistantCommandError,
+    HomeAssistantCommandTimeout,
+)
+from ..client.websocket_client import get_websocket_client
+from .component_api import (
+    component_supports,
+    get_component_caps,
+    invalidate_caps,
+    is_unknown_command,
+)
+
+logger = logging.getLogger(__name__)
+
+WS_ENTITY_LOOKUP = "ha_mcp_tools/entity_lookup"
+WS_CONFIG_REFERENCES = "ha_mcp_tools/config_references"
+CONFIG_REFERENCES = "config_references"
+
+
+async def fetch_entity_lookup_via_component(
+    client: Any,
+    unique_id: str,
+    *,
+    domain: str | None = None,
+) -> list[dict[str, Any]] | None:
+    """One ``ha_mcp_tools/entity_lookup`` read; ``None`` ⇒ use the legacy path.
+
+    Returns the component's ``matches`` list — every entity-registry entry whose
+    ``unique_id`` equals ``unique_id`` (each ``{entity_id, unique_id, platform,
+    domain, config_entry_id, categories, disabled_by, hidden_by}``), optionally
+    narrowed by the entity's own ``domain``. Multiple matches (one ``unique_id``
+    across platforms) are all returned — the caller picks. An AUTHORITATIVE empty
+    list (no registry entry with that unique_id) is kept distinct from the
+    ``None`` miss (component unavailable → legacy).
+
+    ``None`` on capability miss, downgrade (``unknown_command`` → invalidate the
+    cached caps), command error/timeout (logged), a connection-establishment
+    failure (logged — see the module docstring: the resolvers' legacy paths ride
+    the WS bridge / REST, NOT this pooled socket, so a transport
+    failure must fall back rather than abort a landed write), or a shape-drift
+    payload (no ``matches`` list). Same error-taxonomy and silent fallback as
+    ``component_devices.fetch_device_via_component``.
+    """
+    caps = await get_component_caps(client)
+    if not component_supports(caps, "entity_lookup"):
+        return None
+    kwargs: dict[str, Any] = {"unique_id": unique_id}
+    if domain is not None:
+        kwargs["domain"] = domain
+    try:
+        ws = await get_websocket_client(
+            url=client.base_url,
+            token=client.token,
+            verify_ssl=getattr(client, "verify_ssl", None),
+        )
+        raw = await ws.send_command(WS_ENTITY_LOOKUP, **kwargs)
+    except (HomeAssistantCommandError, HomeAssistantCommandTimeout) as exc:
+        if is_unknown_command(exc):
+            invalidate_caps(client)
+        else:
+            logger.warning("%s failed; fell back to legacy: %r", WS_ENTITY_LOOKUP, exc)
+        return None
+    except Exception as exc:  # noqa: BLE001
+        # HomeAssistantConnectionError (a pooled-WS drop or a failed
+        # (re)connect) or any other error.
+        # The resolvers' legacy paths do NOT die identically (see module docstring),
+        # so route to legacy rather than escape.
+        logger.warning(
+            "%s connection error; falling back to legacy: %r", WS_ENTITY_LOOKUP, exc
+        )
+        return None
+    result = raw.get("result")
+    matches = result.get("matches") if isinstance(result, dict) else None
+    if not isinstance(matches, list):
+        logger.debug(
+            "%s returned a malformed result (no 'matches' list); falling back to legacy",
+            WS_ENTITY_LOOKUP,
+        )
+        return None
+    return matches
+
+
+_INSTALL_HINT = (
+    "install the ha_mcp_tools component via HACS (the Marketplace on Home "
+    "Assistant 2026.11+) and restart Home Assistant"
+)
+
+
+def _unavailable(error: str) -> dict[str, Any]:
+    return {"status": "unavailable", "error": error}
+
+
+def _answer_shape_error(result: Any) -> str | None:
+    """Why *result* is not a ``config_references`` answer, or None if it is."""
+    if not isinstance(result, dict) or not isinstance(result.get("status"), str):
+        return "no status"
+    if result["status"] != "ok":
+        return None if result.get("error") else "no error for a failed check"
+    fields = {
+        "missing": ("kind", "value"),
+        "mismatches": ("path", "kind", "name", "entity_id"),
+    }
+    for key, strings in fields.items():
+        items = result.get(key)
+        if not isinstance(items, list) or not all(
+            isinstance(item, dict)
+            and all(isinstance(item.get(k), str) for k in strings)
+            and (
+                key != "mismatches"
+                or (
+                    isinstance(item.get("offered"), list)
+                    and all(isinstance(o, str) for o in item["offered"])
+                )
+            )
+            for item in items
+        ):
+            return f"malformed {key}"
+    return None
+
+
+async def fetch_config_references_via_component(
+    client: Any, kind: str, config: dict[str, Any]
+) -> dict[str, Any]:
+    """Core's verdict on *config*'s references, through ``ha_mcp_tools/config_references``.
+
+    The component validates *config* (an automation, script or scene, per
+    *kind*) with Core, collects its references with Core's helpers, checks them
+    against Core's registries and puts each entity target to Core's target
+    lookups. It answers ``{"status": "ok", "missing": [...], "mismatches":
+    [...]}``, ``{"status": "invalid", "error": ...}`` when Core's validator
+    refuses the config, or ``{"status": "unavailable", "error": ...}``. An
+    absent or outdated component, a command or transport failure and an answer
+    of the wrong shape are answered the same unavailable way, naming the cause:
+    the write goes on and the caller reports the references as unchecked. There
+    is no REST/WebSocket fallback by design: Core serves the target lookups,
+    ``validate_config`` for a config's trigger, condition and action lists, and
+    the registries over its API, but does not collect an unsaved config's
+    references, which is where the check starts; a server-side copy of that
+    part is the walker this replaced.
+    """
+    caps = await get_component_caps(client)
+    if caps is None:
+        return _unavailable(
+            "references were not checked: Home Assistant checks them through the "
+            "ha_mcp_tools component, which is not installed or did not answer; "
+            + _INSTALL_HINT
+        )
+    outdated = _unavailable(
+        "references were not checked: the installed ha_mcp_tools component "
+        "predates the reference check; update it via HACS (the Marketplace on "
+        "Home Assistant 2026.11+)"
+    )
+    if not component_supports(caps, CONFIG_REFERENCES):
+        return outdated
+    try:
+        ws = await get_websocket_client(
+            url=client.base_url,
+            token=client.token,
+            verify_ssl=getattr(client, "verify_ssl", None),
+        )
+        raw = await ws.send_command(WS_CONFIG_REFERENCES, kind=kind, config=config)
+    except (HomeAssistantCommandError, HomeAssistantCommandTimeout) as exc:
+        if is_unknown_command(exc):
+            invalidate_caps(client)
+            return outdated
+        logger.warning("%s failed: %r", WS_CONFIG_REFERENCES, exc)
+        return _unavailable(str(exc) or type(exc).__name__)
+    except Exception as exc:
+        # A soft check must never abort the write it accompanies.
+        logger.warning("%s connection error", WS_CONFIG_REFERENCES, exc_info=True)
+        return _unavailable(str(exc) or type(exc).__name__)
+    result = raw.get("result")
+    if (shape := _answer_shape_error(result)) is not None or not isinstance(
+        result, dict
+    ):
+        logger.warning("%s answered with %s: %r", WS_CONFIG_REFERENCES, shape, result)
+        return _unavailable(f"{WS_CONFIG_REFERENCES} answered with {shape}")
+    return result

{ha_mcp_dev-9.1.2.dev3397 → ha_mcp_dev-9.1.2.dev3399}/src/ha_mcp/tools/config_write_helpers.py

@@ -8,7 +8,7 @@ metadata, and the config reload waiter.
 import asyncio
 import json
 import logging
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
 from contextlib import asynccontextmanager
 from typing import Any
 
@@ -177,30 +177,22 @@ async def apply_entity_category(
 
 
 def merge_validation_meta(
-    result: dict[str, Any], validation_meta: dict[str, Any]
+    result: dict[str, Any], validation_meta: Mapping[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, a blueprint
-    short-circuit, target kinds left unchecked, or a failed registry fetch.
-    Keeps the happy-path response unchanged.
+    Produces a single nested ``validation`` field when there's anything worth
+    reporting: Core's warnings, or why the references went unchecked. 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.
+    Shared between ``ha_config_set_automation``, ``ha_config_set_script`` and
+    ``ha_config_set_scene``; see :mod:`ha_mcp.tools.reference_validator`.
     """
-    entry: dict[str, Any] = {}
-    if validation_meta.get("warnings"):
-        entry["warnings"] = validation_meta["warnings"]
-    if validation_meta.get("unvalidated_templates"):
-        entry["unvalidated_templates"] = validation_meta["unvalidated_templates"]
-    if validation_meta.get("blueprint_skipped"):
-        entry["blueprint_skipped"] = True
-    for key in ("unchecked_target_kinds", "references_unchecked"):
-        if validation_meta.get(key):
-            entry[key] = validation_meta[key]
+    entry = {
+        key: validation_meta[key]
+        for key in ("warnings", "references_unchecked")
+        if validation_meta.get(key)
+    }
     if entry:
         result["validation"] = entry
 

ha_mcp_dev-9.1.2.dev3399/src/ha_mcp/tools/reference_validator.py

@@ -0,0 +1,92 @@
+"""References in an automation, script or scene config, checked by Core.
+
+The component's ``ha_mcp_tools/config_references`` bridge runs Core's own
+validator on the proposed config, collects its references with Core's helpers
+and checks them against Core's registries, and puts each entity target to
+Core's target lookups (the editor's target pickers). This module only turns
+that answer into soft warnings beside ``best_practice_warnings``. There is no
+server-side copy of Core's rules to fall back on: without the component the
+response says the references went unchecked.
+
+Background: #940 (a hallucinated ``notify.mobile_app_andrew_phone`` that
+``ha_config_set_automation`` accepted silently) and #2989 (``select.select_option``
+aimed at an ``input_select``, which Core saves and the action then skips).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+from .component_config_reads import fetch_config_references_via_component
+
+ConfigKind = Literal["automation", "script", "scene"]
+RefKind = Literal["service", "entity", "device", "area", "floor", "label"]
+
+
+class ValidationWarning(TypedDict):
+    """One warning in the tool response.
+
+    A missing reference has no ``path``: Core's helpers collect references as
+    sets. A target Core does not offer carries its ``path``, the item it is a
+    target of (``target_of``) and what Core does offer for it (``offered``).
+    """
+
+    kind: RefKind
+    value: str
+    reason: str
+    path: NotRequired[str]
+    target_of: NotRequired[str]
+    offered: NotRequired[list[str]]
+
+
+class ValidationMeta(TypedDict):
+    """Core's warnings, or why the references went unchecked."""
+
+    warnings: list[ValidationWarning]
+    references_unchecked: NotRequired[str]
+
+
+def _warnings(answer: dict[str, Any]) -> list[ValidationWarning]:
+    warnings: list[ValidationWarning] = [
+        {
+            "kind": missing["kind"],
+            "value": missing["value"],
+            "reason": f"Home Assistant has no {missing['kind']} {missing['value']}",
+        }
+        for missing in answer["missing"]
+    ]
+    warnings.extend(
+        {
+            "kind": "entity",
+            "value": mismatch["entity_id"],
+            "path": mismatch["path"],
+            "target_of": mismatch["name"],
+            "offered": mismatch["offered"],
+            "reason": (
+                f"Home Assistant does not offer {mismatch['entity_id']} as a "
+                f"target of {mismatch['name']}; see offered for what it does offer"
+            ),
+        }
+        for mismatch in answer["mismatches"]
+    )
+    return warnings
+
+
+async def validate_config_references(
+    client: Any, config: dict[str, Any], kind: ConfigKind
+) -> ValidationMeta:
+    """Core's verdict on *config*'s references, as validation metadata.
+
+    ``references_unchecked`` names why nothing was checked: the component is
+    absent or outdated, the command or transport failed, Core's validator
+    refused the config (Core then refuses the write itself), or the component's
+    check failed.
+    """
+    answer = await fetch_config_references_via_component(client, kind, config)
+    if answer["status"] != "ok":
+        return {
+            "warnings": [],
+            "references_unchecked": answer.get("error")
+            or f"references were not checked: the check answered {answer['status']}",
+        }
+    return {"warnings": _warnings(answer)}

{ha_mcp_dev-9.1.2.dev3397 → ha_mcp_dev-9.1.2.dev3399}/src/ha_mcp/tools/tools_config_automations.py

@@ -80,7 +80,7 @@ from .helpers import (
     reject_malformed_list_fields,
     validate_identifier_not_empty,
 )
-from .reference_validator import validate_config_references
+from .reference_validator import validate_config_references as ref_check
 from .tool_hints import read_only_hints, write_hints
 from .util_helpers import list_visible_registry_ids
 from .ws_waiters import (
@@ -704,14 +704,12 @@ class AutomationConfigTools:
                 operation = "created" if stored is None else "updated"
 
             bp_warnings = _check_best_practices(config_dict)
-            validation_meta = await validate_config_references(
-                self._client, config_dict
-            )
+            references = await ref_check(self._client, config_dict, "automation")
             await self._check_before_write(
                 config_dict, entity_id, effective_category, bp_warnings
             )
 
-            return await self._run_config_update(
+            response = await self._run_config_update(
                 config_dict,
                 entity_id,
                 target,
@@ -719,12 +717,13 @@ class AutomationConfigTools:
                 effective_category,
                 wait,
                 bp_warnings,
-                validation_meta,
                 MandatoryBPS,
                 detached_blueprint,
                 enabled,
                 run_actions=run_actions,
             )
+            merge_validation_meta(response, references)
+            return response
 
         except ToolError as te:
             raise augment_tool_error_with_skill_content(te, bp_warnings) from None
@@ -1159,6 +1158,7 @@ class AutomationConfigTools:
             transformed_config, entity_id, source="python_transform"
         )
         bp_warnings = _check_best_practices(transformed_config)
+        references = await ref_check(self._client, transformed_config, "automation")
         await self._check_before_write(
             transformed_config, entity_id, effective_category, bp_warnings
         )
@@ -1212,6 +1212,7 @@ class AutomationConfigTools:
             canonical_files=_AUTOMATION_SKILL_FILES,
             referenced_files=bp_warnings.referenced_files,
         )
+        merge_validation_meta(response, references)
         return response, bp_warnings
 
     async def _read_back_hash(
@@ -1236,7 +1237,6 @@ class AutomationConfigTools:
         effective_category: str | None,
         wait: bool,
         bp_warnings: BestPracticeCheckResult,
-        validation_meta: dict[str, Any],
         MandatoryBPS: bool,
         detached_blueprint: str | None = None,
         enabled: bool | None = None,
@@ -1320,8 +1320,6 @@ class AutomationConfigTools:
         if bp_warnings:
             result["best_practice_warnings"] = list(bp_warnings)
 
-        merge_validation_meta(result, validation_meta)
-
         automation_id = resolved_entity_id or entity_id or result.get("unique_id")
         response = {
             "success": True,

{ha_mcp_dev-9.1.2.dev3397 → ha_mcp_dev-9.1.2.dev3399}/src/ha_mcp/tools/tools_config_scenes.py

@@ -56,7 +56,7 @@ from .helpers import (
     register_tool_methods,
     validate_identifier_not_empty,
 )
-from .reference_validator import validate_config_references
+from .reference_validator import validate_config_references as ref_check
 from .scene_discovery import discover_scenes
 from .tool_hints import read_only_hints, write_hints
 from .ws_waiters import verify_entity_removed, wait_for_entity_registered
@@ -970,6 +970,7 @@ class ConfigSceneTools:
         # ``resolved_id`` is the storage key (write target); ``scene_id``
         # stays the caller id so a missing ``name`` defaults caller-facing
         # rather than to the storage key (#1935).
+        references = await ref_check(self._client, transformed_config, "scene")
         # Scene writes reload every scene; activation has to follow that reload.
         async with config_reload_waiter(
             self._client, "scene_reloaded", enabled=activate
@@ -1047,6 +1048,7 @@ class ConfigSceneTools:
             canonical_files=_SCENE_SKILL_FILES,
             referenced_files=None,
         )
+        merge_validation_meta(response, references)
         return response
 
     @staticmethod
@@ -1261,10 +1263,7 @@ class ConfigSceneTools:
             ):
                 await self._client.get_scene_config(scene_id, resolution=resolution)
 
-        # Cross-check literal service and entity references against the
-        # live registries. Soft warnings only.
-        validation_meta = await validate_config_references(self._client, config_dict)
-
+        references = await ref_check(self._client, config_dict, "scene")
         # ``resolved_id`` is already the storage key (from the hash-verify
         # fetch or the resolve above) — pass it as the write target to skip
         # the redundant re-resolve. ``scene_id`` stays the caller id so a
@@ -1323,7 +1322,7 @@ class ConfigSceneTools:
         if activate:
             await self._activate_scene(result, entity_id, standalone=False)
 
-        merge_validation_meta(result, validation_meta)
+        merge_validation_meta(result, references)
 
         # Issue #1168 R3 blocker 6: build response from ``resolved_id``
         # so the outer ``scene_id`` always matches the storage key.

{ha_mcp_dev-9.1.2.dev3397 → ha_mcp_dev-9.1.2.dev3399}/src/ha_mcp/tools/tools_config_scripts.py

@@ -58,7 +58,7 @@ from .helpers import (
     reject_malformed_list_fields,
     validate_identifier_not_empty,
 )
-from .reference_validator import validate_config_references
+from .reference_validator import validate_config_references as ref_check
 from .tool_hints import read_only_hints, write_hints
 from .util_helpers import list_visible_registry_ids
 from .ws_waiters import verify_entity_removed, wait_for_entity_registered
@@ -978,6 +978,7 @@ class ConfigScriptTools:
         # ``script_id`` stays the caller id (the fetched config already
         # carries an alias here, so the default is a no-op, but keep the
         # contract consistent — #1935).
+        references = await ref_check(self._client, transformed_config, "script")
         result = await self._client.upsert_script_config(
             transformed_config, script_id, resolved_id=resolved_id
         )
@@ -1007,6 +1008,7 @@ class ConfigScriptTools:
             canonical_files=_SCRIPT_SKILL_FILES,
             referenced_files=bp_warnings.referenced_files,
         )
+        merge_validation_meta(response, references)
         return response
 
     async def _take_control_config(self, script_id: str) -> TakenControl:
@@ -1038,11 +1040,7 @@ class ConfigScriptTools:
         detached_blueprint: str | None = None,
     ) -> dict[str, Any]:
         """Validate references, upsert, finalize wait/category, and build the response."""
-        # 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)
-
+        references = await ref_check(self._client, config_dict, "script")
         result = await self._upsert_script(config_dict, script_id, resolved_key)
 
         await self._finalize_script_write(
@@ -1052,7 +1050,7 @@ class ConfigScriptTools:
         if bp_warnings:
             result["best_practice_warnings"] = list(bp_warnings)
 
-        merge_validation_meta(result, validation_meta)
+        merge_validation_meta(result, references)
 
         response = {
             "success": True,