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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.9.0.dev739
+Version: 7.9.0.dev740
 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.9.0.dev739 → ha_mcp_dev-7.9.0.dev740}/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.dev740"
 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.dev740/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.dev740/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.dev740/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}")

ha_mcp_dev-7.9.0.dev740/src/ha_mcp/tools/radio/thread.py

@@ -0,0 +1,161 @@
+"""Thread / OpenThread Border Router (OTBR) handler for ``ha_manage_radio``.
+
+Thread is network-scoped, not per-device: operations target the Thread network
+and its border router rather than an individual node. Border-router writes use
+the ``otbr/*`` WebSocket API and take an OTBR ``extended_address`` — resolved
+from ``otbr/info`` when the caller omits it, which covers the common
+single-OTBR setup. Dataset listing and router discovery use the
+integration-wide ``thread/*`` API. When no OTBR is configured the read-only
+``network_status`` degrades to an ``available: False`` payload; the write
+actions raise instead so an unconfigured integration is not a silent no-op.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import (
+    ActionSpec,
+    integration_not_found,
+    integration_required,
+    ok,
+    resolve_entry_id,
+    ws_call,
+)
+
+SUPPORTED: dict[str, ActionSpec] = {
+    "network_status": ActionSpec(
+        "OTBR border-router status keyed by extended address (channel, active "
+        "dataset TLVs, extended PAN id, border agent id)."
+    ),
+    "list_datasets": ActionSpec(
+        "List stored Thread operational datasets (the preferred network + others)."
+    ),
+    "discover_routers": ActionSpec(
+        "Start mDNS discovery of Thread border routers. Results arrive as an "
+        "out-of-band event stream; this kicks off the scan.",
+        long_running=True,
+    ),
+    "create_network": ActionSpec(
+        "Form a brand-new Thread network on the OTBR. Factory-resets the border "
+        "router and replaces its current dataset. Targets the only OTBR when "
+        "extended_address is omitted.",
+        destructive=True,
+    ),
+    "set_network": ActionSpec(
+        "Apply a stored dataset as the OTBR's active Thread network. Replaces "
+        "the current network, which can drop existing Thread devices.",
+        destructive=True,
+        required=("dataset_id",),
+    ),
+    "set_channel": ActionSpec(
+        "Migrate the OTBR's Thread network to a different radio channel.",
+        destructive=True,
+        required=("channel",),
+    ),
+    "add_dataset": ActionSpec(
+        "Import a Thread operational dataset (hex TLV) from a named source.",
+        required=("source", "tlv"),
+    ),
+}
+
+
+async def _resolve_extended_address(client: Any, args: dict[str, Any]) -> str | None:
+    """Return the target OTBR extended address.
+
+    Uses the caller-supplied value, else the first (typically only) border
+    router reported by ``otbr/info``. Returns None when no OTBR is present.
+    """
+    addr = args.get("extended_address")
+    if addr:
+        return str(addr)
+    info = await ws_call(client, "otbr/info")
+    return next(iter(info or {}), None)
+
+
+async def handle(client: Any, action: str, args: dict[str, Any]) -> dict[str, Any]:
+    """Execute one Thread/OTBR action (validation/confirm applied by caller)."""
+    if action == "network_status":
+        entry_id = await resolve_entry_id(client, "otbr")
+        if not entry_id:
+            return integration_not_found("thread", "otbr")
+        info = await ws_call(client, "otbr/info")
+        return ok(
+            "thread",
+            "network_status",
+            config_entry_id=entry_id,
+            border_routers=info,
+        )
+
+    if action == "list_datasets":
+        datasets = await ws_call(client, "thread/list_datasets")
+        return ok("thread", "list_datasets", datasets=datasets)
+
+    if action == "discover_routers":
+        # Subscription command: it streams discovered routers as events. Kick
+        # off the scan and report it started; consumers watch the event stream.
+        await ws_call(client, "thread/discover_routers")
+        return ok(
+            "thread",
+            "discover_routers",
+            long_running=True,
+            note=(
+                "Router discovery started; results are delivered as an event "
+                "stream, not in this response."
+            ),
+        )
+
+    if action == "add_dataset":
+        result = await ws_call(
+            client,
+            "thread/add_dataset_tlv",
+            source=args.get("source"),
+            tlv=args.get("tlv"),
+        )
+        return ok("thread", "add_dataset", result=result)
+
+    # Remaining actions (create_network / set_network / set_channel) are writes
+    # targeting a specific OTBR border router; an absent OTBR must error, not
+    # degrade to a no-op success.
+    extended_address = await _resolve_extended_address(client, args)
+    if not extended_address:
+        integration_required("thread", "otbr")
+    ctx = {"extended_address": extended_address}
+
+    if action == "create_network":
+        result = await ws_call(
+            client,
+            "otbr/create_network",
+            extended_address=extended_address,
+            context=ctx,
+        )
+        return ok(
+            "thread", "create_network", result=result, extended_address=extended_address
+        )
+
+    if action == "set_network":
+        result = await ws_call(
+            client,
+            "otbr/set_network",
+            extended_address=extended_address,
+            dataset_id=args.get("dataset_id"),
+            context=ctx,
+        )
+        return ok(
+            "thread", "set_network", result=result, extended_address=extended_address
+        )
+
+    if action == "set_channel":
+        result = await ws_call(
+            client,
+            "otbr/set_channel",
+            extended_address=extended_address,
+            channel=args.get("channel"),
+            context=ctx,
+        )
+        return ok(
+            "thread", "set_channel", result=result, extended_address=extended_address
+        )
+
+    # Unreachable: dispatcher validates action against SUPPORTED first.
+    raise AssertionError(f"unhandled thread action: {action}")