ha-mcp-dev 7.5.0.dev517__tar.gz → 7.5.0.dev518__tar.gz

{ha_mcp_dev-7.5.0.dev517/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev518}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.5.0.dev517
+Version: 7.5.0.dev518
 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.5.0.dev517 → ha_mcp_dev-7.5.0.dev518}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev517"
+version = "7.5.0.dev518"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.5.0.dev517 → ha_mcp_dev-7.5.0.dev518}/src/ha_mcp/tools/tools_config_helpers.py

@@ -1472,6 +1472,69 @@ async def _apply_registry_updates_to_entity(
     return applied
 
 
+class HelperResponse(TypedDict, total=False):
+    """Uniform response contract for ``ha_config_set_helper`` (issue #1293).
+
+    Documents the legal key set across all three branches (create, update,
+    flow). ``total=False`` because per-branch fields (entity_id, flow extras,
+    warnings) are conditional. Consumed by ``_helper_response`` below — all
+    return literals in this module funnel through that builder so the shape
+    has a single point of construction.
+    """
+
+    success: bool
+    action: str  # "create" | "update"
+    helper_type: str
+    data: dict[str, Any]
+    entity_id: str  # absent on flow branch (use entity_ids[] for multi-entity)
+    message: str | None
+    warnings: list[str]  # omitted when empty
+    # Flow-helper convenience accessors (only set on the flow branch).
+    method: str
+    entry_id: str | None
+    title: str | None
+    updated: bool
+    entity_ids: list[str]
+    area_id: str | None
+    labels: list[str]
+    category: str
+    applied: list[dict[str, Any]]
+
+
+def _helper_response(
+    action: str,
+    helper_type: str,
+    *,
+    data: dict[str, Any],
+    entity_id: str | None = None,
+    message: str | None = None,
+    warnings: list[str] | None = None,
+    **extras: Any,
+) -> dict[str, Any]:
+    """Single construction point for the ``ha_config_set_helper`` response.
+
+    Enforces the uniform shape from issue #1293: ``success`` → ``action`` →
+    ``helper_type`` → ``data`` → ``entity_id`` (when present) → ``message`` →
+    flow-helper extras → ``warnings`` (only when non-empty). Returning
+    ``dict[str, Any]`` rather than ``HelperResponse`` keeps the call sites
+    free of mypy gymnastics around the dynamic ``**extras`` keys; the
+    TypedDict serves as the readable contract anchor instead.
+    """
+    resp: dict[str, Any] = {
+        "success": True,
+        "action": action,
+        "helper_type": helper_type,
+        "data": data,
+    }
+    if entity_id is not None:
+        resp["entity_id"] = entity_id
+    resp["message"] = message
+    resp.update(extras)
+    if warnings:
+        resp["warnings"] = warnings
+    return resp
+
+
 async def _handle_flow_helper(
     client: Any,
     helper_type: str,
@@ -1625,18 +1688,15 @@ async def _handle_flow_helper(
             helper_id,  # type: ignore[arg-type]
         )
 
+    # Cache the flow_result keys read multiple times below (issue #1293
+    # follow-up: reduces three .get() lookups for entry_id and two for title
+    # to one each, and makes the post-flow logic readable as a sequence of
+    # named values rather than repeated dict access). ``.get()`` is kept —
+    # ``create_flow_helper`` propagates HA's optional entry_id via ``.get()``
+    # too (tools_config_entry_flow.py:L700), so a missing key must surface as
+    # None for the ``if entry_id:`` guard below, not raise KeyError.
     entry_id = flow_result.get("entry_id")
-    result: dict[str, Any] = {
-        "success": True,
-        "action": action,
-        "helper_type": helper_type,
-        "method": "config_flow",
-        "entry_id": entry_id,
-        "title": flow_result.get("title"),
-        "message": flow_result.get("message"),
-    }
-    if action == "update":
-        result["updated"] = True
+    title = flow_result.get("title")
 
     # Resolve all entities for this config entry (multi-entity helpers handled naturally).
     # For create with wait=True, poll briefly for at least one entity to appear —
@@ -1680,7 +1740,22 @@ async def _handle_flow_helper(
         else:
             entities = await _get_entities_for_config_entry(client, entry_id, warnings)
     entity_ids = [e["entity_id"] for e in entities if e.get("entity_id")]
-    result["entity_ids"] = entity_ids
+
+    # ``data`` mirrors the HA flow_result payload for cross-action uniformity
+    # with the create/update branches (issue #1293). ``entry_id`` and ``title``
+    # also stay flat as convenience accessors — they are the primary identifiers
+    # callers reach for, and remain heavily used by per-action metadata
+    # consumers throughout the codebase. Per-entity registry-write outcomes
+    # live in the ``applied`` flat array, not nested in ``data``, because one
+    # flow can yield N entities with different per-entity results.
+    extras: dict[str, Any] = {
+        "method": "config_flow",
+        "entry_id": entry_id,
+        "title": title,
+        "entity_ids": entity_ids,
+    }
+    if action == "update":
+        extras["updated"] = True
 
     # Apply registry updates (area_id / labels / category) to every entity.
     # Use `is not None` so an explicit empty value (area_id="" or labels=[])
@@ -1703,17 +1778,21 @@ async def _handle_flow_helper(
             )
         )
         if area_id is not None:
-            result["area_id"] = area_id if area_id else None
+            extras["area_id"] = area_id if area_id else None
         if labels_list is not None:
-            result["labels"] = labels_list
+            extras["labels"] = labels_list
         if category:
-            result["category"] = category
-        result["applied"] = applied_per_entity
-
-    if warnings:
-        result["warnings"] = warnings
-
-    return result
+            extras["category"] = category
+        extras["applied"] = applied_per_entity
+
+    return _helper_response(
+        action,
+        helper_type,
+        data={"entry_id": entry_id, "title": title},
+        message=flow_result.get("message"),
+        warnings=warnings,
+        **extras,
+    )
 
 
 def _format_schedule_days(
@@ -2660,6 +2739,12 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     if not entity_id and helper_data.get("id"):
                         entity_id = f"{helper_type}.{helper_data['id']}"
 
+                    # Issue #1293: collect warnings in a top-level list rather
+                    # than nest them in the payload dict. Aligns this branch
+                    # with the flow-helper path and lets callers do
+                    # ``result.get("warnings", [])`` uniformly.
+                    warnings: list[str] = []
+
                     # Wait for entity to be properly registered before proceeding
                     wait_bool = coerce_bool_param(wait, "wait", default=True)
                     if wait_bool and entity_id:
@@ -2668,11 +2753,11 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                                 client, entity_id
                             )
                             if not registered:
-                                helper_data["warning"] = (
+                                warnings.append(
                                     f"Helper created but {entity_id} not yet queryable. It may take a moment to become available."
                                 )
                         except Exception as e:
-                            helper_data["warning"] = (
+                            warnings.append(
                                 f"Helper created but verification failed: {e}"
                             )
 
@@ -2691,6 +2776,11 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                             update_message
                         )
                         if update_result.get("success"):
+                            # Mirror the update branch's icon propagation
+                            # (line ~3343) so the create response's ``data``
+                            # carries the same registry-write echo set.
+                            if icon is not None:
+                                helper_data["icon"] = icon if icon else None
                             if area_id is not None:
                                 helper_data["area_id"] = area_id if area_id else None
                             if labels is not None:
@@ -2702,29 +2792,39 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                                 if isinstance(error_detail, dict)
                                 else str(error_detail)
                             )
-                            helper_data["warning"] = (
+                            warnings.append(
                                 f"Helper created but entity registry update failed: {error_msg}"
                             )
 
-                    # Apply category via shared helper (consistent with automations/scripts)
+                    # Apply category via shared helper (consistent with automations/scripts).
+                    # Issue #1293: route the success/failure through ``cat_result`` so any
+                    # ``category_warning`` lands in the top-level ``warnings`` list instead
+                    # of leaking nested into ``helper_data``. Mirrors the precedent in
+                    # ``_handle_flow_helper`` (the ``cat_result`` block near the end of
+                    # ``_apply_registry_updates_to_entity``).
                     if category and entity_id:
+                        cat_result: dict[str, Any] = {}
                         await apply_entity_category(
                             client,
                             entity_id,
                             category,
                             "helpers",
-                            helper_data,
+                            cat_result,
                             "helper",
                         )
+                        if "category" in cat_result:
+                            helper_data["category"] = cat_result["category"]
+                        elif "category_warning" in cat_result:
+                            warnings.append(cat_result["category_warning"])
 
-                    return {
-                        "success": True,
-                        "action": "create",
-                        "helper_type": helper_type,
-                        "helper_data": helper_data,
-                        "entity_id": entity_id,
-                        "message": f"Successfully created {helper_type}: {name}",
-                    }
+                    return _helper_response(
+                        "create",
+                        helper_type,
+                        data=helper_data,
+                        entity_id=entity_id,
+                        message=f"Successfully created {helper_type}: {name}",
+                        warnings=warnings,
+                    )
                 else:
                     raise_tool_error(
                         create_error_response(
@@ -2772,6 +2872,11 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 }
 
                 updated_data: dict[str, Any] = {}
+                # Issue #1293: collect warnings in a top-level list for the
+                # update path too, mirroring create + flow-helper branches.
+                # (No re-annotation — the create branch above already defined
+                # ``warnings: list[str]``; mypy treats this as the same binding.)
+                warnings = []
 
                 if helper_type == "tag":
                     # Tags use their own registry — no entity registry entries.
@@ -2806,14 +2911,19 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
                     # Tags don't have entity registry entries, so return directly
                     # without wait_for_entity_registered (they're not entities).
-                    return {
-                        "success": True,
-                        "action": "update",
-                        "helper_type": helper_type,
-                        "entity_id": entity_id,
-                        "updated_data": updated_data,
-                        "message": f"Successfully updated {helper_type}: {entity_id}",
-                    }
+                    # Issue #1293: same uniform builder as the sibling create/update
+                    # branches. No producer appends to ``warnings`` on the tag path
+                    # today, but ``_helper_response`` already omits the key when the
+                    # list is empty — future warnings flow through the same contract
+                    # without further plumbing.
+                    return _helper_response(
+                        "update",
+                        helper_type,
+                        data=updated_data,
+                        entity_id=entity_id,
+                        message=f"Successfully updated {helper_type}: {entity_id}",
+                        warnings=warnings,
+                    )
 
                 elif helper_type in config_store_types:
                     # Person and zone: look up unique_id from entity registry
@@ -3290,30 +3400,49 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                         reg_result = await client.send_websocket_message(
                             registry_update
                         )
-                        if not reg_result.get("success"):
+                        if reg_result.get("success"):
+                            # Issue #1293: mirror the create branch by propagating the
+                            # registry writes into ``updated_data`` so the response's
+                            # ``data`` reflects the post-update state.
+                            if icon is not None:
+                                updated_data["icon"] = icon if icon else None
+                            if area_id is not None:
+                                updated_data["area_id"] = area_id if area_id else None
+                            if labels is not None:
+                                updated_data["labels"] = labels
+                        else:
                             error_detail = reg_result.get("error", {})
                             error_msg = (
                                 error_detail.get("message", "Unknown error")
                                 if isinstance(error_detail, dict)
                                 else str(error_detail)
                             )
-                            logger.warning(
-                                f"Entity registry update failed for {entity_id}: {error_msg}"
-                            )
-                            updated_data["warning"] = (
+                            # No ``logger.warning`` here — the create-branch and
+                            # flow-helper registry-update failure paths surface this
+                            # via ``warnings.append`` only, and the response carries
+                            # the message to the caller in the top-level ``warnings``
+                            # list. Logging again would double-report.
+                            warnings.append(
                                 f"Config updated but entity registry update failed: {error_msg}"
                             )
 
-                    # Apply category via shared helper
+                    # Apply category via shared helper. Issue #1293: route through
+                    # ``cat_result`` so any ``category_warning`` lands in the top-level
+                    # ``warnings`` list instead of nested in ``updated_data``.
                     if category:
+                        cat_result = {}
                         await apply_entity_category(
                             client,
                             entity_id,
                             category,
                             "helpers",
-                            updated_data,
+                            cat_result,
                             "helper",
                         )
+                        if "category" in cat_result:
+                            updated_data["category"] = cat_result["category"]
+                        elif "category_warning" in cat_result:
+                            warnings.append(cat_result["category_warning"])
 
                 else:
                     # Fallback for unknown/future helper types: entity registry update only
@@ -3347,39 +3476,43 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                             )
                         )
 
-                    # Apply category via shared helper
+                    # Apply category via shared helper. Issue #1293: same temp-dict
+                    # routing as the simple-helper branch above.
                     if category:
+                        cat_result = {}
                         await apply_entity_category(
                             client,
                             entity_id,
                             category,
                             "helpers",
-                            updated_data,
+                            cat_result,
                             "helper",
                         )
+                        if "category" in cat_result:
+                            updated_data["category"] = cat_result["category"]
+                        elif "category_warning" in cat_result:
+                            warnings.append(cat_result["category_warning"])
 
                 # Wait for entity to reflect the update
                 wait_bool = coerce_bool_param(wait, "wait", default=True)
-                response: dict[str, Any] = {
-                    "success": True,
-                    "action": "update",
-                    "helper_type": helper_type,
-                    "entity_id": entity_id,
-                    "updated_data": updated_data,
-                    "message": f"Successfully updated {helper_type}: {entity_id}",
-                }
                 if wait_bool:
                     try:
                         registered = await wait_for_entity_registered(client, entity_id)
                         if not registered:
-                            response["warning"] = (
+                            warnings.append(
                                 f"Update applied but {entity_id} not yet queryable."
                             )
                     except Exception as e:
-                        response["warning"] = (
-                            f"Update applied but verification failed: {e}"
-                        )
-                return response
+                        warnings.append(f"Update applied but verification failed: {e}")
+
+                return _helper_response(
+                    "update",
+                    helper_type,
+                    data=updated_data,
+                    entity_id=entity_id,
+                    message=f"Successfully updated {helper_type}: {entity_id}",
+                    warnings=warnings,
+                )
 
             # This should never be reached since action is either "create" or "update"
             raise_tool_error(

{ha_mcp_dev-7.5.0.dev517 → ha_mcp_dev-7.5.0.dev518/src/ha_mcp_dev.egg-info}/PKG-INFO

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