ha-mcp-dev 8.6.0.dev2839__tar.gz → 8.6.0.dev2844__tar.gz

{ha_mcp_dev-8.6.0.dev2839 → ha_mcp_dev-8.6.0.dev2844}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2839
+Version: 8.6.0.dev2844
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-8.6.0.dev2839 → ha_mcp_dev-8.6.0.dev2844}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2839"
+version = "8.6.0.dev2844"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-8.6.0.dev2839 → ha_mcp_dev-8.6.0.dev2844}/pyproject.toml.orig

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

ha_mcp_dev-8.6.0.dev2844/src/ha_mcp/policy/server_channels.py

@@ -0,0 +1,112 @@
+"""The approval-response channel's connections, opened as the server's client.
+
+``HomeAssistantSmartMCPServer._apply_tool_security_policies`` binds these to
+the server and hands them to ``ApprovalResponseListener``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+async def approval_ws_client(server: Any) -> Any:
+    """Return a WebSocket client that authenticates as ``server.client``."""
+    # Imported at call time: the WebSocket stack is only needed once a
+    # gated call is actually announced, which may never happen.
+    from ..client.websocket_client import get_websocket_client
+
+    # Keyed to the credentials the announcement itself goes out
+    # with, the way ``HomeAssistantClient.send_websocket_message``
+    # does it. In OAuth mode ``server.client`` is a proxy resolving to
+    # the current request's client, while the global settings hold
+    # only the ``oauth-mode-token`` placeholder -- so an
+    # unparameterised call would authenticate the response
+    # subscription as nobody, and a request could be announced over
+    # REST on a channel that can never carry the answer back.
+    # Read once, and catch the miss explicitly: a per-attribute
+    # ``getattr`` with a default would swallow an AttributeError
+    # raised anywhere INSIDE the OAuth proxy's resolution, hand
+    # back None, and silently authenticate as the placeholder the
+    # whole change exists to avoid. Three separate reads would also
+    # be three separate resolutions, with nothing tying them to one
+    # client. A client with no credentials at all is the token
+    # deployments' normal case: pooled default connection.
+    client = server.client
+    url: str | None
+    token: str | None
+    verify_ssl: bool | None
+    try:
+        url = client.base_url
+        token = client.token
+        verify_ssl = client.verify_ssl
+    except AttributeError:
+        logger.debug(
+            "policy decisions: %s exposes no per-request credentials; "
+            "opening the approval-response channel on the pooled "
+            "default connection",
+            type(client).__name__,
+            exc_info=True,
+        )
+        url = token = verify_ssl = None
+    return await get_websocket_client(url=url, token=token, verify_ssl=verify_ssl)
+
+
+async def emit_approval_result_as(
+    server: Any,
+    token: str,
+    decision: str,
+    *,
+    applied: bool,
+    reason: str,
+    tool_name: str | None = None,
+) -> None:
+    from ..client.rest_client import HomeAssistantClient
+    from .events import emit_approval_result
+
+    # Credentials read the way ``approval_ws_client`` reads them,
+    # and for the same reason: this runs in a bus handler, not in a
+    # request, so in OAuth mode ``server.client`` resolves to nobody
+    # and the proxy raises rather than handing back a usable client.
+    # A fresh REST client over the snapshot keeps the result going
+    # out as the same identity the request was announced with.
+    client = server.client
+    url: str | None
+    token_value: str | None
+    verify_ssl: bool | None
+    known_is_admin: bool | None
+    admin_route_refused: bool
+    try:
+        url = client.base_url
+        token_value = client.token
+        verify_ssl = client.verify_ssl
+        known_is_admin = client.known_is_admin
+        admin_route_refused = client.admin_route_refused is True
+    except Exception:
+        logger.debug(
+            "policy decisions: no credentials for the result event; "
+            "the decision itself is unaffected",
+            exc_info=True,
+        )
+        return
+    # Owned here, so closed here: this client is built per event and
+    # carries its own httpx connection pool, which nothing else will
+    # ever reclaim. A wrong PIN retried by a chatty automation would
+    # otherwise open one per attempt.
+    async with HomeAssistantClient(
+        url,
+        token_value,
+        verify_ssl=verify_ssl,
+        is_admin=known_is_admin,
+        admin_route_refused=admin_route_refused,
+    ) as result_client:
+        await emit_approval_result(
+            result_client,
+            token,
+            decision,
+            applied=applied,
+            reason=reason,
+            tool_name=tool_name,
+        )

{ha_mcp_dev-8.6.0.dev2839 → ha_mcp_dev-8.6.0.dev2844}/src/ha_mcp/server.py

@@ -10,6 +10,7 @@ Implements lazy initialization pattern for improved startup time:
 from __future__ import annotations
 
 import logging
+from functools import partial
 from pathlib import Path
 from typing import TYPE_CHECKING, Annotated, Any, ClassVar
 
@@ -1264,7 +1265,7 @@ class HomeAssistantSmartMCPServer:
         except Exception:
             logger.exception("Failed to apply tool search transform")
 
-    def _apply_tool_security_policies(self) -> None:  # noqa: PLR0915
+    def _apply_tool_security_policies(self) -> None:
         """Register the tool security policies middleware (#966).
 
         Opt-in via ``ENABLE_TOOL_SECURITY_POLICIES``. When enabled, every
@@ -1311,6 +1312,10 @@ class HomeAssistantSmartMCPServer:
             from .policy.middleware import PolicyMiddleware
             from .policy.model import Policy
             from .policy.persistence import load_policy
+            from .policy.server_channels import (
+                approval_ws_client,
+                emit_approval_result_as,
+            )
             from .utils.data_paths import get_data_dir
         except ImportError:
             logger.exception(
@@ -1330,114 +1335,15 @@ class HomeAssistantSmartMCPServer:
             # roundtrip of a gated tool call.
             return load_policy(data_dir)
 
-        async def _approval_ws_client() -> Any:
-            # Imported at call time, like the rest of this block: the
-            # WebSocket stack is only needed once a gated call is actually
-            # announced, which may never happen.
-            from .client.websocket_client import get_websocket_client
-
-            # Keyed to the credentials the announcement itself goes out
-            # with, the way ``HomeAssistantClient.send_websocket_message``
-            # does it. In OAuth mode ``self.client`` is a proxy resolving to
-            # the current request's client, while the global settings hold
-            # only the ``oauth-mode-token`` placeholder -- so an
-            # unparameterised call would authenticate the response
-            # subscription as nobody, and a request could be announced over
-            # REST on a channel that can never carry the answer back.
-            # Read once, and catch the miss explicitly: a per-attribute
-            # ``getattr`` with a default would swallow an AttributeError
-            # raised anywhere INSIDE the OAuth proxy's resolution, hand
-            # back None, and silently authenticate as the placeholder the
-            # whole change exists to avoid. Three separate reads would also
-            # be three separate resolutions, with nothing tying them to one
-            # client. A client with no credentials at all is the token
-            # deployments' normal case: pooled default connection.
-            client = self.client
-            url: str | None
-            token: str | None
-            verify_ssl: bool | None
-            try:
-                url = client.base_url
-                token = client.token
-                verify_ssl = client.verify_ssl
-            except AttributeError:
-                logger.debug(
-                    "policy decisions: %s exposes no per-request credentials; "
-                    "opening the approval-response channel on the pooled "
-                    "default connection",
-                    type(client).__name__,
-                    exc_info=True,
-                )
-                url = token = verify_ssl = None
-            return await get_websocket_client(
-                url=url, token=token, verify_ssl=verify_ssl
-            )
-
         # Reads the same policy file as the middleware, so the toggle that
         # opens this channel is the one the user flips in the settings UI,
         # with no restart in between.
-        async def _emit_approval_result(
-            token: str,
-            decision: str,
-            *,
-            applied: bool,
-            reason: str,
-            tool_name: str | None = None,
-        ) -> None:
-            from .client.rest_client import HomeAssistantClient
-            from .policy.events import emit_approval_result
-
-            # Credentials read the way ``_approval_ws_client`` reads them,
-            # and for the same reason: this runs in a bus handler, not in a
-            # request, so in OAuth mode ``self.client`` resolves to nobody
-            # and the proxy raises rather than handing back a usable client.
-            # A fresh REST client over the snapshot keeps the result going
-            # out as the same identity the request was announced with.
-            client = self.client
-            url: str | None
-            token_value: str | None
-            verify_ssl: bool | None
-            known_is_admin: bool | None
-            admin_route_refused: bool
-            try:
-                url = client.base_url
-                token_value = client.token
-                verify_ssl = client.verify_ssl
-                known_is_admin = client.known_is_admin
-                admin_route_refused = client.admin_route_refused is True
-            except Exception:
-                logger.debug(
-                    "policy decisions: no credentials for the result event; "
-                    "the decision itself is unaffected",
-                    exc_info=True,
-                )
-                return
-            # Owned here, so closed here: this client is built per event and
-            # carries its own httpx connection pool, which nothing else will
-            # ever reclaim. A wrong PIN retried by a chatty automation would
-            # otherwise open one per attempt.
-            async with HomeAssistantClient(
-                url,
-                token_value,
-                verify_ssl=verify_ssl,
-                is_admin=known_is_admin,
-                admin_route_refused=admin_route_refused,
-            ) as result_client:
-                await emit_approval_result(
-                    result_client,
-                    token,
-                    decision,
-                    applied=applied,
-                    reason=reason,
-                    tool_name=tool_name,
-                )
-
         self.approval_response_listener = ApprovalResponseListener(
             policy_provider=_policy_provider,
             queue=self.approval_queue,
             data_dir=data_dir,
-            get_ws_client=_approval_ws_client,
-            emit_result=_emit_approval_result,
+            get_ws_client=partial(approval_ws_client, self),
+            emit_result=partial(emit_approval_result_as, self),
         )
 
         try:

{ha_mcp_dev-8.6.0.dev2839 → ha_mcp_dev-8.6.0.dev2844}/src/ha_mcp/tools/bulk_selector.py

@@ -654,7 +654,34 @@ async def _load_hidden_entities(
     return visibility_hidden | registry_hidden, warnings
 
 
-async def resolve_bulk_selector(  # noqa: PLR0915
+def _build_operation_common(
+    action: str,
+    parameters: dict[str, Any] | None,
+    timeout_seconds: float | None,
+    validate_first: bool,
+) -> dict[str, Any]:
+    """Build the fields every resolved operation row shares."""
+    operation_common: dict[str, Any] = {
+        "action": action,
+        "validate_first": validate_first,
+    }
+    if parameters is not None:
+        # Deep copy, not the caller's own object by reference (and not a
+        # shallow `dict(...)`, which stops only top-level rebinding and
+        # still shares nested values like an `rgb_color` list): the
+        # per-row copy in BulkSelectorResolution.operations protects each
+        # DISPATCH row from cross-row mutation, but does nothing about the
+        # resolution's own stored copy -- without this, a caller that
+        # still holds `parameters` and mutates it (at any depth) after
+        # this call returns would silently rewrite the "frozen"
+        # resolution's own payload too.
+        operation_common["parameters"] = copy.deepcopy(parameters)
+    if timeout_seconds is not None:
+        operation_common["timeout_seconds"] = timeout_seconds
+    return operation_common
+
+
+async def resolve_bulk_selector(
     client: HomeAssistantClient,
     selector: Mapping[str, Any],
     *,
@@ -825,23 +852,9 @@ async def resolve_bulk_selector(  # noqa: PLR0915
             f"The selector resolved to {len(resolved_entity_ids)} entities; "
             f"the maximum is {MAX_SELECTOR_ENTITIES}"
         )
-    operation_common: dict[str, Any] = {
-        "action": action,
-        "validate_first": validate_first,
-    }
-    if parameters is not None:
-        # Deep copy, not the caller's own object by reference (and not a
-        # shallow `dict(...)`, which stops only top-level rebinding and
-        # still shares nested values like an `rgb_color` list): the
-        # per-row copy in BulkSelectorResolution.operations protects each
-        # DISPATCH row from cross-row mutation, but does nothing about the
-        # resolution's own stored copy -- without this, a caller that
-        # still holds `parameters` and mutates it (at any depth) after
-        # this call returns would silently rewrite the "frozen"
-        # resolution's own payload too.
-        operation_common["parameters"] = copy.deepcopy(parameters)
-    if timeout_seconds is not None:
-        operation_common["timeout_seconds"] = timeout_seconds
+    operation_common = _build_operation_common(
+        action, parameters, timeout_seconds, validate_first
+    )
     excluded_and_hidden = effective_excluded & hidden
     hidden_count = len(directly_hidden | hidden_selected | excluded_and_hidden)
     warnings: list[str] = list(visibility_warnings)

ha_mcp_dev-8.6.0.dev2844/src/ha_mcp/tools/device_enrichment.py

@@ -0,0 +1,133 @@
+"""Best-effort radio enrichment for ha_get_device single-device results."""
+
+import logging
+from typing import Any
+
+from ..client.rest_client import HomeAssistantAPIError, HomeAssistantConnectionError
+
+logger = logging.getLogger(__name__)
+
+
+async def enrich_zha_metrics(
+    client: Any, device_info: dict[str, Any], warnings: list[str]
+) -> None:
+    """Fetch ZHA radio metrics (LQI/RSSI) and add to device_info in-place.
+
+    Enrichment is best-effort, but a skipped fetch is named in ``warnings`` so
+    a device answered without ``radio_metrics`` is distinguishable from one
+    whose radio genuinely reports none (#1947).
+    """
+    try:
+        zha_result = await client.send_websocket_message({"type": "zha/devices"})
+        if zha_result.get("success"):
+            zha_by_ieee = {
+                d.get("ieee"): d for d in zha_result.get("result", []) if d.get("ieee")
+            }
+            zha_dev = zha_by_ieee.get(device_info["ieee_address"])
+            if zha_dev:
+                device_info["radio_metrics"] = {
+                    "lqi": zha_dev.get("lqi"),
+                    "rssi": zha_dev.get("rssi"),
+                }
+        else:
+            warnings.append(
+                f"ZHA radio metrics unavailable: {zha_result.get('error') or 'request failed'}"
+            )
+    except (
+        HomeAssistantConnectionError,
+        HomeAssistantAPIError,
+        TimeoutError,
+        OSError,
+    ) as e:
+        logger.warning(
+            "Could not fetch ZHA radio metrics for device %s: %s",
+            device_info.get("device_id"),
+            e,
+        )
+        warnings.append(f"ZHA radio metrics unavailable: {e}")
+
+
+async def enrich_zwave_status(
+    client: Any, device_id: str, device_info: dict[str, Any], warnings: list[str]
+) -> None:
+    """Fetch Z-Wave node status and add to device_info in-place.
+
+    Best-effort like the ZHA metrics, and named in ``warnings`` on failure for
+    the same reason (#1947).
+    """
+    try:
+        zwave_result = await client.send_websocket_message(
+            {"type": "zwave_js/node_status", "device_id": device_id}
+        )
+        if zwave_result.get("success"):
+            node_data = zwave_result.get("result", {})
+            device_info["node_status"] = {
+                "node_id": node_data.get("node_id"),
+                "status": node_data.get("status"),
+                "is_routing": node_data.get("is_routing"),
+                "is_secure": node_data.get("is_secure"),
+                "highest_security_class": node_data.get("highest_security_class"),
+                "zwave_plus_version": node_data.get("zwave_plus_version"),
+                "is_controller_node": node_data.get("is_controller_node"),
+            }
+        else:
+            warnings.append(
+                f"Z-Wave node status unavailable: {zwave_result.get('error') or 'request failed'}"
+            )
+    except (
+        HomeAssistantConnectionError,
+        HomeAssistantAPIError,
+        TimeoutError,
+        OSError,
+    ) as e:
+        logger.warning(
+            "Could not fetch Z-Wave node status for device %s: %s",
+            device_info.get("device_id"),
+            e,
+        )
+        warnings.append(f"Z-Wave node status unavailable: {e}")
+
+
+async def enrich_matter_diagnostics(
+    client: Any, device_id: str, device_info: dict[str, Any], warnings: list[str]
+) -> None:
+    """Fetch Matter node diagnostics and add to device_info in-place.
+
+    Mirrors enrich_zwave_status: surfaces the Matter equivalent of Z-Wave node
+    status — network type (wifi/thread), reachability, IPs and joined fabrics,
+    and names a skipped fetch in ``warnings`` (#1947).
+    """
+    try:
+        result = await client.send_websocket_message(
+            {"type": "matter/node_diagnostics", "device_id": device_id}
+        )
+        if result.get("success"):
+            data = result.get("result", {})
+            device_info["node_diagnostics"] = {
+                "network_type": data.get("network_type"),
+                "node_type": data.get("node_type"),
+                "available": data.get("available"),
+                "network_name": data.get("network_name"),
+                # Upstream NodeDiagnostics misspells the field "ip_adresses"
+                # (single d); read that key but surface it correctly.
+                "ip_addresses": data.get("ip_adresses"),
+                "mac_address": data.get("mac_address"),
+                "active_fabrics": data.get("active_fabrics"),
+                "active_fabric_index": data.get("active_fabric_index"),
+            }
+        else:
+            warnings.append(
+                f"Matter node diagnostics unavailable: {result.get('error') or 'request failed'}"
+            )
+    except (
+        HomeAssistantConnectionError,
+        HomeAssistantAPIError,
+        TimeoutError,
+        OSError,
+    ) as e:
+        logger.warning(
+            "Could not fetch Matter node diagnostics for device %s: %s",
+            device_info.get("device_id"),
+            e,
+        )
+        warnings.append(f"Matter node diagnostics unavailable: {e}")

ha_mcp_dev-8.6.0.dev2844/src/ha_mcp/tools/entity_update_fields.py

@@ -0,0 +1,68 @@
+"""Builders for the config/entity_registry/update message of ha_set_entity."""
+
+from typing import Any
+
+from .helpers import clearable_value
+
+
+def build_name_visibility_fields(
+    message: dict[str, Any],
+    updates_made: list[str],
+    area_id: str | None,
+    name: str | None,
+    icon: str | None,
+    device_class: str | None,
+) -> None:
+    """Add basic positioning/appearance fields to the update message."""
+    if area_id is not None:
+        area_id = clearable_value(area_id, "area_id")
+        message["area_id"] = area_id
+        updates_made.append(f"area_id='{area_id}'" if area_id else "area cleared")
+    if name is not None:
+        name = clearable_value(name, "name")
+        message["name"] = name
+        updates_made.append(f"name='{name}'" if name else "name cleared")
+    if icon is not None:
+        icon = clearable_value(icon, "icon")
+        message["icon"] = icon
+        updates_made.append(f"icon='{icon}'" if icon else "icon cleared")
+    if device_class is not None:
+        device_class = clearable_value(device_class, "device_class")
+        message["device_class"] = device_class
+        updates_made.append(
+            f"device_class='{device_class}'" if device_class else "device_class cleared"
+        )
+
+
+def build_state_tag_fields(
+    message: dict[str, Any],
+    updates_made: list[str],
+    enabled: bool | None,
+    hidden: bool | None,
+    parsed_aliases: list[str | None] | None,
+    parsed_categories: dict[str, str | None] | None,
+    final_labels: list[str] | None,
+    label_operation: str,
+    parsed_labels: list[str] | None,
+) -> None:
+    """Add enabled/hidden/alias/category/label fields to the update message."""
+    if enabled is not None:
+        message["disabled_by"] = None if enabled else "user"
+        updates_made.append("enabled" if enabled else "disabled")
+    if hidden is not None:
+        message["hidden_by"] = "user" if hidden else None
+        updates_made.append("hidden" if hidden else "visible")
+    if parsed_aliases is not None:
+        message["aliases"] = parsed_aliases
+        updates_made.append(f"aliases={parsed_aliases}")
+    if parsed_categories is not None:
+        message["categories"] = parsed_categories
+        updates_made.append(f"categories={parsed_categories}")
+    if final_labels is not None:
+        message["labels"] = final_labels
+        if label_operation == "set":
+            updates_made.append(f"labels={final_labels}")
+        elif label_operation == "add":
+            updates_made.append(f"labels added: {parsed_labels} -> {final_labels}")
+        else:  # remove
+            updates_made.append(f"labels removed: {parsed_labels} -> {final_labels}")

{ha_mcp_dev-8.6.0.dev2839 → ha_mcp_dev-8.6.0.dev2844}/src/ha_mcp/tools/helpers.py

@@ -250,6 +250,49 @@ def validate_identifier_not_empty(
     )
 
 
+WHITESPACE_CLEARS_NOTE = (
+    "A whitespace-only value acts like '', for clients that cannot send an "
+    "empty string."
+)
+_QUOTE_ONLY = re.compile(r"[\s\"'‘’“”]+")
+
+
+def clear_hint(param_name: str) -> str:
+    return (
+        f"To clear {param_name}, pass an empty string '', or a single space ' ' "
+        "if your client cannot send an empty string"
+    )
+
+
+def clearable_value(
+    value: str | None,
+    param_name: str,
+    *,
+    hint: str | None = None,
+) -> str | None:
+    """Map an empty or whitespace-only value to None, the registry's clear value.
+
+    Other values are returned stripped. A model whose client cannot send ``''``
+    falls back to ``'""'`` (#2585); a value made only of quotes and whitespace
+    is never a real value, so reject it.
+    """
+    if value is None:
+        return None
+    value = value.strip()
+    if not value:
+        return None
+    if _QUOTE_ONLY.fullmatch(value):
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"{param_name} {value!r} contains only quote characters and whitespace",
+                suggestions=[hint or clear_hint(param_name)],
+                context={"parameter": param_name, "value": value},
+            )
+        )
+    return value
+
+
 async def get_connected_ws_client(
     base_url: str, token: str, verify_ssl: bool | None = None
 ) -> tuple[HomeAssistantWebSocketClient | None, dict[str, Any] | None]: