ha-mcp-dev 8.4.3.dev2670__tar.gz → 8.5.0.dev2675__tar.gz

{ha_mcp_dev-8.4.3.dev2670/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.5.0.dev2675}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2670
+Version: 8.5.0.dev2675
 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.4.3.dev2670 → ha_mcp_dev-8.5.0.dev2675}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.3.dev2670"
+version = "8.5.0.dev2675"
 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.4.3.dev2670 → ha_mcp_dev-8.5.0.dev2675}/src/ha_mcp/tools/tools_areas.py

@@ -36,6 +36,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 +126,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 +140,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 +149,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 +170,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 +187,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 +198,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 +213,8 @@ class AreaTools:
             message["aliases"] = parsed_aliases
         if picture:
             message["picture"] = picture
+        if parsed_labels:
+            message["labels"] = parsed_labels
         return message
 
     @staticmethod
@@ -476,6 +492,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 +508,7 @@ class AreaTools:
                     icon,
                     parsed_aliases,
                     picture,
+                    parsed_labels,
                 )
                 operation = "update"
             else:
@@ -509,6 +527,7 @@ class AreaTools:
                     icon,
                     parsed_aliases,
                     picture,
+                    parsed_labels,
                 )
                 operation = "create"
             result_key = "area"
@@ -542,6 +561,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 +793,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 +831,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 +867,39 @@ 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.
+            # 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, None, None, floor_id=floor_id, fail_closed=True
+                self._client,
+                None,
+                parsed_labels,
+                None,
+                floor_id=floor_id,
+                fail_closed=True,
             )
 
             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}",
-                }
+                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 +931,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.4.3.dev2670 → ha_mcp_dev-8.5.0.dev2675}/src/ha_mcp/tools/tools_config_helpers.py

@@ -1454,10 +1454,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