ha-mcp-dev 7.14.2.dev2098__tar.gz → 7.14.2.dev2103__tar.gz

{ha_mcp_dev-7.14.2.dev2098/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.14.2.dev2103}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.14.2.dev2098
+Version: 7.14.2.dev2103
 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.14.2.dev2098 → ha_mcp_dev-7.14.2.dev2103}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.14.2.dev2098"
+version = "7.14.2.dev2103"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-7.14.2.dev2098 → ha_mcp_dev-7.14.2.dev2103}/src/ha_mcp/client/rest_client.py

@@ -8,7 +8,8 @@ import logging
 import os
 import ssl
 import time
-from typing import Any
+from dataclasses import dataclass
+from typing import Any, NoReturn
 
 import httpx
 from websockets.exceptions import WebSocketException
@@ -97,6 +98,54 @@ class HomeAssistantAPIError(HomeAssistantError):
         self.response_data = response_data
 
 
+@dataclass(frozen=True)
+class SceneResolution:
+    """Outcome of resolving a scene identifier via the entity registry.
+
+    ``registry_hit`` records whether ``config/entity_registry/get`` returned a
+    usable ``unique_id`` - i.e. the entity actually EXISTS. It is the signal that
+    separates a genuinely-missing scene from one that exists but is not editable
+    through HA's scene config API (a Hue/vendor scene, or a raw-YAML scene): both
+    resolve fine yet 404 on ``config/scene/config/{id}``, because that endpoint is
+    backed only by the managed ``scenes.yaml`` (issue #1971). ``platform`` carries
+    the registry entry's integration domain (``"hue"``, ``"homeassistant"``, …)
+    for error-message enrichment only - it never drives the classification, since
+    a raw-YAML scene is ``platform="homeassistant"`` yet still 404s.
+    """
+
+    storage_key: str
+    registry_hit: bool
+    platform: str | None
+
+
+class SceneStorageConfigNotFoundError(HomeAssistantAPIError):
+    """A scene entity resolved in the registry, but ``config/scene/config/{id}``
+    (backed by ``scenes.yaml``) has no matching entry.
+
+    The entity EXISTS; it is simply not an editable Home Assistant storage scene
+    (Hue/vendor scene, or a raw-YAML scene). Raised instead of a bare 404 so the
+    tools layer can surface ``CONFIG_NOT_FOUND`` rather than the misleading
+    ``ENTITY_NOT_FOUND``/``RESOURCE_NOT_FOUND`` (issue #1971). Subclasses
+    ``HomeAssistantAPIError`` so existing ``except HomeAssistantAPIError`` sites
+    keep treating it as the 404 it is.
+    """
+
+    def __init__(
+        self,
+        scene_id: str,
+        *,
+        platform: str | None = None,
+        storage_key: str | None = None,
+    ):
+        self.scene_id = scene_id
+        self.platform = platform
+        self.storage_key = storage_key
+        msg = f"Scene not found in editable storage: {scene_id}"
+        if storage_key and storage_key != scene_id:
+            msg += f" (resolved storage key: {storage_key})"
+        super().__init__(msg, status_code=404)
+
+
 class HomeAssistantCommandError(HomeAssistantError):
     """WebSocket command returned success=False.
 
@@ -1773,20 +1822,23 @@ class HomeAssistantClient:
                 ) from e
             raise
 
-    async def resolve_scene_id(self, identifier: str) -> str:
-        """
-        Resolve a scene identifier to its storage key via the entity registry.
+    async def _resolve_scene(self, identifier: str) -> SceneResolution:
+        """Resolve a scene identifier to its storage key AND registry metadata.
 
-        Scenes may be renamed in the HA UI, changing the entity_id but keeping
-        the original storage key. Mirrors :meth:`_resolve_script_id` — scenes
-        likewise need a WebSocket entity registry lookup; their state attributes
-        do not surface the storage key.
+        Backs :meth:`resolve_scene_id`. Returns the storage key together with
+        ``registry_hit`` (did the entity actually resolve?) and ``platform`` - the
+        two signals a bare storage key throws away. Callers that hit a config-API
+        404 need ``registry_hit`` to tell "entity missing" from "entity exists but
+        has no editable storage config", and ``platform`` to name the owning
+        integration in the resulting error (issue #1971).
 
         Args:
             identifier: Scene ID (with or without ``scene.`` prefix)
 
         Returns:
-            The storage key for the configuration API
+            A :class:`SceneResolution`. On any lookup failure it falls back to the
+            bare id with ``registry_hit=False`` - a write path must not treat the
+            guessed bare id as a confirmed resolve.
         """
         bare_id = identifier.removeprefix("scene.")
         entity_id = f"scene.{bare_id}"
@@ -1795,13 +1847,18 @@ class HomeAssistantClient:
                 {"type": "config/entity_registry/get", "entity_id": entity_id}
             )
             if result.get("success") is not False:
-                unique_id = result.get("result", {}).get("unique_id")
+                entry = result.get("result") or {}
+                unique_id = entry.get("unique_id")
                 if unique_id:
                     if unique_id != bare_id:
                         logger.debug(
                             f"Resolved scene entity_id {entity_id} to storage key {unique_id}"
                         )
-                    return str(unique_id)
+                    return SceneResolution(
+                        storage_key=str(unique_id),
+                        registry_hit=True,
+                        platform=entry.get("platform"),
+                    )
         except HomeAssistantConnectionError:
             # A dead transport must not become a silent guess: the fallback
             # below assumes the storage key equals the bare entity_id, which is
@@ -1814,19 +1871,111 @@ class HomeAssistantClient:
                 f"Entity registry lookup failed for {entity_id}, using bare id: {bare_id}",
                 exc_info=True,
             )
-        return bare_id
+        return SceneResolution(storage_key=bare_id, registry_hit=False, platform=None)
+
+    async def resolve_scene_id(self, identifier: str) -> str:
+        """
+        Resolve a scene identifier to its storage key via the entity registry.
+
+        Scenes may be renamed in the HA UI, changing the entity_id but keeping
+        the original storage key. Like :meth:`_resolve_script_id`, this returns
+        the bare storage key and needs a WebSocket entity registry lookup because
+        the state attributes do not surface it; the parity ends there, since the
+        underlying :meth:`_resolve_scene` additionally carries registry metadata
+        (``registry_hit``/``platform``) that the script resolver has no analogue for.
+
+        Thin wrapper over :meth:`_resolve_scene` for callers that only need the
+        storage key (e.g. the write path); the read/delete paths use the richer
+        :class:`SceneResolution` directly.
+
+        Args:
+            identifier: Scene ID (with or without ``scene.`` prefix)
+
+        Returns:
+            The storage key for the configuration API
+        """
+        return (await self._resolve_scene(identifier)).storage_key
+
+    async def _scene_state_exists(self, storage_key: str) -> bool:
+        """Return True if ``scene.<storage_key>`` exists in the state machine.
+
+        An ``id``-less YAML scene has no registry ``unique_id`` (so
+        ``registry_hit`` is False) yet still registers a state-machine entity.
+        This one-shot existence check separates that real-but-not-storage scene
+        from a genuinely-absent one after a config-API 404 (issue #1971). A 404
+        here is a clean "absent"; a transport failure propagates (fail loud).
+        """
+        try:
+            await self.get_entity_state(f"scene.{storage_key}")
+            return True
+        except HomeAssistantAPIError as e:
+            if e.status_code == 404:
+                return False
+            raise
+
+    async def _raise_scene_config_404(
+        self,
+        scene_id: str,
+        resolved_id: str,
+        resolution: SceneResolution | None,
+    ) -> NoReturn:
+        """Translate a scene config-API 404 into the right exception.
+
+        When the registry resolve succeeded (``registry_hit``), the entity exists
+        and the 404 means "no editable storage config" → raise
+        :class:`SceneStorageConfigNotFoundError` carrying the platform. On a
+        registry miss the entity may still be an ``id``-less YAML scene, which has
+        no registry ``unique_id`` yet exists in the state machine: a state hit
+        upgrades the 404 to the same not-storage-scene case with ``platform=None``
+        (issue #1971). Only a state miss too is the historic genuinely-absent bare
+        404. The state check is skipped when ``resolution`` is None (the internal
+        ``_resolved`` re-fetch fast path, where a 404 is a genuine disappearance).
+        Always raises.
+        """
+        if resolution is not None:
+            if resolution.registry_hit:
+                raise SceneStorageConfigNotFoundError(
+                    scene_id, platform=resolution.platform, storage_key=resolved_id
+                )
+            if await self._scene_state_exists(resolved_id):
+                raise SceneStorageConfigNotFoundError(
+                    scene_id, platform=None, storage_key=resolved_id
+                )
+        msg = f"Scene not found: {scene_id}"
+        if resolved_id != scene_id:
+            msg += f" (resolved storage key: {resolved_id})"
+        raise HomeAssistantAPIError(msg, status_code=404)
 
     async def get_scene_config(
-        self, scene_id: str, *, _resolved: bool = False
+        self,
+        scene_id: str,
+        *,
+        _resolved: bool = False,
+        resolution: SceneResolution | None = None,
     ) -> dict[str, Any]:
         """Get Home Assistant scene configuration by scene_id.
 
+        ``resolution`` lets a caller that already ran :meth:`_resolve_scene` pass
+        the full outcome through: the endpoint uses its ``storage_key`` and its
+        ``registry_hit``/``platform`` drive the config-404 classification (issue
+        #1971) with no extra lookup. It takes precedence over ``_resolved``.
+
         ``_resolved=True`` signals ``scene_id`` is already the resolved storage
         key (the caller ran :meth:`resolve_scene_id`), skipping the redundant
         registry lookup. ``resolve_scene_id`` is idempotent, so the result is
-        identical either way.
+        identical either way. This fast path is the internal re-fetch of an
+        already-resolved scene (its sole caller is the post-write re-fetch), where
+        a subsequent 404 is a genuine disappearance, not the not-storage-scene
+        case; the ``registry_hit``/``platform`` signals a config 404 needs are
+        deliberately unavailable there.
         """
-        resolved_id = scene_id if _resolved else await self.resolve_scene_id(scene_id)
+        if resolution is not None:
+            resolved_id = resolution.storage_key
+        elif _resolved:
+            resolved_id = scene_id
+        else:
+            resolution = await self._resolve_scene(scene_id)
+            resolved_id = resolution.storage_key
         try:
             endpoint = f"config/scene/config/{resolved_id}"
             response = await self._request("GET", endpoint)
@@ -1834,10 +1983,7 @@ class HomeAssistantClient:
             return {"success": True, "scene_id": resolved_id, "config": response}
         except HomeAssistantAPIError as e:
             if e.status_code == 404:
-                msg = f"Scene not found: {scene_id}"
-                if resolved_id != scene_id:
-                    msg += f" (resolved storage key: {resolved_id})"
-                raise HomeAssistantAPIError(msg, status_code=404) from e
+                await self._raise_scene_config_404(scene_id, resolved_id, resolution)
             raise
         except Exception as e:
             logger.error(f"Failed to get scene config for {scene_id}: {e}")
@@ -1904,15 +2050,24 @@ class HomeAssistantClient:
             raise
 
     async def delete_scene_config(
-        self, scene_id: str, *, _resolved: bool = False
+        self,
+        scene_id: str,
+        *,
+        resolution: SceneResolution | None = None,
     ) -> dict[str, Any]:
         """Delete Home Assistant scene configuration.
 
-        ``_resolved=True`` signals ``scene_id`` is already the resolved storage
-        key, skipping the redundant registry lookup (``resolve_scene_id`` is
-        idempotent, so the endpoint id is unchanged).
+        ``resolution`` lets a caller that already ran :meth:`_resolve_scene` pass
+        the full outcome through - the endpoint uses its ``storage_key`` while
+        ``scene_id`` stays the caller's slug for messages, and its ``registry_hit``
+        drives the config-404 classification (issue #1971) with no extra lookup.
+        Otherwise the id is resolved here.
         """
-        resolved_id = scene_id if _resolved else await self.resolve_scene_id(scene_id)
+        if resolution is not None:
+            resolved_id = resolution.storage_key
+        else:
+            resolution = await self._resolve_scene(scene_id)
+            resolved_id = resolution.storage_key
         try:
             endpoint = f"config/scene/config/{resolved_id}"
             response = await self._request("DELETE", endpoint)
@@ -1925,10 +2080,7 @@ class HomeAssistantClient:
             }
         except HomeAssistantAPIError as e:
             if e.status_code == 404:
-                msg = f"Scene not found: {scene_id}"
-                if resolved_id != scene_id:
-                    msg += f" (resolved storage key: {resolved_id})"
-                raise HomeAssistantAPIError(msg, status_code=404) from e
+                await self._raise_scene_config_404(scene_id, resolved_id, resolution)
             elif e.status_code == 405:
                 raise HomeAssistantAPIError(
                     f"Cannot delete scene '{scene_id}': The HTTP DELETE method is blocked. "

{ha_mcp_dev-7.14.2.dev2098 → ha_mcp_dev-7.14.2.dev2103}/src/ha_mcp/tools/tools_config_scenes.py

@@ -9,7 +9,7 @@ keyed by entity_id (not a list).
 
 import asyncio
 import logging
-from typing import Annotated, Any, cast
+from typing import Annotated, Any, NoReturn, cast
 
 from fastmcp.exceptions import ToolError
 from fastmcp.tools import tool
@@ -19,6 +19,7 @@ from ..client.rest_client import (
     HomeAssistantAPIError,
     HomeAssistantAuthError,
     HomeAssistantConnectionError,
+    SceneStorageConfigNotFoundError,
 )
 from ..errors import ErrorCode, create_error_response
 from ..strict_bps import BestPracticeKeyParam
@@ -63,6 +64,50 @@ _SCENE_SKILL_FILES: tuple[str, ...] = ("SKILL.md",)
 logger = logging.getLogger(__name__)
 
 
+def _raise_scene_not_storage_error(scene_id: str, platform: str | None) -> NoReturn:
+    """Raise ``CONFIG_NOT_FOUND`` for a scene that exists but has no editable config.
+
+    The scene entity was confirmed to exist - in the entity registry, or, for an
+    ``id``-less YAML scene that has no registry entry, in the state machine - but
+    ``config/scene/config/{id}``, backed only by the managed ``scenes.yaml``, has
+    no entry for it. That is the not-a-storage-scene case (a Hue/vendor scene, or
+    a scene defined directly in YAML): the entity EXISTS, so ``ENTITY_NOT_FOUND``
+    would be wrong (issue #1971). ``platform`` names the owning integration when
+    the registry exposed it; the message stays generic otherwise.
+    """
+    entity_id = f"scene.{scene_id.removeprefix('scene.')}"
+    suggestions = [
+        "Activate it with the scene.turn_on service: "
+        f"ha_call_service('scene', 'turn_on', {{'entity_id': '{entity_id}'}}).",
+    ]
+    if platform and platform != "homeassistant":
+        platform_note = (
+            f" It is provided by the '{platform}' integration, which manages its "
+            "own scenes outside Home Assistant's editable scene storage."
+        )
+        suggestions.append(
+            f"Edit this scene in the '{platform}' integration or its companion app; "
+            "ha_config_get_scene / ha_config_set_scene only edit Home Assistant "
+            "UI/storage scenes."
+        )
+    else:
+        platform_note = ""
+        suggestions.append(
+            "ha_config_get_scene / ha_config_set_scene only read and edit Home "
+            "Assistant UI/storage scenes (Settings > Automations & Scenes > Scenes). "
+            "Scenes defined directly in YAML are not editable through this API."
+        )
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.CONFIG_NOT_FOUND,
+            f"Scene '{entity_id}' exists but has no editable Home Assistant "
+            f"storage configuration.{platform_note}",
+            suggestions=suggestions,
+            context={"scene_id": scene_id, "platform": platform},
+        )
+    )
+
+
 class ConfigSceneTools:
     """Scene configuration management tools for Home Assistant."""
 
@@ -352,6 +397,11 @@ class ConfigSceneTools:
             return await self._legacy_get_scene(scene_id)
         except ToolError:
             raise
+        except SceneStorageConfigNotFoundError as e:
+            # The entity resolved but scenes.yaml has no config for it - a Hue/
+            # vendor or raw-YAML scene. Surface CONFIG_NOT_FOUND, not the
+            # ENTITY_NOT_FOUND the generic handler below would emit (#1971).
+            _raise_scene_not_storage_error(e.scene_id, e.platform)
         except Exception as e:
             # Pass `entity_id` so a 404 from rest_client surfaces as
             # ENTITY_NOT_FOUND (not the generic RESOURCE_NOT_FOUND fallback).
@@ -746,6 +796,12 @@ class ConfigSceneTools:
 
         except ToolError as te:
             raise augment_tool_error_with_skill_content(te, bp_warnings=None) from None
+        except SceneStorageConfigNotFoundError as e:
+            # Set on a non-storage scene: the hash-verify / python_transform
+            # pre-fetch read 404s because the entity has no editable scenes.yaml
+            # config (Hue/vendor or raw-YAML). Same CONFIG_NOT_FOUND
+            # classification as get/delete (#1971), not a generic write failure.
+            _raise_scene_not_storage_error(e.scene_id, e.platform)
         except Exception as e:
             error = exception_to_structured_error(
                 e,
@@ -1079,18 +1135,36 @@ class ConfigSceneTools:
         # so subsequent upsert/response builders use the storage key
         # consistently (issue #1168 R3 blocker 6).
         #
-        # Path branching: if a hash is supplied for a non-existent
-        # scene, the inner fetch raises 404 and surfaces as
-        # ENTITY_NOT_FOUND via the outer except — which is the right
-        # caller-facing semantics ("you can't lock against a scene
-        # that doesn't exist"). The no-hash branch resolves separately
-        # so a fresh create still threads the resolved id correctly.
+        # Path branching: the hash arm's inner fetch reads the config
+        # first, so a non-storage scene (Hue/vendor, raw-YAML) surfaces
+        # as CONFIG_NOT_FOUND and a genuinely-missing scene as the bare
+        # 404 – you cannot lock against a config that isn't there. The
+        # no-hash arm has no such read, so it resolves richly and, when
+        # the entity already exists, pre-checks the config API below
+        # before the upsert (issue #1971) so a plain ``set`` on a
+        # non-storage scene cannot silently shadow-create a duplicate.
         if config_hash:
             _, resolved_id = await self._fetch_and_verify_hash(
                 scene_id, config_hash, "set"
             )
         else:
-            resolved_id = await self._client.resolve_scene_id(scene_id)
+            resolution = await self._client._resolve_scene(scene_id)
+            resolved_id = resolution.storage_key
+            # If the scene already exists this is an EDIT, and without a hash
+            # there is no prior read: a POST to ``config/scene/config/<key>``
+            # for a Hue/vendor or YAML scene would CREATE a duplicate managed
+            # ``scenes.yaml`` entry instead of erroring. Pre-check the config
+            # API first – its 404 raises SceneStorageConfigNotFoundError, which
+            # the outer handler maps to CONFIG_NOT_FOUND.
+            #
+            # Existence takes both signals: an ``id``-less YAML scene has no
+            # registry unique_id yet still holds a state-machine entity, and
+            # shadow-creates just the same. Only a scene missing from both is a
+            # real create, at the price of one extra ``/states/`` GET there.
+            if resolution.registry_hit or await self._client._scene_state_exists(
+                resolved_id
+            ):
+                await self._client.get_scene_config(scene_id, resolution=resolution)
 
         # Cross-check literal service and entity references against the
         # live registries. Soft warnings only.
@@ -1229,8 +1303,12 @@ class ConfigSceneTools:
             # callsite (entity_id resolver, delete call, response) uses the
             # storage key consistently — outer ``scene_id`` matches the
             # inner body regardless of whether the caller passed the
-            # entity_id slug or the storage key.
-            resolved_id = await self._client.resolve_scene_id(scene_id)
+            # entity_id slug or the storage key. The rich resolution also
+            # carries ``registry_hit``/``platform`` so a config-API 404 on a
+            # non-storage scene (Hue/vendor, raw-YAML) classifies as
+            # CONFIG_NOT_FOUND rather than the misleading generic 404 (#1971).
+            resolution = await self._client._resolve_scene(scene_id)
+            resolved_id = resolution.storage_key
 
             # Resolve actual entity_id BEFORE delete — once the registry
             # entry is gone, the unique_id lookup can no longer find it.
@@ -1240,9 +1318,11 @@ class ConfigSceneTools:
                 resolved_id, allow_component=True
             )
 
-            # ``resolved_id`` is already the storage key (resolved above), so
-            # skip the redundant re-resolve inside delete_scene_config.
-            result = await self._client.delete_scene_config(resolved_id, _resolved=True)
+            # Thread the resolution through so delete_scene_config reuses the
+            # storage key (no redundant re-resolve) and can classify a 404.
+            result = await self._client.delete_scene_config(
+                scene_id, resolution=resolution
+            )
 
             if wait:
                 try:
@@ -1264,6 +1344,10 @@ class ConfigSceneTools:
             }
         except ToolError:
             raise
+        except SceneStorageConfigNotFoundError as e:
+            # Entity resolved but scenes.yaml has no config for it - a Hue/
+            # vendor or raw-YAML scene, not a genuinely missing entity (#1971).
+            _raise_scene_not_storage_error(e.scene_id, e.platform)
         except Exception as e:
             exception_to_structured_error(
                 e,