ha-mcp-dev 7.5.0.dev595__tar.gz → 7.5.0.dev596__tar.gz

{ha_mcp_dev-7.5.0.dev595/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev596}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev595"
+version = "7.5.0.dev596"
 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.dev595 → ha_mcp_dev-7.5.0.dev596}/src/ha_mcp/tools/tools_integrations.py

@@ -7,7 +7,7 @@ integrations (config entries) via the REST and WebSocket APIs.
 
 import asyncio
 import logging
-from typing import Annotated, Any, Literal, cast, get_args
+from typing import Annotated, Any, Literal, get_args
 
 from fastmcp.exceptions import ToolError
 from fastmcp.tools import tool
@@ -459,27 +459,18 @@ class IntegrationTools:
             include_diagnostics_bool = coerce_bool_param(
                 include_diagnostics, "include_diagnostics", default=False
             )
-            include_subentries_bool = cast(
-                bool,
-                coerce_bool_param(
-                    include_subentries, "include_subentries", default=False
-                ),
+            include_subentries_bool = coerce_bool_param(
+                include_subentries, "include_subentries", default=False
             )
-            include_subentry_schema_bool = cast(
-                bool,
-                coerce_bool_param(
-                    include_subentry_schema,
-                    "include_subentry_schema",
-                    default=False,
-                ),
+            include_subentry_schema_bool = coerce_bool_param(
+                include_subentry_schema,
+                "include_subentry_schema",
+                default=False,
             )
-            show_advanced_options_bool = cast(
-                bool,
-                coerce_bool_param(
-                    show_advanced_options,
-                    "show_advanced_options",
-                    default=False,
-                ),
+            show_advanced_options_bool = coerce_bool_param(
+                show_advanced_options,
+                "show_advanced_options",
+                default=False,
             )
             exact_match_bool = coerce_bool_param(
                 exact_match, "exact_match", default=True
@@ -1316,8 +1307,7 @@ class IntegrationTools:
             context={"helper_type": helper_type},
         )
 
-        # default=True guarantees a non-None return; cast for mypy.
-        wait_bool = cast(bool, coerce_bool_param(wait, "wait", default=True))
+        wait_bool = coerce_bool_param(wait, "wait", default=True)
         warnings: list[str] = []
 
         # === Routing dispatch ===

{ha_mcp_dev-7.5.0.dev595 → ha_mcp_dev-7.5.0.dev596}/src/ha_mcp/tools/tools_search.py

@@ -30,6 +30,9 @@ from .util_helpers import (
     public_fields,
     result_fields_warning,
 )
+from .util_helpers import (
+    project_entity_record as _project_entity,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -166,85 +169,6 @@ async def _exact_match_search(
     }
 
 
-def _project_entity(
-    record: dict[str, Any],
-    fields: list[str] | None,
-    attribute_keys: list[str] | None,
-) -> tuple[dict[str, Any], str | None]:
-    """Apply optional field projection to a HA entity record.
-
-    ``fields`` filters which top-level keys to keep (e.g. ["state", "attributes"]).
-    ``attribute_keys`` further filters the ``attributes`` sub-dict.
-    Both default None = full payload (no-op).
-
-    Returns ``(projected_record, warning_string | None)``.  *warning_string* is
-    non-None when ``attribute_keys`` was specified, the original ``attributes``
-    dict was non-empty, and the filter produced an empty result — i.e. the caller
-    supplied only unknown attribute keys (typo guard).  Callers should append the
-    warning to the response ``warnings`` list so the user receives a diagnostic
-    rather than a silently empty ``attributes: {}``.
-
-    Both parameters are already parsed into ``list[str] | None`` — string/CSV inputs
-    must be normalised at the call site via ``parse_string_list_param`` (see
-    ``ha_get_state`` which parses once before the bulk loop to avoid re-parsing per
-    entity record).
-
-    Unlike ``project_fields``, this helper does not auto-retain ``success`` — entity
-    records have no ``success`` field, so the asymmetry is intentional.
-
-    Non-dict ``attributes`` handling: when ``attribute_keys`` is set but the
-    record's ``attributes`` value is not a dict (``None``, a string, a list —
-    rare from HA's state API but possible from malformed records, partial
-    error payloads, or mocked fixtures), the key-set filter cannot be
-    applied and the ``attributes`` value is returned unchanged. A
-    ``warning``-level log line records the short-circuit so it is visible
-    at default log levels. The bulk path shares this helper, so
-    both single- and bulk-entity calls behave identically here. This is
-    deliberately silent (no caller-facing warning) because malformed
-    ``attributes`` is rare and the call still produces a usable record.
-    """
-    if not isinstance(record, dict):
-        return (
-            record,
-            None,
-        )  # non-dict (e.g. error path returning None) — skip projection
-    if fields is not None:
-        keep = set(fields)
-        record = {k: v for k, v in record.items() if k in keep}
-    attr_warn: str | None = None
-    if attribute_keys is not None:
-        attrs = record.get("attributes")
-        if isinstance(attrs, dict):
-            attr_keep = set(attribute_keys)
-            filtered_attrs = {k: v for k, v in attrs.items() if k in attr_keep}
-            # Typo guard: if the original had keys AND the caller specified at least
-            # one key AND the filter yielded nothing, the caller likely mistyped an
-            # attribute name.  Return a diagnostic so the agent gets
-            # "attributes came out empty — available: [...]" instead of silently
-            # receiving ``attributes: {}``.
-            # Exclude the attribute_keys=[] case — an empty list is an explicit
-            # "keep nothing" request, not a typo.
-            if attrs and attribute_keys and not filtered_attrs:
-                available = sorted(attrs.keys())
-                attr_warn = (
-                    f"attribute_keys {sorted(attribute_keys)!r} matched no attribute "
-                    f"keys — attributes came out empty. "
-                    f"Available keys: {available!r}"
-                )
-            record = {**record, "attributes": filtered_attrs}
-        elif "attributes" in record:
-            # ``attributes`` is present but not a dict — filter cannot apply.
-            # Log at warning so the no-op is visible at default log levels
-            # (this branch is exercised rarely; see docstring for rationale).
-            logger.warning(
-                "_project_entity: attribute_keys filter skipped — "
-                "'attributes' is %s (expected dict) for record keys=%r",
-                type(attrs).__name__,
-                list(record.keys()),
-            )
-    return record, attr_warn
-
-
 def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     """Register search and discovery tools with the MCP server."""
     smart_tools = kwargs.get("smart_tools")
@@ -1564,8 +1488,8 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         """
         # Parse search_types to handle JSON string input from MCP clients
         parsed_search_types = parse_string_list_param(search_types, "search_types")
-        include_config_bool = (
-            coerce_bool_param(include_config, "include_config", default=False) or False
+        include_config_bool = coerce_bool_param(
+            include_config, "include_config", default=False
         )
         exact_match_bool = coerce_bool_param(exact_match, "exact_match", default=True)
         try:

{ha_mcp_dev-7.5.0.dev595 → ha_mcp_dev-7.5.0.dev596}/src/ha_mcp/tools/tools_service.py

@@ -23,7 +23,14 @@ from .helpers import (
     raise_tool_error,
     register_tool_methods,
 )
-from .util_helpers import coerce_bool_param, parse_json_param, wait_for_state_change
+from .util_helpers import (
+    coerce_bool_param,
+    compact_service_result,
+    parse_json_param,
+    parse_string_list_param,
+    project_entity_record,
+    wait_for_state_change,
+)
 
 
 def _parse_json_dict_param(
@@ -215,6 +222,62 @@ class ServiceTools:
                 f"Service executed but state verification failed: {e}"
             )
 
+    @staticmethod
+    def _project_service_result(
+        result: Any,
+        *,
+        entity_id: str | None,
+        verbose: bool,
+        fields: list[str] | None,
+        attribute_keys: list[str] | None,
+    ) -> tuple[Any, list[str]]:
+        """Apply compact / explicit projection to a service-call ``result``.
+
+        Issue #1446. Precedence:
+
+        - ``verbose=True``: bypass every transformation; return ``result`` as-is.
+        - Explicit ``fields`` or ``attribute_keys``: apply per-record projection
+          via ``project_entity_record`` to every record. No compaction; this is
+          the power-user path.
+        - Default: apply ``compact_service_result`` (filter to ``entity_id``
+          record when single string, drop top-level metadata + heavy lists).
+
+        Returns ``(projected, warnings)``. ``warnings`` collects per-record
+        typo-guard diagnostics from ``project_entity_record`` (e.g. all-empty
+        ``attribute_keys`` filter) — deduplicated so an N-record list with the
+        same typo doesn't emit N copies of the same warning.
+        """
+        if verbose:
+            return result, []
+        if fields is None and attribute_keys is None:
+            return compact_service_result(result, entity_id), []
+        if not isinstance(result, list):
+            return result, []
+        warnings: list[str] = []
+        # ``result_attribute_keys`` only takes effect when ``attributes`` is in
+        # the projected ``result_fields`` (or ``result_fields`` is None). Surface
+        # a warning rather than silently ignoring the parameter — mirrors
+        # ha_get_state's attribute_keys_no_effect handling.
+        if (
+            attribute_keys is not None
+            and fields is not None
+            and "attributes" not in fields
+        ):
+            warnings.append(
+                "result_attribute_keys was ignored because 'attributes' is not "
+                "in result_fields. Add 'attributes' to result_fields (or omit "
+                "result_fields) to apply result_attribute_keys."
+            )
+        projected: list[Any] = []
+        seen_warnings: set[str] = set()
+        for record in result:
+            new_record, warn = project_entity_record(record, fields, attribute_keys)
+            projected.append(new_record)
+            if warn and warn not in seen_warnings:
+                seen_warnings.add(warn)
+                warnings.append(warn)
+        return projected, warnings
+
     @tool(
         name="ha_call_service",
         tags={"Service & Device Control"},
@@ -229,6 +292,43 @@ class ServiceTools:
         data: str | dict[str, Any] | None = None,
         return_response: bool | str = False,
         wait: bool | str = True,
+        verbose: Annotated[
+            bool | str,
+            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). "
+                    "WARNING: brings back token-bloat for nested-group targets — "
+                    "prefer result_fields / result_attribute_keys for targeted control."
+                ),
+            ),
+        ] = False,
+        result_fields: Annotated[
+            str | list[str] | None,
+            Field(
+                default=None,
+                description=(
+                    "Project each record in 'result' to only these top-level keys "
+                    "(e.g. ['entity_id', 'state']). Mirrors ha_get_state's fields=. "
+                    "Setting this DISABLES default compaction — no entity-id filter, "
+                    "no metadata strip — and applies the explicit projection instead."
+                ),
+            ),
+        ] = None,
+        result_attribute_keys: Annotated[
+            str | list[str] | None,
+            Field(
+                default=None,
+                description=(
+                    "Project each record's 'attributes' dict to only these keys "
+                    "(e.g. ['brightness', 'rgb_color']). Mirrors ha_get_state's "
+                    "attribute_keys=. Setting this DISABLES default compaction. "
+                    "Requires 'attributes' to be present in result_fields (or "
+                    "result_fields=None)."
+                ),
+            ),
+        ] = None,
     ) -> dict[str, Any]:
         """
         Execute Home Assistant services to control entities and trigger automations.
@@ -252,15 +352,15 @@ class ServiceTools:
         ha_call_service("homeassistant", "toggle", entity_id="switch.porch_light")
         ```
 
-        **Parameters:**
-        - **domain**: Service domain (light, climate, automation, etc.)
-        - **service**: Service name (turn_on, set_temperature, trigger, etc.)
-        - **entity_id**: Optional target entity. For some services (e.g., light.turn_off), omitting this targets all entities in the domain
-        - **data**: Optional dict of service-specific parameters
-        - **return_response**: Set to True for services that return data
-        - **wait**: Wait for the entity state to change after the service call (default: True).
-          Only applies to state-changing services on a single entity. Set to False for
-          fire-and-forget calls, bulk operations, or services without observable state changes.
+        **Key behavior:**
+        - **wait** (default True): wait for the entity state to change before
+          returning. Only applies to state-changing services on a single entity.
+        - **Result compaction (issue #1446, default ON)**: ``result`` is trimmed
+          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 detailed service documentation, use ha_get_skill_guide.**
 
@@ -271,11 +371,30 @@ class ServiceTools:
             service_data = self._parse_service_data(data, entity_id)
 
             # Coerce return_response boolean parameter
-            return_response_bool = (
-                coerce_bool_param(return_response, "return_response", default=False)
-                or False
+            return_response_bool = coerce_bool_param(
+                return_response, "return_response", default=False
             )
             wait_bool = coerce_bool_param(wait, "wait", default=True)
+            try:
+                verbose_bool = coerce_bool_param(verbose, "verbose", default=False)
+            except ValueError as e:
+                raise_tool_error(create_validation_error(str(e), parameter="verbose"))
+            try:
+                parsed_result_fields = parse_string_list_param(
+                    result_fields, "result_fields", allow_csv=True
+                )
+            except ValueError as e:
+                raise_tool_error(
+                    create_validation_error(str(e), parameter="result_fields")
+                )
+            try:
+                parsed_result_attribute_keys = parse_string_list_param(
+                    result_attribute_keys, "result_attribute_keys", allow_csv=True
+                )
+            except ValueError as e:
+                raise_tool_error(
+                    create_validation_error(str(e), parameter="result_attribute_keys")
+                )
 
             # Determine if we should wait for state change:
             # Only for state-changing services on a single entity, not for
@@ -296,15 +415,25 @@ class ServiceTools:
                 domain, service, service_data, return_response=return_response_bool
             )
 
+            projected_result, projection_warnings = self._project_service_result(
+                result,
+                entity_id=entity_id,
+                verbose=verbose_bool,
+                fields=parsed_result_fields,
+                attribute_keys=parsed_result_attribute_keys,
+            )
+
             response: dict[str, Any] = {
                 "success": True,
                 "domain": domain,
                 "service": service,
                 "entity_id": entity_id,
                 "parameters": data,
-                "result": result,
+                "result": projected_result,
                 "message": f"Successfully executed {domain}.{service}",
             }
+            if projection_warnings:
+                response.setdefault("warnings", []).extend(projection_warnings)
 
             # If return_response was requested, include the service_response key prominently
             if return_response_bool and isinstance(result, dict):

{ha_mcp_dev-7.5.0.dev595 → ha_mcp_dev-7.5.0.dev596}/src/ha_mcp/tools/tools_system.py

@@ -65,7 +65,11 @@ class SystemTools:
     @tool(
         name="ha_check_config",
         tags={"System"},
-        annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Check Configuration"},
+        annotations={
+            "idempotentHint": True,
+            "readOnlyHint": True,
+            "title": "Check Configuration",
+        },
     )
     @log_tool_usage
     async def ha_check_config(self) -> dict[str, Any]:
@@ -142,22 +146,24 @@ class SystemTools:
         instead, which reloads specific components without a full restart.
         """
         # Coerce boolean parameter that may come as string from XML-style calls
-        confirm_bool = coerce_bool_param(confirm, "confirm", default=False) or False
+        confirm_bool = coerce_bool_param(confirm, "confirm", default=False)
 
         if not confirm_bool:
-            raise_tool_error(create_error_response(
-                ErrorCode.VALIDATION_INVALID_PARAMETER,
-                "Restart not confirmed",
-                details=(
-                    "You must set confirm=True to restart Home Assistant. "
-                    "This is a safety measure to prevent accidental restarts."
-                ),
-                suggestions=[
-                    "Run ha_check_config() first to validate configuration",
-                    "Call ha_restart(confirm=True) to proceed with restart",
-                    "Consider using ha_reload_core() for config-only changes",
-                ],
-            ))
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    "Restart not confirmed",
+                    details=(
+                        "You must set confirm=True to restart Home Assistant. "
+                        "This is a safety measure to prevent accidental restarts."
+                    ),
+                    suggestions=[
+                        "Run ha_check_config() first to validate configuration",
+                        "Call ha_restart(confirm=True) to proceed with restart",
+                        "Consider using ha_reload_core() for config-only changes",
+                    ],
+                )
+            )
 
         restart_initiated = False
         try:
@@ -165,15 +171,17 @@ class SystemTools:
             config_result = await self._client.check_config()
             if config_result.get("result") != "valid":
                 errors = config_result.get("errors") or []
-                raise_tool_error(create_error_response(
-                    ErrorCode.CONFIG_INVALID,
-                    "Configuration is invalid - restart aborted",
-                    details=(
-                        "Home Assistant configuration has errors. "
-                        "Fix the errors before restarting."
-                    ),
-                    context={"config_errors": errors},
-                ))
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.CONFIG_INVALID,
+                        "Configuration is invalid - restart aborted",
+                        details=(
+                            "Home Assistant configuration has errors. "
+                            "Fix the errors before restarting."
+                        ),
+                        context={"config_errors": errors},
+                    )
+                )
 
             # Call the restart service - mark as initiated before the call
             # as the connection may be closed before we get a response
@@ -199,8 +207,7 @@ class SystemTools:
             # Connection errors after restart initiated are expected
             # (HA closes connections during restart)
             if restart_initiated and any(
-                pattern in error_msg.lower()
-                for pattern in ("connect", "closed", "504")
+                pattern in error_msg.lower() for pattern in ("connect", "closed", "504")
             ):
                 return {
                     "success": True,
@@ -272,12 +279,17 @@ class SystemTools:
         target = target.lower().strip()
 
         if target not in RELOAD_TARGETS:
-            raise_tool_error(create_error_response(
-                ErrorCode.VALIDATION_INVALID_PARAMETER,
-                f"Invalid reload target: {target}",
-                context={"target": target, "valid_targets": list(RELOAD_TARGETS.keys())},
-                suggestions=[f"Use one of: {', '.join(RELOAD_TARGETS.keys())}"],
-            ))
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"Invalid reload target: {target}",
+                    context={
+                        "target": target,
+                        "valid_targets": list(RELOAD_TARGETS.keys()),
+                    },
+                    suggestions=[f"Use one of: {', '.join(RELOAD_TARGETS.keys())}"],
+                )
+            )
 
         try:
             if target == "all":
@@ -313,11 +325,13 @@ class SystemTools:
                 service_info = RELOAD_TARGETS[target]
                 if service_info is None:
                     # This shouldn't happen as we check for "all" above
-                    raise_tool_error(create_error_response(
-                        ErrorCode.INTERNAL_ERROR,
-                        f"Invalid target configuration for: {target}",
-                        context={"target": target},
-                    ))
+                    raise_tool_error(
+                        create_error_response(
+                            ErrorCode.INTERNAL_ERROR,
+                            f"Invalid target configuration for: {target}",
+                            context={"target": target},
+                        )
+                    )
                 domain, service = service_info
                 await self._client.call_service(domain, service, {})
 
@@ -343,7 +357,11 @@ class SystemTools:
     @tool(
         name="ha_get_system_health",
         tags={"System", "Zigbee", "Z-Wave", "Integrations"},
-        annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get System Health (incl. ZHA/Z-Wave/integration diagnostics)"},
+        annotations={
+            "idempotentHint": True,
+            "readOnlyHint": True,
+            "title": "Get System Health (incl. ZHA/Z-Wave/integration diagnostics)",
+        },
     )
     @log_tool_usage
     async def ha_get_system_health(
@@ -474,9 +492,7 @@ class SystemTools:
                     ("zha_network", self._fetch_zha_network(ws_client, full=zha_full))
                 )
             if want_zwave:
-                sections.append(
-                    ("zwave_network", self._fetch_zwave_network(ws_client))
-                )
+                sections.append(("zwave_network", self._fetch_zwave_network(ws_client)))
 
             if sections:
                 gathered = await asyncio.gather(
@@ -641,25 +657,32 @@ class SystemTools:
             verify_ssl=self._client.verify_ssl,
         )
         if error or ws_client is None:
-            raise_tool_error(error or create_error_response(
-                ErrorCode.CONNECTION_FAILED,
-                "Failed to connect to Home Assistant WebSocket",
-            ))
+            raise_tool_error(
+                error
+                or create_error_response(
+                    ErrorCode.CONNECTION_FAILED,
+                    "Failed to connect to Home Assistant WebSocket",
+                )
+            )
 
         try:
             _, event_response = await ws_client.send_command_with_event(
                 "system_health/info", wait_timeout=10.0
             )
         except TimeoutError:
-            raise_tool_error(create_error_response(
-                ErrorCode.SERVICE_CALL_FAILED,
-                "Timeout waiting for system health data",
-            ))
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    "Timeout waiting for system health data",
+                )
+            )
         except Exception as e:
-            raise_tool_error(create_error_response(
-                ErrorCode.SERVICE_CALL_FAILED,
-                str(e),
-            ))
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    str(e),
+                )
+            )
 
         health_info = event_response.get("event", {})
         component_count = len(health_info) if isinstance(health_info, dict) else 0
@@ -673,7 +696,6 @@ class SystemTools:
 
         return ws_client, result
 
-
     @staticmethod
     async def _fetch_repairs(
         ws_client: Any, *, include_dismissed: bool = False
@@ -703,9 +725,7 @@ class SystemTools:
             else:
                 err = repairs_result.get("error") or {}
                 err_msg = (
-                    err.get("message")
-                    if isinstance(err, dict)
-                    else str(err)
+                    err.get("message") if isinstance(err, dict) else str(err)
                 ) or "unknown error"
                 logger.warning(
                     "repairs/list_issues returned success=false: %s", err_msg
@@ -717,9 +737,7 @@ class SystemTools:
         return repairs
 
     @staticmethod
-    async def _fetch_zha_network(
-        ws_client: Any, *, full: bool
-    ) -> dict[str, Any]:
+    async def _fetch_zha_network(ws_client: Any, *, full: bool) -> dict[str, Any]:
         """Fetch ZHA Zigbee network device data."""
         ZHA_SUMMARY_LIMIT = 50
         ZHA_FULL_LIMIT = 25