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

{ha_mcp_dev-7.5.0.dev516/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.dev516
+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.dev516 → 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.dev516"
+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.dev516 → ha_mcp_dev-7.5.0.dev518}/src/ha_mcp/tools/tools_config_helpers.py

@@ -867,6 +867,69 @@ def _validate_numeric_range(
             )
 
 
+def _validate_initial_in_options(
+    options: Any, initial: Any, helper_type: str = "input_select"
+) -> None:
+    """Reject ``initial`` values not in ``options``.
+
+    Called from both create and update branches with the resolved values —
+    caller-supplied on create, merged with the existing config on update.
+    ``initial=None`` is the unset case and passes through. The
+    ``isinstance(options, list)`` early-return mirrors the defensive shape
+    check in ``_validate_input_select_options`` below — both validators are
+    invariant gates, not type contracts; a future non-list caller is
+    silently skipped rather than raising a confusing ``TypeError`` on
+    ``initial not in options``.
+    """
+    if not isinstance(options, list) or initial is None:
+        return
+    if initial not in options:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"initial={initial!r} must be one of options "
+                f"{options!r} for {helper_type}.",
+                context=_simple_helper_error_context(
+                    helper_type,
+                    initial=initial,
+                    options=options,
+                ),
+                suggestions=[
+                    "Pick an `initial` value that's in `options`.",
+                    "Or omit `initial` to use the default or existing value.",
+                ],
+            )
+        )
+
+
+def _validate_datetime_has_date_or_time(
+    has_date: bool | None, has_time: bool | None
+) -> None:
+    """Reject ``input_datetime`` payloads where both components are False.
+
+    Treats ``None`` as "not constrained" — only the explicit (False, False)
+    case is flagged, since that's what reaches HA as the broken-entity
+    payload. Both the create and update branches call this with the
+    resolved-after-merge ``has_date`` / ``has_time`` pair.
+    """
+    if has_date is False and has_time is False:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                "At least one of has_date or has_time must be True for input_datetime",
+                context=_simple_helper_error_context(
+                    "input_datetime",
+                    has_date=has_date,
+                    has_time=has_time,
+                ),
+                suggestions=[
+                    "Set has_date=True to keep the date component.",
+                    "Set has_time=True to keep the time component.",
+                ],
+            )
+        )
+
+
 def _validate_input_select_options(options: Any) -> None:
     """Reject input_select option lists containing duplicates (Bug 17, issue #1150).
 
@@ -1409,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,
@@ -1562,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 —
@@ -1617,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=[])
@@ -1640,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(
@@ -2398,28 +2540,12 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                             )
                         )
                     message["options"] = options
-                    # Bug 4a (issue #1150): if `initial` was passed but isn't
-                    # one of the options, reject explicitly instead of silently
-                    # dropping. The previous `if initial and initial in options`
-                    # check stripped invalid initials with `success: true`.
+                    # If `initial` was passed but isn't one of the options,
+                    # reject explicitly instead of silently dropping. Shared
+                    # with the update branch via the helper so the same
+                    # invariant fires on both code paths.
+                    _validate_initial_in_options(options, initial)
                     if initial is not None:
-                        if initial not in options:
-                            raise_tool_error(
-                                create_error_response(
-                                    ErrorCode.VALIDATION_INVALID_PARAMETER,
-                                    f"initial={initial!r} must be one of options "
-                                    f"{options!r} for input_select.",
-                                    context=_simple_helper_error_context(
-                                        helper_type,
-                                        initial=initial,
-                                        options=options,
-                                    ),
-                                    suggestions=[
-                                        "Pick an `initial` value that's in `options`.",
-                                        "Or omit `initial` so the entity starts unset.",
-                                    ],
-                                )
-                            )
                         message["initial"] = initial
 
                 elif helper_type == "input_number":
@@ -2477,15 +2603,12 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                         message["has_date"] = has_date
                         message["has_time"] = has_time
 
-                    # Validate that at least one is True
-                    if not message["has_date"] and not message["has_time"]:
-                        raise_tool_error(
-                            create_error_response(
-                                ErrorCode.VALIDATION_INVALID_PARAMETER,
-                                "At least one of has_date or has_time must be True for input_datetime",
-                                context=_simple_helper_error_context(helper_type),
-                            )
-                        )
+                    # Validate that at least one is True — shared with the
+                    # update branch via the helper so the same invariant
+                    # fires on both code paths.
+                    _validate_datetime_has_date_or_time(
+                        message["has_date"], message["has_time"]
+                    )
 
                     if initial is not None:
                         message["initial"] = initial
@@ -2616,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:
@@ -2624,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}"
                             )
 
@@ -2647,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:
@@ -2658,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(
@@ -2728,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.
@@ -2762,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
@@ -3048,6 +3202,14 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                                 if initial is not None
                                 else existing.get("initial")
                             )
+                            # Parity with the create-branch guard. Resolves to
+                            # (new options, new initial) / (new options, old
+                            # initial) / (old options, new initial) — any
+                            # combination that excludes initial from the final
+                            # options list is caught.
+                            _validate_initial_in_options(
+                                update_msg["options"], initial_val
+                            )
                             if initial_val is not None:
                                 update_msg["initial"] = initial_val
 
@@ -3140,6 +3302,14 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                                 if has_time is not None
                                 else existing.get("has_time", False)
                             )
+                            # Parity with the create-branch guard. A merge
+                            # that resolves to (False, False) — caller
+                            # disabling the one component the existing entity
+                            # had — would otherwise write a broken-entity
+                            # payload and surface HA's cryptic generic error.
+                            _validate_datetime_has_date_or_time(
+                                update_msg["has_date"], update_msg["has_time"]
+                            )
                             initial_val = (
                                 initial
                                 if initial is not None
@@ -3230,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
@@ -3287,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.dev516 → 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.dev516
+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