mcp-server-zwave-js-ui: Instructions file for Claude Code

CLAUDE.md

Project Overview

Python MCP server for Z-Wave device management. It connects to the zwave-js-server WebSocket exposed by Z-Wave JS UI (the "Z-Wave JS Server" port, default 3000 — not the 8091 web UI) and exposes the Z-Wave network as MCP tools.

Scope is delivered in levels:

1. Read-only (done) — controller info, node listing/detail, values, config parameters.
2. Read/write (done) — set values, set config parameters, set node name/location, manage associations.
3. Admin/lifecycle (mostly done) — inclusion/exclusion, re-interview, network heal, remove failed node, plus rebuild/firmware status polls. Triggering OTA firmware still pending (see below).

Read-only lockdown: setting ZWAVE_JS_READ_ONLY (1/true/yes/on) makes server._apply_read_only() remove every tool in server._MUTATING_TOOLS from the FastMCP registry at import, so a locked server never advertises them (the pattern used by mcp-server-vyos). Any new mutating tool must be added to _MUTATING_TOOLS — a test asserts the mutating and read-only name sets partition the registry.

Commands

uv sync --extra dev            # create .venv from uv.lock (matches CI's --locked)
uv run pytest
uv run ruff check . && uv run ruff format --check .
ZWAVE_JS_URL=ws://<host>:3000 uv run python -m zwave_js_ui_mcp  # run server (stdio)

Architecture

• src/zwave_js_ui_mcp/server.py — MCP tool registration (FastMCP). Tools are thin: connect, delegate to a projection, return the dict.
• src/zwave_js_ui_mcp/client.py — the entire backend. connected_driver() opens/tears down a connection; project_* functions turn library model objects into plain JSON-serializable dicts.

The tool layer never touches a zwave-js-server-python object — only the dicts client.py returns. This isolates the transport so it can be swapped without touching tools.

Key Design Decisions

• Depends on zwave-js-server-python (the Home Assistant library) for connection, schema negotiation, and — decisive for level 3 — firmware/heal progress events. This pins Python >= 3.12 (the library's floor).
• Connection is per tool call (open → wait for full-state dump → read → close), matching the stateless MCP style. client.listen() must run as a background task for driver_ready to fire and for async_send_command futures to resolve.
• Mutating ops fit the per-call model because they are single request→response or fire-and-forget: set_value/set_config validate against live metadata then wait for the command result; inclusion/exclusion and network heal only toggle server-side controller state (a later stop_* call ends them). Long-running ops surface progress by a poll tool (zwave_rebuild_routes_status, zwave_firmware_update_status) rather than event streaming. Triggering an OTA firmware update does not fit — flashing streams progress over minutes, longer than one tool call, so it's deferred until a persistent-connection design lands. Interactive S2 inclusion (DSK/PIN grant over events) likewise can't complete statelessly; begin_inclusion documents this.
• Configuration-CC (112) values are excluded from zwave_node_values and surfaced only by zwave_node_config, so parameters aren't reported twice.
• Server URL via ZWAVE_JS_URL (default ws://localhost:3000). The WS server needs no auth by default; only the 8091 UI does.