ha-mcp-dev 7.14.2.dev2181__tar.gz → 7.14.2.dev2185__tar.gz

{ha_mcp_dev-7.14.2.dev2181/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.14.2.dev2185}/PKG-INFO

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

{ha_mcp_dev-7.14.2.dev2181 → ha_mcp_dev-7.14.2.dev2185}/pyproject.toml

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

{ha_mcp_dev-7.14.2.dev2181 → ha_mcp_dev-7.14.2.dev2185}/src/ha_mcp/tools/tools_service.py

@@ -151,6 +151,32 @@ _NON_STATE_CHANGING_DOMAINS = {
     "system_log",
 }
 
+#: Emitted when a ``return_response=true`` reply is not HA's
+#: ``{"changed_states": [...], "service_response": ...}`` envelope. Without it an
+#: empty ``result`` reads as an affirmative "no entity states changed" rather than
+#: "the records could not be separated out". Module-level so the tests that
+#: pin the behaviour assert against this exact string instead of a prose fragment
+#: that goes tautologically green when the wording is edited.
+_NON_ENVELOPE_WARNING = (
+    "Home Assistant's return_response reply did not match the expected "
+    "{changed_states, service_response} envelope, so no changed-state records "
+    "could be separated from the response data. An empty 'result' here does NOT "
+    "mean nothing changed — the whole reply is reported under 'service_response'."
+)
+
+#: Emitted when the component served a ``return_response`` call but returned no
+#: ``service_response`` key. The component only sets that key for a non-null
+#: response, so an absent key is ambiguous server-side: the service may genuinely
+#: have returned nothing, or the component may have discarded the response on its
+#: dispatched-but-unconfirmed path. Only raised alongside ``partial`` — the case
+#: where the discard is actually possible — so a plain null response stays quiet.
+_COMPONENT_RESPONSE_UNCONFIRMED_WARNING = (
+    "The service was dispatched but its confirmation did not arrive, and no "
+    "response data came back with it. A null 'service_response' here does NOT "
+    "prove the service returned nothing — the response may have been produced "
+    "and lost with the confirmation. Re-read state to confirm the outcome."
+)
+
 # ``_SERVICE_TO_STATE`` (the service -> expected primary-state map) is the single
 # source of truth in ``util_helpers`` — imported above and shared with the bulk
 # consumer (``device_control``) so both write paths hand the component the same
@@ -343,9 +369,18 @@ class ServiceTools:
         service: str,
         entity_id: str | None,
         data: str | dict[str, Any] | None,
+        *,
+        return_response: bool = False,
     ) -> dict[str, Any]:
-        """Build a partial-success response for service call timeouts."""
-        return {
+        """Build a partial-success response for service call timeouts.
+
+        When ``return_response`` was requested the key is emitted here too, so a
+        caller never has to branch on whether the key exists: every successful
+        reply carries it. It is necessarily null — the reply never arrived — and
+        that null proves nothing about what the service returned, so it comes
+        with the same ambiguity warning the component's unconfirmed path uses.
+        """
+        response: dict[str, Any] = {
             "success": True,
             "partial": True,
             "domain": domain,
@@ -366,6 +401,10 @@ class ServiceTools:
                 "The service was dispatched and may still be executing."
             ],
         }
+        if return_response:
+            response["service_response"] = None
+            response["warnings"].append(_COMPONENT_RESPONSE_UNCONFIRMED_WARNING)
+        return response
 
     async def _capture_initial_state(self, entity_id: str | None) -> str | None:
         """Capture the current state of an entity before a service call."""
@@ -406,6 +445,54 @@ class ServiceTools:
                 f"Service executed but state verification failed: {e}"
             )
 
+    @staticmethod
+    def _split_return_response_envelope(
+        result: Any, *, return_response: bool
+    ) -> tuple[Any, Any, bool, list[str]]:
+        """Split HA's reply into (changed states, response, present, warnings).
+
+        HA answers ``return_response=true`` with an envelope
+        ``{"changed_states": [...], "service_response": ...}``. The response data
+        belongs at the top level of ha_call_service's reply exactly ONCE — the
+        placement the component path (``_build_component_call_response``) already
+        uses — so it is peeled off here, BEFORE projection, leaving only the
+        changed states to project into ``result``. Returning it in both places
+        shipped it twice, byte-identical, doubling its token cost (issue #2085).
+
+        A legitimately null ``service_response`` is still reported as present
+        (``True``) so the caller emits the key.
+
+        With ``return_response`` false there is no envelope to split: HA returns a
+        plain changed-states list, so it passes through untouched and no
+        ``service_response`` key is emitted (``present`` False). That is the
+        overwhelming majority of calls.
+
+        Anything else — a non-dict reply, a missing key, or a ``changed_states``
+        that is not a list — means a non-conforming responder (HA core always
+        sends both keys, with a list). Every such shape takes ONE path: the whole
+        reply becomes the response data, ``result`` stays empty, and a warning
+        says so. Uniformity is the point — peeling a recognised key out of an
+        unrecognised envelope would silently discard whatever else it carried,
+        and an empty ``result`` would otherwise read as an affirmative "no entity
+        states changed". A caller that asked for response data must never get back
+        neither the data nor an explanation.
+        """
+        if not return_response:
+            return result, None, False, []
+        if (
+            isinstance(result, dict)
+            and "service_response" in result
+            and isinstance(result.get("changed_states"), list)
+        ):
+            return result["changed_states"], result["service_response"], True, []
+        # Any other shape is non-conforming. Hand the WHOLE reply back as the
+        # response data rather than guessing which part is which: splitting one
+        # recognised key out of an unrecognised envelope discards the rest (a
+        # non-list ``changed_states`` would vanish entirely) and would make the
+        # warning's "the whole reply is reported under 'service_response'" a lie.
+        # Projecting nothing into ``result`` keeps the records from shipping twice.
+        return [], result, True, [_NON_ENVELOPE_WARNING]
+
     @staticmethod
     def _project_service_result(
         result: Any,
@@ -420,6 +507,10 @@ class ServiceTools:
         Issue #1446. Precedence:
 
         - ``verbose=True``: bypass every transformation; return ``result`` as-is.
+          (``result`` here is always changed-state records, never an envelope:
+          the legacy path splits the envelope off before calling this — see
+          ``_split_return_response_envelope`` — and the component path passes
+          transition ``new_state``s, which are never enveloped to begin with.)
         - Explicit ``fields`` or ``attribute_keys``: apply per-record projection
           via ``project_entity_record`` to every record. No compaction; this is
           the power-user path.
@@ -470,6 +561,7 @@ class ServiceTools:
         service: str,
         entity_id: str | None,
         data: str | dict[str, Any] | None,
+        return_response: bool = False,
     ) -> dict[str, Any]:
         """Handle a HomeAssistantConnectionError raised while calling a service.
 
@@ -481,7 +573,9 @@ class ServiceTools:
         # mean the service was dispatched but HA didn't respond in time.
         # The operation is likely still running (e.g., update.install, long automations).
         if isinstance(error.__cause__, httpx.TimeoutException):
-            return self._build_timeout_response(domain, service, entity_id, data)
+            return self._build_timeout_response(
+                domain, service, entity_id, data, return_response=return_response
+            )
         # Non-timeout connection errors are real failures
         exception_to_structured_error(
             error,
@@ -892,8 +986,23 @@ class ServiceTools:
         }
         if projection_warnings:
             response.setdefault("warnings", []).extend(projection_warnings)
-        if return_response and component_result.get("service_response") is not None:
-            response["service_response"] = component_result["service_response"]
+        if return_response:
+            # Emit the key whenever it was requested, even for a null response —
+            # the legacy path does the same (``_split_return_response_envelope``),
+            # and gating on ``is not None`` made the two paths answer the same
+            # call with different shapes. The component only sets the key for a
+            # non-null response, so a null one arrives as an absent key here.
+            response["service_response"] = component_result.get("service_response")
+            # ...which makes an absent key ambiguous: genuinely-null response, or
+            # one the component produced and dropped with the confirmation on its
+            # dispatched-unconfirmed path. Only the latter is possible when
+            # ``partial``, so warn there rather than on every null.
+            if "service_response" not in component_result and component_result.get(
+                "partial"
+            ):
+                response.setdefault("warnings", []).append(
+                    _COMPONENT_RESPONSE_UNCONFIRMED_WARNING
+                )
         if should_wait:
             if component_result.get("partial"):
                 # Dispatched, but the confirming state_changed did not arrive within
@@ -965,7 +1074,9 @@ class ServiceTools:
             return_response=return_response,
         )
         if isinstance(component_result, _AmbiguousDispatch):
-            return self._build_timeout_response(domain, service, entity_id, data)
+            return self._build_timeout_response(
+                domain, service, entity_id, data, return_response=return_response
+            )
         if component_result is None:
             return None
         return self._build_component_call_response(
@@ -1003,9 +1114,12 @@ class ServiceTools:
             bool,
             Field(
                 description=(
-                    "Return HA's raw service response unchanged (default: False). "
-                    "Use as an escape hatch when you need the full propagation "
-                    "chain or raw attribute payload (debug / inspection). "
+                    "Return HA's raw changed-state records unchanged (default: "
+                    "False). Use as an escape hatch when you need the full "
+                    "propagation chain or raw attribute payload (debug / "
+                    "inspection). With return_response=True the response data "
+                    "still surfaces once as the top-level service_response key, "
+                    "never nested in result. "
                     "WARNING: brings back token-bloat for nested-group targets — "
                     "prefer result_fields / result_attribute_keys for targeted control."
                 ),
@@ -1083,8 +1197,12 @@ class ServiceTools:
           to the targeted entity's record (drops parent-group propagation) and
           stripped of ``context`` / ``last_*`` metadata and heavy attribute
           lists (``effect_list``, ``hue_scenes``). Escape hatches: ``verbose=True``
-          for the raw HA response, or ``result_fields`` / ``result_attribute_keys``
-          for explicit per-record projection (mirrors ``ha_get_state``).
+          for the raw changed-state records, or ``result_fields`` /
+          ``result_attribute_keys`` for explicit per-record projection (mirrors
+          ``ha_get_state``).
+        - **return_response** (default False): the service's response data is
+          returned once, as the top-level ``service_response`` key — never nested
+          inside ``result``, which carries the changed entity states.
 
         **For detailed service documentation, use ha_get_skill_guide.**
 
@@ -1177,6 +1295,15 @@ class ServiceTools:
                 domain, service, service_data, return_response=return_response_bool
             )
 
+            # Peel the return_response envelope apart BEFORE projection so the
+            # response data is emitted once, top-level, and only the changed
+            # states reach ``result`` (issue #2085).
+            result, service_response, has_response_envelope, envelope_warnings = (
+                self._split_return_response_envelope(
+                    result, return_response=return_response_bool
+                )
+            )
+
             projected_result, projection_warnings = self._project_service_result(
                 result,
                 entity_id=entity_id,
@@ -1194,12 +1321,12 @@ class ServiceTools:
                 "result": projected_result,
                 "message": f"Successfully executed {domain}.{service}",
             }
-            if projection_warnings:
-                response.setdefault("warnings", []).extend(projection_warnings)
+            call_warnings = [*projection_warnings, *envelope_warnings]
+            if call_warnings:
+                response.setdefault("warnings", []).extend(call_warnings)
 
-            # If return_response was requested, include the service_response key prominently
-            if return_response_bool and isinstance(result, dict):
-                response["service_response"] = result.get("service_response", result)
+            if has_response_envelope:
+                response["service_response"] = service_response
 
             # Wait for entity state to change
             if should_wait and entity_id is not None:
@@ -1218,6 +1345,10 @@ class ServiceTools:
                 service=service,
                 entity_id=entity_id,
                 data=data,
+                # The parameter, not ``return_response_bool`` — that local is
+                # bound inside the try and would be unbound if the error fired
+                # before it.
+                return_response=return_response,
             )
         except ToolError:
             raise

{ha_mcp_dev-7.14.2.dev2181 → ha_mcp_dev-7.14.2.dev2185}/src/ha_mcp/tools/util_helpers.py

@@ -346,8 +346,9 @@ def compact_service_result(
     3. Drop known-heavy attribute keys (``effect_list``, ``hue_scenes``) from
        every record's ``attributes`` dict.
 
-    Returns ``result`` unchanged when not a list (e.g. dict from
-    ``return_response=True`` services), or when the list is empty.
+    Returns ``result`` unchanged when it is not a list (defensive — every
+    ha_call_service path now projects a changed-state list), or when the list
+    is empty.
     """
     if not isinstance(result, list) or not result:
         return result
@@ -496,6 +497,14 @@ def unwrap_service_response(result: dict[str, Any]) -> dict[str, Any]:
     HA's call_service with return_response wraps results in
     {"changed_states": [...], "service_response": {...}}.
     Returns service_response if present and is a dict, otherwise the original result.
+
+    Deliberately NOT the same rule as ``ServiceTools._split_return_response_envelope``,
+    which powers ha_call_service: that one returns the response whatever its type and
+    reports the whole reply only when the key is absent. The two disagree solely for a
+    NON-DICT ``service_response`` (this helper hands back the envelope, the split hands
+    back the value). Consumers here read component services that always answer with a
+    dict, so the divergence is unreachable — but do not "align" one to the other
+    without checking those ~20 call sites.
     """
     sr = result.get("service_response")
     return sr if isinstance(sr, dict) else result

{ha_mcp_dev-7.14.2.dev2181 → ha_mcp_dev-7.14.2.dev2185/src/ha_mcp_dev.egg-info}/PKG-INFO

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