ha-mcp-dev 8.6.0.dev2894__tar.gz → 8.6.0.dev2897__tar.gz

{ha_mcp_dev-8.6.0.dev2894 → ha_mcp_dev-8.6.0.dev2897}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2894
+Version: 8.6.0.dev2897
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien
@@ -318,6 +318,12 @@ If the original entry has been deleted, restore recreates the helper and reports
 <!-- TOOLS_TABLE_END -->
 </details>
 
+Z-Wave configuration values can be read through `ha_manage_radio` with
+`action="get_config_params"` or `action="get_config_param"`, even when their
+configuration entities are disabled or absent. Reads use the Z-Wave JS cache
+by default; a single full root parameter can explicitly request a device read.
+See [parameter reads, freshness, and examples](docs/zwave-parameter-reads.md).
+
 ---
 
 ## 🆚 ha-mcp vs. Home Assistant's built-in MCP Server

{ha_mcp_dev-8.6.0.dev2894 → ha_mcp_dev-8.6.0.dev2897}/README.md

@@ -258,6 +258,12 @@ If the original entry has been deleted, restore recreates the helper and reports
 <!-- TOOLS_TABLE_END -->
 </details>
 
+Z-Wave configuration values can be read through `ha_manage_radio` with
+`action="get_config_params"` or `action="get_config_param"`, even when their
+configuration entities are disabled or absent. Reads use the Z-Wave JS cache
+by default; a single full root parameter can explicitly request a device read.
+See [parameter reads, freshness, and examples](docs/zwave-parameter-reads.md).
+
 ---
 
 ## 🆚 ha-mcp vs. Home Assistant's built-in MCP Server

{ha_mcp_dev-8.6.0.dev2894 → ha_mcp_dev-8.6.0.dev2897}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2894"
+version = "8.6.0.dev2897"
 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.dev2894 → ha_mcp_dev-8.6.0.dev2897}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2894"
+version = "8.6.0.dev2897"
 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.dev2894 → ha_mcp_dev-8.6.0.dev2897}/src/ha_mcp/read_only.py

@@ -229,7 +229,8 @@ def _radio_write(args: dict[str, Any]) -> str | None:
     action = args.get("action")
     # Reads (allowed): per-node diagnostics, the integration/network summary,
     # the active reachability probe, a single Zigbee cluster-attribute read, and
-    # the Thread dataset listing. Everything else is a write — commission/add,
+    # the Thread dataset listing, and Z-Wave configuration-parameter reads
+    # (cache or explicit device request). Everything else is a write — commission/add,
     # remove, reinterview, firmware, fabric/credential/channel/network changes,
     # plus the two actions that LOOK read-ish but are not: zigbee network_backup
     # (creates a backup artifact + key material, like ha_manage_backup's blocked
@@ -241,6 +242,8 @@ def _radio_write(args: dict[str, Any]) -> str | None:
         "ping",
         "cluster_read",
         "list_datasets",
+        "get_config_params",
+        "get_config_param",
     ):
         return None
     return f"action={action!r}"
@@ -251,7 +254,8 @@ def _radio_write(args: dict[str, Any]) -> str | None:
 # APIs; energy prefs and assist pipelines are reachable only through
 # these tools; edit-backup listing exists nowhere else; the saved-tools
 # cache is only listable here; ha_manage_radio's 'ping' probe, 'cluster_read'
-# and 'list_datasets' have no pure-read duplicate elsewhere, while its
+# 'list_datasets', 'get_config_params' and 'get_config_param' have no pure-read
+# duplicate elsewhere, while its
 # 'diagnostics'/'network_status' reads mirror ha_get_device /
 # ha_get_system_health but stay reachable here mid-management;
 # ha_manage_security_policy's policy read is duplicated only by the
@@ -300,7 +304,8 @@ READ_ONLY_EXEMPT_TOOLS: dict[str, ReadOnlyExemption] = {
         "node diagnostics ('diagnostics'), the integration/network summary "
         "('network_status'), the active reachability probe ('ping'), a Zigbee "
         "cluster-attribute read ('cluster_read'), and the Thread dataset "
-        "listing ('list_datasets')",
+        "listing ('list_datasets'), and Z-Wave parameter reads "
+        "('get_config_params' / 'get_config_param', including explicit refresh)",
     ),
     # Update listing/details exist only here — ha_get_updates was merged
     # into this tool (issue #1726), so hiding it would remove the read

{ha_mcp_dev-8.6.0.dev2894 → ha_mcp_dev-8.6.0.dev2897}/src/ha_mcp/tools/config_helpers/update.py

@@ -317,10 +317,26 @@ async def _execute_zone_config_update(
     longitude: float | None,
     radius: float | None,
     passive: bool | None,
+    icon: str | None,
 ) -> dict[str, Any]:
     """Update a zone entity via zone/update."""
+    item_icon = None
+    if icon is not None:
+        listed = await client.send_websocket_message({"type": "zone/list"})
+        if not listed.get("success"):
+            raise_tool_error(
+                create_error_response(
+                    ws_failure_code(listed),
+                    f"Failed to read zone config: {listed.get('error', 'Unknown error')}",
+                    context=_simple_helper_error_context("zone", entity_id=entity_id),
+                )
+            )
+        stored: dict[str, Any] = next(
+            (z for z in listed.get("result") or [] if z.get("id") == unique_id), {}
+        )
+        item_icon = _zone_item_icon(stored, icon, entity_id)
     update_msg = _zone_update_message(
-        unique_id, name, latitude, longitude, radius, passive
+        unique_id, name, latitude, longitude, radius, passive, item_icon
     )
     result = await client.send_websocket_message(update_msg)
     if not result.get("success"):
@@ -431,6 +447,7 @@ async def _execute_config_store_update(
             kw.get("longitude"),
             kw.get("radius"),
             kw.get("passive"),
+            icon,
         )
     return await _execute_standard_helper_update(
         client, helper_type, entity_id, unique_id, name, icon, **kw
@@ -764,6 +781,7 @@ def _zone_update_message(
     longitude: float | None,
     radius: float | None,
     passive: bool | None,
+    icon: str | None = None,
     **_: Any,
 ) -> dict[str, Any]:
     fields = {
@@ -772,6 +790,7 @@ def _zone_update_message(
         "longitude": longitude,
         "radius": radius,
         "passive": passive,
+        "icon": icon,
     }
     return {
         "type": "zone/update",
@@ -780,6 +799,34 @@ def _zone_update_message(
     }
 
 
+def _zone_item_icon(
+    stored: dict[str, Any], icon: str | None, entity_id: str
+) -> str | None:
+    """The icon to write into a zone's stored item, ``None`` to leave it.
+
+    The zone entity shows the registry icon over the item's, and Core's zone
+    update merges into the item and rejects an empty or null icon, so an icon
+    stored there can never be removed. A new icon therefore goes into the item
+    only when it already holds one, which keeps it from showing again once the
+    registry override is cleared; otherwise the registry alone carries it and
+    stays clearable. Clearing an icon the item holds is refused.
+    """
+    if not stored.get("icon"):
+        return None
+    if icon == "":
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"The icon of {entity_id} cannot be removed: the zone's stored "
+                f"icon ({stored['icon']}) is kept by Home Assistant's zone update "
+                "and would show again.",
+                context=_simple_helper_error_context("zone", entity_id=entity_id),
+                suggestions=["Set a different icon instead of an empty one"],
+            )
+        )
+    return icon
+
+
 def _tag_update_message(
     item_id: str, name: str | None, description: str | None = None, **_: Any
 ) -> dict[str, Any]:
@@ -803,7 +850,7 @@ def _build_update_message(
     if helper_type == "person":
         return _person_update_message(unique_id, existing, name, **kw)
     if helper_type == "zone":
-        return _zone_update_message(unique_id, name, **kw)
+        return _zone_update_message(unique_id, name, icon=icon, **kw)
     if helper_type == "tag":
         return _tag_update_message(unique_id, name, **kw)
     return _build_standard_update_message(
@@ -835,8 +882,11 @@ async def _update_via_component(
     item = await read_helper_item(client, helper_type, **target)
     if item is None:
         return None
+    message_icon = icon
+    if helper_type == "zone":
+        message_icon = _zone_item_icon(item["item"], icon, entity_id)
     message = _build_update_message(
-        helper_type, item["item_id"], item["item"], name, icon, **kw
+        helper_type, item["item_id"], item["item"], name, message_icon, **kw
     )
     registry = {
         key: value

{ha_mcp_dev-8.6.0.dev2894 → ha_mcp_dev-8.6.0.dev2897}/src/ha_mcp/tools/radio/base.py

@@ -17,6 +17,7 @@ firmware installs).
 from __future__ import annotations
 
 import logging
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -66,22 +67,61 @@ def require(args: dict[str, Any], spec: ActionSpec, radio: str, action: str) ->
 
 
 async def ws_call(
-    client: Any, ws_type: str, *, context: dict[str, Any] | None = None, **fields: Any
+    client: Any,
+    ws_type: str,
+    *,
+    context: dict[str, Any] | None = None,
+    on_error: Callable[[dict[str, Any], dict[str, Any]], None] | None = None,
+    **fields: Any,
 ) -> Any:
     """Send a WebSocket command and return its ``result``; raise on failure.
 
     Mirrors the ``send_websocket_message`` usage in the ``ha_get_device``
-    enrichers. Raises ToolError (SERVICE_CALL_FAILED) when HA reports the
-    command failed, attaching the command type and any caller context.
+    enrichers. Failed replies retain HA's error code, command type and caller
+    context, with recovery suggestions for common failures. ``on_error`` may
+    raise a command-specific error before the shared mapping runs.
     """
     message = {"type": ws_type, **{k: v for k, v in fields.items() if v is not None}}
     result = await client.send_websocket_message(message)
     if not result.get("success"):
+        ha_code = result.get("error_code")
+        error_context = {"ws_type": ws_type, **(context or {})}
+        if ha_code is not None:
+            error_context["ha_error_code"] = ha_code
+        if on_error is not None:
+            on_error(result, error_context)
+        domain = ws_type.split("/", 1)[0]
+        recovery = {
+            "unauthorized": (
+                ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
+                "Use a Home Assistant administrator connection for this radio command",
+            ),
+            "not_found": (
+                ErrorCode.RESOURCE_NOT_FOUND,
+                "Verify the device or config-entry ID using ha_get_device or ha_get_integration",
+            ),
+            "not_loaded": (
+                ErrorCode.SERVICE_CALL_FAILED,
+                f"Load/configure the {domain} integration and check that its driver is ready",
+            ),
+            "unknown_command": (
+                ErrorCode.SERVICE_CALL_FAILED,
+                f"Check that the {domain} integration is configured and this Home Assistant version supports the command",
+            ),
+        }.get(ha_code)
+        error_message = result.get("error", f"WebSocket command '{ws_type}' failed")
+        if ha_code == "not_loaded":
+            error_message = f"The {domain} integration is not loaded: {error_message}"
+        elif ha_code == "unknown_command":
+            error_message = (
+                f"The {domain} integration or command is unavailable: {error_message}"
+            )
         raise_tool_error(
             create_error_response(
-                ErrorCode.SERVICE_CALL_FAILED,
-                result.get("error", f"WebSocket command '{ws_type}' failed"),
-                context={"ws_type": ws_type, **(context or {})},
+                recovery[0] if recovery else ErrorCode.SERVICE_CALL_FAILED,
+                error_message,
+                context=error_context,
+                suggestions=[recovery[1]] if recovery else result.get("suggestions"),
             )
         )
     return result.get("result")

{ha_mcp_dev-8.6.0.dev2894 → ha_mcp_dev-8.6.0.dev2897}/src/ha_mcp/tools/radio/zwave.py

@@ -6,6 +6,9 @@ non-interactive inclusion / exclusion, re-interview, mesh route rebuilds,
 configuration-parameter writes, firmware install, and the network-wiping
 controller hard reset.
 
+Configuration-parameter reads use the node's Z-Wave JS values, independently
+of enabled Home Assistant entities.
+
 Node-scoped actions key on ``device_id``; controller-scoped actions resolve the
 single ``zwave_js`` config entry via ``resolve_entry_id``. Interactive S2 secure
 inclusion (the read-the-PIN handshake) is *not* scriptable here — provide
@@ -18,6 +21,7 @@ from typing import Any
 
 from ...errors import ErrorCode, create_error_response
 from ..helpers import raise_tool_error
+from . import zwave_parameters
 from .base import (
     ActionSpec,
     integration_not_found,
@@ -83,6 +87,17 @@ SUPPORTED: dict[str, ActionSpec] = {
         "Set a Z-Wave configuration parameter on a node.",
         required=("device_id", "property", "value"),
     ),
+    "get_config_params": ActionSpec(
+        "List cached configuration parameters and metadata, including endpoints "
+        "and partial parameters, without requiring configuration entities.",
+        required=("device_id",),
+    ),
+    "get_config_param": ActionSpec(
+        "Read a cached parameter (params.property, optional endpoint/property_key). "
+        "params.refresh=True requests a raw device read of a full root parameter; "
+        "endpoint/partial refresh is not supported by HA's raw-read API.",
+        required=("device_id", "property"),
+    ),
     "firmware_update": ActionSpec(
         "Install a pending firmware update for a Z-Wave node via its update entity.",
         long_running=True,
@@ -105,6 +120,9 @@ async def handle(client: Any, action: str, args: dict[str, Any]) -> dict[str, An
     """Execute one Z-Wave action (validation/confirm already applied by caller)."""
     device_id = args.get("device_id")
 
+    if action in ("get_config_params", "get_config_param"):
+        return await zwave_parameters.read(client, action, args)
+
     if action == "diagnostics":
         node = (
             await ws_call(

ha_mcp_dev-8.6.0.dev2897/src/ha_mcp/tools/radio/zwave_parameters.py

@@ -0,0 +1,220 @@
+"""Entity-independent reads through Home Assistant's Z-Wave JS API."""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+from ...client.rest_client import (
+    HomeAssistantCommandTimeout,
+    HomeAssistantConnectionError,
+)
+from ...errors import ErrorCode, create_error_response
+from ..helpers import exception_to_structured_error, raise_tool_error
+from .base import ok, ws_call
+
+
+def _invalid(message: str) -> NoReturn:
+    raise_tool_error(
+        create_error_response(ErrorCode.VALIDATION_INVALID_PARAMETER, message)
+    )
+
+
+def _integer(args: dict[str, Any], name: str, minimum: int, maximum: int) -> None:
+    value = args.get(name)
+    if type(value) is not int or not minimum <= value <= maximum:
+        _invalid(f"params.{name} must be an integer between {minimum} and {maximum}")
+
+
+def _validate(action: str, args: dict[str, Any]) -> bool:
+    """Validate read arguments before traffic; return whether refresh was requested."""
+    device_id = args["device_id"]
+    if not isinstance(device_id, str) or not device_id.strip():
+        _invalid("device_id must be a non-empty Home Assistant device ID")
+    refresh = args.get("refresh", False)
+    if not isinstance(refresh, bool):
+        _invalid("params.refresh must be a boolean")
+    if action == "get_config_params" and refresh:
+        _invalid(
+            "get_config_params is cache-only; use get_config_param to refresh one parameter"
+        )
+    if action == "get_config_param":
+        _integer(args, "property", 0, 65535)
+        if "endpoint" in args:
+            _integer(args, "endpoint", 0, 127)
+        if args.get("property_key") is not None:
+            _integer(args, "property_key", 1, 0xFFFFFFFF)
+        if refresh and (
+            args.get("endpoint", 0) != 0 or args.get("property_key") is not None
+        ):
+            _invalid(
+                "HA's raw-read API cannot refresh endpoint or partial parameters; use a cached read"
+            )
+
+    return refresh
+
+
+def _no_raw_value(context: dict[str, Any], details: str | None = None) -> NoReturn:
+    message = (
+        "Device parameter read failed without a value (HA unknown_error); no cached fallback was used"
+        if context.get("ha_error_code") == "unknown_error"
+        else "Device parameter read returned no value; no cached fallback was used"
+    )
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            message,
+            details=details,
+            context=context,
+            suggestions=[
+                "Verify that the parameter number is supported by this device",
+                "Check node availability or wake a sleeping device before retrying",
+                "Inspect Home Assistant logs if the failure persists; unknown_error does not identify the cause",
+            ],
+        )
+    )
+
+
+def _raw_read_error(reply: dict[str, Any], context: dict[str, Any]) -> None:
+    # HA reports unknown_error when the raw client asserts on an empty result;
+    # the code can also mean another upstream failure, so preserve its details.
+    if reply.get("error_code") == "unknown_error":
+        _no_raw_value(context, reply.get("error"))
+
+
+async def _read_raw(client: Any, device_id: str, property_: int) -> Any:
+    context: dict[str, Any] = {
+        "radio": "zwave",
+        "action": "get_config_param",
+        "ws_type": "zwave_js/get_raw_config_parameter",
+        "device_id": device_id,
+        "property": property_,
+        "refresh_requested": True,
+    }
+    try:
+        raw = await ws_call(
+            client,
+            context["ws_type"],
+            device_id=device_id,
+            property=property_,
+            context=context,
+            on_error=_raw_read_error,
+        )
+    except (HomeAssistantCommandTimeout, HomeAssistantConnectionError) as error:
+        # The REST bridge wraps its command deadline in a connection error.
+        # A socket failure without that cause must remain a transport failure.
+        if isinstance(error, HomeAssistantCommandTimeout) or isinstance(
+            error.__cause__, HomeAssistantCommandTimeout
+        ):
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.TIMEOUT_WEBSOCKET,
+                    "Device parameter read did not answer before the command timeout; "
+                    "no cached fallback was used. The Get may still be queued until the node wakes",
+                    context=context,
+                    suggestions=[
+                        "Wake/check the device and allow any queued Get to finish before retrying"
+                    ],
+                )
+            )
+        exception_to_structured_error(error, context=context)
+    if not isinstance(raw, dict) or raw.get("value") is None:
+        _no_raw_value(context)
+    return raw["value"]
+
+
+async def read(client: Any, action: str, args: dict[str, Any]) -> dict[str, Any]:
+    """Read cached values, or explicitly request one root parameter from the device."""
+    refresh = _validate(action, args)
+    device_id = args["device_id"]
+
+    parameters = await ws_call(
+        client,
+        "zwave_js/get_config_parameters",
+        device_id=device_id,
+        context={"device_id": device_id},
+    )
+    if not isinstance(parameters, dict):
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                "HA returned an invalid configuration-parameter response",
+                context={"device_id": device_id},
+            )
+        )
+    if action == "get_config_params":
+        return ok(
+            "zwave",
+            action,
+            device_id=device_id,
+            parameters=parameters,
+            source="cache",
+            refresh_requested=False,
+        )
+
+    property_ = args["property"]
+    endpoint = args.get("endpoint", 0)
+    property_key = args.get("property_key")
+    matches = [
+        {"value_id": value_id, **parameter}
+        for value_id, parameter in parameters.items()
+        if parameter.get("property") == property_
+        and parameter.get("endpoint") == endpoint
+        and parameter.get("property_key") == property_key
+    ]
+    if len(matches) > 1:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                "HA returned multiple matching configuration parameters",
+                context={"device_id": device_id, "property": property_},
+            )
+        )
+    if not refresh and not matches:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.RESOURCE_NOT_FOUND,
+                "Configuration parameter not found in the Z-Wave JS cache",
+                context={
+                    "device_id": device_id,
+                    "property": property_,
+                    "endpoint": endpoint,
+                    "property_key": property_key,
+                },
+                suggestions=[
+                    "Use get_config_params to inspect available endpoints and property_key bit masks",
+                    "For a full root parameter, request params.refresh=True to query the device",
+                ],
+            )
+        )
+
+    parameter = (
+        matches[0]
+        if matches
+        else {
+            "property": property_,
+            "endpoint": 0,
+            "property_key": None,
+            "metadata": None,
+        }
+    )
+    if refresh:
+        parameter = {
+            **parameter,
+            "value": await _read_raw(client, device_id, property_),
+        }
+
+    result = ok(
+        "zwave",
+        action,
+        device_id=device_id,
+        parameter=parameter,
+        source="device_request" if refresh else "cache",
+        refresh_requested=refresh,
+    )
+    if parameter.get("value") is None:
+        result["warnings"] = [
+            "Z-Wave JS has no cached value for this parameter; the device was not queried"
+        ]
+    if refresh and matches:
+        result["metadata_source"] = "cache"
+    return result

{ha_mcp_dev-8.6.0.dev2894 → ha_mcp_dev-8.6.0.dev2897}/src/ha_mcp/tools/tools_config_helpers.py

@@ -679,7 +679,7 @@ class HelperConfigTools:
         icon: Annotated[
             str | None,
             Field(
-                description="Material Design Icon (e.g., 'mdi:bell'); '' or ' ' clears it",
+                description="Material Design Icon (e.g., 'mdi:bell'); '' or ' ' clears it, except a zone's stored icon (the icon in the zone's own config, set at creation or by ha_set_zone; ha_get_zone shows it), which cannot be removed",
                 default=None,
             ),
         ] = None,

{ha_mcp_dev-8.6.0.dev2894 → ha_mcp_dev-8.6.0.dev2897}/src/ha_mcp/tools/tools_radio.py

@@ -136,7 +136,10 @@ class RadioTools:
             JSON_STRING_COERCION,
             Field(
                 description=(
-                    "Action-specific parameters (e.g. code, pin, channel, property, value)."
+                    "Action-specific parameters (e.g. code, pin, channel, property, value). "
+                    "Z-Wave get_config_param: property (parameter number), endpoint "
+                    "(default 0), property_key (partial-parameter bit mask), refresh "
+                    "(default False; full root parameters only)."
                 ),
                 default=None,
             ),
@@ -155,17 +158,20 @@ class RadioTools:
     ) -> dict[str, Any]:
         """Manage Home Assistant radios — Z-Wave, Zigbee, Matter, and Thread.
 
-        For read-only inspection prefer ha_get_device / ha_get_system_health,
-        which mirror the 'diagnostics' and 'network_status' actions; use this
-        tool for writes and the active 'ping' probe (unique to this tool). Write
-        actions perform inclusion/commissioning, removal, healing,
+        For node diagnostics and network summaries prefer ha_get_device /
+        ha_get_system_health, which mirror 'diagnostics' and 'network_status'.
+        This tool also exposes active 'ping' probes and parameter reads.
+        Z-Wave 'get_config_params' lists cached configuration values/metadata;
+        'get_config_param' reads one from the cache or explicitly from the device.
+        Neither enables or creates entities. Write actions perform
+        inclusion/commissioning, removal, healing,
         reconfiguration, firmware updates and credential provisioning.
 
         Caveats: long-running actions (inclusion, rebuild routes, firmware) start the
         operation and return immediately with long_running=true; completion
         happens out-of-band. Interactive Z-Wave S2 secure inclusion (read-the-
         PIN pairing) is not scriptable — use SmartStart/QR provisioning here or
-        the HA UI.
+        the HA UI. HA administrator access is required for parameter reads.
         """
         try:
             handler = HANDLERS[radio]