ha-mcp-dev 8.5.0.dev2674__tar.gz → 8.5.0.dev2678__tar.gz

{ha_mcp_dev-8.5.0.dev2674/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.5.0.dev2678}/PKG-INFO

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

{ha_mcp_dev-8.5.0.dev2674 → ha_mcp_dev-8.5.0.dev2678}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.5.0.dev2674"
+version = "8.5.0.dev2678"
 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-8.5.0.dev2674 → ha_mcp_dev-8.5.0.dev2678}/src/ha_mcp/backup_manager.py

@@ -54,7 +54,7 @@ import time
 import weakref
 from collections import Counter
 from collections.abc import AsyncIterator, Awaitable, Callable
-from contextlib import asynccontextmanager, suppress
+from contextlib import AsyncExitStack, asynccontextmanager, suppress
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from functools import cached_property
@@ -67,6 +67,7 @@ from ha_mcp._vendor.fastmcp.exceptions import ToolError
 
 from .client.rest_client import HomeAssistantConnectionError, HomeAssistantError
 from .utils.data_paths import get_data_dir
+from .utils.registry_update_lock import registry_update_lock
 
 logger = logging.getLogger(__name__)
 
@@ -2592,7 +2593,8 @@ async def _restore_area_or_floor(client: Any, entity_id: str, config: Any) -> An
         payload["floor_id"] = real_id
     else:
         raise ValueError(f"Unknown area/floor kind: {kind!r}")
-    return await _ws_send(client, payload)
+    async with registry_update_lock(kind, real_id):
+        return await _ws_send(client, payload)
 
 
 # Todo items — entity_id is "<todo.entity>::<item_uid>"
@@ -3538,43 +3540,56 @@ async def _restore_template_entity_id(
     """Restore only the newly created entity's ID/name, guarded by ownership."""
     row = await _created_template_entity(client, entry_id)
     source, target = row["entity_id"], saved["entity_id"]
-    if source.split(".")[0] != target.split(".")[0]:
-        raise BackupRestoreError(
-            "Recreated Template entity has an unexpected domain",
-            reason="entity_identity_mismatch",
-            verification_status="mismatched",
-        )
-    await _check_template_entity_collision(client, target, owned_entry_id=entry_id)
-    update: dict[str, Any] = {
-        "type": "config/entity_registry/update",
-        "entity_id": source,
-    }
-    if source != target:
-        update["new_entity_id"] = target
-    if row.get("name") != saved.get("name"):
-        update["name"] = saved.get("name")
-    if len(update) > 2:
-        try:
-            await _ws_send(client, update)
-        except _CAPTURE_TRANSIENT_ERRORS as err:
-            _log_template_failure("entity_rename", err)
+    locked_ids = {source, target}
+    async with AsyncExitStack() as locks:
+        # A rename changes the lock key; hold both IDs in a stable order.
+        for entity_id in sorted(locked_ids):
+            await locks.enter_async_context(registry_update_lock("entity", entity_id))
+        row = await _created_template_entity(client, entry_id)
+        source = row["entity_id"]
+        if source not in locked_ids:
             raise BackupRestoreError(
-                "The recreated helper's entity rename outcome is unknown",
-                reason="entity_rename_outcome_unknown",
-                entity_id_mapping={
-                    "created_entity_id": source,
-                    "target_entity_id": target,
-                },
-                verification_status="unavailable",
-            ) from err
-    actual = await _created_template_entity(client, entry_id)
-    if actual["entity_id"] != target or actual.get("name") != saved.get("name"):
-        raise BackupRestoreError(
-            "Recreated Template entity identity did not match",
-            reason="entity_identity_mismatch",
-            verification_status="mismatched",
-        )
-    return {"created_entity_id": source, "restored_entity_id": target}
+                "Recreated Template entity ID changed while waiting to restore it",
+                reason="entity_identity_mismatch",
+                verification_status="mismatched",
+            )
+        if source.split(".")[0] != target.split(".")[0]:
+            raise BackupRestoreError(
+                "Recreated Template entity has an unexpected domain",
+                reason="entity_identity_mismatch",
+                verification_status="mismatched",
+            )
+        await _check_template_entity_collision(client, target, owned_entry_id=entry_id)
+        update: dict[str, Any] = {
+            "type": "config/entity_registry/update",
+            "entity_id": source,
+        }
+        if source != target:
+            update["new_entity_id"] = target
+        if row.get("name") != saved.get("name"):
+            update["name"] = saved.get("name")
+        if len(update) > 2:
+            try:
+                await _ws_send(client, update)
+            except _CAPTURE_TRANSIENT_ERRORS as err:
+                _log_template_failure("entity_rename", err)
+                raise BackupRestoreError(
+                    "The recreated helper's entity rename outcome is unknown",
+                    reason="entity_rename_outcome_unknown",
+                    entity_id_mapping={
+                        "created_entity_id": source,
+                        "target_entity_id": target,
+                    },
+                    verification_status="unavailable",
+                ) from err
+        actual = await _created_template_entity(client, entry_id)
+        if actual["entity_id"] != target or actual.get("name") != saved.get("name"):
+            raise BackupRestoreError(
+                "Recreated Template entity identity did not match",
+                reason="entity_identity_mismatch",
+                verification_status="mismatched",
+            )
+        return {"created_entity_id": source, "restored_entity_id": target}
 
 
 async def _recreate_template_helper(

{ha_mcp_dev-8.5.0.dev2674 → ha_mcp_dev-8.5.0.dev2678}/src/ha_mcp/tools/tools_areas.py

@@ -7,6 +7,7 @@ Home Assistant areas and floors - essential organizational features for smart ho
 
 import asyncio
 import logging
+from contextlib import nullcontext
 from typing import Annotated, Any, Literal
 
 from pydantic import Field
@@ -15,6 +16,7 @@ from ha_mcp._vendor.fastmcp.exceptions import ToolError
 from ha_mcp._vendor.fastmcp.tools import tool
 
 from ..errors import ErrorCode, create_error_response, create_validation_error
+from ..utils.registry_update_lock import registry_update_lock
 from .auto_backup import with_auto_backup
 from .component_registries import fetch_registries_via_component
 from .helpers import (
@@ -36,6 +38,13 @@ from .util_helpers import (
 logger = logging.getLogger(__name__)
 
 
+def _label_id_set(entry: dict[str, Any] | None) -> set[str]:
+    """String label IDs stored on an area registry entry."""
+    if not isinstance(entry, dict):
+        return set()
+    return {lbl for lbl in (entry.get("labels") or []) if isinstance(lbl, str)}
+
+
 def _parse_projection_params(
     fields: str | list[str] | None,
     area_fields: str | list[str] | None,
@@ -119,11 +128,12 @@ def _validate_cross_kind_params(
     level: int | None,
     floor_id: str | None,
     picture: str | None,
+    labels: list[str] | None = None,
 ) -> None:
     """Reject params that don't belong to *kind* before building a set message."""
     # Reject cross-kind params loudly so silent intent loss can't happen
     # (e.g., kind='floor' with picture='...' previously dropped the picture
-    # without a diagnostic).
+    # without a diagnostic). Floors have no labels in HA core.
     cross_kind_params: list[str] = []
     if kind == "area" and level is not None:
         cross_kind_params.append("level")
@@ -132,6 +142,8 @@ def _validate_cross_kind_params(
             cross_kind_params.append("floor_id")
         if picture is not None:
             cross_kind_params.append("picture")
+        if labels is not None:
+            cross_kind_params.append("labels")
     if cross_kind_params:
         raise_tool_error(
             create_error_response(
@@ -139,7 +151,7 @@ def _validate_cross_kind_params(
                 f"Parameter(s) {cross_kind_params} are not valid for kind={kind!r}",
                 context={"kind": kind, "invalid_parameters": cross_kind_params},
                 suggestions=[
-                    "For kind='area' use: name, id, floor_id, icon, aliases, picture",
+                    "For kind='area' use: name, id, floor_id, icon, aliases, picture, labels",
                     "For kind='floor' use: name, id, level, icon, aliases",
                 ],
             )
@@ -160,6 +172,7 @@ class AreaTools:
         icon: str | None,
         parsed_aliases: list[str] | None,
         picture: str | None,
+        parsed_labels: list[str] | None,
     ) -> dict[str, Any]:
         """Build a WebSocket message for updating an existing area."""
         message: dict[str, Any] = {
@@ -176,6 +189,8 @@ class AreaTools:
             message["aliases"] = parsed_aliases
         if picture is not None:
             message["picture"] = picture if picture else None
+        if parsed_labels is not None:
+            message["labels"] = parsed_labels
         return message
 
     @staticmethod
@@ -185,6 +200,7 @@ class AreaTools:
         icon: str | None,
         parsed_aliases: list[str] | None,
         picture: str | None,
+        parsed_labels: list[str] | None,
     ) -> dict[str, Any]:
         """Build a WebSocket message for creating a new area."""
         message: dict[str, Any] = {
@@ -199,6 +215,8 @@ class AreaTools:
             message["aliases"] = parsed_aliases
         if picture:
             message["picture"] = picture
+        if parsed_labels:
+            message["labels"] = parsed_labels
         return message
 
     @staticmethod
@@ -476,6 +494,7 @@ class AreaTools:
         icon: str | None,
         parsed_aliases: list[str] | None,
         picture: str | None,
+        parsed_labels: list[str] | None,
     ) -> tuple[dict[str, Any], str, str, str, str | None]:
         """Build the WS message plus (result_key, id_key, operation, name) for a set.
 
@@ -491,6 +510,7 @@ class AreaTools:
                     icon,
                     parsed_aliases,
                     picture,
+                    parsed_labels,
                 )
                 operation = "update"
             else:
@@ -509,6 +529,7 @@ class AreaTools:
                     icon,
                     parsed_aliases,
                     picture,
+                    parsed_labels,
                 )
                 operation = "create"
             result_key = "area"
@@ -542,6 +563,157 @@ class AreaTools:
             id_key = "floor_id"
         return message, result_key, id_key, operation, name
 
+    @staticmethod
+    def _label_verify_context(
+        *,
+        parsed_labels: list[str],
+        kind: str,
+        returned_id: str | None,
+        operation: str,
+        name: str | None,
+        write_committed: bool = False,
+    ) -> dict[str, Any]:
+        """Error context shared by both label-verification failure paths."""
+        ctx: dict[str, Any] = {
+            "operation": operation,
+            "kind": kind,
+            "area_id": returned_id,
+            "expected_labels": parsed_labels,
+        }
+        if write_committed:
+            ctx["write_committed"] = True
+        if name:
+            ctx["name"] = name
+        return ctx
+
+    async def _verify_area_labels_written(
+        self,
+        *,
+        parsed_labels: list[str] | None,
+        kind: str,
+        data: dict[str, Any],
+        returned_id: str | None,
+        operation: str,
+        name: str | None,
+    ) -> None:
+        """Confirm HA stored the requested label set, not just a success ack.
+
+        Home Assistant answers an area create/update with ``success`` even when
+        it dropped label IDs it did not recognise, so the ack alone is not
+        evidence the set was applied. The response entry is checked first; the
+        registry is re-read only when that entry disagrees, which also covers
+        an ack that carries no labels at all.
+
+        Both failure paths report ``write_committed: True``: the area write
+        itself has already landed by the time this runs, so a caller that
+        retries a create would end up with a duplicate area. Only the labels
+        are still open, and those are fixed with ha_set_area_or_floor.
+        """
+        if kind != "area" or parsed_labels is None:
+            return
+        expected = set(parsed_labels)
+        if _label_id_set(data) == expected:
+            return
+        try:
+            listed = await self._client.send_websocket_message(
+                {"type": "config/area_registry/list"}
+            )
+        except Exception as exc:
+            # Write already succeeded; a transport failure on re-read must
+            # not look like a failed create (retry would duplicate the area).
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    "Area write succeeded, but label verification failed",
+                    details=str(exc),
+                    context=self._label_verify_context(
+                        parsed_labels=parsed_labels,
+                        kind=kind,
+                        returned_id=returned_id,
+                        operation=operation,
+                        name=name,
+                        write_committed=True,
+                    ),
+                    suggestions=[
+                        "The area write already committed; do not retry create.",
+                        "Re-read with ha_list_floors_areas() before retrying labels.",
+                    ],
+                )
+            )
+        rows = listed.get("result") if listed.get("success") else None
+        found: dict[str, Any] | None = None
+        if isinstance(rows, list):
+            found = next(
+                (
+                    a
+                    for a in rows
+                    if isinstance(a, dict) and a.get("area_id") == returned_id
+                ),
+                None,
+            )
+        if found is not None and _label_id_set(found) == expected:
+            return
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                "Area write succeeded but the returned entry does not contain "
+                "the requested labels",
+                context=self._label_verify_context(
+                    parsed_labels=parsed_labels,
+                    kind=kind,
+                    returned_id=returned_id,
+                    operation=operation,
+                    name=name,
+                    write_committed=True,
+                ),
+                suggestions=[
+                    "The area write already committed; do not retry create.",
+                    (
+                        "Apply the labels on their own with ha_set_area_or_floor("
+                        + f"kind='area', id={returned_id!r}, "
+                        + f"labels={parsed_labels!r})."
+                    ),
+                    (
+                        "Verify the label IDs exist with ha_config_get_label() "
+                        + "— Home Assistant drops unknown ones silently."
+                    ),
+                ],
+            )
+        )
+
+    async def _area_or_floor_write_success(
+        self,
+        result: dict[str, Any],
+        *,
+        result_key: str,
+        id_key: str,
+        identifier: str | None,
+        kind: str,
+        operation: str,
+        name: str | None,
+        parsed_labels: list[str] | None,
+    ) -> dict[str, Any]:
+        data = result.get("result", {})
+        if not isinstance(data, dict):
+            data = {}
+        returned_id = data.get(id_key, identifier)
+        await self._verify_area_labels_written(
+            parsed_labels=parsed_labels,
+            kind=kind,
+            data=data,
+            returned_id=returned_id if isinstance(returned_id, str) else identifier,
+            operation=operation,
+            name=name,
+        )
+        display_name = name or data.get("name", returned_id)
+        return {
+            "success": True,
+            result_key: data,
+            id_key: returned_id,
+            "kind": kind,
+            "message": f"Successfully {operation}d {kind}: {display_name}",
+        }
+
     # ============================================================
     # COMBINED SET / REMOVE
     # ============================================================
@@ -623,16 +795,29 @@ class AreaTools:
                 default=None,
             ),
         ] = None,
+        labels: Annotated[
+            str | list[str] | None,
+            JSON_STRING_COERCION,
+            Field(
+                description=(
+                    "Label IDs when kind='area' (replaces the area's label set; "
+                    "empty list to clear). Omit to leave labels unchanged. "
+                    "Only valid when kind='area' — floors have no labels."
+                ),
+                default=None,
+            ),
+        ] = None,
     ) -> dict[str, Any]:
         """Create or update a Home Assistant area or floor.
 
-        Pass kind='area' (with optional floor_id, picture) or kind='floor' (with optional level).
+        Pass kind='area' (with optional floor_id, picture, labels) or kind='floor' (with optional level).
         Provide name only to create a new entry; provide id to update an existing one.
-        Cross-kind parameters (e.g., picture under kind='floor') are rejected with VALIDATION_INVALID_PARAMETER.
+        Cross-kind parameters (e.g., picture or labels under kind='floor') are rejected with VALIDATION_INVALID_PARAMETER.
 
         EXAMPLES:
         ha_set_area_or_floor(kind="area", name="Kitchen")
         ha_set_area_or_floor(kind="area", id="kitchen", floor_id="ground_floor")
+        ha_set_area_or_floor(kind="area", id="kitchen", labels=["site_home"])
         ha_set_area_or_floor(kind="floor", name="Basement", level=-1)
         ha_set_area_or_floor(kind="floor", id="ground_floor", level=0)
         """
@@ -648,7 +833,17 @@ class AreaTools:
                     )
                 )
 
-            _validate_cross_kind_params(kind, level, floor_id, picture)
+            try:
+                parsed_labels = parse_string_list_param(labels, "labels")
+            except ValueError as e:
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        f"Invalid labels parameter: {e}",
+                    )
+                )
+
+            _validate_cross_kind_params(kind, level, floor_id, picture, parsed_labels)
 
             # ``None`` stays the documented "create-new" sentinel; explicit
             # empty/whitespace would silently route to the ``if id:`` create
@@ -674,30 +869,42 @@ class AreaTools:
                     icon,
                     parsed_aliases,
                     picture,
+                    parsed_labels,
                 )
             )
 
-            # Issue #2159: the area registry stores an unknown floor_id
-            # verbatim, orphaning the area. ``_validate_cross_kind_params``
-            # already rejected floor_id for kind='floor', so this only ever
-            # runs for areas; None and "" (clear) skip the lookup.
-            await validate_registry_ids(
-                self._client, None, None, None, floor_id=floor_id, fail_closed=True
-            )
+            async with (
+                registry_update_lock(kind, id) if id is not None else nullcontext()
+            ):
+                # Issue #2159: the area registry stores an unknown floor_id
+                # verbatim, and an unknown label_id is dropped on the way in
+                # (HA filters the set through the label registry) — both end as a
+                # success envelope that does not match what was asked for, so
+                # validate before writing. ``_validate_cross_kind_params`` already
+                # rejected floor_id/labels for kind='floor', so this only ever
+                # runs for areas; None and "" / [] (clear) skip the lookup.
+                await validate_registry_ids(
+                    self._client,
+                    None,
+                    parsed_labels,
+                    None,
+                    floor_id=floor_id,
+                    fail_closed=True,
+                )
 
-            result = await self._client.send_websocket_message(message)
+                result = await self._client.send_websocket_message(message)
 
-            if result.get("success"):
-                data = result.get("result", {})
-                returned_id = data.get(id_key, id)
-                display_name = name or data.get("name", returned_id)
-                return {
-                    "success": True,
-                    result_key: data,
-                    id_key: returned_id,
-                    "kind": kind,
-                    "message": f"Successfully {operation}d {kind}: {display_name}",
-                }
+                if result.get("success"):
+                    return await self._area_or_floor_write_success(
+                        result,
+                        result_key=result_key,
+                        id_key=id_key,
+                        identifier=id,
+                        kind=kind,
+                        operation=operation,
+                        name=name,
+                        parsed_labels=parsed_labels,
+                    )
 
             error = result.get("error", {})
             error_msg = (
@@ -729,6 +936,9 @@ class AreaTools:
             ]
             if kind == "area":
                 suggestions.append("If assigning to a floor, verify floor_id exists")
+                suggestions.append(
+                    "If assigning labels, verify label IDs with ha_config_get_label()"
+                )
             exception_to_structured_error(
                 e,
                 context={"operation": operation, "kind": kind, "name": name, "id": id},

{ha_mcp_dev-8.5.0.dev2674 → ha_mcp_dev-8.5.0.dev2678}/src/ha_mcp/tools/tools_config_helpers.py

@@ -27,6 +27,7 @@ from ..client.websocket_client import get_websocket_client
 from ..errors import ErrorCode, create_auth_error, create_error_response
 from ..redaction import redact_flow_schema, redaction_enabled
 from ..strict_bps import BestPracticeKeyParam
+from ..utils.registry_update_lock import registry_update_lock
 from .auto_backup import with_auto_backup
 from .component_api import (
     component_supports,
@@ -1454,10 +1455,14 @@ async def validate_registry_ids(
     """Validate that registry references point at entries that actually exist.
 
     Bug 16 (issue #1150) / issue #2159: HA's registry-update APIs accept any
-    string for a cross-registry reference and store it verbatim, so a typo or a
-    since-deleted ID becomes a dangling reference the write tool still reports
-    as a success. Validate before sending so the caller gets a clear error with
-    the available IDs to choose from.
+    string for a cross-registry reference and answer with a success envelope
+    either way, so without this check a typo or a since-deleted ID passes as a
+    completed write. What happens to the bad value differs per reference:
+    area_id / floor_id / category are stored verbatim and become a dangling
+    reference, while an unknown label_id is dropped (the area registry filters
+    the requested set through the label registry), leaving the caller with a
+    success it cannot distinguish from an applied one. Validate before sending
+    so the caller gets a clear error with the available IDs to choose from.
 
     ``categories`` maps a category SCOPE ("helpers", "automation", "script",
     "scene") to the category_id being assigned in that scope; each distinct
@@ -1822,7 +1827,8 @@ async def _entity_registry_update_coro(
         update_message["labels"] = labels
     if icon is not None:
         update_message["icon"] = icon if icon else None
-    return await client.send_websocket_message(update_message)
+    async with registry_update_lock("entity", entity_id):
+        return await client.send_websocket_message(update_message)
 
 
 async def _category_apply_coro(
@@ -2633,7 +2639,8 @@ async def _apply_create_entity_registry(
         update_message["area_id"] = area_id if area_id else None
     if labels is not None:
         update_message["labels"] = labels
-    update_result = await client.send_websocket_message(update_message)
+    async with registry_update_lock("entity", entity_id):
+        update_result = await client.send_websocket_message(update_message)
     if update_result.get("success"):
         if icon is not None:
             helper_data["icon"] = icon if icon else None
@@ -3265,7 +3272,8 @@ async def _apply_update_icon_area_labels(
         registry_update["area_id"] = area_id if area_id else None
     if labels is not None:
         registry_update["labels"] = labels
-    reg_result = await client.send_websocket_message(registry_update)
+    async with registry_update_lock("entity", entity_id):
+        reg_result = await client.send_websocket_message(registry_update)
     if reg_result.get("success"):
         if icon is not None:
             updated_data["icon"] = icon if icon else None
@@ -3329,7 +3337,8 @@ async def _execute_fallback_registry_update(
         fallback_msg["area_id"] = area_id if area_id else None
     if labels is not None:
         fallback_msg["labels"] = labels
-    result = await client.send_websocket_message(fallback_msg)
+    async with registry_update_lock("entity", entity_id):
+        result = await client.send_websocket_message(fallback_msg)
     updated_data: dict[str, Any] = {}
     if result.get("success"):
         updated_data = result.get("result", {}).get("entity_entry", {})