ha-mcp-dev 7.9.0.dev739__tar.gz → 7.9.0.dev741__tar.gz

{ha_mcp_dev-7.9.0.dev739/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.9.0.dev741}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.9.0.dev739
+Version: 7.9.0.dev741
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -40,7 +40,7 @@ Dynamic: license-file
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-84-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-85-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -211,7 +211,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (84 tools)</b></summary>
+<summary><b>Complete Tool List (85 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -234,6 +234,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs` |
 | **Integrations** | `ha_get_integration`, `ha_get_system_health`, `ha_set_integration_enabled` |
 | **Labels & Categories** | `ha_config_get_category`, `ha_config_get_label`, `ha_config_remove_category`, `ha_config_remove_label`, `ha_config_set_category`, `ha_config_set_label` |
+| **Matter** | `ha_manage_radio` |
 | **Scenes** | `ha_config_get_scene`, `ha_config_remove_scene`, `ha_config_set_scene` |
 | **Scripts** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` |
 | **Search & Discovery** | `ha_get_overview`, `ha_get_state`, `ha_search` |

{ha_mcp_dev-7.9.0.dev739 → ha_mcp_dev-7.9.0.dev741}/README.md

@@ -8,7 +8,7 @@
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-84-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-85-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -179,7 +179,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (84 tools)</b></summary>
+<summary><b>Complete Tool List (85 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -202,6 +202,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs` |
 | **Integrations** | `ha_get_integration`, `ha_get_system_health`, `ha_set_integration_enabled` |
 | **Labels & Categories** | `ha_config_get_category`, `ha_config_get_label`, `ha_config_remove_category`, `ha_config_remove_label`, `ha_config_set_category`, `ha_config_set_label` |
+| **Matter** | `ha_manage_radio` |
 | **Scenes** | `ha_config_get_scene`, `ha_config_remove_scene`, `ha_config_set_scene` |
 | **Scripts** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` |
 | **Search & Discovery** | `ha_get_overview`, `ha_get_state`, `ha_search` |

{ha_mcp_dev-7.9.0.dev739 → ha_mcp_dev-7.9.0.dev741}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.9.0.dev739"
+version = "7.9.0.dev741"
 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.9.0.dev739 → ha_mcp_dev-7.9.0.dev741}/src/ha_mcp/read_only.py

@@ -131,12 +131,37 @@ def _custom_tool_write(args: dict[str, Any]) -> str | None:
     return "sandbox code execution"
 
 
+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,
+    # 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
+    # snapshot create) and thread discover_routers (kicks off a long-running
+    # mDNS scan). A missing action fails closed.
+    if action in (
+        "diagnostics",
+        "network_status",
+        "ping",
+        "cluster_read",
+        "list_datasets",
+    ):
+        return None
+    return f"action={action!r}"
+
+
 # Mixed read/write tools whose read surface has no pure-read duplicate
 # (verified per tool: ha_get_addon cannot proxy-read addon-internal
 # 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). Everything NOT in this table and not
-# ``readOnlyHint=True`` is hidden and blocked outright.
+# cache is only listable here; ha_manage_radio's 'ping' probe, 'cluster_read'
+# and 'list_datasets' 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). Everything
+# NOT in this table and not ``readOnlyHint=True`` is hidden and blocked
+# outright.
 #
 # ``MANDATORY_TOOLS`` (settings_ui/__init__.py) intentionally needs no special
 # case here: every mandatory tool is either ``readOnlyHint=True`` or
@@ -168,6 +193,13 @@ READ_ONLY_EXEMPT_TOOLS: dict[str, ReadOnlyExemption] = {
         _custom_tool_write,
         "listing saved tools (list_saved=True)",
     ),
+    "ha_manage_radio": ReadOnlyExemption(
+        _radio_write,
+        "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')",
+    ),
 }
 
 

ha_mcp_dev-7.9.0.dev741/src/ha_mcp/tools/radio/__init__.py

@@ -0,0 +1,6 @@
+"""Per-radio handler modules for the ``ha_manage_radio`` tool.
+
+Each radio (Z-Wave, Zigbee/ZHA, Matter, Thread) gets its own handler module so
+no single file spans every protocol (keeps modules focused per AGENTS.md). The
+``tools_radio`` module wires them together behind one MCP tool.
+"""

ha_mcp_dev-7.9.0.dev741/src/ha_mcp/tools/radio/base.py

@@ -0,0 +1,183 @@
+"""Shared contract and helpers for ``ha_manage_radio`` per-radio handlers.
+
+A handler module exposes:
+
+- ``SUPPORTED``: ``dict[action_name, ActionSpec]`` describing every action it
+  implements, used for validation, the destructive-confirm gate, and building
+  actionable "unsupported action" errors.
+- ``async def handle(client, action, args) -> dict``: execute one action.
+
+Handlers send raw WebSocket commands through the REST client's
+``send_websocket_message`` bridge (same path the ``ha_get_device`` enrichers
+use), or call services via ``call_service`` for the operations that are
+service-only (most ZHA writes, plus ``zwave_js.ping`` and ``update.install``
+firmware installs).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from ...errors import ErrorCode, create_error_response
+from ..helpers import raise_tool_error
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ActionSpec:
+    """Metadata for one radio action.
+
+    summary: one-line description (surfaced in unsupported-action errors).
+    destructive: requires ``confirm=True`` before it will run.
+    long_running: starts an operation that completes out-of-band (inclusion,
+        rebuild routes, firmware) — the result documents how to follow up.
+    required: parameter names that must be present in ``args`` (or supplied as
+        the top-level ``device_id``).
+    """
+
+    summary: str
+    destructive: bool = False
+    long_running: bool = False
+    required: tuple[str, ...] = field(default_factory=tuple)
+
+
+def ok(radio: str, action: str, **data: Any) -> dict[str, Any]:
+    """Build the standard success envelope for a radio action."""
+    return {"success": True, "radio": radio, "action": action, **data}
+
+
+def require(args: dict[str, Any], spec: ActionSpec, radio: str, action: str) -> None:
+    """Raise VALIDATION_INVALID_PARAMETER if any required arg is missing/empty."""
+    missing = [k for k in spec.required if args.get(k) in (None, "")]
+    if missing:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"{radio}/{action} requires: {', '.join(missing)}",
+                context={"radio": radio, "action": action, "missing": missing},
+                suggestions=[f"Pass {m} (in params or as device_id)" for m in missing],
+            )
+        )
+
+
+async def ws_call(
+    client: Any, ws_type: str, *, context: dict[str, Any] | 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.
+    """
+    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"):
+        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 {})},
+            )
+        )
+    return result.get("result")
+
+
+async def resolve_entry_id(client: Any, domain: str) -> str | None:
+    """Return the config entry_id for a single-instance integration ``domain``.
+
+    Uses ``config_entries/get`` (underscore form; the slash form is rejected as
+    "Unknown command"). Returns None when the integration is not configured.
+    """
+    entries = await ws_call(client, "config_entries/get", context={"domain": domain})
+    for entry in entries or []:
+        if entry.get("domain") == domain:
+            entry_id = entry.get("entry_id")
+            return str(entry_id) if entry_id is not None else None
+    return None
+
+
+async def resolve_update_entity(
+    client: Any, device_id: Any, *, platform: str | None = None
+) -> str:
+    """Return the device's ``update.*`` firmware entity_id from the registry.
+
+    Filters the ``update.*`` entities tied to ``device_id``, preferring the given
+    ``platform`` (e.g. "matter", "zha", "zwave_js") when a device exposes more
+    than one. Raises ENTITY_NOT_FOUND when the device exposes no update entity.
+    """
+    entities = await ws_call(
+        client, "config/entity_registry/list", context={"device_id": device_id}
+    )
+    candidates = [
+        e
+        for e in (entities or [])
+        if e.get("device_id") == device_id
+        and str(e.get("entity_id", "")).startswith("update.")
+    ]
+    if platform is not None:
+        for entity in candidates:
+            if entity.get("platform") == platform:
+                return str(entity["entity_id"])
+    if candidates:
+        return str(candidates[0]["entity_id"])
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.ENTITY_NOT_FOUND,
+            f"No update entity found for device {device_id}; no firmware update is available",
+            context={"device_id": device_id},
+            suggestions=[
+                "Firmware updates appear only when the device exposes an update.* entity",
+                "Check ha_get_device for an 'update.' entity on this device",
+            ],
+        )
+    )
+    raise AssertionError  # py/mixed-returns terminal: raise_tool_error is NoReturn
+
+
+def integration_not_found(radio: str, domain: str) -> dict[str, Any]:
+    """Standard degraded payload when an integration/config-entry is absent.
+
+    For read-only actions (``network_status``) only — reporting the absent
+    integration as a graceful ``success: True`` degradation is correct there.
+    Write/management actions must call ``integration_required`` instead so an
+    unconfigured integration surfaces as an error rather than a silent no-op.
+    """
+    return {
+        "success": True,
+        "radio": radio,
+        "available": False,
+        "warnings": [f"{domain} integration is not configured on this Home Assistant"],
+    }
+
+
+def integration_required(radio: str, domain: str) -> None:
+    """Raise a ToolError when a write action's integration/config-entry is absent.
+
+    The write-action counterpart to ``integration_not_found``: management actions
+    must not report a no-op as ``success: True``, so this raises instead of
+    degrading to an ``available: False`` payload.
+    """
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            f"{domain} integration is not configured on this Home Assistant; "
+            f"cannot run this {radio} management action.",
+            context={"radio": radio, "domain": domain, "available": False},
+            suggestions=[f"Install/configure the {domain} integration first"],
+        )
+    )
+
+
+def confirm_required(radio: str, action: str) -> None:
+    """Raise the ToolError for a destructive action lacking confirm=True."""
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            f"{radio}/{action} is destructive; pass confirm=True to proceed",
+            context={"radio": radio, "action": action, "destructive": True},
+            suggestions=["Re-run with confirm=True once you intend the change"],
+        )
+    )

ha_mcp_dev-7.9.0.dev741/src/ha_mcp/tools/radio/matter.py

@@ -0,0 +1,223 @@
+"""Matter radio handler for ``ha_manage_radio``.
+
+Wraps the Home Assistant ``matter/*`` WebSocket API: per-node diagnostics and
+ping (read), commissioning / multi-admin share-out / fabric removal / interview
+(write), and credential provisioning. All commands are single request/response
+or fire-and-return; Matter has no interactive PIN handshake (unlike Z-Wave S2).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...errors import ErrorCode, create_error_response
+from ..helpers import raise_tool_error
+from .base import (
+    ActionSpec,
+    integration_not_found,
+    ok,
+    resolve_entry_id,
+    resolve_update_entity,
+    ws_call,
+)
+
+SUPPORTED: dict[str, ActionSpec] = {
+    "diagnostics": ActionSpec(
+        "Per-node Matter diagnostics: network type (wifi/thread), availability, "
+        "IPs, node type, active fabrics.",
+        required=("device_id",),
+    ),
+    "network_status": ActionSpec("Matter fabric / integration summary."),
+    "ping": ActionSpec(
+        "Actively ping a Matter node at its known IP addresses.",
+        required=("device_id",),
+    ),
+    "commission": ActionSpec(
+        "Commission a Matter device from a setup code (QR or manual pairing code).",
+        long_running=True,
+        required=("code",),
+    ),
+    "commission_on_network": ActionSpec(
+        "Commission an already-networked Matter device by its PIN.",
+        long_running=True,
+        required=("pin",),
+    ),
+    "share_out": ActionSpec(
+        "Open a commissioning window and return a pairing code so another "
+        "controller can add this device (multi-admin).",
+        required=("device_id",),
+    ),
+    "interview": ActionSpec(
+        "Re-interview a Matter node to refresh its endpoints/clusters.",
+        long_running=True,
+        required=("device_id",),
+    ),
+    "remove_fabric": ActionSpec(
+        "Remove ANOTHER controller's fabric from a Matter node (pass "
+        "params.fabric_index; see active_fabrics in diagnostics). To detach the "
+        "device from Home Assistant itself, delete it with ha_remove_device.",
+        destructive=True,
+        required=("device_id",),
+    ),
+    "set_thread": ActionSpec(
+        "Provide Thread operational credentials used for the next commissioning.",
+        required=("thread_operation_dataset",),
+    ),
+    "set_wifi_credentials": ActionSpec(
+        "Provide WiFi credentials used for the next commissioning.",
+        required=("network_name", "password"),
+    ),
+    "firmware_update": ActionSpec(
+        "Install an available OTA firmware update for this Matter node.",
+        long_running=True,
+        required=("device_id",),
+    ),
+}
+
+
+async def handle(client: Any, action: str, args: dict[str, Any]) -> dict[str, Any]:
+    """Execute one Matter action (validation/confirm already applied by caller)."""
+    device_id = args.get("device_id")
+
+    if action == "diagnostics":
+        diag = await ws_call(
+            client,
+            "matter/node_diagnostics",
+            device_id=device_id,
+            context={"device_id": device_id},
+        )
+        # Upstream NodeDiagnostics misspells the IP field "ip_adresses" (one d);
+        # normalize so callers see the same "ip_addresses" key ha_get_device
+        # surfaces. Copy first so the upstream/result dict is not mutated.
+        if isinstance(diag, dict) and "ip_adresses" in diag:
+            diag = dict(diag)
+            diag["ip_addresses"] = diag.pop("ip_adresses")
+        return ok("matter", "diagnostics", diagnostics=diag)
+
+    if action == "ping":
+        reachability = await ws_call(
+            client,
+            "matter/ping_node",
+            device_id=device_id,
+            context={"device_id": device_id},
+        )
+        return ok("matter", "ping", reachability=reachability)
+
+    if action == "network_status":
+        entry_id = await resolve_entry_id(client, "matter")
+        if not entry_id:
+            return integration_not_found("matter", "matter")
+        return ok(
+            "matter",
+            "network_status",
+            config_entry_id=entry_id,
+            note=(
+                "Matter exposes health per node; call action='diagnostics' with a "
+                "device_id for node-level network type, availability and fabrics."
+            ),
+        )
+
+    if action == "commission":
+        result = await ws_call(
+            client,
+            "matter/commission",
+            code=args.get("code"),
+            network_only=bool(args.get("network_only", False)),
+        )
+        return ok("matter", "commission", result=result, long_running=True)
+
+    if action == "commission_on_network":
+        result = await ws_call(
+            client,
+            "matter/commission_on_network",
+            pin=args.get("pin"),
+            ip_addr=args.get("ip_addr"),
+        )
+        return ok("matter", "commission_on_network", result=result, long_running=True)
+
+    if action == "share_out":
+        commissioning = await ws_call(
+            client,
+            "matter/open_commissioning_window",
+            device_id=device_id,
+            context={"device_id": device_id},
+        )
+        # Returns setup_pin_code, setup_manual_code, setup_qr_code.
+        return ok("matter", "share_out", commissioning=commissioning)
+
+    if action == "interview":
+        result = await ws_call(
+            client,
+            "matter/interview_node",
+            device_id=device_id,
+            context={"device_id": device_id},
+        )
+        return ok("matter", "interview", result=result, long_running=True)
+
+    if action == "remove_fabric":
+        diag = await ws_call(
+            client,
+            "matter/node_diagnostics",
+            device_id=device_id,
+            context={"device_id": device_id},
+        )
+        active = (diag or {}).get("active_fabric_index")
+        fabric_index = args.get("fabric_index")
+        # remove_fabric removes ANOTHER controller's fabric. Removing HA's OWN
+        # active fabric over that fabric makes the node drop the session, so the
+        # Matter server aborts the confirmation (the removal still happens, but
+        # reports as an error). The clean "detach from HA" path is deleting the
+        # device, so refuse the own-fabric case with that guidance.
+        if fabric_index is None or fabric_index == active:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    "remove_fabric removes ANOTHER controller's fabric from a "
+                    "node; pass params.fabric_index (see active_fabrics). To "
+                    "detach this device from Home Assistant itself, delete the "
+                    "device with ha_remove_device — removing HA's own active "
+                    "fabric here is aborted by the Matter server.",
+                    context={
+                        "device_id": device_id,
+                        "active_fabric_index": active,
+                        "active_fabrics": (diag or {}).get("active_fabrics", []),
+                    },
+                    suggestions=[
+                        "Pass params.fabric_index = the other controller's index",
+                        "To remove Home Assistant, use ha_remove_device",
+                    ],
+                )
+            )
+        result = await ws_call(
+            client,
+            "matter/remove_matter_fabric",
+            device_id=device_id,
+            fabric_index=fabric_index,
+            context={"device_id": device_id, "fabric_index": fabric_index},
+        )
+        return ok("matter", "remove_fabric", result=result, fabric_index=fabric_index)
+
+    if action == "set_thread":
+        result = await ws_call(
+            client,
+            "matter/set_thread",
+            thread_operation_dataset=args.get("thread_operation_dataset"),
+        )
+        return ok("matter", "set_thread", result=result)
+
+    if action == "set_wifi_credentials":
+        result = await ws_call(
+            client,
+            "matter/set_wifi_credentials",
+            network_name=args.get("network_name"),
+            password=args.get("password"),
+        )
+        return ok("matter", "set_wifi_credentials", result=result)
+
+    if action == "firmware_update":
+        entity_id = await resolve_update_entity(client, device_id, platform="matter")
+        await client.call_service("update", "install", {"entity_id": entity_id})
+        return ok("matter", "firmware_update", entity_id=entity_id, long_running=True)
+
+    # Unreachable: dispatcher validates action against SUPPORTED first.
+    raise AssertionError(f"unhandled matter action: {action}")