Start of MCP server and test suite

.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "meshtastic": {
+      "command": "/Users/benmeadors/Documents/GitHub/firmware/mcp-server/.venv/bin/python",
+      "args": ["-m", "meshtastic_mcp"],
+      "env": {
+        "MESHTASTIC_FIRMWARE_ROOT": "/Users/benmeadors/Documents/GitHub/firmware"
+      }
+    }
+  }
+}

mcp-server/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+dist/
+build/
+
+# Test harness artifacts
+tests/report.html
+tests/junit.xml
+tests/tool_coverage.json
+tests/.coverage
+htmlcov/

mcp-server/README.md

@@ -0,0 +1,174 @@
+# Meshtastic MCP Server
+
+An [MCP](https://modelcontextprotocol.io) server for working with the Meshtastic firmware repo and connected devices. Lets Claude Code / Claude Desktop:
+
+- Discover USB-connected Meshtastic devices
+- Enumerate PlatformIO board variants (166+) with Meshtastic metadata
+- Build, clean, flash, erase-and-flash (factory), and OTA-update firmware
+- Read serial logs via `pio device monitor` (with board-specific exception decoders)
+- Trigger 1200bps touch-reset for bootloader entry (nRF52, ESP32-S3, RP2040)
+- Query and administer a running node via the [`meshtastic` Python API](https://github.com/meshtastic/python): owner name, config (LocalConfig + ModuleConfig), channels, messaging, reboot/shutdown/factory-reset
+- Call `esptool`, `nrfutil`, `picotool` directly when PlatformIO doesn't cover the operation
+
+## Design principle
+
+**PlatformIO first.** Its `pio run -t upload` knows the correct protocol, offsets, and post-build chain for every variant in `variants/`. Direct vendor-tool wrappers (`esptool_*`, `nrfutil_*`, `picotool_*`) exist as escape hatches for operations pio doesn't cover (blank-chip erase, DFU `.zip` packages, BOOTSEL-mode inspection).
+
+## Prerequisites
+
+- Python ≥ 3.11
+- [PlatformIO Core](https://platformio.org/install/cli) — `pio` on `$PATH` or at `~/.platformio/penv/bin/pio`
+- The Meshtastic firmware repo checked out somewhere (set via `MESHTASTIC_FIRMWARE_ROOT`)
+- Optional: `esptool`, `nrfutil`, `picotool` on `$PATH` (or under the firmware venv at `.venv/bin/`) if you want to use the direct-tool wrappers
+
+## Install
+
+```bash
+cd <firmware-repo>/mcp-server
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+Verify:
+
+```bash
+MESHTASTIC_FIRMWARE_ROOT=<firmware-repo> .venv/bin/python -m meshtastic_mcp
+```
+
+The server blocks on stdin (that's correct — it speaks MCP over stdio). Ctrl-C to exit.
+
+## Register with Claude Code
+
+Edit `~/.claude/settings.json` (global) or `<firmware-repo>/.claude/settings.local.json` (project-only):
+
+```json
+{
+  "mcpServers": {
+    "meshtastic": {
+      "command": "<firmware-repo>/mcp-server/.venv/bin/python",
+      "args": ["-m", "meshtastic_mcp"],
+      "env": {
+        "MESHTASTIC_FIRMWARE_ROOT": "<firmware-repo>"
+      }
+    }
+  }
+}
+```
+
+Replace `<firmware-repo>` with the absolute path, e.g. `/Users/you/GitHub/firmware`. Restart Claude Code after editing.
+
+## Register with Claude Desktop
+
+Same `mcpServers` block, but in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
+
+## Tools (32)
+
+### Discovery & metadata
+
+| Tool           | What it does                                                                               |
+| -------------- | ------------------------------------------------------------------------------------------ |
+| `list_devices` | USB/serial port listing, flags likely-Meshtastic candidates                                |
+| `list_boards`  | PlatformIO envs with `custom_meshtastic_*` metadata; filters by arch/supported/query/level |
+| `get_board`    | Full env dict incl. raw pio config                                                         |
+
+### Build & flash
+
+| Tool              | What it does                                                         |
+| ----------------- | -------------------------------------------------------------------- |
+| `build`           | `pio run -e <env>` (+ mtjson target)                                 |
+| `clean`           | `pio run -e <env> -t clean`                                          |
+| `pio_flash`       | `pio run -e <env> -t upload --upload-port <port>` — any architecture |
+| `erase_and_flash` | ESP32 full factory flash via `bin/device-install.sh`                 |
+| `update_flash`    | ESP32 OTA app-partition update via `bin/device-update.sh`            |
+| `touch_1200bps`   | 1200-baud open/close to trigger USB CDC bootloader entry             |
+
+### Serial log sessions
+
+Backed by long-running `pio device monitor` subprocesses with a 10k-line ring buffer per session and board-specific filters (`esp32_exception_decoder` auto-selected when you pass `env=`).
+
+| Tool           | What it does                                                       |
+| -------------- | ------------------------------------------------------------------ |
+| `serial_open`  | Start a monitor session; returns `session_id`                      |
+| `serial_read`  | Cursor-based pull; reports `dropped` if lines aged out of the ring |
+| `serial_list`  | All active sessions                                                |
+| `serial_close` | Terminate a session                                                |
+
+### Device reads
+
+| Tool          | What it does                                                                |
+| ------------- | --------------------------------------------------------------------------- |
+| `device_info` | my_node_num, long/short name, firmware version, region, channel, node count |
+| `list_nodes`  | Full node database with position, SNR, RSSI, last_heard, battery            |
+
+### Device writes
+
+| Tool              | What it does                                                               |
+| ----------------- | -------------------------------------------------------------------------- |
+| `set_owner`       | Long name + optional short name (≤4 chars)                                 |
+| `get_config`      | One section or all (LocalConfig + ModuleConfig)                            |
+| `set_config`      | Dot-path field write: `lora.region`=`"US"`, `device.role`=`"ROUTER"`, etc. |
+| `get_channel_url` | Primary-only or include_all=admin URL                                      |
+| `set_channel_url` | Import channels from a Meshtastic URL                                      |
+| `send_text`       | Broadcast or direct text message                                           |
+| `reboot`          | `localNode.reboot(secs)` — requires `confirm=True`                         |
+| `shutdown`        | `localNode.shutdown(secs)` — requires `confirm=True`                       |
+| `factory_reset`   | `localNode.factoryReset(full?)` — requires `confirm=True`                  |
+
+### Direct hardware tools (escape hatches)
+
+| Tool                  | What it does                                              |
+| --------------------- | --------------------------------------------------------- |
+| `esptool_chip_info`   | Read chip, MAC, crystal, flash size                       |
+| `esptool_erase_flash` | Full-chip erase (destructive)                             |
+| `esptool_raw`         | Pass-through; confirm=True required for write/erase/merge |
+| `nrfutil_dfu`         | DFU-flash a `.zip` package                                |
+| `nrfutil_raw`         | Pass-through                                              |
+| `picotool_info`       | Read Pico BOOTSEL-mode info                               |
+| `picotool_load`       | Load a UF2                                                |
+| `picotool_raw`        | Pass-through                                              |
+
+## Safety
+
+- **All destructive flash/admin tools require `confirm=True`** as a tool-level gate, on top of any permission prompt from Claude.
+- **Serial port is exclusive.** If a `serial_*` session is active on a port, `device_info`/admin tools on the same port will fail fast with a pointer at the active `session_id`. Close the session first.
+- **Flash confirmation by architecture**: `erase_and_flash` / `update_flash` error if the env's architecture isn't ESP32 — use `pio_flash` for nRF52/RP2040/STM32.
+
+## Environment variables
+
+| Var                        | Default                                                     | Purpose                 |
+| -------------------------- | ----------------------------------------------------------- | ----------------------- |
+| `MESHTASTIC_FIRMWARE_ROOT` | walks up from cwd for `platformio.ini`                      | Pin the firmware repo   |
+| `MESHTASTIC_PIO_BIN`       | `~/.platformio/penv/bin/pio` → `$PATH` `pio` → `platformio` | Override `pio` location |
+| `MESHTASTIC_ESPTOOL_BIN`   | `<firmware>/.venv/bin/esptool` → `$PATH`                    | Override esptool        |
+| `MESHTASTIC_NRFUTIL_BIN`   | `$PATH`                                                     | Override nrfutil        |
+| `MESHTASTIC_PICOTOOL_BIN`  | `$PATH`                                                     | Override picotool       |
+
+## Layout
+
+```
+mcp-server/
+├── pyproject.toml
+├── README.md
+└── src/meshtastic_mcp/
+    ├── __main__.py         # entry: python -m meshtastic_mcp
+    ├── server.py           # FastMCP app + @app.tool() registrations (thin)
+    ├── config.py           # firmware_root, pio_bin, esptool_bin, etc.
+    ├── pio.py              # subprocess wrapper (timeouts, JSON, tail_lines)
+    ├── devices.py          # list_devices (findPorts + comports)
+    ├── boards.py           # list_boards / get_board (pio project config parse + cache)
+    ├── flash.py            # build, clean, flash, erase_and_flash, update_flash, touch_1200bps
+    ├── serial_session.py   # SerialSession + reader thread + ring buffer
+    ├── registry.py         # session registry + per-port locks
+    ├── connection.py       # connect(port) ctx mgr — SerialInterface + port lock
+    ├── info.py             # device_info, list_nodes
+    ├── admin.py            # set_owner, get/set_config, channels, send_text, reboot/shutdown/factory_reset
+    └── hw_tools.py         # esptool / nrfutil / picotool wrappers
+```
+
+## Troubleshooting
+
+- **"Could not locate Meshtastic firmware root"** — set `MESHTASTIC_FIRMWARE_ROOT`.
+- **"Could not find `pio`"** — install PlatformIO or set `MESHTASTIC_PIO_BIN`.
+- **"Port is held by serial session ..."** — call `serial_close(session_id)` or `serial_list` to find it.
+- **`factory.bin` not found after build** — the env may not be ESP32; only ESP32 envs produce a `.factory.bin`.
+- **`touch_1200bps` reported `new_port: null`** — the device may not have 1200bps-reset stdio, or the bootloader re-uses the same port name. Check `list_devices` manually.

mcp-server/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "meshtastic-mcp"
+version = "0.1.0"
+description = "MCP server for Meshtastic firmware development: device discovery, PlatformIO tooling, flashing, serial monitoring, and device administration via the meshtastic Python API."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "GPL-3.0-only" }
+authors = [{ name = "thebentern" }]
+dependencies = ["mcp>=1.2", "pyserial>=3.5", "meshtastic>=2.7.8"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+test = [
+  "pytest>=8",
+  "pytest-html>=4",
+  "pytest-reportlog>=0.4",
+  "pytest-timeout>=2.3",
+  "coverage[toml]>=7",
+  "pyyaml>=6",
+]
+
+[project.scripts]
+meshtastic-mcp = "meshtastic_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/meshtastic_mcp"]

mcp-server/src/meshtastic_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Meshtastic MCP server — device discovery, PlatformIO tooling, and device admin."""
+
+__version__ = "0.1.0"

mcp-server/src/meshtastic_mcp/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point for `python -m meshtastic_mcp`."""
+
+from meshtastic_mcp.server import app
+
+
+def main() -> None:
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

mcp-server/src/meshtastic_mcp/admin.py

@@ -0,0 +1,321 @@
+"""Device administration: owner, config, channels, messaging, admin actions.
+
+All operations use the same `connect()` context manager so port selection,
+port-busy detection, and cleanup are handled uniformly.
+
+Config writes use a dot-path: the first segment names a section (e.g.
+`"lora"` in LocalConfig or `"mqtt"` in LocalModuleConfig), remaining segments
+walk protobuf fields. Enum fields accept their string names (`"US"` for
+`lora.region`) so callers don't need to know the numeric values.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.protobuf import descriptor as pb_descriptor
+from google.protobuf import json_format
+from meshtastic.protobuf import localonly_pb2
+
+from .connection import connect
+
+
+class AdminError(RuntimeError):
+    pass
+
+
+LOCAL_CONFIG_SECTIONS = {f.name for f in localonly_pb2.LocalConfig.DESCRIPTOR.fields}
+MODULE_CONFIG_SECTIONS = {
+    f.name for f in localonly_pb2.LocalModuleConfig.DESCRIPTOR.fields
+}
+
+
+def _require_confirm(confirm: bool, operation: str) -> None:
+    if not confirm:
+        raise AdminError(f"{operation} is destructive and requires confirm=True.")
+
+
+def _message_to_dict(msg: Any) -> dict[str, Any]:
+    return json_format.MessageToDict(
+        msg,
+        preserving_proto_field_name=True,
+        including_default_value_fields=False,
+    )
+
+
+# ---------- owner ----------------------------------------------------------
+
+
+def set_owner(
+    long_name: str,
+    short_name: str | None = None,
+    port: str | None = None,
+) -> dict[str, Any]:
+    if short_name is not None and len(short_name) > 4:
+        raise AdminError("short_name must be 4 characters or fewer")
+    with connect(port=port) as iface:
+        iface.localNode.setOwner(long_name=long_name, short_name=short_name)
+    return {
+        "ok": True,
+        "long_name": long_name,
+        "short_name": short_name,
+    }
+
+
+# ---------- config reads ---------------------------------------------------
+
+
+def _section_container(node, section: str) -> tuple[Any, str]:
+    """Return (container_message, parent_name) for a section name.
+
+    Parent is 'localConfig' or 'moduleConfig' so callers know where to call
+    writeConfig() after mutating.
+    """
+    if section in LOCAL_CONFIG_SECTIONS:
+        return getattr(node.localConfig, section), "localConfig"
+    if section in MODULE_CONFIG_SECTIONS:
+        return getattr(node.moduleConfig, section), "moduleConfig"
+    raise AdminError(
+        f"Unknown config section: {section!r}. "
+        f"Valid sections: {sorted(LOCAL_CONFIG_SECTIONS | MODULE_CONFIG_SECTIONS)}"
+    )
+
+
+def get_config(section: str | None = None, port: str | None = None) -> dict[str, Any]:
+    """Read one or all config sections.
+
+    `section` may be any name in LocalConfig (device, lora, position, power,
+    network, display, bluetooth, security) or LocalModuleConfig (mqtt, serial,
+    telemetry, ...). Omit `section` or pass `"all"` for everything.
+    """
+    with connect(port=port) as iface:
+        node = iface.localNode
+        if section in (None, "all"):
+            lc = _message_to_dict(node.localConfig)
+            mc = _message_to_dict(node.moduleConfig)
+            return {
+                "config": {
+                    "localConfig": lc,
+                    "moduleConfig": mc,
+                }
+            }
+        container, _parent = _section_container(node, section)
+        return {"config": {section: _message_to_dict(container)}}
+
+
+# ---------- config writes --------------------------------------------------
+
+
+def _coerce_enum(field: pb_descriptor.FieldDescriptor, value: Any) -> int:
+    """Accept an enum value as either its int or its string name."""
+    enum_type = field.enum_type
+    if isinstance(value, bool):
+        raise AdminError(f"{field.name}: expected enum {enum_type.name}, got bool")
+    if isinstance(value, int):
+        if enum_type.values_by_number.get(value) is None:
+            raise AdminError(
+                f"{field.name}: {value} is not a valid {enum_type.name} value"
+            )
+        return value
+    if isinstance(value, str):
+        upper = value.upper()
+        ev = enum_type.values_by_name.get(upper)
+        if ev is None:
+            valid = sorted(enum_type.values_by_name.keys())
+            raise AdminError(
+                f"{field.name}: {value!r} is not a valid {enum_type.name}. "
+                f"Valid: {valid}"
+            )
+        return ev.number
+    raise AdminError(
+        f"{field.name}: expected enum {enum_type.name}, got {type(value).__name__}"
+    )
+
+
+def _coerce_scalar(field: pb_descriptor.FieldDescriptor, value: Any) -> Any:
+    t = field.type
+    FT = pb_descriptor.FieldDescriptor
+    if t == FT.TYPE_ENUM:
+        return _coerce_enum(field, value)
+    if t == FT.TYPE_BOOL:
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            return value.strip().lower() in ("true", "yes", "1", "on")
+        if isinstance(value, int):
+            return bool(value)
+    if t in (
+        FT.TYPE_INT32,
+        FT.TYPE_INT64,
+        FT.TYPE_UINT32,
+        FT.TYPE_UINT64,
+        FT.TYPE_SINT32,
+        FT.TYPE_SINT64,
+        FT.TYPE_FIXED32,
+        FT.TYPE_FIXED64,
+    ):
+        return int(value)
+    if t in (FT.TYPE_FLOAT, FT.TYPE_DOUBLE):
+        return float(value)
+    if t == FT.TYPE_STRING:
+        return str(value)
+    if t == FT.TYPE_BYTES:
+        if isinstance(value, (bytes, bytearray)):
+            return bytes(value)
+        return str(value).encode("utf-8")
+    raise AdminError(
+        f"{field.name}: unsupported field type {t}. Use raw protobuf for this field."
+    )
+
+
+def _walk_to_field(
+    root_msg: Any, path_segments: list[str]
+) -> tuple[Any, pb_descriptor.FieldDescriptor]:
+    """Walk `root_msg` by field names until the leaf; return (parent_msg, leaf_field_descriptor)."""
+    msg = root_msg
+    for i, name in enumerate(path_segments):
+        desc = msg.DESCRIPTOR
+        field = desc.fields_by_name.get(name)
+        if field is None:
+            trail = ".".join(path_segments[:i] or ["<root>"])
+            valid = [f.name for f in desc.fields]
+            raise AdminError(f"No field {name!r} in {trail}. Valid: {valid}")
+        is_last = i == len(path_segments) - 1
+        if is_last:
+            return msg, field
+        if field.type != pb_descriptor.FieldDescriptor.TYPE_MESSAGE:
+            raise AdminError(
+                f"{'.'.join(path_segments[:i+1])} is a scalar; cannot descend into it"
+            )
+        msg = getattr(msg, name)
+    # path_segments was empty
+    raise AdminError("Empty config path")
+
+
+def set_config(path: str, value: Any, port: str | None = None) -> dict[str, Any]:
+    """Set a single config field by dot-path and write it to the device.
+
+    Examples:
+        set_config("lora.region", "US")
+        set_config("lora.modem_preset", "LONG_FAST")
+        set_config("device.role", "ROUTER")
+        set_config("mqtt.enabled", True)
+        set_config("mqtt.address", "mqtt.example.com")
+    """
+    segments = [s for s in path.split(".") if s]
+    if not segments:
+        raise AdminError("path cannot be empty")
+    section = segments[0]
+
+    with connect(port=port) as iface:
+        node = iface.localNode
+        container, parent_name = _section_container(node, section)
+
+        # Treat the section as the root; the rest of the path walks into it.
+        leaf_parent, field = _walk_to_field(container, segments[1:] or [])
+        if field.label == pb_descriptor.FieldDescriptor.LABEL_REPEATED:
+            raise AdminError(
+                f"{path!r} is a repeated field; v1 only supports scalar sets. "
+                "Use the raw meshtastic CLI for now."
+            )
+        old_raw = getattr(leaf_parent, field.name)
+        coerced = _coerce_scalar(field, value)
+        try:
+            setattr(leaf_parent, field.name, coerced)
+        except (TypeError, ValueError) as exc:
+            raise AdminError(f"{path}: {exc}") from exc
+
+        node.writeConfig(section)
+
+        # Stringify enums for the response (so the caller can see the change in
+        # the same vocabulary they used to set it).
+        if field.type == pb_descriptor.FieldDescriptor.TYPE_ENUM:
+            try:
+                old_display = field.enum_type.values_by_number[old_raw].name
+                new_display = field.enum_type.values_by_number[coerced].name
+            except Exception:
+                old_display, new_display = old_raw, coerced
+        else:
+            old_display, new_display = old_raw, coerced
+
+    return {
+        "ok": True,
+        "path": path,
+        "section": section,
+        "parent": parent_name,
+        "old_value": old_display,
+        "new_value": new_display,
+    }
+
+
+# ---------- channels -------------------------------------------------------
+
+
+def get_channel_url(
+    include_all: bool = False, port: str | None = None
+) -> dict[str, Any]:
+    with connect(port=port) as iface:
+        url = iface.localNode.getURL(includeAll=include_all)
+    return {"url": url}
+
+
+def set_channel_url(url: str, port: str | None = None) -> dict[str, Any]:
+    with connect(port=port) as iface:
+        # setURL replaces the channel set from the URL's contents. It does not
+        # return a count; we infer by counting non-DISABLED channels after.
+        iface.localNode.setURL(url)
+        channels = iface.localNode.channels or []
+        active = sum(1 for c in channels if getattr(c, "role", 0) != 0)
+    return {"ok": True, "channels_imported": active}
+
+
+# ---------- messaging ------------------------------------------------------
+
+
+def send_text(
+    text: str,
+    to: str | int | None = None,
+    channel_index: int = 0,
+    want_ack: bool = False,
+    port: str | None = None,
+) -> dict[str, Any]:
+    destination = to if to is not None else "^all"
+    with connect(port=port) as iface:
+        packet = iface.sendText(
+            text,
+            destinationId=destination,
+            wantAck=want_ack,
+            channelIndex=channel_index,
+        )
+        packet_id = getattr(packet, "id", None)
+    return {"ok": True, "packet_id": packet_id, "destination": destination}
+
+
+# ---------- admin actions --------------------------------------------------
+
+
+def reboot(
+    port: str | None = None, confirm: bool = False, seconds: int = 10
+) -> dict[str, Any]:
+    _require_confirm(confirm, "reboot")
+    with connect(port=port) as iface:
+        iface.localNode.reboot(secs=seconds)
+    return {"ok": True, "rebooting_in_s": seconds}
+
+
+def shutdown(
+    port: str | None = None, confirm: bool = False, seconds: int = 10
+) -> dict[str, Any]:
+    _require_confirm(confirm, "shutdown")
+    with connect(port=port) as iface:
+        iface.localNode.shutdown(secs=seconds)
+    return {"ok": True, "shutting_down_in_s": seconds}
+
+
+def factory_reset(
+    port: str | None = None, confirm: bool = False, full: bool = False
+) -> dict[str, Any]:
+    _require_confirm(confirm, "factory_reset")
+    with connect(port=port) as iface:
+        iface.localNode.factoryReset(full=full)
+    return {"ok": True, "full": full}

mcp-server/src/meshtastic_mcp/boards.py

@@ -0,0 +1,159 @@
+"""Board / PlatformIO env enumeration.
+
+Parses `pio project config --json-output` — a nested list of
+`[section_name, [[key, value], ...]]` pairs — into a dict keyed by env name,
+extracting the `custom_meshtastic_*` metadata the firmware variants expose.
+
+The parsed config is cached and invalidated when `platformio.ini`'s mtime
+changes, so subsequent calls don't pay the 1–2s pio startup cost.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from . import config, pio
+
+_CACHE_LOCK = threading.Lock()
+_CACHE: dict[str, Any] = {"mtime": None, "envs": None}
+
+
+def _parse_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in ("true", "yes", "1", "on")
+    return bool(value)
+
+
+def _parse_int(value: Any) -> int | None:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse_tags(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [str(v).strip() for v in value if str(v).strip()]
+    return [t.strip() for t in str(value).replace(",", " ").split() if t.strip()]
+
+
+def _env_record(env_name: str, items: list[list[Any]]) -> dict[str, Any]:
+    """Build a normalized dict for one env section."""
+    d = dict(items)
+    return {
+        "env": env_name,
+        "architecture": d.get("custom_meshtastic_architecture"),
+        "hw_model": _parse_int(d.get("custom_meshtastic_hw_model")),
+        "hw_model_slug": d.get("custom_meshtastic_hw_model_slug"),
+        "display_name": d.get("custom_meshtastic_display_name"),
+        "actively_supported": _parse_bool(
+            d.get("custom_meshtastic_actively_supported")
+        ),
+        "support_level": _parse_int(d.get("custom_meshtastic_support_level")),
+        "board_level": d.get("board_level"),  # "pr", "extra", or None
+        "tags": _parse_tags(d.get("custom_meshtastic_tags")),
+        "images": _parse_tags(d.get("custom_meshtastic_images")),
+        "board": d.get("board"),
+        "upload_speed": _parse_int(d.get("upload_speed")),
+        "upload_protocol": d.get("upload_protocol"),
+        "monitor_speed": _parse_int(d.get("monitor_speed")),
+        "monitor_filters": d.get("monitor_filters") or [],
+        "_raw": d,  # Full dict for get_board
+    }
+
+
+def _load_all() -> dict[str, dict[str, Any]]:
+    """Parse `pio project config` into `{env_name: record}`."""
+    raw = pio.run_json(["project", "config"], timeout=pio.TIMEOUT_PROJECT_CONFIG)
+    result: dict[str, dict[str, Any]] = {}
+    for section_name, items in raw:
+        if not isinstance(section_name, str) or not section_name.startswith("env:"):
+            continue
+        env_name = section_name.split(":", 1)[1]
+        result[env_name] = _env_record(env_name, items)
+    return result
+
+
+def _get_cached() -> dict[str, dict[str, Any]]:
+    root = config.firmware_root()
+    platformio_ini = root / "platformio.ini"
+    try:
+        mtime = platformio_ini.stat().st_mtime
+    except FileNotFoundError:
+        mtime = None
+
+    with _CACHE_LOCK:
+        if _CACHE["envs"] is not None and _CACHE["mtime"] == mtime:
+            return _CACHE["envs"]
+        envs = _load_all()
+        _CACHE["envs"] = envs
+        _CACHE["mtime"] = mtime
+        return envs
+
+
+def invalidate_cache() -> None:
+    with _CACHE_LOCK:
+        _CACHE["envs"] = None
+        _CACHE["mtime"] = None
+
+
+def _public_record(rec: dict[str, Any]) -> dict[str, Any]:
+    """Strip the `_raw` field for list outputs."""
+    return {k: v for k, v in rec.items() if not k.startswith("_")}
+
+
+def list_boards(
+    architecture: str | None = None,
+    actively_supported_only: bool = False,
+    query: str | None = None,
+    board_level: str | None = None,  # "release" | "pr" | "extra"
+) -> list[dict[str, Any]]:
+    """Enumerate PlatformIO envs with Meshtastic metadata.
+
+    Filters are cumulative (AND). `board_level="release"` means envs with no
+    explicit `board_level` set (the default release targets).
+    """
+    envs = _get_cached()
+    q = query.lower().strip() if query else None
+
+    out = []
+    for rec in envs.values():
+        if architecture and rec.get("architecture") != architecture:
+            continue
+        if actively_supported_only and not rec.get("actively_supported"):
+            continue
+        if board_level is not None:
+            rec_level = rec.get("board_level")
+            if board_level == "release":
+                if rec_level not in (None, ""):
+                    continue
+            elif rec_level != board_level:
+                continue
+        if q:
+            display = (rec.get("display_name") or "").lower()
+            env_name = rec.get("env", "").lower()
+            slug = (rec.get("hw_model_slug") or "").lower()
+            if q not in display and q not in env_name and q not in slug:
+                continue
+        out.append(_public_record(rec))
+
+    out.sort(key=lambda r: (r.get("architecture") or "", r.get("env")))
+    return out
+
+
+def get_board(env: str) -> dict[str, Any]:
+    """Full metadata for one env, including the raw pio config dict."""
+    envs = _get_cached()
+    rec = envs.get(env)
+    if rec is None:
+        raise KeyError(
+            f"Unknown env: {env!r}. Use list_boards() to see available envs."
+        )
+    public = _public_record(rec)
+    public["raw_config"] = rec["_raw"]
+    return public

mcp-server/src/meshtastic_mcp/config.py

@@ -0,0 +1,137 @@
+"""Resolves the firmware repo root and the binaries we invoke.
+
+Everything that needs a path (the firmware root, `pio`, `esptool`, etc.) goes
+through this module so the rest of the package never calls `shutil.which` or
+parses environment variables directly.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import Iterable
+
+
+class ConfigError(RuntimeError):
+    """Raised when a required path or binary cannot be resolved."""
+
+
+def firmware_root() -> Path:
+    """The root of the Meshtastic firmware repo.
+
+    Resolution order:
+      1. `MESHTASTIC_FIRMWARE_ROOT` env var.
+      2. Walk up from `cwd` looking for a directory with `platformio.ini`.
+    """
+    env = os.environ.get("MESHTASTIC_FIRMWARE_ROOT")
+    if env:
+        root = Path(env).expanduser().resolve()
+        if not (root / "platformio.ini").is_file():
+            raise ConfigError(
+                f"MESHTASTIC_FIRMWARE_ROOT={env!r} does not contain platformio.ini"
+            )
+        return root
+
+    cur = Path.cwd().resolve()
+    for candidate in (cur, *cur.parents):
+        if (candidate / "platformio.ini").is_file():
+            return candidate
+    raise ConfigError(
+        "Could not locate Meshtastic firmware root. Set MESHTASTIC_FIRMWARE_ROOT "
+        "to the directory containing platformio.ini."
+    )
+
+
+def _first_existing(paths: Iterable[Path]) -> Path | None:
+    for p in paths:
+        if p and p.is_file() and os.access(p, os.X_OK):
+            return p
+    return None
+
+
+def pio_bin() -> Path:
+    """Resolve the `pio` binary.
+
+    Order: MESHTASTIC_PIO_BIN → ~/.platformio/penv/bin/pio (PlatformIO keeps
+    this one current) → `pio` on PATH → `platformio` on PATH.
+    """
+    env = os.environ.get("MESHTASTIC_PIO_BIN")
+    if env:
+        p = Path(env).expanduser()
+        if p.is_file() and os.access(p, os.X_OK):
+            return p
+        raise ConfigError(f"MESHTASTIC_PIO_BIN={env!r} is not an executable file")
+
+    penv = Path.home() / ".platformio" / "penv" / "bin" / "pio"
+    if penv.is_file() and os.access(penv, os.X_OK):
+        return penv
+
+    for name in ("pio", "platformio"):
+        w = shutil.which(name)
+        if w:
+            return Path(w)
+
+    raise ConfigError(
+        "Could not find `pio`. Install PlatformIO (https://platformio.org/install/cli) "
+        "or set MESHTASTIC_PIO_BIN."
+    )
+
+
+def _hw_tool(env_var: str, names: tuple[str, ...], install_hint: str) -> Path:
+    """Shared resolver for esptool / nrfutil / picotool.
+
+    Prefers the firmware repo's own `.venv/bin/<name>` (esptool lives there),
+    then PATH.
+    """
+    env = os.environ.get(env_var)
+    if env:
+        p = Path(env).expanduser()
+        if p.is_file() and os.access(p, os.X_OK):
+            return p
+        raise ConfigError(f"{env_var}={env!r} is not an executable file")
+
+    try:
+        venv_bin = firmware_root() / ".venv" / "bin"
+    except ConfigError:
+        venv_bin = None
+
+    for name in names:
+        if venv_bin is not None:
+            p = venv_bin / name
+            if p.is_file() and os.access(p, os.X_OK):
+                return p
+
+    for name in names:
+        w = shutil.which(name)
+        if w:
+            return Path(w)
+
+    raise ConfigError(
+        f"Could not find `{names[0]}`. {install_hint} "
+        f"Or set {env_var} to an absolute path."
+    )
+
+
+def esptool_bin() -> Path:
+    return _hw_tool(
+        "MESHTASTIC_ESPTOOL_BIN",
+        ("esptool", "esptool.py"),
+        "Install via `pip install esptool`.",
+    )
+
+
+def nrfutil_bin() -> Path:
+    return _hw_tool(
+        "MESHTASTIC_NRFUTIL_BIN",
+        ("nrfutil", "adafruit-nrfutil"),
+        "Install via `pip install adafruit-nrfutil` or download Nordic nRF Util.",
+    )
+
+
+def picotool_bin() -> Path:
+    return _hw_tool(
+        "MESHTASTIC_PICOTOOL_BIN",
+        ("picotool",),
+        "Install via `brew install picotool` or build from https://github.com/raspberrypi/picotool.",
+    )

mcp-server/src/meshtastic_mcp/connection.py

@@ -0,0 +1,84 @@
+"""Context manager for meshtastic.SerialInterface connections.
+
+Every info/admin tool goes through `connect(port)` so we have a single place
+that:
+  - auto-selects the port when one likely_meshtastic device is present,
+  - fails fast if a serial_session is already holding the port,
+  - guarantees `.close()` is called, even on exception.
+
+The `SerialInterface` blocks on construction waiting for the node database;
+that's fine for v1 since every tool is a short-lived request.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Iterator
+
+from . import devices, registry
+
+
+class ConnectionError(RuntimeError):
+    pass
+
+
+def resolve_port(port: str | None) -> str:
+    """Pick a port: explicit > sole likely_meshtastic candidate > error."""
+    if port:
+        return port
+    candidates = [d for d in devices.list_devices() if d["likely_meshtastic"]]
+    if not candidates:
+        raise ConnectionError(
+            "No Meshtastic devices detected. Plug one in or pass `port` explicitly. "
+            "Run `list_devices` with include_unknown=True to see all serial ports."
+        )
+    if len(candidates) > 1:
+        ports = ", ".join(c["port"] for c in candidates)
+        raise ConnectionError(
+            f"Multiple Meshtastic devices detected ({ports}). "
+            "Specify `port` explicitly."
+        )
+    return candidates[0]["port"]
+
+
+@contextmanager
+def connect(port: str | None = None, timeout_s: float = 8.0) -> Iterator:
+    """Open a `meshtastic.SerialInterface` and always close it.
+
+    Raises `ConnectionError` immediately if another serial session holds the
+    port (a `pio device monitor` in `serial_sessions/`, for instance).
+    """
+    from meshtastic.serial_interface import (
+        SerialInterface,  # type: ignore[import-untyped]
+    )
+
+    resolved = resolve_port(port)
+
+    active = registry.active_session_for_port(resolved)
+    if active is not None:
+        raise ConnectionError(
+            f"Port {resolved} is held by serial session {active.id}. "
+            "Call `serial_close` first."
+        )
+
+    lock = registry.port_lock(resolved)
+    if not lock.acquire(blocking=False):
+        raise ConnectionError(
+            f"Port {resolved} is busy — another device operation is in flight. "
+            "Retry shortly."
+        )
+
+    iface = None
+    try:
+        iface = SerialInterface(devPath=resolved, connectNow=True, noProto=False)
+        yield iface
+    finally:
+        if iface is not None:
+            try:
+                iface.close()
+            except Exception:
+                pass
+        try:
+            lock.release()
+        except RuntimeError:
+            pass

mcp-server/src/meshtastic_mcp/devices.py

@@ -0,0 +1,75 @@
+"""USB/serial device discovery.
+
+Combines the canonical `meshtastic.util.findPorts()` allowlist/blocklist with
+the richer metadata (`serial.tools.list_ports.comports()`) so callers see
+VID/PID, descriptions, and manufacturer strings alongside the "is this likely
+a Meshtastic device" signal.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from serial.tools import list_ports
+
+
+def _to_hex(value: int | None) -> str | None:
+    if value is None:
+        return None
+    return f"0x{value:04x}"
+
+
+def list_devices(include_unknown: bool = False) -> list[dict[str, Any]]:
+    """Return enriched info for serial ports, flagging Meshtastic candidates.
+
+    `likely_meshtastic` is True when the port's USB VID matches the Meshtastic
+    allowlist (`0x239a` Adafruit/RAK, `0x303a` Espressif). When no allowlisted
+    ports are present, ports whose VID is NOT in the blocklist (J-Link, ST-LINK,
+    PPK2, etc.) are surfaced as `likely_meshtastic=False` candidates.
+
+    With `include_unknown=False` (default), we return only ports that are
+    plausibly Meshtastic. With `include_unknown=True`, every serial port the
+    OS knows about is returned (useful for debugging "why isn't my board
+    detected").
+    """
+    # Import lazily so the module loads even without the `meshtastic` package
+    # (useful for introspection / schema generation).
+    from meshtastic import util as mt_util  # type: ignore[import-untyped]
+
+    meshtastic_ports: set[str] = set(mt_util.findPorts(eliminate_duplicates=True))
+    whitelist = getattr(mt_util, "whitelistVids", {})
+    blacklist = getattr(mt_util, "blacklistVids", {})
+
+    results: list[dict[str, Any]] = []
+    for info in list_ports.comports():
+        port_path = info.device
+        vid = info.vid
+        in_whitelist = vid is not None and vid in whitelist
+        in_blacklist = vid is not None and vid in blacklist
+
+        likely = port_path in meshtastic_ports and in_whitelist
+        # If no allowlisted ports were found, findPorts falls back to
+        # everything-not-in-blacklist; treat those as plausible candidates
+        # but not "likely".
+        fallback_candidate = port_path in meshtastic_ports and not in_whitelist
+
+        if not likely and not fallback_candidate and not include_unknown:
+            continue
+
+        results.append(
+            {
+                "port": port_path,
+                "vid": _to_hex(vid),
+                "pid": _to_hex(info.pid),
+                "description": info.description or None,
+                "manufacturer": info.manufacturer or None,
+                "product": info.product or None,
+                "serial_number": info.serial_number or None,
+                "likely_meshtastic": likely,
+                "blacklisted": in_blacklist,
+            }
+        )
+
+    # Stable ordering: likely_meshtastic first, then by port path
+    results.sort(key=lambda r: (not r["likely_meshtastic"], r["port"]))
+    return results

mcp-server/src/meshtastic_mcp/flash.py

@@ -0,0 +1,338 @@
+"""Build, clean, flash, and bootloader-entry operations.
+
+Design: pio is the preferred path for every architecture via `flash()`. For
+ESP32 factory flashes we shell out to `bin/device-install.sh` (which knows
+about partition offsets and the OTA/littlefs partitions); for ESP32 OTA
+updates we use `bin/device-update.sh`. Both scripts require the build
+artifacts to exist, so these tools build first if needed.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+import serial
+
+from . import boards, config, devices, pio, userprefs
+
+ESP32_ARCHES = {"esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c6"}
+
+
+class FlashError(RuntimeError):
+    pass
+
+
+def _require_confirm(confirm: bool, operation: str) -> None:
+    if not confirm:
+        raise FlashError(
+            f"{operation} is destructive and requires confirm=True. "
+            "This will overwrite firmware on the device."
+        )
+
+
+def _artifacts_for(env: str) -> list[Path]:
+    build_dir = config.firmware_root() / ".pio" / "build" / env
+    if not build_dir.is_dir():
+        return []
+    patterns = (
+        "firmware*.bin",
+        "firmware*.uf2",
+        "firmware*.hex",
+        "firmware*.zip",
+        "firmware*.elf",
+        "*.mt.json",
+        "littlefs-*.bin",
+    )
+    out: list[Path] = []
+    for pat in patterns:
+        out.extend(sorted(build_dir.glob(pat)))
+    return out
+
+
+def _factory_bin_for(env: str) -> Path | None:
+    build_dir = config.firmware_root() / ".pio" / "build" / env
+    if not build_dir.is_dir():
+        return None
+    matches = sorted(build_dir.glob("firmware-*.factory.bin"))
+    return matches[0] if matches else None
+
+
+def _firmware_bin_for(env: str) -> Path | None:
+    """Return the OTA-update firmware binary (app partition only)."""
+    build_dir = config.firmware_root() / ".pio" / "build" / env
+    if not build_dir.is_dir():
+        return None
+    # device-update.sh expects firmware-<env>-<version>.bin (not .factory.bin)
+    matches = sorted(
+        p
+        for p in build_dir.glob("firmware-*.bin")
+        if not p.name.endswith(".factory.bin")
+    )
+    return matches[0] if matches else None
+
+
+def _userprefs_summary(active: dict[str, str]) -> dict[str, Any]:
+    """Compact summary of which USERPREFS_* are baked into the build."""
+    return {"count": len(active), "keys": sorted(active.keys())}
+
+
+def build(
+    env: str,
+    with_manifest: bool = True,
+    userprefs_overrides: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Run `pio run -e <env>` and return artifact paths.
+
+    `userprefs_overrides` (optional): dict of `USERPREFS_<KEY>: value` to inject
+    into userPrefs.jsonc for this build only. File is restored byte-for-byte
+    on exit. Use `userprefs_set()` for persistent changes.
+    """
+    args = ["run", "-e", env]
+    if with_manifest:
+        args.extend(["-t", "mtjson"])
+    with userprefs.temporary_overrides(userprefs_overrides) as effective:
+        result = pio.run(args, timeout=pio.TIMEOUT_BUILD, check=False)
+    return {
+        "exit_code": result.returncode,
+        "artifacts": [str(p) for p in _artifacts_for(env)],
+        "stdout_tail": pio.tail_lines(result.stdout, 200),
+        "stderr_tail": pio.tail_lines(result.stderr, 200),
+        "duration_s": round(result.duration_s, 2),
+        "userprefs": _userprefs_summary(effective),
+    }
+
+
+def clean(env: str) -> dict[str, Any]:
+    """Run `pio run -e <env> -t clean`."""
+    result = pio.run(["run", "-e", env, "-t", "clean"], timeout=120, check=False)
+    return {
+        "exit_code": result.returncode,
+        "stdout_tail": pio.tail_lines(result.stdout, 200),
+        "stderr_tail": pio.tail_lines(result.stderr, 200),
+        "duration_s": round(result.duration_s, 2),
+    }
+
+
+def flash(
+    env: str,
+    port: str,
+    confirm: bool = False,
+    userprefs_overrides: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """`pio run -e <env> -t upload --upload-port <port>`. All architectures.
+
+    `userprefs_overrides` (optional): see `build()` — the rebuild-before-upload
+    that pio performs will pick up the injected values.
+    """
+    _require_confirm(confirm, "flash")
+    with userprefs.temporary_overrides(userprefs_overrides) as effective:
+        result = pio.run(
+            ["run", "-e", env, "-t", "upload", "--upload-port", port],
+            timeout=pio.TIMEOUT_UPLOAD,
+            check=False,
+        )
+    return {
+        "exit_code": result.returncode,
+        "stdout_tail": pio.tail_lines(result.stdout, 200),
+        "stderr_tail": pio.tail_lines(result.stderr, 200),
+        "duration_s": round(result.duration_s, 2),
+        "userprefs": _userprefs_summary(effective),
+    }
+
+
+def _check_esp32_env(env: str) -> str:
+    rec = boards.get_board(env)
+    arch = rec.get("architecture")
+    if arch not in ESP32_ARCHES:
+        raise FlashError(
+            f"Env {env!r} has architecture {arch!r}, not ESP32. "
+            "Use `flash` for non-ESP32 boards."
+        )
+    return arch
+
+
+def _run_install_script(script: Path, port: str, binary: Path) -> dict[str, Any]:
+    """Invoke bin/device-install.sh or bin/device-update.sh."""
+    t0 = time.monotonic()
+    proc = subprocess.run(
+        [str(script), "-p", port, "-f", str(binary)],
+        cwd=str(config.firmware_root()),
+        capture_output=True,
+        text=True,
+        timeout=pio.TIMEOUT_UPLOAD,
+    )
+    duration = time.monotonic() - t0
+    return {
+        "exit_code": proc.returncode,
+        "stdout_tail": pio.tail_lines(proc.stdout, 200),
+        "stderr_tail": pio.tail_lines(proc.stderr, 200),
+        "duration_s": round(duration, 2),
+    }
+
+
+def erase_and_flash(
+    env: str,
+    port: str,
+    confirm: bool = False,
+    skip_build: bool = False,
+    userprefs_overrides: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """ESP32-only: full erase + factory flash via bin/device-install.sh.
+
+    `userprefs_overrides`: baked into the factory.bin via a fresh build. If
+    overrides are provided we always force a rebuild (skip_build=True errors
+    in that case) since a cached factory.bin would not reflect the new prefs.
+    """
+    _require_confirm(confirm, "erase_and_flash")
+    _check_esp32_env(env)
+
+    if userprefs_overrides and skip_build:
+        raise FlashError(
+            "userprefs_overrides forces a rebuild so the factory.bin reflects "
+            "the new values; skip_build=True is incompatible."
+        )
+
+    with userprefs.temporary_overrides(userprefs_overrides) as effective:
+        # If overrides were provided, always build; otherwise only build if
+        # no factory.bin is present.
+        factory = _factory_bin_for(env)
+        if factory is None or userprefs_overrides:
+            if skip_build:
+                raise FlashError(
+                    f"No factory.bin found for env {env!r} and skip_build=True. "
+                    "Run `build` first or set skip_build=False."
+                )
+            build_args = ["run", "-e", env, "-t", "mtjson"]
+            build_result = pio.run(build_args, timeout=pio.TIMEOUT_BUILD, check=False)
+            if build_result.returncode != 0:
+                return {
+                    "exit_code": build_result.returncode,
+                    "stdout_tail": pio.tail_lines(build_result.stdout, 200),
+                    "stderr_tail": pio.tail_lines(build_result.stderr, 200),
+                    "duration_s": round(build_result.duration_s, 2),
+                    "error": "build failed before erase_and_flash could run",
+                    "userprefs": _userprefs_summary(effective),
+                }
+            factory = _factory_bin_for(env)
+            if factory is None:
+                raise FlashError(
+                    f"Build succeeded but no factory.bin appeared in .pio/build/{env}/"
+                )
+
+        script = config.firmware_root() / "bin" / "device-install.sh"
+        if not script.is_file():
+            raise FlashError(f"device-install.sh not found at {script}")
+        result = _run_install_script(script, port, factory)
+
+    result["userprefs"] = _userprefs_summary(effective)
+    return result
+
+
+def update_flash(
+    env: str,
+    port: str,
+    confirm: bool = False,
+    skip_build: bool = False,
+    userprefs_overrides: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """ESP32-only: OTA app-partition update via bin/device-update.sh.
+
+    `userprefs_overrides`: baked into the firmware.bin via a fresh build. If
+    overrides are provided we always force a rebuild.
+    """
+    _require_confirm(confirm, "update_flash")
+    _check_esp32_env(env)
+
+    if userprefs_overrides and skip_build:
+        raise FlashError(
+            "userprefs_overrides forces a rebuild so the firmware.bin reflects "
+            "the new values; skip_build=True is incompatible."
+        )
+
+    with userprefs.temporary_overrides(userprefs_overrides) as effective:
+        firmware = _firmware_bin_for(env)
+        if firmware is None or userprefs_overrides:
+            if skip_build:
+                raise FlashError(
+                    f"No firmware.bin found for env {env!r} and skip_build=True. "
+                    "Run `build` first or set skip_build=False."
+                )
+            build_args = ["run", "-e", env, "-t", "mtjson"]
+            build_result = pio.run(build_args, timeout=pio.TIMEOUT_BUILD, check=False)
+            if build_result.returncode != 0:
+                return {
+                    "exit_code": build_result.returncode,
+                    "stdout_tail": pio.tail_lines(build_result.stdout, 200),
+                    "stderr_tail": pio.tail_lines(build_result.stderr, 200),
+                    "duration_s": round(build_result.duration_s, 2),
+                    "error": "build failed before update_flash could run",
+                    "userprefs": _userprefs_summary(effective),
+                }
+            firmware = _firmware_bin_for(env)
+            if firmware is None:
+                raise FlashError(
+                    f"Build succeeded but no firmware.bin appeared in .pio/build/{env}/"
+                )
+
+        script = config.firmware_root() / "bin" / "device-update.sh"
+        if not script.is_file():
+            raise FlashError(f"device-update.sh not found at {script}")
+        result = _run_install_script(script, port, firmware)
+
+    result["userprefs"] = _userprefs_summary(effective)
+    return result
+
+
+def touch_1200bps(port: str, settle_ms: int = 250) -> dict[str, Any]:
+    """Open port at 1200 baud, close immediately — triggers USB CDC bootloader.
+
+    Works for: nRF52840 (Adafruit bootloader), ESP32-S3 (native USB download
+    mode), RP2040 (when built with 1200bps-reset stdio), Arduino Leonardo/Micro.
+
+    Afterward, polls `list_devices()` for up to 3 seconds to detect a new
+    bootloader port that replaced the original application port.
+    """
+    before_ports = {d["port"] for d in devices.list_devices(include_unknown=True)}
+
+    try:
+        s = serial.Serial(port, 1200)
+        # Some drivers need a brief settle before close; others disconnect
+        # immediately when we set 1200 baud. Either is fine.
+        time.sleep(settle_ms / 1000.0)
+        try:
+            s.close()
+        except Exception:
+            pass
+    except serial.SerialException as exc:
+        # Many boards drop the port mid-open when 1200 is set; that's expected.
+        # Only treat "port doesn't exist" as a real error.
+        if "No such file" in str(exc) or "could not open" in str(exc).lower():
+            raise FlashError(f"Cannot open {port}: {exc}") from exc
+
+    # Poll for a new port appearing (bootloader) or the old one disappearing
+    deadline = time.monotonic() + 3.0
+    new_port: str | None = None
+    while time.monotonic() < deadline:
+        time.sleep(0.2)
+        current = {d["port"] for d in devices.list_devices(include_unknown=True)}
+        added = current - before_ports
+        if added:
+            # Prefer a likely-meshtastic port among the newly appeared ones.
+            current_list = devices.list_devices(include_unknown=True)
+            added_records = [d for d in current_list if d["port"] in added]
+            likely = next((d for d in added_records if d["likely_meshtastic"]), None)
+            new_port = (likely or added_records[0])["port"]
+            break
+        if port not in current:
+            # Old port went away entirely; bootloader may have shown up with a
+            # different name. Give it a moment more.
+            continue
+
+    return {
+        "ok": True,
+        "former_port": port,
+        "new_port": new_port,
+    }

mcp-server/src/meshtastic_mcp/hw_tools.py

@@ -0,0 +1,243 @@
+"""Direct wrappers around vendor flashing tools: esptool, nrfutil, picotool.
+
+These are escape hatches. Prefer the pio-based tools in flash.py when they
+cover the operation — pio knows the correct offsets, protocols, and filters
+for every supported board. Use these when pio doesn't: to erase a bricked
+ESP32, DFU-flash an nRF52 zip package, or inspect an RP2040's bootloader.
+
+Every destructive `*_raw` subcommand is gated by `confirm=True` so callers
+can't accidentally `--write-flash` from freeform args.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Sequence
+
+from . import config, pio
+
+_TIMEOUT_SHORT = 30
+_TIMEOUT_LONG = 600
+
+
+class ToolError(RuntimeError):
+    pass
+
+
+def _run(
+    binary: Path,
+    args: Sequence[str],
+    *,
+    timeout: float = _TIMEOUT_LONG,
+    cwd: Path | None = None,
+) -> dict[str, Any]:
+    t0 = time.monotonic()
+    try:
+        proc = subprocess.run(
+            [str(binary), *args],
+            cwd=str(cwd) if cwd else None,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise ToolError(
+            f"{binary.name} {' '.join(args)} timed out after {timeout}s"
+        ) from exc
+    duration = time.monotonic() - t0
+    return {
+        "exit_code": proc.returncode,
+        "stdout": proc.stdout or "",
+        "stderr": proc.stderr or "",
+        "stdout_tail": pio.tail_lines(proc.stdout or "", 200),
+        "stderr_tail": pio.tail_lines(proc.stderr or "", 200),
+        "duration_s": round(duration, 2),
+    }
+
+
+def _require_confirm(confirm: bool, what: str) -> None:
+    if not confirm:
+        raise ToolError(f"{what} is destructive and requires confirm=True.")
+
+
+# ---------- esptool --------------------------------------------------------
+
+ESPTOOL_DESTRUCTIVE = {
+    "write_flash",
+    "write-flash",
+    "erase_flash",
+    "erase-flash",
+    "erase_region",
+    "erase-region",
+    "merge_bin",
+    "merge-bin",
+}
+
+
+def _parse_esptool_chip_info(stdout: str) -> dict[str, Any]:
+    """Parse `esptool chip_id` / `flash_id` output into structured fields."""
+    result: dict[str, Any] = {
+        "chip": None,
+        "mac": None,
+        "crystal_mhz": None,
+        "flash_size": None,
+        "features": [],
+    }
+    for line in stdout.splitlines():
+        line = line.strip()
+        if m := re.match(r"Chip is (.+)", line):
+            result["chip"] = m.group(1).strip()
+        elif m := re.match(r"MAC: ([0-9a-fA-F:]+)", line):
+            result["mac"] = m.group(1)
+        elif m := re.match(r"Crystal is (\d+)MHz", line):
+            result["crystal_mhz"] = int(m.group(1))
+        elif m := re.match(r"Detected flash size: (\S+)", line):
+            result["flash_size"] = m.group(1)
+        elif m := re.match(r"Features: (.+)", line):
+            result["features"] = [f.strip() for f in m.group(1).split(",") if f.strip()]
+    return result
+
+
+def esptool_chip_info(port: str) -> dict[str, Any]:
+    binary = config.esptool_bin()
+    # `chip_id` prints chip + mac + crystal + features. `flash_id` adds flash.
+    combined = _run(binary, ["--port", port, "flash_id"], timeout=_TIMEOUT_SHORT)
+    if combined["exit_code"] != 0:
+        raise ToolError(
+            f"esptool failed (exit {combined['exit_code']}):\n{combined['stderr_tail']}"
+        )
+    parsed = _parse_esptool_chip_info(combined["stdout"])
+    return {**parsed, "raw_stdout_tail": combined["stdout_tail"]}
+
+
+def esptool_erase_flash(port: str, confirm: bool = False) -> dict[str, Any]:
+    """Full-chip erase. Leaves the device unbootable until reflashed."""
+    _require_confirm(confirm, "esptool_erase_flash")
+    binary = config.esptool_bin()
+    # esptool v5 uses `erase-flash`, older uses `erase_flash`. Try the new name
+    # first; if it fails with unknown command, retry old.
+    res = _run(binary, ["--port", port, "erase-flash"], timeout=_TIMEOUT_LONG)
+    if (
+        res["exit_code"] != 0
+        and "unrecognized" in (res["stderr"] or res["stdout"]).lower()
+    ):
+        res = _run(binary, ["--port", port, "erase_flash"], timeout=_TIMEOUT_LONG)
+    return res
+
+
+def esptool_raw(
+    args: list[str], port: str | None = None, confirm: bool = False
+) -> dict[str, Any]:
+    """Raw esptool passthrough. Destructive subcommands require confirm=True."""
+    if not args:
+        raise ToolError("args must not be empty")
+    # Find the first non-flag arg (the subcommand).
+    subcommand = next((a for a in args if not a.startswith("-")), None)
+    if subcommand and subcommand.replace("-", "_") in {
+        s.replace("-", "_") for s in ESPTOOL_DESTRUCTIVE
+    }:
+        _require_confirm(confirm, f"esptool {subcommand}")
+
+    binary = config.esptool_bin()
+    full_args: list[str] = []
+    if port:
+        full_args.extend(["--port", port])
+    full_args.extend(args)
+    return _run(binary, full_args, timeout=_TIMEOUT_LONG)
+
+
+# ---------- nrfutil --------------------------------------------------------
+
+NRFUTIL_DESTRUCTIVE = {"dfu", "settings"}
+
+
+def nrfutil_dfu(port: str, package_path: str, confirm: bool = False) -> dict[str, Any]:
+    _require_confirm(confirm, "nrfutil_dfu")
+    pkg = Path(package_path).expanduser()
+    if not pkg.is_file():
+        raise ToolError(f"Package not found: {pkg}")
+    binary = config.nrfutil_bin()
+    return _run(
+        binary,
+        ["dfu", "serial", "--package", str(pkg), "--port", port, "-b", "115200"],
+        timeout=_TIMEOUT_LONG,
+    )
+
+
+def nrfutil_raw(args: list[str], confirm: bool = False) -> dict[str, Any]:
+    if not args:
+        raise ToolError("args must not be empty")
+    subcommand = next((a for a in args if not a.startswith("-")), None)
+    if subcommand in NRFUTIL_DESTRUCTIVE:
+        _require_confirm(confirm, f"nrfutil {subcommand}")
+    binary = config.nrfutil_bin()
+    return _run(binary, args, timeout=_TIMEOUT_LONG)
+
+
+# ---------- picotool -------------------------------------------------------
+
+PICOTOOL_DESTRUCTIVE = {"load", "reboot", "save", "erase"}
+
+
+def _parse_picotool_info(stdout: str) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "vendor": None,
+        "product": None,
+        "serial": None,
+        "flash_size": None,
+        "program_name": None,
+        "program_version": None,
+    }
+    for line in stdout.splitlines():
+        line = line.strip()
+        if m := re.match(r"Program information:", line):
+            continue
+        if m := re.match(r"name:\s*(.+)", line):
+            result["program_name"] = m.group(1).strip()
+        elif m := re.match(r"version:\s*(.+)", line):
+            result["program_version"] = m.group(1).strip()
+        elif m := re.match(r"vendor:\s*(.+)", line):
+            result["vendor"] = m.group(1).strip()
+        elif m := re.match(r"product:\s*(.+)", line):
+            result["product"] = m.group(1).strip()
+        elif m := re.match(r"serial number:\s*(.+)", line):
+            result["serial"] = m.group(1).strip()
+        elif m := re.match(r"flash size:\s*(.+)", line):
+            result["flash_size"] = m.group(1).strip()
+    return result
+
+
+def picotool_info(port: str | None = None) -> dict[str, Any]:
+    """Read device info from a Pico in BOOTSEL mode. `port` is informational
+    only — picotool auto-detects."""
+    binary = config.picotool_bin()
+    res = _run(binary, ["info", "-a"], timeout=_TIMEOUT_SHORT)
+    if res["exit_code"] != 0:
+        raise ToolError(
+            f"picotool info failed (exit {res['exit_code']}): "
+            "is the Pico in BOOTSEL mode?\n" + res["stderr_tail"]
+        )
+    parsed = _parse_picotool_info(res["stdout"])
+    return {**parsed, "raw_stdout_tail": res["stdout_tail"]}
+
+
+def picotool_load(uf2_path: str, confirm: bool = False) -> dict[str, Any]:
+    _require_confirm(confirm, "picotool_load")
+    uf2 = Path(uf2_path).expanduser()
+    if not uf2.is_file():
+        raise ToolError(f"UF2 not found: {uf2}")
+    binary = config.picotool_bin()
+    return _run(binary, ["load", "-x", "-t", "uf2", str(uf2)], timeout=_TIMEOUT_LONG)
+
+
+def picotool_raw(args: list[str], confirm: bool = False) -> dict[str, Any]:
+    if not args:
+        raise ToolError("args must not be empty")
+    subcommand = next((a for a in args if not a.startswith("-")), None)
+    if subcommand in PICOTOOL_DESTRUCTIVE:
+        _require_confirm(confirm, f"picotool {subcommand}")
+    binary = config.picotool_bin()
+    return _run(binary, args, timeout=_TIMEOUT_LONG)

mcp-server/src/meshtastic_mcp/info.py

@@ -0,0 +1,103 @@
+"""Read-only device queries via meshtastic.SerialInterface."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .connection import connect
+
+
+def _primary_channel_name(iface) -> str | None:
+    try:
+        channels = iface.localNode.channels or []
+    except AttributeError:
+        return None
+    for ch in channels:
+        role = getattr(ch, "role", None)
+        # Role enum: 0 DISABLED, 1 PRIMARY, 2 SECONDARY
+        if role == 1:
+            name = getattr(getattr(ch, "settings", None), "name", None)
+            return name or "(default)"
+    return None
+
+
+def device_info(port: str | None = None, timeout_s: float = 8.0) -> dict[str, Any]:
+    """Return summary info for the connected device."""
+    with connect(port=port, timeout_s=timeout_s) as iface:
+        my = iface.myInfo
+        meta = iface.metadata
+        local = iface.localNode
+
+        # Owner (long/short name) is on the local node's user record
+        long_name: str | None = None
+        short_name: str | None = None
+        hw_model: str | int | None = None
+        if iface.nodesByNum and my is not None:
+            local_rec = iface.nodesByNum.get(my.my_node_num, {})
+            user = local_rec.get("user") or {}
+            long_name = user.get("longName")
+            short_name = user.get("shortName")
+            hw_model = user.get("hwModel")
+
+        region = None
+        if local is not None and local.localConfig is not None:
+            try:
+                lora = local.localConfig.lora
+                # region is an enum; get its string name
+                region = (
+                    lora.DESCRIPTOR.fields_by_name["region"]
+                    .enum_type.values_by_number[lora.region]
+                    .name
+                )
+            except Exception:
+                region = None
+
+        return {
+            "port": iface.devPath if hasattr(iface, "devPath") else port,
+            "my_node_num": getattr(my, "my_node_num", None),
+            "long_name": long_name,
+            "short_name": short_name,
+            "firmware_version": getattr(meta, "firmware_version", None),
+            "hw_model": hw_model,
+            "region": region,
+            "num_nodes": len(iface.nodesByNum) if iface.nodesByNum else 0,
+            "primary_channel": _primary_channel_name(iface),
+        }
+
+
+def _node_record(node_dict: dict[str, Any]) -> dict[str, Any]:
+    user = node_dict.get("user") or {}
+    position = node_dict.get("position") or None
+    device_metrics = node_dict.get("deviceMetrics") or {}
+    return {
+        "node_num": node_dict.get("num"),
+        "user": {
+            "long_name": user.get("longName"),
+            "short_name": user.get("shortName"),
+            "hw_model": user.get("hwModel"),
+            "role": user.get("role"),
+        },
+        "position": (
+            {
+                "latitude": position.get("latitude"),
+                "longitude": position.get("longitude"),
+                "altitude": position.get("altitude"),
+                "time": position.get("time"),
+            }
+            if position
+            else None
+        ),
+        "snr": node_dict.get("snr"),
+        "rssi": node_dict.get("rssi"),
+        "last_heard": node_dict.get("lastHeard"),
+        "battery_level": device_metrics.get("batteryLevel"),
+        "is_favorite": bool(node_dict.get("isFavorite", False)),
+    }
+
+
+def list_nodes(port: str | None = None, timeout_s: float = 8.0) -> list[dict[str, Any]]:
+    """Return the device's node database."""
+    with connect(port=port, timeout_s=timeout_s) as iface:
+        if not iface.nodesByNum:
+            return []
+        return [_node_record(n) for n in iface.nodesByNum.values()]

mcp-server/src/meshtastic_mcp/pio.py

@@ -0,0 +1,124 @@
+"""Subprocess wrappers around the `pio` CLI.
+
+Every PlatformIO interaction in this package funnels through `run()` so we
+have a single place that owns timeouts, buffer sizes, JSON parsing, and the
+"stderr on exit-0 is informational" convention.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+from . import config
+
+# 10 MB matches the reference impl (jl-codes/platformio-mcp). Build output can
+# be hundreds of KB; we'd rather keep it in memory than truncate.
+_MAX_BUFFER = 10 * 1024 * 1024
+
+# Per-operation defaults (seconds). None = no timeout.
+TIMEOUT_DEFAULT = 120
+TIMEOUT_PROJECT_CONFIG = 60
+TIMEOUT_DEVICE_LIST = 15
+TIMEOUT_BUILD = 900
+TIMEOUT_UPLOAD = 600
+
+
+class PioError(RuntimeError):
+    """pio exited non-zero."""
+
+    def __init__(self, args: Sequence[str], returncode: int, stdout: str, stderr: str):
+        self.args = list(args)
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+        tail = (stderr or stdout).strip().splitlines()[-20:]
+        super().__init__(
+            f"pio {' '.join(args)} failed with exit {returncode}:\n" + "\n".join(tail)
+        )
+
+
+class PioTimeout(RuntimeError):
+    """pio did not return within the timeout."""
+
+
+@dataclass
+class PioResult:
+    args: list[str]
+    returncode: int
+    stdout: str
+    stderr: str
+    duration_s: float
+
+
+def run(
+    args: Sequence[str],
+    *,
+    cwd: Path | None = None,
+    timeout: float | None = TIMEOUT_DEFAULT,
+    check: bool = True,
+) -> PioResult:
+    """Invoke `pio <args>` and return captured output.
+
+    `cwd` defaults to the firmware root. `check=True` raises `PioError` on
+    non-zero exit; set `check=False` to inspect `returncode` manually.
+    """
+    binary = str(config.pio_bin())
+    work_dir = cwd or config.firmware_root()
+    full = [binary, *args]
+    t0 = time.monotonic()
+    try:
+        proc = subprocess.run(
+            full,
+            cwd=str(work_dir),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise PioTimeout(f"pio {' '.join(args)} timed out after {timeout}s") from exc
+    duration = time.monotonic() - t0
+
+    result = PioResult(
+        args=list(args),
+        returncode=proc.returncode,
+        stdout=proc.stdout or "",
+        stderr=proc.stderr or "",
+        duration_s=duration,
+    )
+    if check and result.returncode != 0:
+        raise PioError(args, result.returncode, result.stdout, result.stderr)
+    return result
+
+
+def run_json(
+    args: Sequence[str],
+    *,
+    cwd: Path | None = None,
+    timeout: float | None = TIMEOUT_DEFAULT,
+):
+    """Run pio with `--json-output` appended and parse the result."""
+    full = list(args)
+    if "--json-output" not in full:
+        full.append("--json-output")
+    res = run(full, cwd=cwd, timeout=timeout, check=True)
+    if not res.stdout.strip():
+        raise PioError(args, 0, res.stdout, res.stderr or "pio returned empty output")
+    try:
+        return json.loads(res.stdout)
+    except json.JSONDecodeError as exc:
+        raise PioError(
+            args, 0, res.stdout[:2000], f"invalid JSON from pio: {exc}"
+        ) from exc
+
+
+def tail_lines(text: str, n: int = 200) -> str:
+    """Last `n` lines of `text`, joined with newlines. Empty string stays empty."""
+    if not text:
+        return ""
+    lines = text.splitlines()
+    return "\n".join(lines[-n:])

mcp-server/src/meshtastic_mcp/registry.py

@@ -0,0 +1,99 @@
+"""In-memory registry of active serial monitor sessions and port locks.
+
+Two things live here so the rest of the package has a single place to reach
+them:
+  1. `sessions`: `{session_id: SerialSession}` for pio device monitor subprocs.
+  2. `port_locks`: `{port: threading.Lock}` so admin/info tools can fail fast
+     when a serial monitor or another meshtastic client already owns a port.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from .serial_session import SerialSession, close_session
+
+_LOCK = threading.Lock()
+_sessions: dict[str, SerialSession] = {}
+_port_locks: dict[str, threading.Lock] = {}
+
+
+def register_session(session: SerialSession) -> None:
+    with _LOCK:
+        _sessions[session.id] = session
+
+
+def get_session(session_id: str) -> SerialSession:
+    with _LOCK:
+        session = _sessions.get(session_id)
+    if session is None:
+        raise KeyError(f"Unknown session_id: {session_id!r}")
+    return session
+
+
+def remove_session(session_id: str) -> SerialSession | None:
+    with _LOCK:
+        return _sessions.pop(session_id, None)
+
+
+def active_session_for_port(port: str) -> SerialSession | None:
+    """Find any active (non-eof) session owning `port`."""
+    sweep_dead()
+    with _LOCK:
+        for s in _sessions.values():
+            if s.port == port and s.proc.poll() is None:
+                return s
+    return None
+
+
+def all_sessions() -> list[SerialSession]:
+    with _LOCK:
+        return list(_sessions.values())
+
+
+def sweep_dead() -> int:
+    """Remove sessions whose subprocess has exited. Returns count removed."""
+    removed = 0
+    with _LOCK:
+        for sid in list(_sessions):
+            s = _sessions[sid]
+            if s.proc.poll() is not None:
+                # Leave the session object around for one read so callers can
+                # see eof=True. We only remove after stopped_at is older than
+                # a few seconds, so an immediate poll-after-close still sees
+                # it. For v1 simpler: just leave dead sessions until explicit
+                # close. No-op.
+                pass
+    return removed
+
+
+def shutdown_all() -> None:
+    """Close every live session (called on server exit)."""
+    with _LOCK:
+        items = list(_sessions.items())
+        _sessions.clear()
+    for _sid, session in items:
+        try:
+            close_session(session)
+        except Exception:
+            pass
+
+
+def port_lock(port: str) -> threading.Lock:
+    """Per-port lock for SerialInterface / admin tool serialization."""
+    with _LOCK:
+        lock = _port_locks.get(port)
+        if lock is None:
+            lock = threading.Lock()
+            _port_locks[port] = lock
+        return lock
+
+
+def snapshot() -> dict[str, Any]:
+    """Debug dump: session count, port lock count."""
+    with _LOCK:
+        return {
+            "sessions": len(_sessions),
+            "port_locks": len(_port_locks),
+        }

mcp-server/src/meshtastic_mcp/serial_session.py

@@ -0,0 +1,178 @@
+"""Long-running serial monitor sessions via `pio device monitor`.
+
+Why pio instead of raw pyserial: pio applies the board's monitor_filters —
+`esp32_exception_decoder` symbolicates crash stacks, `time` adds timestamps,
+etc. Raw pyserial would give us bytes; pio gives us developer-grade logs.
+
+Each session runs `pio device monitor` in a subprocess, with a daemon reader
+thread draining stdout into a bounded ring buffer. Callers pull lines via
+`serial_read` using a cursor that survives across calls.
+"""
+
+from __future__ import annotations
+
+import collections
+import subprocess
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from . import config, pio
+
+_BUFFER_MAX_LINES = 10_000
+_POLL_NEW_PORT_TIMEOUT_S = 3.0
+
+
+@dataclass
+class SerialSession:
+    id: str
+    port: str
+    baud: int
+    filters: list[str]
+    env: str | None
+    proc: subprocess.Popen
+    buffer: collections.deque = field(
+        default_factory=lambda: collections.deque(maxlen=_BUFFER_MAX_LINES)
+    )
+    # Total lines seen (not bounded by buffer maxlen). `dropped = total - len(buffer)`
+    # if the reader has advanced past buffer head.
+    total_lines: int = 0
+    started_at: float = field(default_factory=time.time)
+    stopped_at: float | None = None
+    lock: threading.Lock = field(default_factory=threading.Lock)
+    _thread: threading.Thread | None = None
+
+
+def _drain(session: SerialSession) -> None:
+    """Reader thread: line-by-line pull stdout into buffer."""
+    assert session.proc.stdout is not None
+    try:
+        for line in session.proc.stdout:
+            line_stripped = line.rstrip("\r\n")
+            with session.lock:
+                session.buffer.append(line_stripped)
+                session.total_lines += 1
+    except Exception:  # pragma: no cover - defensive
+        pass
+    finally:
+        session.stopped_at = time.time()
+
+
+def open_session(
+    port: str,
+    baud: int = 115200,
+    env: str | None = None,
+    filters: list[str] | None = None,
+) -> SerialSession:
+    """Spawn `pio device monitor` and return a SerialSession.
+
+    If `env` is supplied, pio resolves baud and filters from platformio.ini.
+    Otherwise uses the supplied `baud` and `filters` (default `['direct']`).
+    """
+    args = ["device", "monitor", "--port", port, "--no-reconnect"]
+    effective_filters: list[str]
+    effective_baud: int = baud
+    if env is not None:
+        args.extend(["-e", env])
+        effective_filters = filters or []  # pio will fill in from env
+    else:
+        args.extend(["--baud", str(baud)])
+        effective_filters = filters or ["direct"]
+        for f in effective_filters:
+            args.extend(["--filter", f])
+
+    binary = str(config.pio_bin())
+    work_dir = str(config.firmware_root())
+
+    proc = subprocess.Popen(
+        [binary, *args],
+        cwd=work_dir,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,  # line-buffered
+    )
+
+    session = SerialSession(
+        id=uuid.uuid4().hex,
+        port=port,
+        baud=effective_baud,
+        filters=effective_filters,
+        env=env,
+        proc=proc,
+    )
+    t = threading.Thread(target=_drain, args=(session,), daemon=True)
+    t.start()
+    session._thread = t
+    return session
+
+
+def read_session(
+    session: SerialSession, max_lines: int = 200, since_cursor: int | None = None
+) -> dict[str, Any]:
+    """Snapshot recent lines from the buffer.
+
+    Cursor semantics: the global cursor is `total_lines` at read time. Pass
+    `since_cursor` from a previous response's `new_cursor` to page forward.
+    `since_cursor=0` reads everything still in the ring buffer.
+    """
+    with session.lock:
+        total = session.total_lines
+        buf_len = len(session.buffer)
+        head_cursor = total - buf_len  # cursor value at buffer[0]
+        current_buffer = list(session.buffer)
+
+    if since_cursor is None:
+        since_cursor = head_cursor
+
+    # Clamp: never read what's aged out of the buffer.
+    effective_start = max(since_cursor, head_cursor)
+    # Number of lines skipped because they aged out between reads.
+    dropped = max(0, head_cursor - since_cursor) if since_cursor < head_cursor else 0
+
+    start_idx = effective_start - head_cursor
+    end_idx = min(start_idx + max_lines, buf_len)
+    lines = current_buffer[start_idx:end_idx]
+    new_cursor = effective_start + len(lines)
+
+    eof = session.proc.poll() is not None
+    return {
+        "lines": lines,
+        "new_cursor": new_cursor,
+        "eof": eof,
+        "dropped": dropped,
+    }
+
+
+def close_session(session: SerialSession) -> bool:
+    """Terminate the subprocess and join the reader thread."""
+    proc = session.proc
+    if proc.poll() is None:
+        try:
+            proc.terminate()
+            proc.wait(timeout=3)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait(timeout=3)
+    if session._thread is not None:
+        session._thread.join(timeout=3)
+    session.stopped_at = session.stopped_at or time.time()
+    return True
+
+
+def session_summary(session: SerialSession) -> dict[str, Any]:
+    with session.lock:
+        line_count = session.total_lines
+    return {
+        "session_id": session.id,
+        "port": session.port,
+        "baud": session.baud,
+        "filters": session.filters,
+        "env": session.env,
+        "started_at": session.started_at,
+        "stopped_at": session.stopped_at,
+        "line_count": line_count,
+        "eof": session.proc.poll() is not None,
+    }

mcp-server/src/meshtastic_mcp/server.py

@@ -0,0 +1,569 @@
+"""FastMCP server wiring — 32 tools across 6 categories.
+
+Each tool handler is a thin delegation to a named module (pio.py, admin.py,
+etc.). Business logic does not live here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from . import (
+    admin,
+    boards,
+    devices,
+    flash,
+    hw_tools,
+    info,
+    registry,
+    serial_session,
+)
+from . import userprefs as userprefs_mod
+
+app = FastMCP("meshtastic-mcp")
+
+
+# ---------- Discovery & metadata ------------------------------------------
+
+
+@app.tool()
+def list_devices(include_unknown: bool = False) -> list[dict[str, Any]]:
+    """List USB/serial ports, flagging those likely to be Meshtastic devices.
+
+    With include_unknown=True, returns every serial port the OS knows about
+    (useful for debugging when a device isn't detected). Otherwise returns
+    only likely-Meshtastic candidates.
+    """
+    return devices.list_devices(include_unknown=include_unknown)
+
+
+@app.tool()
+def list_boards(
+    architecture: str | None = None,
+    actively_supported_only: bool = False,
+    query: str | None = None,
+    board_level: str | None = None,
+) -> list[dict[str, Any]]:
+    """Enumerate PlatformIO envs (boards) with Meshtastic metadata.
+
+    architecture: filter to one arch ("esp32", "esp32s3", "nrf52840", "rp2040", "stm32", "native").
+    actively_supported_only: filter to boards marked custom_meshtastic_actively_supported=true.
+    query: substring match on display_name, env name, or hw_model_slug (case-insensitive).
+    board_level: "release" (default-track release boards), "pr" (PR CI), or "extra" (opt-in extras).
+    """
+    return boards.list_boards(
+        architecture=architecture,
+        actively_supported_only=actively_supported_only,
+        query=query,
+        board_level=board_level,
+    )
+
+
+@app.tool()
+def get_board(env: str) -> dict[str, Any]:
+    """Full metadata for one PlatformIO env, including raw pio config fields."""
+    return boards.get_board(env)
+
+
+# ---------- Build & flash -------------------------------------------------
+
+
+@app.tool()
+def build(
+    env: str,
+    with_manifest: bool = True,
+    userprefs: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build firmware for one env via `pio run -e <env>`.
+
+    Returns exit_code, duration, artifact paths under .pio/build/<env>/, and
+    tails of stdout/stderr (last 200 lines each). with_manifest=True adds the
+    mtjson target which produces an .mt.json manifest alongside the firmware.
+
+    `userprefs` (optional): dict of `USERPREFS_<KEY>: value` baked into this
+    build via userPrefs.jsonc injection. The file is restored after the build
+    completes. Use `userprefs_manifest` to discover available keys. Use
+    `userprefs_set` for persistent changes.
+    """
+    return flash.build(env, with_manifest=with_manifest, userprefs_overrides=userprefs)
+
+
+@app.tool()
+def clean(env: str) -> dict[str, Any]:
+    """Clean one env's build output via `pio run -e <env> -t clean`.
+
+    Useful when switching branches or debugging a stale-cache build failure.
+    """
+    return flash.clean(env)
+
+
+@app.tool()
+def pio_flash(
+    env: str,
+    port: str,
+    confirm: bool = False,
+    userprefs: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Flash firmware via `pio run -e <env> -t upload --upload-port <port>`.
+
+    Works for any architecture (ESP32/nRF52/RP2040/STM32). Requires confirm=True.
+    For first-time flashing a blank ESP32 board (erase + bootloader + app + fs),
+    prefer `erase_and_flash`. For ESP32 OTA updates, prefer `update_flash`.
+
+    `userprefs` (optional): dict of `USERPREFS_<KEY>: value` baked into this
+    build via userPrefs.jsonc injection; restored after upload.
+    """
+    return flash.flash(env, port, confirm=confirm, userprefs_overrides=userprefs)
+
+
+@app.tool()
+def erase_and_flash(
+    env: str,
+    port: str,
+    confirm: bool = False,
+    skip_build: bool = False,
+    userprefs: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """ESP32-only: full erase + factory flash via bin/device-install.sh.
+
+    Wipes the entire flash and writes bootloader, app, OTA, and LittleFS
+    partitions from the factory.bin. Requires confirm=True. Runs `build` first
+    if no factory.bin is present (set skip_build=True to require a prior build).
+
+    `userprefs` (optional): dict of `USERPREFS_<KEY>: value` baked into the
+    factory.bin via userPrefs.jsonc injection. When provided, forces a rebuild
+    (skip_build=True is incompatible). File is restored after upload.
+    """
+    return flash.erase_and_flash(
+        env, port, confirm=confirm, skip_build=skip_build, userprefs_overrides=userprefs
+    )
+
+
+@app.tool()
+def update_flash(
+    env: str,
+    port: str,
+    confirm: bool = False,
+    skip_build: bool = False,
+    userprefs: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """ESP32-only: OTA app-partition update via bin/device-update.sh.
+
+    Updates only the application partition, preserving device config and node
+    database. Faster than erase_and_flash but won't recover a broken bootloader.
+    Requires confirm=True. Builds first if needed.
+
+    `userprefs` (optional): dict of `USERPREFS_<KEY>: value` baked into the
+    firmware.bin via userPrefs.jsonc injection. When provided, forces a rebuild.
+    """
+    return flash.update_flash(
+        env, port, confirm=confirm, skip_build=skip_build, userprefs_overrides=userprefs
+    )
+
+
+# ---------- USERPREFS discovery & persistence -----------------------------
+
+
+@app.tool()
+def userprefs_manifest() -> dict[str, Any]:
+    """Full manifest of USERPREFS_* keys the firmware knows about.
+
+    Combines `userPrefs.jsonc` (active + commented examples) with a scan of
+    `src/**` for `USERPREFS_<KEY>` references — so every key the firmware
+    actually consumes shows up, even if undocumented in the jsonc.
+
+    Each entry has: key, active (is it uncommented), value (current), example
+    (jsonc commented default), declared_in_jsonc, consumed_by (list of src
+    files), inferred_type (brace|number|bool|enum|string|unknown).
+
+    `inferred_type` mirrors how platformio-custom.py wraps values at build
+    time: `brace` = byte array `{ 0x01, ... }`, `number` = decimal, `bool` =
+    true/false, `enum` = `meshtastic_*` constant, `string` = wrapped in quotes
+    via StringifyMacro.
+    """
+    return userprefs_mod.build_manifest()
+
+
+@app.tool()
+def userprefs_get() -> dict[str, Any]:
+    """Return the current userPrefs.jsonc state.
+
+    `active` is the dict of uncommented `USERPREFS_*` → value that will be
+    baked into the next build. `commented` is the dict of commented example
+    defaults (shown for reference).
+    """
+    state = userprefs_mod.read_state()
+    # Drop `order` (internal for round-trip rendering) from the public payload.
+    return {
+        "path": state["path"],
+        "active": state["active"],
+        "commented": state["commented"],
+    }
+
+
+@app.tool()
+def userprefs_set(prefs: dict[str, Any]) -> dict[str, Any]:
+    """Persistently merge `prefs` into userPrefs.jsonc (uncommenting keys).
+
+    Existing active values not in `prefs` are kept. To remove a key from the
+    active set, call `userprefs_reset` (restores the MCP backup if present)
+    or edit the jsonc manually. Values are stringified the way
+    platformio-custom.py expects (bool → "true"/"false", int → "42", etc.).
+    """
+    return userprefs_mod.merge_active(prefs)
+
+
+@app.tool()
+def userprefs_reset() -> dict[str, Any]:
+    """Restore userPrefs.jsonc from the most recent MCP backup (if any).
+
+    The backup is only created by the legacy `userprefs_set` workflow (not
+    currently written automatically). Returns `{restored: bool, ...}` — false
+    when no backup is present, in which case the caller should edit the
+    jsonc directly.
+    """
+    return userprefs_mod.reset()
+
+
+@app.tool()
+def userprefs_testing_profile(
+    psk_seed: str | None = None,
+    channel_name: str = "McpTest",
+    channel_num: int = 88,
+    region: str = "US",
+    modem_preset: str = "LONG_FAST",
+    short_name: str | None = None,
+    long_name: str | None = None,
+    disable_mqtt: bool = True,
+    disable_position: bool = False,
+) -> dict[str, Any]:
+    """Generate a USERPREFS dict for provisioning an isolated test-mesh device.
+
+    Baking this into firmware produces devices that:
+      - Run on a deterministic non-default LoRa slot (default 88 on US LONG_FAST,
+        well off the `hash("LongFast")` slot a stock production device uses)
+      - Join a private channel with a name and PSK that differ from public
+        defaults — so no accidental mesh-with-production-devices
+      - Have MQTT disabled (no uplink/downlink bridge), so test traffic never
+        leaks to a public broker
+      - Optionally disable GPS for bench-test conditions
+
+    For a multi-device test cluster, pass the same `psk_seed` to every call so
+    every device shares the same PSK and lands on the same isolated mesh.
+
+    Returned dict is ready to pass straight to `build`, `pio_flash`,
+    `erase_and_flash`, or `update_flash` via their `userprefs` parameter.
+
+    Example:
+        profile = userprefs_testing_profile(psk_seed="ci-run-2026-04-16")
+        erase_and_flash(env="tbeam", port="/dev/cu.usbmodem...", confirm=True,
+                        userprefs=profile)
+
+    Args:
+        psk_seed: seed for deterministic 32-byte PSK via SHA-256. None = random
+            (fine one-off, useless for multi-device clusters).
+        channel_name: primary channel name (≤11 chars). Default "McpTest".
+        channel_num: 1-indexed LoRa slot (0 = fall back to name-hash). Default
+            88 — mid-upper US band, unlikely to collide with production slots.
+        region: short code — one of US, EU_433, EU_868, CN, JP, ANZ, KR, TW,
+            RU, IN, NZ_865, TH, UA_433, UA_868, MY_433, MY_919, SG_923, LORA_24.
+        modem_preset: one of LONG_FAST, LONG_SLOW, LONG_MODERATE, VERY_LONG_SLOW,
+            MEDIUM_SLOW, MEDIUM_FAST, SHORT_SLOW, SHORT_FAST, SHORT_TURBO.
+        short_name: optional owner short name (≤4 chars) stamped into the build.
+        long_name: optional owner long name stamped into the build.
+        disable_mqtt: disable MQTT module + uplink/downlink (default True).
+        disable_position: disable GPS + smart-position broadcasts (default False).
+    """
+    return userprefs_mod.build_testing_profile(
+        psk_seed=psk_seed,
+        channel_name=channel_name,
+        channel_num=channel_num,
+        region=region,
+        modem_preset=modem_preset,
+        short_name=short_name,
+        long_name=long_name,
+        disable_mqtt=disable_mqtt,
+        disable_position=disable_position,
+    )
+
+
+@app.tool()
+def touch_1200bps(port: str, settle_ms: int = 250) -> dict[str, Any]:
+    """Open `port` at 1200 baud and immediately close, triggering USB CDC
+    bootloader entry on nRF52840, ESP32-S3 (native USB), RP2040, etc.
+
+    After the touch, polls serial devices for up to 3 seconds and reports any
+    new port that appeared (the bootloader often enumerates as a different
+    device). Not destructive — this is just a reset signal.
+    """
+    return flash.touch_1200bps(port, settle_ms=settle_ms)
+
+
+# ---------- Serial log sessions -------------------------------------------
+
+
+@app.tool()
+def serial_open(
+    port: str,
+    baud: int = 115200,
+    env: str | None = None,
+    filters: list[str] | None = None,
+) -> dict[str, Any]:
+    """Open a `pio device monitor` session reading from `port`.
+
+    If `env` is set, pio picks up monitor_speed and monitor_filters from
+    platformio.ini — recommended for firmware debugging since it enables
+    esp32_exception_decoder / esp32_c3_exception_decoder for ESP32 envs.
+
+    Without `env`, uses the supplied baud and filters (default ["direct"]).
+    Common filters: direct, time, hexlify, esp32_exception_decoder,
+    esp32_c3_exception_decoder, log2file.
+
+    Returns a session_id for use with serial_read / serial_close, plus the
+    resolved baud and filters so callers can confirm what pio selected.
+    """
+    session = serial_session.open_session(
+        port=port, baud=baud, env=env, filters=filters
+    )
+    registry.register_session(session)
+    return {
+        "session_id": session.id,
+        "resolved_baud": session.baud,
+        "resolved_filters": session.filters,
+        "env": session.env,
+    }
+
+
+@app.tool()
+def serial_read(
+    session_id: str,
+    max_lines: int = 200,
+    since_cursor: int | None = None,
+) -> dict[str, Any]:
+    """Read buffered lines from a serial monitor session.
+
+    Default: returns everything since your last call to serial_read (uses an
+    advancing cursor). Pass `since_cursor=N` to re-read from a specific point,
+    or `since_cursor=0` to read from the start of the in-memory buffer.
+
+    Returns `dropped` = count of lines that aged out of the 10k-line ring
+    buffer between reads — so a value > 0 means you missed data.
+    """
+    session = registry.get_session(session_id)
+    return serial_session.read_session(
+        session, max_lines=max_lines, since_cursor=since_cursor
+    )
+
+
+@app.tool()
+def serial_list() -> list[dict[str, Any]]:
+    """List all active serial monitor sessions."""
+    return [serial_session.session_summary(s) for s in registry.all_sessions()]
+
+
+@app.tool()
+def serial_close(session_id: str) -> dict[str, Any]:
+    """Terminate a serial monitor session and free its port."""
+    session = registry.remove_session(session_id)
+    if session is None:
+        return {"ok": False, "reason": f"Unknown session_id {session_id!r}"}
+    serial_session.close_session(session)
+    return {"ok": True}
+
+
+# ---------- Device interaction: reads -------------------------------------
+
+
+@app.tool()
+def device_info(port: str | None = None, timeout_s: float = 8.0) -> dict[str, Any]:
+    """Connect via meshtastic.SerialInterface and return a summary of the node.
+
+    If `port` is omitted and exactly one likely-Meshtastic device is connected,
+    it's auto-selected; otherwise the tool errors with the candidate list.
+    """
+    return info.device_info(port=port, timeout_s=timeout_s)
+
+
+@app.tool()
+def list_nodes(port: str | None = None, timeout_s: float = 8.0) -> list[dict[str, Any]]:
+    """Return the device's current node database (local node + all known peers)."""
+    return info.list_nodes(port=port, timeout_s=timeout_s)
+
+
+# ---------- Device interaction: writes ------------------------------------
+
+
+@app.tool()
+def set_owner(
+    long_name: str, short_name: str | None = None, port: str | None = None
+) -> dict[str, Any]:
+    """Set the device's owner long name and (optional) short name (≤4 chars)."""
+    return admin.set_owner(long_name=long_name, short_name=short_name, port=port)
+
+
+@app.tool()
+def get_config(section: str | None = None, port: str | None = None) -> dict[str, Any]:
+    """Read one or all config sections.
+
+    `section` may be any LocalConfig section (device, position, power, network,
+    display, lora, bluetooth, security) or LocalModuleConfig section (mqtt,
+    serial, telemetry, external_notification, canned_message, range_test,
+    store_forward, neighbor_info, ambient_lighting, detection_sensor,
+    paxcounter, audio, remote_hardware, statusmessage, traffic_management).
+    Omit or pass "all" for every section.
+    """
+    return admin.get_config(section=section, port=port)
+
+
+@app.tool()
+def set_config(path: str, value: Any, port: str | None = None) -> dict[str, Any]:
+    """Set one config field via dot-path and write it to the device.
+
+    Examples: "lora.region"="US", "lora.modem_preset"="LONG_FAST",
+    "device.role"="ROUTER", "mqtt.enabled"=True, "mqtt.address"="host".
+    Enum fields accept their name (case-insensitive) or int.
+    """
+    return admin.set_config(path=path, value=value, port=port)
+
+
+@app.tool()
+def get_channel_url(
+    include_all: bool = False, port: str | None = None
+) -> dict[str, Any]:
+    """Get the shareable channel URL (QR-code content).
+
+    include_all=True returns the admin URL including all secondary channels;
+    False returns only the primary channel (what users typically share).
+    """
+    return admin.get_channel_url(include_all=include_all, port=port)
+
+
+@app.tool()
+def set_channel_url(url: str, port: str | None = None) -> dict[str, Any]:
+    """Import channels from a Meshtastic channel URL."""
+    return admin.set_channel_url(url=url, port=port)
+
+
+@app.tool()
+def send_text(
+    text: str,
+    to: str | int | None = None,
+    channel_index: int = 0,
+    want_ack: bool = False,
+    port: str | None = None,
+) -> dict[str, Any]:
+    """Send a text message over the mesh.
+
+    `to` defaults to broadcast ("^all"). Pass a node ID (hex string like
+    "!abcdef01") or node number (int) to direct-message a specific node.
+    channel_index picks which configured channel to send on.
+    """
+    return admin.send_text(
+        text=text, to=to, channel_index=channel_index, want_ack=want_ack, port=port
+    )
+
+
+@app.tool()
+def reboot(
+    port: str | None = None, confirm: bool = False, seconds: int = 10
+) -> dict[str, Any]:
+    """Reboot the connected node in `seconds` seconds. Requires confirm=True."""
+    return admin.reboot(port=port, confirm=confirm, seconds=seconds)
+
+
+@app.tool()
+def shutdown(
+    port: str | None = None, confirm: bool = False, seconds: int = 10
+) -> dict[str, Any]:
+    """Shut down the connected node in `seconds` seconds. Requires confirm=True."""
+    return admin.shutdown(port=port, confirm=confirm, seconds=seconds)
+
+
+@app.tool()
+def factory_reset(
+    port: str | None = None, confirm: bool = False, full: bool = False
+) -> dict[str, Any]:
+    """Factory-reset the connected node. Requires confirm=True.
+
+    `full=True` also wipes device identity/keys (not just config).
+    """
+    return admin.factory_reset(port=port, confirm=confirm, full=full)
+
+
+# ---------- Direct hardware tools -----------------------------------------
+
+
+@app.tool()
+def esptool_chip_info(port: str) -> dict[str, Any]:
+    """Run `esptool flash_id` and return chip, MAC, crystal, and flash size.
+
+    Read-only — no confirm required. Prefer this over parsing pio upload logs
+    when you just want to identify the chip.
+    """
+    return hw_tools.esptool_chip_info(port)
+
+
+@app.tool()
+def esptool_erase_flash(port: str, confirm: bool = False) -> dict[str, Any]:
+    """Full-chip erase via `esptool erase_flash`. Leaves the device unbootable.
+
+    Prefer `erase_and_flash` which also writes firmware. Use this only for
+    recovery when a device is in a weird state. Requires confirm=True.
+    """
+    return hw_tools.esptool_erase_flash(port, confirm=confirm)
+
+
+@app.tool()
+def esptool_raw(
+    args: list[str], port: str | None = None, confirm: bool = False
+) -> dict[str, Any]:
+    """Pass-through to `esptool`. Destructive subcommands (write_flash,
+    erase_flash, erase_region, merge_bin) require confirm=True.
+
+    Prefer the high-level `pio_flash` / `erase_and_flash` / `update_flash`
+    tools where possible — they know board-specific offsets and protocols.
+    """
+    return hw_tools.esptool_raw(args, port=port, confirm=confirm)
+
+
+@app.tool()
+def nrfutil_dfu(port: str, package_path: str, confirm: bool = False) -> dict[str, Any]:
+    """DFU-flash a .zip package to an nRF52840 via `nrfutil dfu serial`.
+
+    Prefer `pio_flash` for flashing firmware built from this repo — pio handles
+    the DFU invocation automatically. Use this tool when flashing a pre-built
+    release zip or a custom bootloader. Requires confirm=True.
+    """
+    return hw_tools.nrfutil_dfu(port, package_path, confirm=confirm)
+
+
+@app.tool()
+def nrfutil_raw(args: list[str], confirm: bool = False) -> dict[str, Any]:
+    """Pass-through to `nrfutil`. dfu/settings subcommands require confirm=True."""
+    return hw_tools.nrfutil_raw(args, confirm=confirm)
+
+
+@app.tool()
+def picotool_info(port: str | None = None) -> dict[str, Any]:
+    """Run `picotool info -a`. Requires the RP2040 to be in BOOTSEL mode
+    (hold BOOTSEL button while plugging in, or call `touch_1200bps` if the
+    firmware supports 1200bps-reset)."""
+    return hw_tools.picotool_info(port=port)
+
+
+@app.tool()
+def picotool_load(uf2_path: str, confirm: bool = False) -> dict[str, Any]:
+    """Load a UF2 to a Pico in BOOTSEL mode via `picotool load -x -t uf2`.
+
+    Prefer `pio_flash` for flashing firmware built from this repo.
+    Requires confirm=True.
+    """
+    return hw_tools.picotool_load(uf2_path, confirm=confirm)
+
+
+@app.tool()
+def picotool_raw(args: list[str], confirm: bool = False) -> dict[str, Any]:
+    """Pass-through to `picotool`. load/reboot/save/erase require confirm=True."""
+    return hw_tools.picotool_raw(args, confirm=confirm)

mcp-server/src/meshtastic_mcp/userprefs.py

@@ -0,0 +1,529 @@
+"""USERPREFS: build-time constants baked into the firmware binary.
+
+The firmware repo has `userPrefs.jsonc` at its root — a JSONC file with every
+available USERPREFS_* key listed, most commented out. At build time,
+`bin/platformio-custom.py` reads it, strips comments, and emits
+`-DUSERPREFS_<KEY>=<value>` build flags into the compile step. Firmware code
+uses `#ifdef USERPREFS_<KEY>` to pick up the baked-in defaults for channels,
+owner name, LoRa region, OEM branding, MQTT credentials, etc.
+
+This module:
+  1. Parses `userPrefs.jsonc` (preserving which keys are active vs commented)
+  2. Greps `src/` for the set of keys the firmware actually consumes (the
+     real discovery manifest — anything here that isn't in the jsonc is still
+     a valid override)
+  3. Provides a context manager for temporarily swapping in overrides during
+     a build/flash, then restoring the original file
+  4. Provides persistent `set` / `reset` for when the caller wants the change
+     to stick across multiple builds
+
+The firmware's platformio-custom.py value-type detection mirrors what we need
+for serialization: dict-like `{...}` (byte arrays, enum lists), digit-like
+(ints and floats), `true`/`false`, `meshtastic_*` enum constants, and
+everything else gets string-wrapped via `env.StringifyMacro`. We store the
+raw string values exactly as they'd appear in the jsonc to avoid round-trip
+surprises.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Iterator
+
+from . import config
+
+USERPREFS_FILE = "userPrefs.jsonc"
+BACKUP_SUFFIX = ".mcp.bak"
+
+# Pattern for lines like `// "USERPREFS_FOO": "value",` or `"USERPREFS_FOO": "v"`
+_ACTIVE_LINE = re.compile(r'^\s*"(USERPREFS_[A-Z0-9_]+)"\s*:\s*"((?:[^"\\]|\\.)*)"')
+_COMMENTED_LINE = re.compile(
+    r'^\s*//\s*"(USERPREFS_[A-Z0-9_]+)"\s*:\s*"((?:[^"\\]|\\.)*)"'
+)
+# Inline comment stripper (matches platformio-custom.py:219)
+_LINE_COMMENT = re.compile(r"//.*")
+
+# USERPREFS_* usage in firmware source (#ifdef, #if defined, direct refs)
+_USAGE_PATTERN = re.compile(r"\bUSERPREFS_[A-Z0-9_]+\b")
+
+
+def jsonc_path() -> Path:
+    return config.firmware_root() / USERPREFS_FILE
+
+
+def _read_file(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def _parse_jsonc_state(text: str) -> dict[str, Any]:
+    """Parse userPrefs.jsonc while preserving comment state per key.
+
+    Returns:
+        {
+          "active": {key: string_value, ...},   # uncommented
+          "commented": {key: string_value, ...}, # commented examples
+          "order": [key, ...]                   # source order for round-trip
+        }
+    """
+    active: dict[str, str] = {}
+    commented: dict[str, str] = {}
+    order: list[str] = []
+    for line in text.splitlines():
+        if m := _COMMENTED_LINE.match(line):
+            key, val = m.group(1), m.group(2)
+            commented[key] = val
+            order.append(key)
+        elif m := _ACTIVE_LINE.match(line):
+            key, val = m.group(1), m.group(2)
+            active[key] = val
+            order.append(key)
+    return {"active": active, "commented": commented, "order": order}
+
+
+def _parse_jsonc_active(text: str) -> dict[str, str]:
+    """Parse active-only values by stripping line comments + feeding to json."""
+    stripped = "\n".join(_LINE_COMMENT.sub("", line) for line in text.splitlines())
+    try:
+        return {k: str(v) for k, v in json.loads(stripped).items()}
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"userPrefs.jsonc is not valid JSONC: {exc}") from exc
+
+
+def read_state() -> dict[str, Any]:
+    """Return {active, commented, order, path}."""
+    path = jsonc_path()
+    if not path.is_file():
+        return {"active": {}, "commented": {}, "order": [], "path": str(path)}
+    state = _parse_jsonc_state(_read_file(path))
+    state["path"] = str(path)
+    return state
+
+
+# ---------- Manifest ------------------------------------------------------
+
+
+def _scan_consumed_keys() -> dict[str, list[str]]:
+    """Grep firmware src/ for USERPREFS_* references.
+
+    Returns {key: [relative_file_paths]} — only includes files under `src/`.
+    """
+    src_dir = config.firmware_root() / "src"
+    if not src_dir.is_dir():
+        return {}
+    out: dict[str, set[str]] = {}
+    for path in src_dir.rglob("*"):
+        if not path.is_file() or path.suffix.lower() not in {
+            ".c",
+            ".cc",
+            ".cpp",
+            ".h",
+            ".hpp",
+            ".ipp",
+            ".inl",
+        }:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+        except Exception:
+            continue
+        for m in _USAGE_PATTERN.finditer(text):
+            key = m.group(0)
+            # Skip our own "_USERPREFS_" artifacts (reserve-word guard from build-userprefs-json.py)
+            if key.startswith("_USERPREFS_"):
+                continue
+            out.setdefault(key, set()).add(
+                str(path.relative_to(config.firmware_root()))
+            )
+    return {k: sorted(v) for k, v in sorted(out.items())}
+
+
+def build_manifest() -> dict[str, Any]:
+    """Build the discovery manifest.
+
+    Every known USERPREFS_* key appears exactly once with:
+      - `value` (current active value, if any)
+      - `example` (commented default from jsonc, if any)
+      - `active` bool
+      - `declared_in_jsonc` bool (key appears anywhere in userPrefs.jsonc)
+      - `consumed_by` list of source files that reference it
+      - `inferred_type`: one of "brace", "number", "bool", "enum", "string"
+        — matches platformio-custom.py's value-wrapping switch
+    """
+    state = read_state()
+    consumed = _scan_consumed_keys()
+
+    all_keys = set(state["active"]) | set(state["commented"]) | set(consumed)
+    records = []
+    for key in sorted(all_keys):
+        example = state["commented"].get(key)
+        value = state["active"].get(key)
+        records.append(
+            {
+                "key": key,
+                "active": key in state["active"],
+                "value": value,
+                "example": example,
+                "declared_in_jsonc": key in state["active"]
+                or key in state["commented"],
+                "consumed_by": consumed.get(key, []),
+                "inferred_type": infer_type(value if value is not None else example),
+            }
+        )
+    return {
+        "path": state["path"],
+        "active_count": len(state["active"]),
+        "commented_count": len(state["commented"]),
+        "consumed_key_count": len(consumed),
+        "total_keys": len(records),
+        "entries": records,
+    }
+
+
+def infer_type(value: str | None) -> str:
+    """Classify a raw value string the way platformio-custom.py does.
+
+    Mirrors the branch order in `bin/platformio-custom.py:222-235`.
+    """
+    if value is None:
+        return "unknown"
+    v = value.strip()
+    if v.startswith("{"):
+        return "brace"  # byte array / enum init list
+    if v.lstrip("-").replace(".", "", 1).isdigit():
+        return "number"
+    if v in ("true", "false"):
+        return "bool"
+    if v.startswith("meshtastic_"):
+        return "enum"
+    return "string"
+
+
+# ---------- Writing -------------------------------------------------------
+
+
+def _format_jsonc_line(key: str, value: str, commented: bool) -> str:
+    prefix = "  // " if commented else "  "
+    # Escape backslashes and quotes inside value the way platformio-custom.py
+    # expects — the original jsonc uses raw strings for most content. Keep it
+    # literal; callers are responsible for correct escaping if they pass
+    # dict/enum-init values that contain quotes.
+    return f'{prefix}"{key}": "{value}",'
+
+
+def _render_jsonc(
+    active: dict[str, str], commented: dict[str, str], order: list[str]
+) -> str:
+    """Render userPrefs.jsonc preserving source order and comment state."""
+    seen: set[str] = set()
+    lines = ["{"]
+    for key in order:
+        if key in seen:
+            continue
+        seen.add(key)
+        if key in active:
+            lines.append(_format_jsonc_line(key, active[key], commented=False))
+        elif key in commented:
+            lines.append(_format_jsonc_line(key, commented[key], commented=True))
+    # Append any newly-added keys (not in original order) at the end, active.
+    for key, value in active.items():
+        if key in seen:
+            continue
+        seen.add(key)
+        lines.append(_format_jsonc_line(key, value, commented=False))
+    # Strip trailing comma on the last data line (valid JSONC allows it, but
+    # strict `json.loads` after comment-stripping does not; the loader in
+    # platformio-custom.py uses json.loads).
+    if len(lines) > 1 and lines[-1].endswith(","):
+        lines[-1] = lines[-1].rstrip(",")
+    lines.append("}")
+    lines.append("")  # trailing newline
+    return "\n".join(lines)
+
+
+def _validate_after_write(text: str) -> None:
+    """Ensure the rendered text still parses the way platformio-custom.py does."""
+    stripped = "\n".join(_LINE_COMMENT.sub("", line) for line in text.splitlines())
+    json.loads(stripped)  # raises on any error
+
+
+def write_state(
+    active: dict[str, str], commented: dict[str, str], order: list[str]
+) -> None:
+    path = jsonc_path()
+    text = _render_jsonc(active, commented, order)
+    _validate_after_write(text)
+    path.write_text(text, encoding="utf-8")
+
+
+def merge_active(overrides: dict[str, Any]) -> dict[str, Any]:
+    """Merge `overrides` into the active set and persist.
+
+    Existing active values not in `overrides` are kept. Example/commented
+    values are preserved. Returns {before_active, after_active, path}.
+    """
+    state = read_state()
+    before = dict(state["active"])
+    after = dict(before)
+    commented = dict(state["commented"])
+    order = list(state["order"])
+    for key, raw in overrides.items():
+        if not key.startswith("USERPREFS_"):
+            raise ValueError(f"key {key!r} must start with USERPREFS_")
+        after[key] = _stringify(raw)
+        # If the key was commented, uncommenting it means removing from commented set.
+        commented.pop(key, None)
+        if key not in order:
+            order.append(key)
+    write_state(after, commented, order)
+    return {"before_active": before, "after_active": after, "path": str(jsonc_path())}
+
+
+def _stringify(value: Any) -> str:
+    """Convert a Python value to the string form userPrefs.jsonc expects.
+
+    bool → "true" / "false"; int/float → str(); anything else → str(value).
+    Callers passing brace-init strings (`"{ 0x01, 0x02, ... }"`) must format
+    them themselves — this function doesn't try to synthesize them.
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    return str(value)
+
+
+def reset() -> dict[str, Any]:
+    """Restore userPrefs.jsonc from the MCP backup if present.
+
+    Returns {restored: bool, path, backup_path}.
+    """
+    path = jsonc_path()
+    backup = path.with_suffix(path.suffix + BACKUP_SUFFIX)
+    if backup.is_file():
+        shutil.copy2(backup, path)
+        backup.unlink()
+        return {"restored": True, "path": str(path), "backup_path": str(backup)}
+    return {"restored": False, "path": str(path), "backup_path": str(backup)}
+
+
+# ---------- Transient override (for build/flash) --------------------------
+
+
+# ---------- Pre-baked profiles --------------------------------------------
+
+
+def _psk_from_bytes(data: bytes) -> str:
+    """Format 32 bytes as a C-style brace-init list for USERPREFS_CHANNEL_*_PSK.
+
+    Matches the exact format used in userPrefs.jsonc:
+        { 0x38, 0x4b, 0xbc, ... }
+    """
+    if len(data) != 32:
+        raise ValueError(f"PSK must be exactly 32 bytes, got {len(data)}")
+    return "{ " + ", ".join(f"0x{b:02x}" for b in data) + " }"
+
+
+def generate_psk(seed: str | None = None) -> str:
+    """Generate a 32-byte PSK as a brace-init string.
+
+    If `seed` is provided, the PSK is deterministic (derived via SHA-256 of
+    the seed); otherwise it's cryptographically random. Use a seed for
+    automated testing so every device in a test run shares the same key.
+    """
+    if seed is None:
+        import secrets
+
+        raw = secrets.token_bytes(32)
+    else:
+        import hashlib
+
+        raw = hashlib.sha256(seed.encode("utf-8")).digest()
+    return _psk_from_bytes(raw)
+
+
+# Meshtastic region enum name → short description (for the manifest tool).
+# Not exhaustive; these are the regions a US-based test lab is likely to pick.
+KNOWN_REGIONS = {
+    "US": "meshtastic_Config_LoRaConfig_RegionCode_US",
+    "EU_433": "meshtastic_Config_LoRaConfig_RegionCode_EU_433",
+    "EU_868": "meshtastic_Config_LoRaConfig_RegionCode_EU_868",
+    "CN": "meshtastic_Config_LoRaConfig_RegionCode_CN",
+    "JP": "meshtastic_Config_LoRaConfig_RegionCode_JP",
+    "ANZ": "meshtastic_Config_LoRaConfig_RegionCode_ANZ",
+    "KR": "meshtastic_Config_LoRaConfig_RegionCode_KR",
+    "TW": "meshtastic_Config_LoRaConfig_RegionCode_TW",
+    "RU": "meshtastic_Config_LoRaConfig_RegionCode_RU",
+    "IN": "meshtastic_Config_LoRaConfig_RegionCode_IN",
+    "NZ_865": "meshtastic_Config_LoRaConfig_RegionCode_NZ_865",
+    "TH": "meshtastic_Config_LoRaConfig_RegionCode_TH",
+    "UA_433": "meshtastic_Config_LoRaConfig_RegionCode_UA_433",
+    "UA_868": "meshtastic_Config_LoRaConfig_RegionCode_UA_868",
+    "MY_433": "meshtastic_Config_LoRaConfig_RegionCode_MY_433",
+    "MY_919": "meshtastic_Config_LoRaConfig_RegionCode_MY_919",
+    "SG_923": "meshtastic_Config_LoRaConfig_RegionCode_SG_923",
+    "LORA_24": "meshtastic_Config_LoRaConfig_RegionCode_LORA_24",
+}
+
+KNOWN_MODEM_PRESETS = {
+    "LONG_FAST": "meshtastic_Config_LoRaConfig_ModemPreset_LONG_FAST",
+    "LONG_SLOW": "meshtastic_Config_LoRaConfig_ModemPreset_LONG_SLOW",
+    "LONG_MODERATE": "meshtastic_Config_LoRaConfig_ModemPreset_LONG_MODERATE",
+    "VERY_LONG_SLOW": "meshtastic_Config_LoRaConfig_ModemPreset_VERY_LONG_SLOW",
+    "MEDIUM_SLOW": "meshtastic_Config_LoRaConfig_ModemPreset_MEDIUM_SLOW",
+    "MEDIUM_FAST": "meshtastic_Config_LoRaConfig_ModemPreset_MEDIUM_FAST",
+    "SHORT_SLOW": "meshtastic_Config_LoRaConfig_ModemPreset_SHORT_SLOW",
+    "SHORT_FAST": "meshtastic_Config_LoRaConfig_ModemPreset_SHORT_FAST",
+    "SHORT_TURBO": "meshtastic_Config_LoRaConfig_ModemPreset_SHORT_TURBO",
+}
+
+
+def build_testing_profile(
+    psk_seed: str | None = None,
+    channel_name: str = "McpTest",
+    channel_num: int = 88,
+    region: str = "US",
+    modem_preset: str = "LONG_FAST",
+    short_name: str | None = None,
+    long_name: str | None = None,
+    disable_mqtt: bool = True,
+    disable_position: bool = False,
+) -> dict[str, Any]:
+    """Build a USERPREFS dict for an isolated test-mesh device.
+
+    Defaults: US region, LONG_FAST modem, channel slot 88 (well away from the
+    default `hash("LongFast") % numChannels` slot that production devices use),
+    and a private PSK. Devices baked with the same `psk_seed` land on the same
+    isolated mesh.
+
+    See `src/mesh/RadioInterface.cpp:849` for the slot-selection math:
+    `slot = (channel_num ? channel_num - 1 : hash(name)) % numChannels`.
+    Setting `channel_num` explicitly (non-zero) forces a deterministic slot.
+
+    Args:
+        psk_seed: seed for deterministic PSK generation. `None` = random (fine
+            for one-off bakes, useless for multi-device test clusters).
+        channel_name: primary channel name. Must differ from defaults
+            ("LongFast", "MediumFast", etc.) so production devices don't
+            accidentally match after the PSK check.
+        channel_num: 1-indexed LoRa slot (1..numChannels). 88 is mid-upper US
+            band. Set to 0 to fall back to name-hash (not recommended for
+            isolation).
+        region: short code from `KNOWN_REGIONS`.
+        modem_preset: short code from `KNOWN_MODEM_PRESETS`.
+        short_name / long_name: optional owner identity stamps.
+        disable_mqtt: if True (default), disables the MQTT module and the
+            uplink/downlink bridge on the primary channel — so private test
+            traffic never leaks to a public broker.
+        disable_position: if True, disables GPS + position broadcasts — useful
+            when test devices sit on a bench without antennas.
+    """
+    if region not in KNOWN_REGIONS:
+        raise ValueError(
+            f"Unknown region {region!r}. Known: {sorted(KNOWN_REGIONS.keys())}"
+        )
+    if modem_preset not in KNOWN_MODEM_PRESETS:
+        raise ValueError(
+            f"Unknown modem_preset {modem_preset!r}. Known: {sorted(KNOWN_MODEM_PRESETS.keys())}"
+        )
+    if not (0 <= channel_num <= 255):
+        raise ValueError(f"channel_num must be 0..255, got {channel_num}")
+    if len(channel_name) > 11:
+        raise ValueError(
+            f"channel_name {channel_name!r} exceeds Meshtastic's 11-char max"
+        )
+    if short_name is not None and len(short_name) > 4:
+        raise ValueError(f"short_name must be ≤4 chars, got {len(short_name)}")
+
+    psk = generate_psk(seed=psk_seed)
+
+    prefs: dict[str, Any] = {
+        # --- LoRa ---
+        "USERPREFS_CONFIG_LORA_REGION": KNOWN_REGIONS[region],
+        "USERPREFS_LORACONFIG_MODEM_PRESET": KNOWN_MODEM_PRESETS[modem_preset],
+        "USERPREFS_LORACONFIG_CHANNEL_NUM": channel_num,
+        # --- Primary channel (isolated from public default) ---
+        "USERPREFS_CHANNELS_TO_WRITE": 1,
+        "USERPREFS_CHANNEL_0_NAME": channel_name,
+        "USERPREFS_CHANNEL_0_PSK": psk,
+        "USERPREFS_CHANNEL_0_PRECISION": 14,
+    }
+    if disable_mqtt:
+        prefs.update(
+            {
+                "USERPREFS_CONFIG_LORA_IGNORE_MQTT": True,
+                "USERPREFS_MQTT_ENABLED": 0,
+                "USERPREFS_CHANNEL_0_UPLINK_ENABLED": False,
+                "USERPREFS_CHANNEL_0_DOWNLINK_ENABLED": False,
+            }
+        )
+    if disable_position:
+        prefs.update(
+            {
+                "USERPREFS_CONFIG_GPS_MODE": "meshtastic_Config_PositionConfig_GpsMode_DISABLED",
+                "USERPREFS_CONFIG_SMART_POSITION_ENABLED": False,
+            }
+        )
+    if long_name is not None:
+        prefs["USERPREFS_CONFIG_OWNER_LONG_NAME"] = long_name
+    if short_name is not None:
+        prefs["USERPREFS_CONFIG_OWNER_SHORT_NAME"] = short_name
+
+    return prefs
+
+
+@contextmanager
+def temporary_overrides(overrides: dict[str, Any] | None) -> Iterator[dict[str, str]]:
+    """Apply `overrides` to userPrefs.jsonc for the duration of the context.
+
+    Yields a dict of the *effective* active values (original active merged
+    with overrides). Always restores the original file on exit, even on
+    exception. If `overrides` is None or empty, this is a no-op.
+
+    The restore writes the original file content byte-for-byte, so there's no
+    round-trip ambiguity even if the file had unusual whitespace.
+    """
+    if not overrides:
+        state = read_state()
+        yield dict(state["active"])
+        return
+
+    path = jsonc_path()
+    if not path.is_file():
+        raise FileNotFoundError(f"userPrefs.jsonc not found at {path}")
+
+    original_bytes = path.read_bytes()
+    original_stat = path.stat()
+
+    # Merge and write
+    state = _parse_jsonc_state(original_bytes.decode("utf-8"))
+    effective = dict(state["active"])
+    commented = dict(state["commented"])
+    order = list(state["order"])
+    for key, raw in overrides.items():
+        if not key.startswith("USERPREFS_"):
+            raise ValueError(f"key {key!r} must start with USERPREFS_")
+        effective[key] = _stringify(raw)
+        commented.pop(key, None)
+        if key not in order:
+            order.append(key)
+
+    rendered = _render_jsonc(effective, commented, order)
+    _validate_after_write(rendered)
+    path.write_text(rendered, encoding="utf-8")
+    # pio watches file mtimes to invalidate build cache; force the modification
+    # time to now so a pre-existing `.pio/build/<env>/` cache is discarded.
+    now = time.time()
+    import os
+
+    os.utime(path, (now, now))
+
+    try:
+        yield effective
+    finally:
+        path.write_bytes(original_bytes)
+        os.utime(path, (original_stat.st_atime, original_stat.st_mtime))

mcp-server/tests/README.md

@@ -0,0 +1,116 @@
+# Meshtastic MCP Server — Test Harness
+
+Automated test suite for the MCP server, organized around real operator
+concerns rather than generic "unit vs hardware".
+
+## Tiers
+
+| Dir             | Hardware                | Question this tier answers                                            |
+| --------------- | ----------------------- | --------------------------------------------------------------------- |
+| `unit/`         | none                    | Do the parsing / filtering / profile-generation primitives work?      |
+| `provisioning/` | 1 device, per-test bake | Did my pre-bake recipe stick? Does it survive a factory reset?        |
+| `admin/`        | 1 device, shared bake   | Do my daily admin ops (owner, channel URL, config writes) round-trip? |
+| `mesh/`         | 2 devices, shared bake  | Do my devices actually form a mesh? Send + receive? ACKs?             |
+| `telemetry/`    | 2 devices, shared bake  | Is telemetry reporting? Is position broadcast correct?                |
+| `monitor/`      | 1 device, shared bake   | Is the boot log clean (no panics)?                                    |
+| `fleet/`        | varies                  | Are my CI runs isolated from each other? Are reflashes idempotent?    |
+
+## Quick start
+
+```bash
+cd mcp-server
+pip install -e ".[test]"
+
+# No hardware — 33 unit tests, ~3 seconds
+pytest tests/unit -v
+
+# Hub attached (nRF52840 + ESP32-S3) — first run bakes, then exercises everything
+pytest tests/ --html=report.html
+
+# Hub already baked with session profile (dev loop) — skip bake
+pytest tests/ --assume-baked --html=report.html
+
+# Force a rebake (new firmware, new seed, etc.)
+pytest tests/ --force-bake --html=report.html
+```
+
+## CLI flags
+
+- `--force-bake` — always reflash both roles at session start, even if the
+  current state matches the session profile.
+- `--assume-baked` — skip `test_00_bake.py` entirely. Use when you know the
+  devices are already baked and want a fast dev loop.
+- `--hub-profile=<yaml>` — point at a YAML file for non-default hub hardware.
+  Default targets VID `0x239a` (nRF52) and `0x303a`/`0x10c4` (ESP32-S3).
+- `--no-teardown-rebake` — skip the session-end rebake that `provisioning/`
+  and `fleet/` tests perform. Useful in rapid iteration.
+
+## Environment variables
+
+- `MESHTASTIC_FIRMWARE_ROOT` — firmware repo path (defaults to `../` from tests/)
+- `MESHTASTIC_MCP_ENV_NRF52` — PlatformIO env for the nRF52 role (default
+  `heltec-mesh-node-t114`)
+- `MESHTASTIC_MCP_ENV_ESP32S3` — PlatformIO env for the ESP32-S3 role (default
+  `t-beam-1w`)
+- `MESHTASTIC_MCP_SEED` — override the session PSK seed (default:
+  `pytest-<unix-ts>`). Set this to reproduce a specific failing run.
+
+## Fixtures you'll use when adding tests
+
+All defined in `conftest.py`:
+
+- **`hub_devices`** → `{"nrf52": "/dev/cu.X", "esp32s3": "/dev/cu.Y"}`. Auto-
+  skips the test if a required role isn't present.
+- **`test_profile`** → USERPREFS dict for the session (`build_testing_profile`).
+- **`no_region_profile`** → variant without `USERPREFS_CONFIG_LORA_REGION`.
+- **`baked_mesh`** → verifies both devices are baked with the session profile
+  (does NOT reflash — that's `test_00_bake.py`'s job).
+- **`baked_single`** → single verified baked device; parametrize `request.param`
+  to pick role.
+- **`serial_capture`** → factory; `cap = serial_capture("esp32s3")` starts a
+  pio device monitor session, drains into a per-test buffer, attaches the
+  buffer to the pytest-html report on failure.
+- **`wait_until`** → exponential-backoff polling helper; `wait_until(lambda:
+predicate(), timeout=60)` replaces flaky `time.sleep()` patterns.
+
+## Reports
+
+`pytest --html=report.html` produces a self-contained HTML with:
+
+- Per-test pass/fail/skip with timings
+- On failure: serial log capture from any `serial_capture` fixture used
+- On failure: `device_info` + lora config JSON for every role on the hub
+- Session seed and session start time (for reproducibility)
+
+`pytest --junitxml=junit.xml` produces CI-integration XML.
+
+`tool_coverage.json` is emitted at session end in the tests directory — shows
+which of the 37 MCP tools the run exercised. Useful for closing test gaps.
+
+## Adding a new test
+
+1. Pick the category that matches the operator concern (not the technical
+   surface). "Does my fleet's owner name persist" is `admin/`, not `unit/`.
+2. If you need both devices, depend on `baked_mesh`. If you need one, depend
+   on `baked_single`. If you need to mutate hardware state, put it in
+   `provisioning/` or `fleet/` and add a `try/finally` teardown that re-bakes
+   the session profile.
+3. Use `wait_until` for anything involving LoRa timing — fixed `sleep()`
+   produces flakes.
+4. Use `serial_capture` when you need to observe firmware log output (e.g.
+   "did the packet get decoded?").
+5. Add a `@pytest.mark.timeout(N)` — mesh tests routinely hit LoRa-airtime
+   waits; default pytest timeout is infinite.
+
+## Troubleshooting
+
+- **All hardware tests SKIP** → hub not detected. Plug in the USB hub, verify
+  with `pytest tests/ --collect-only` or `python -c "from meshtastic_mcp import
+devices; print(devices.list_devices())"`.
+- **`baked_mesh` fails with "devices not baked"** → run `pytest
+tests/test_00_bake.py` first, or pass `--force-bake` on the full run.
+- **Mesh formation tests time out** → check that both devices are on the same
+  session profile (`--force-bake` forces both to the current seed).
+- **Provisioning tests leave device in bad state** → teardowns re-bake, but
+  if a test crashes between "bake broken state" and "bake good state", run
+  `pytest tests/test_00_bake.py --force-bake` to recover.

mcp-server/tests/admin/test_channel_url_roundtrip.py

@@ -0,0 +1,54 @@
+"""Admin: channel URL export and re-import round-trip.
+
+Real operator workflow: "I have two fleets, I want them to share a channel
+config. Export URL from fleet A's bootstrap device, paste into fleet B's
+onboarding tool, expect identical channels." Proves `getURL` + `setURL`
+round-trip without data loss.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import pytest
+from meshtastic_mcp import admin, info
+
+
+@pytest.mark.timeout(60)
+def test_channel_url_roundtrip(
+    baked_mesh: dict[str, Any],
+    test_profile: dict[str, Any],
+) -> None:
+    """Verify:
+    1. `get_channel_url()` on a baked device returns a non-empty URL.
+    2. The URL parses — `set_channel_url(url)` accepts it without error.
+    3. After set, `get_channel_url()` returns the same (canonicalized) URL.
+    4. Primary channel name survives round-trip.
+    """
+    target = "esp32s3"
+    if target not in baked_mesh:
+        pytest.skip(f"role {target!r} not on hub")
+    port = baked_mesh[target]["port"]
+
+    url_before = admin.get_channel_url(include_all=False, port=port)["url"]
+    assert url_before, "device returned empty channel URL"
+    assert (
+        "meshtastic" in url_before.lower() or "#" in url_before
+    ), f"URL does not look like a Meshtastic channel URL: {url_before!r}"
+
+    # Re-apply the same URL — no-op in content but exercises the setURL path.
+    applied = admin.set_channel_url(url=url_before, port=port)
+    assert applied["ok"] is True
+    assert applied["channels_imported"] >= 1
+    time.sleep(2.0)
+
+    # Confirm the primary channel name survived
+    live = info.device_info(port=port, timeout_s=8.0)
+    assert live["primary_channel"] == test_profile["USERPREFS_CHANNEL_0_NAME"]
+
+    url_after = admin.get_channel_url(include_all=False, port=port)["url"]
+    # Canonicalization: URLs should match bit-for-bit after a no-op set.
+    assert (
+        url_after == url_before
+    ), f"URL changed across setURL round-trip:\nbefore: {url_before}\nafter:  {url_after}"

mcp-server/tests/admin/test_owner_survives_reboot.py

@@ -0,0 +1,60 @@
+"""Admin: owner name persists across a reboot.
+
+The single most common "did my admin change stick?" test. Proves
+`localNode.setOwner()` + `writeConfig("device")` commits to non-volatile
+storage before the reboot.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import pytest
+from meshtastic_mcp import admin, info
+
+
+@pytest.mark.timeout(120)
+def test_owner_survives_reboot(
+    baked_mesh: dict[str, Any],
+    wait_until,
+) -> None:
+    target = "esp32s3"
+    if target not in baked_mesh:
+        pytest.skip(f"role {target!r} not on hub")
+    port = baked_mesh[target]["port"]
+
+    pre = info.device_info(port=port, timeout_s=8.0)
+    original = pre.get("long_name") or ""
+    marker = "RebootSurvive"
+    try:
+        admin.set_owner(long_name=marker, short_name="RS", port=port)
+        time.sleep(1.5)
+
+        # Confirm pre-reboot
+        confirmed = info.device_info(port=port, timeout_s=8.0)
+        assert confirmed["long_name"] == marker
+
+        # Reboot (short delay)
+        admin.reboot(port=port, confirm=True, seconds=3)
+
+        # Wait for device to come back
+        time.sleep(8.0)
+        wait_until(
+            lambda: info.device_info(port=port, timeout_s=5.0).get("my_node_num")
+            is not None,
+            timeout=60,
+            backoff_start=1.0,
+        )
+
+        post = info.device_info(port=port, timeout_s=8.0)
+        assert post["long_name"] == marker, (
+            f"owner name did not persist across reboot: "
+            f"expected {marker!r}, got {post['long_name']!r}"
+        )
+    finally:
+        # Restore original (best-effort)
+        try:
+            admin.set_owner(long_name=original or "TestNode", port=port)
+        except Exception:
+            pass

mcp-server/tests/admin/test_placeholders.py

@@ -0,0 +1,28 @@
+"""Admin placeholders: v2 roadmap entries, skipped in v2.0."""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.skip(reason="placeholder — implement in v2.1")
+
+
+def test_set_channel_url_imports_all() -> None:
+    """Synthesize a URL with primary + 2 secondary channels; `set_channel_url`;
+    verify all 3 show up in `localNode.channels` with correct PSKs + names.
+    Common operator flow: deploy a new channel scheme across a fleet."""
+    pass
+
+
+def test_telemetry_interval_configurable() -> None:
+    """`set_config("telemetry.device_update_interval", 60)`; wait 2× interval;
+    verify telemetry packets arrived at ~60s cadence (within ±20% jitter
+    tolerance). A frequent 'my telemetry isn't working' user issue."""
+    pass
+
+
+def test_fixed_position_set_and_reported() -> None:
+    """`set_fixed_position(lat, lon, alt)`; verify `position_config.fixed_position=true`
+    and `list_nodes()[self].position` reports lat/lon within 1e-6 degree tolerance.
+    The privacy-vs-utility trade-off position-precision users care about."""
+    pass

mcp-server/tests/conftest.py

@@ -0,0 +1,466 @@
+"""Root conftest for the MCP server test harness.
+
+Organizes the fixture graph used by every test tier:
+
+    session_seed ── test_profile ─┐
+    hub_devices ──────────────────┴─ baked_mesh (verifies) ── baked_single (parametrized)
+    hub_devices ──────────────────── no_region_profile (provisioning negative test)
+    (per-test)  ──────────────────── serial_capture, device_state_dump, wait_until
+
+CLI flags (see `pytest_addoption`):
+    --force-bake       always reflash at session start, even if state matches
+    --assume-baked     trust the operator; skip test_00_bake collection entirely
+    --hub-profile=...  path to a YAML file mapping role → {vid, pid_contains}
+    --no-teardown-rebake  skip the session-end rebake that provisioning/fleet perform
+
+Coverage hooks:
+    - Failure artifacts (serial capture, device_info, get_config) are attached
+      to pytest-html reports via `pytest_runtest_makereport`.
+    - Tool-surface coverage (which of the 37 MCP tools got exercised) is
+      accumulated in `tests/tool_coverage.py` and written to
+      `tool_coverage.json` at session end.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import sys
+import time
+from typing import Any, Callable
+
+import pytest
+
+# Ensure the MCP server is on `sys.path` without requiring installation in
+# development mode for every checkout (we DO install in .venv but this makes
+# `pytest tests/` work from a fresh clone too).
+_HERE = pathlib.Path(__file__).resolve().parent
+_MCP_SRC = _HERE.parent / "src"
+if str(_MCP_SRC) not in sys.path:
+    sys.path.insert(0, str(_MCP_SRC))
+
+# Default firmware root: the repo this mcp-server/ lives inside.
+os.environ.setdefault("MESHTASTIC_FIRMWARE_ROOT", str(_HERE.parent.parent))
+
+from meshtastic_mcp import (
+    admin,
+)
+from meshtastic_mcp import (  # noqa: E402  (import after path setup)
+    devices as devices_module,
+)
+from meshtastic_mcp import (
+    flash,
+    info,
+    serial_session,
+    userprefs,
+)
+
+from . import tool_coverage  # noqa: E402
+
+# ---------- CLI options ---------------------------------------------------
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("meshtastic", "Meshtastic MCP test options")
+    group.addoption(
+        "--force-bake",
+        action="store_true",
+        help="Flash both hub roles at session start, even if devices appear baked.",
+    )
+    group.addoption(
+        "--assume-baked",
+        action="store_true",
+        help="Skip `test_00_bake.py` and trust devices are already baked.",
+    )
+    group.addoption(
+        "--hub-profile",
+        default=None,
+        help="YAML file mapping role → {vid, pid_contains} for non-default hardware.",
+    )
+    group.addoption(
+        "--no-teardown-rebake",
+        action="store_true",
+        help="Skip session-end rebake after provisioning/fleet tests mutate state.",
+    )
+
+
+def pytest_collection_modifyitems(
+    config: pytest.Config, items: list[pytest.Item]
+) -> None:
+    """Deselect `test_00_bake.py` when --assume-baked is passed."""
+    if config.getoption("--assume-baked"):
+        keep, skip = [], []
+        for item in items:
+            if "test_00_bake" in item.nodeid:
+                skip.append(item)
+            else:
+                keep.append(item)
+        if skip:
+            for item in skip:
+                item.add_marker(pytest.mark.skip(reason="skipped by --assume-baked"))
+
+
+# ---------- Session-scoped fixtures ---------------------------------------
+
+
+@pytest.fixture(scope="session")
+def session_seed(request: pytest.FixtureRequest) -> str:
+    """Deterministic PSK seed for this pytest session.
+
+    Logged in the HTML report header so two runs can be correlated — and so a
+    flaky-looking test can be reproduced exactly by passing the seed back via
+    an env var (future extension).
+    """
+    # Pytest session `starttime` isn't directly exposed on the pytest API we
+    # care about, so derive from process start time — unique enough for human
+    # purposes and stable across the session.
+    seed = os.environ.get("MESHTASTIC_MCP_SEED") or f"pytest-{int(time.time())}"
+    return seed
+
+
+@pytest.fixture(scope="session")
+def test_profile(session_seed: str) -> dict[str, Any]:
+    """The canonical isolated-mesh test profile for this session."""
+    return userprefs.build_testing_profile(
+        psk_seed=session_seed,
+        channel_name="McpTest",
+        channel_num=88,
+        region="US",
+        modem_preset="LONG_FAST",
+    )
+
+
+@pytest.fixture(scope="session")
+def no_region_profile(session_seed: str) -> dict[str, Any]:
+    """Variant of `test_profile` with the LoRa region stripped.
+
+    Used only by the negative `unset_region_blocks_tx` test. That test MUST
+    re-bake `test_profile` in its own teardown so downstream shared-state
+    tests still see a correctly-configured mesh.
+    """
+    profile = userprefs.build_testing_profile(
+        psk_seed=session_seed,
+        channel_name="McpTest",
+        channel_num=88,
+        region="US",  # placeholder; we delete the key below
+        modem_preset="LONG_FAST",
+    )
+    profile.pop("USERPREFS_CONFIG_LORA_REGION", None)
+    return profile
+
+
+@pytest.fixture(scope="session")
+def hub_profile(request: pytest.FixtureRequest) -> dict[str, dict[str, Any]]:
+    """Role → {vid, pid_contains} map for detecting connected hardware.
+
+    Default covers the common nRF52840 + ESP32-S3 lab hub. Override via
+    `--hub-profile=path/to/hub.yaml`. Example YAML:
+
+        nrf52:
+          vid: 0x239a
+          pid_contains: null
+        esp32s3:
+          vid: 0x303a
+          pid_contains: null
+    """
+    path = request.config.getoption("--hub-profile")
+    if path:
+        import yaml
+
+        with open(path, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f)
+    return {
+        "nrf52": {"vid": 0x239A, "pid_contains": None},
+        # ESP32-S3 can enumerate under Espressif native USB (0x303a) or via a
+        # CP2102 USB-serial chip (0x10c4). Both should match for
+        # Meshtastic-compatible boards.
+        "esp32s3": {"vid": 0x303A, "pid_contains": None},
+        "esp32s3_alt": {"vid": 0x10C4, "pid_contains": None},
+    }
+
+
+def _hex_to_int(value: Any) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        return int(value, 16) if value.startswith("0x") else int(value)
+    return None
+
+
+@pytest.fixture(scope="session")
+def hub_devices(hub_profile: dict[str, dict[str, Any]]) -> dict[str, str]:
+    """Map of `role → port` for devices detected on the hub.
+
+    Excludes `*_alt` roles from the returned map (they're additional VID
+    matchers for the same logical role). If a role isn't detected, an entry is
+    absent from the return value; fixtures that require specific roles should
+    check presence and `pytest.skip` with an actionable message.
+    """
+    # include_unknown=True so non-whitelisted VIDs (e.g. CP2102 at 0x10c4) that
+    # are configured as hub roles still match. The hub_profile itself gates
+    # which VIDs we consider — no risk of unrelated serial ports sneaking in.
+    found = devices_module.list_devices(include_unknown=True)
+    # Coalesce alt roles into their base name (esp32s3_alt → esp32s3)
+    resolved: dict[str, str] = {}
+    for role, spec in hub_profile.items():
+        target_vid = spec["vid"]
+        pid_contains = spec.get("pid_contains")
+        canonical = role.split("_alt", 1)[0]
+        if canonical in resolved:
+            continue
+        for dev in found:
+            vid = _hex_to_int(dev.get("vid"))
+            pid = _hex_to_int(dev.get("pid"))
+            if vid != target_vid:
+                continue
+            if pid_contains is not None and (pid is None or pid_contains not in pid):
+                continue
+            resolved[canonical] = dev["port"]
+            break
+    return resolved
+
+
+@pytest.fixture(scope="session")
+def baked_mesh(
+    hub_devices: dict[str, str],
+    test_profile: dict[str, Any],
+    session_seed: str,
+    request: pytest.FixtureRequest,
+) -> dict[str, Any]:
+    """Verifies that both roles are baked with the session `test_profile`.
+
+    Does NOT reflash. `test_00_bake.py` is responsible for applying the bake;
+    this fixture just checks the result by connecting to each device and
+    comparing the live config to the expected profile.
+
+    Raises with an actionable error if state is missing or mismatched:
+        "device nrf52 at /dev/cu.X not baked with session profile —
+         run test_00_bake.py first or pass --force-bake"
+
+    Returns a per-role dict with `{port, iface_fresh: callable, my_node_num}`.
+    """
+    required = {"nrf52", "esp32s3"}
+    missing = required - set(hub_devices)
+    if missing:
+        pytest.skip(
+            f"hub missing required role(s): {sorted(missing)}. "
+            f"Attach the hub or override with --hub-profile."
+        )
+
+    expected_region = test_profile["USERPREFS_CONFIG_LORA_REGION"]
+    expected_preset = test_profile["USERPREFS_LORACONFIG_MODEM_PRESET"]
+    expected_slot = test_profile["USERPREFS_LORACONFIG_CHANNEL_NUM"]
+    expected_channel_name = test_profile["USERPREFS_CHANNEL_0_NAME"]
+
+    out: dict[str, Any] = {}
+    for role in ("nrf52", "esp32s3"):
+        port = hub_devices[role]
+        try:
+            live = info.device_info(port=port, timeout_s=12.0)
+        except Exception as exc:
+            pytest.fail(
+                f"device {role} at {port}: could not query device_info "
+                f"({exc!r}). Run test_00_bake.py or pass --force-bake."
+            )
+        # `device_info` surfaces region/primary_channel but not modem preset
+        # or channel_num directly; pull those via a separate get_config call.
+        lora_cfg = admin.get_config(section="lora", port=port)["config"]["lora"]
+        channel_num = int(lora_cfg.get("channel_num", 0))
+        modem_preset = lora_cfg.get("modem_preset")
+        region_short = live.get("region")
+        primary = live.get("primary_channel")
+
+        mismatches = []
+        if region_short and not expected_region.endswith(str(region_short)):
+            mismatches.append(f"region={region_short} (expected {expected_region})")
+        if modem_preset and not expected_preset.endswith(str(modem_preset)):
+            mismatches.append(
+                f"modem_preset={modem_preset} (expected {expected_preset})"
+            )
+        if channel_num != expected_slot:
+            mismatches.append(f"channel_num={channel_num} (expected {expected_slot})")
+        if primary and primary != expected_channel_name:
+            mismatches.append(
+                f"primary_channel={primary!r} (expected {expected_channel_name!r})"
+            )
+
+        if mismatches:
+            pytest.fail(
+                f"device {role} at {port} not baked with session profile:\n  "
+                + "\n  ".join(mismatches)
+                + "\nRun `pytest tests/test_00_bake.py` first or pass --force-bake."
+            )
+
+        out[role] = {
+            "port": port,
+            "my_node_num": live.get("my_node_num"),
+            "firmware_version": live.get("firmware_version"),
+        }
+
+    return out
+
+
+@pytest.fixture
+def baked_single(
+    baked_mesh: dict[str, Any], request: pytest.FixtureRequest
+) -> dict[str, Any]:
+    """Function-scoped: a single verified baked device.
+
+    Parametrize over `request.param` = role name. Defaults to "esp32s3"
+    because it's typically more stable as an admin target (no UF2 transitions).
+    """
+    role = getattr(request, "param", "esp32s3")
+    if role not in baked_mesh:
+        pytest.skip(f"role {role!r} not present on the hub")
+    return {"role": role, **baked_mesh[role]}
+
+
+# ---------- Failure-artifact fixtures -------------------------------------
+
+
+class _SerialCapture:
+    """Active-session wrapper that lazily opens + closes a pio monitor."""
+
+    def __init__(self, port: str, env: str | None = None) -> None:
+        self._port = port
+        self._env = env
+        self._session = None
+        self._last_cursor: int | None = None
+
+    def start(self) -> None:
+        self._session = serial_session.open_session(port=self._port, env=self._env)
+
+    def snapshot(self, max_lines: int = 500) -> list[str]:
+        if self._session is None:
+            return []
+        out = serial_session.read_session(
+            self._session, max_lines=max_lines, since_cursor=0
+        )
+        return out.get("lines", [])
+
+    def stop(self) -> None:
+        if self._session is not None:
+            try:
+                serial_session.close_session(self._session)
+            except Exception:
+                pass
+            self._session = None
+
+
+@pytest.fixture
+def serial_capture(hub_devices: dict[str, str], request: pytest.FixtureRequest) -> Any:
+    """Returns a `_SerialCapture` factory.
+
+    Usage:
+        cap = serial_capture("esp32s3")
+        cap.start()
+        ... run test ...
+        # on failure, serial buffer is attached via pytest_runtest_makereport
+    """
+    captures: list[_SerialCapture] = []
+
+    def factory(role: str, env: str | None = None) -> _SerialCapture:
+        if role not in hub_devices:
+            pytest.skip(f"role {role!r} not present on the hub")
+        cap = _SerialCapture(port=hub_devices[role], env=env)
+        cap.start()
+        captures.append(cap)
+        request.node._serial_captures = captures  # type: ignore[attr-defined]
+        return cap
+
+    yield factory
+
+    for cap in captures:
+        cap.stop()
+
+
+@pytest.fixture
+def wait_until() -> Callable[..., Any]:
+    """Exponential-backoff polling helper.
+
+    Usage:
+        wait_until(lambda: b.node_num in a.iface.nodesByNum, timeout=60)
+    """
+
+    def _impl(
+        predicate: Callable[[], Any],
+        timeout: float = 60.0,
+        backoff_start: float = 0.5,
+        backoff_max: float = 5.0,
+    ) -> Any:
+        deadline = time.monotonic() + timeout
+        delay = backoff_start
+        last: Any = None
+        while time.monotonic() < deadline:
+            last = predicate()
+            if last:
+                return last
+            time.sleep(delay)
+            delay = min(delay * 1.5, backoff_max)
+        raise AssertionError(
+            f"predicate did not return truthy within {timeout}s (last={last!r})"
+        )
+
+    return _impl
+
+
+# ---------- pytest hooks: report attachments + coverage -------------------
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo[Any]) -> Any:
+    """On test failure, attach serial capture + device state as report artifacts."""
+    outcome = yield
+    report = outcome.get_result()
+
+    if report.when != "call" or report.outcome != "failed":
+        return
+
+    extras: list[str] = []
+
+    # Attach serial captures (if the test used `serial_capture`)
+    caps = getattr(item, "_serial_captures", None)
+    if caps:
+        for i, cap in enumerate(caps):
+            lines = cap.snapshot(max_lines=2000)
+            extras.append(
+                f"--- serial capture [{cap._port}] ({len(lines)} lines) ---\n"
+                + "\n".join(lines[-200:])
+            )
+
+    # Dump device state for any role in hub_devices (if fixture available)
+    hub_fixture = (
+        item.funcargs.get("hub_devices") if hasattr(item, "funcargs") else None
+    )
+    if hub_fixture:
+        for role, port in hub_fixture.items():
+            state: dict[str, Any] = {"role": role, "port": port}
+            try:
+                state["device_info"] = info.device_info(port=port, timeout_s=5.0)
+            except Exception as exc:
+                state["device_info_error"] = repr(exc)
+            try:
+                state["config"] = admin.get_config(section="lora", port=port)
+            except Exception as exc:
+                state["config_error"] = repr(exc)
+            extras.append(
+                f"--- device state [{role}] ---\n{json.dumps(state, indent=2, default=str)}"
+            )
+
+    if extras:
+        # Attach to pytest-html via `report.sections`; pytest-html renders these
+        report.sections.append(("Meshtastic debug", "\n\n".join(extras)))
+
+
+def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
+    """Emit `tool_coverage.json` at session end."""
+    out_path = pathlib.Path(__file__).parent / "tool_coverage.json"
+    tool_coverage.write_report(out_path)
+
+
+# Activate the tool-coverage tracker at import time so imports in fixtures are
+# also counted.
+tool_coverage.install()

mcp-server/tests/fleet/test_placeholders.py

@@ -0,0 +1,21 @@
+"""Fleet placeholders: v2 roadmap entries, skipped in v2.0."""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.skip(reason="placeholder — implement in v2.1")
+
+
+def test_reflash_is_idempotent() -> None:
+    """`erase_and_flash` + wait-for-boot; `erase_and_flash` again with same
+    env+profile; second pass completes with the device reachable and
+    `device_info` identical to first pass. Operational CI workflow check."""
+    pass
+
+
+def test_concurrent_admin_ops_dont_stomp() -> None:
+    """Launch two threads: one calls `device_info(nrf52)` repeatedly, the other
+    calls `device_info(esp32s3)`. Both succeed, no cross-port contamination.
+    Validates `connection.py`'s per-port lock."""
+    pass

mcp-server/tests/fleet/test_psk_seed_isolates_runs.py

@@ -0,0 +1,43 @@
+"""Fleet: different session seeds produce non-overlapping PSKs.
+
+No hardware needed — this is a pure property check on the test profile
+generator, elevated into the `fleet/` tier because it's the critical
+invariant for running concurrent CI labs without cross-contamination.
+"""
+
+from __future__ import annotations
+
+from meshtastic_mcp import userprefs
+
+
+def test_psk_seed_isolates_runs() -> None:
+    """Two labs running simultaneously with different seeds must end up with
+    different PSKs — which means firmware baked in lab A cannot decode lab B's
+    traffic, and vice versa.
+
+    This is the formal statement of the isolation claim that
+    `testing_profile` promises operators.
+    """
+    lab_a_morning = userprefs.build_testing_profile(psk_seed="lab-a-2026-04-16-morning")
+    lab_a_evening = userprefs.build_testing_profile(psk_seed="lab-a-2026-04-16-evening")
+    lab_b_morning = userprefs.build_testing_profile(psk_seed="lab-b-2026-04-16-morning")
+
+    # Same lab, same date, different time-of-day → different PSKs
+    assert (
+        lab_a_morning["USERPREFS_CHANNEL_0_PSK"]
+        != lab_a_evening["USERPREFS_CHANNEL_0_PSK"]
+    )
+    # Different labs, same time-of-day → different PSKs
+    assert (
+        lab_a_morning["USERPREFS_CHANNEL_0_PSK"]
+        != lab_b_morning["USERPREFS_CHANNEL_0_PSK"]
+    )
+
+    # Re-deriving with the same seed yields the same PSK (reproducibility)
+    lab_a_morning_again = userprefs.build_testing_profile(
+        psk_seed="lab-a-2026-04-16-morning"
+    )
+    assert (
+        lab_a_morning["USERPREFS_CHANNEL_0_PSK"]
+        == lab_a_morning_again["USERPREFS_CHANNEL_0_PSK"]
+    )

mcp-server/tests/mesh/test_broadcast_delivers.py

@@ -0,0 +1,46 @@
+"""Mesh: broadcast text from A arrives at B.
+
+Proves end-to-end send → receive path across a 2-device mesh. Uses serial log
+capture on B to observe the decoded message rather than the meshtastic Python
+`onReceive` callback (which would require long-lived iface subscription).
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import pytest
+from meshtastic_mcp import admin
+
+
+@pytest.mark.timeout(120)
+def test_broadcast_delivers(
+    baked_mesh: dict[str, Any],
+    serial_capture,
+    wait_until,
+) -> None:
+    """Flow:
+    1. Start a serial capture on B before sending.
+    2. From A, send a uniquely-tagged text broadcast.
+    3. Poll B's serial buffer for the unique tag.
+    """
+    if "nrf52" not in baked_mesh or "esp32s3" not in baked_mesh:
+        pytest.skip("both roles required")
+
+    # Capture on B (esp32s3) — pio device monitor shows decoded mesh packets
+    b_env = os.environ.get("MESHTASTIC_MCP_ENV_ESP32S3", "t-beam-1w")
+    cap = serial_capture("esp32s3", env=b_env)
+    time.sleep(2.0)  # let monitor settle
+
+    unique = f"mcp-test-{int(time.time())}"
+    admin.send_text(
+        text=unique,
+        port=baked_mesh["nrf52"]["port"],
+    )
+
+    def unique_in_log() -> bool:
+        return any(unique in line for line in cap.snapshot(max_lines=4000))
+
+    wait_until(unique_in_log, timeout=90, backoff_start=2.0, backoff_max=10.0)

mcp-server/tests/mesh/test_direct_with_ack.py

@@ -0,0 +1,59 @@
+"""Mesh: direct message with want_ack=True returns a real ACK.
+
+Real operator concern: "did my message actually arrive?" — want_ack exists
+precisely to answer that question. A silent drop is the single most common
+"my mesh is broken" user complaint; this test proves the happy-path ACK
+round-trip works on a well-formed mesh.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from meshtastic_mcp.connection import connect
+
+
+@pytest.mark.timeout(180)
+def test_direct_with_ack_roundtrip(baked_mesh: dict[str, Any], wait_until) -> None:
+    """Wait for mesh formation, then send A → B with want_ack=True via the
+    raw SerialInterface (so we can observe the ACK bookkeeping on the sender
+    iface). The meshtastic SDK exposes `iface.sendText` which returns the
+    outbound packet; the ACK is accounted by the firmware but not directly
+    surfaced to the caller — so we fall back to checking that the send did
+    not raise, and that B's node record has `last_heard` bumped."""
+    if "nrf52" not in baked_mesh or "esp32s3" not in baked_mesh:
+        pytest.skip("both roles required")
+
+    a_port = baked_mesh["nrf52"]["port"]
+    b_node_num = baked_mesh["esp32s3"]["my_node_num"]
+
+    # Wait for mesh formation first (B in A's DB)
+    def b_in_a() -> bool:
+        with connect(port=a_port) as iface:
+            return b_node_num in (iface.nodesByNum or {})
+
+    wait_until(b_in_a, timeout=120, backoff_start=2.0, backoff_max=10.0)
+
+    # Send with want_ack and record lastHeard before/after
+    with connect(port=a_port) as iface:
+        b_record_before = iface.nodesByNum.get(b_node_num, {})
+        last_heard_before = b_record_before.get("lastHeard", 0) or 0
+
+        packet = iface.sendText(
+            "ack-check",
+            destinationId=b_node_num,
+            wantAck=True,
+        )
+        assert packet is not None, "sendText returned None"
+        assert hasattr(packet, "id") or isinstance(
+            packet, dict
+        ), "sendText did not return a recognizable packet object"
+
+    # Within a few ACK round-trips on LONG_FAST, lastHeard should tick forward
+    def last_heard_advanced() -> bool:
+        with connect(port=a_port) as iface:
+            current = (iface.nodesByNum.get(b_node_num) or {}).get("lastHeard", 0) or 0
+            return current > last_heard_before
+
+    wait_until(last_heard_advanced, timeout=60, backoff_start=2.0)

mcp-server/tests/mesh/test_mesh_formation.py

@@ -0,0 +1,35 @@
+"""Mesh: two devices baked with the same session profile discover each other.
+
+The fundamental "does my mesh work" test. If both devices share a PSK, LoRa
+region, modem preset, and channel slot, they should hear each other's
+NodeInfo packets within ~60s of boot and appear in each other's `nodesByNum`
+DB.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from meshtastic_mcp import info
+from meshtastic_mcp.connection import connect
+
+
+@pytest.mark.timeout(180)
+def test_mesh_formation_within_60s(baked_mesh: dict[str, Any], wait_until) -> None:
+    """Connect to A, poll its node DB until B's node_num appears. If both
+    devices were freshly baked, NodeInfo broadcast should happen within
+    ~30-60s on LONG_FAST."""
+    if "nrf52" not in baked_mesh or "esp32s3" not in baked_mesh:
+        pytest.skip("both roles required")
+
+    a_port = baked_mesh["nrf52"]["port"]
+    b_node_num = baked_mesh["esp32s3"]["my_node_num"]
+    assert b_node_num is not None, "esp32s3 my_node_num not populated"
+
+    def b_visible_from_a() -> bool:
+        with connect(port=a_port) as iface:
+            nodes = iface.nodesByNum or {}
+            return b_node_num in nodes
+
+    wait_until(b_visible_from_a, timeout=120, backoff_start=2.0, backoff_max=10.0)

mcp-server/tests/mesh/test_placeholders.py

@@ -0,0 +1,50 @@
+"""Mesh placeholders: v2 roadmap entries, skipped in v2.0."""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.skip(reason="placeholder — implement in v2.1")
+
+
+def test_direct_to_ghost_times_out_or_naks() -> None:
+    """Send a direct message to a fabricated node_num (e.g. 0xDEADBEEF) with
+    want_ack=True; assert caller observes NAK or timeout within 60s. Operator
+    fleet-health check — 'is my offline-peer detection working'."""
+    pass
+
+
+def test_hop_limit_decrements() -> None:
+    """Send a message with hop_limit=3; inspect received packet on B via
+    serial decoder; assert hop_limit=2 (1-hop decrement across A→B). Prevents
+    runaway rebroadcasting that destroys mesh throughput."""
+    pass
+
+
+def test_snr_rssi_populated() -> None:
+    """After 2 min of idle mesh traffic, B's entry in A's node DB must have
+    `snr ∈ [-25, 15]` and `rssi ∈ [-140, 0]`. The most common 'my mesh is
+    broken' misdiagnosis is actually just an empty node DB."""
+    pass
+
+
+def test_secondary_channel_stays_private() -> None:
+    """Bake A with channels [primary + secondary 'Secret' PSK K1]; bake B
+    with primary only. A sends on ch_index=1; B's decoded log must NOT contain
+    the secret payload. The privacy-by-channel promise."""
+    pass
+
+
+def test_psk_mismatch_no_decode() -> None:
+    """Bake A with psk_seed='run-A', B with psk_seed='run-B' (same
+    channel_name). A sends broadcast; B's log shows packet-received-but-
+    rejected at decode (PSK mismatch). Proves session isolation between
+    concurrent test labs."""
+    pass
+
+
+def test_traceroute_one_hop() -> None:
+    """A → traceroute(B); response path contains exactly [A, B] with no
+    intermediate routers (since there aren't any in a 2-device mesh).
+    Validates `traceroute` packet round-trip."""
+    pass

mcp-server/tests/monitor/test_boot_log_no_panic.py

@@ -0,0 +1,66 @@
+"""Monitor: boot log is clean — no panic markers in the first 60 seconds.
+
+This is the single highest-signal test for catching firmware regressions.
+If a commit broke something critical at boot (stack overflow, NULL deref, HAL
+misconfig), this test fails within a minute of reboot.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+from typing import Any
+
+import pytest
+from meshtastic_mcp import admin
+
+# Substrings that indicate a panic/assert/crash. Case-insensitive.
+_PANIC_MARKERS = [
+    "guru meditation",
+    "corrupt heap",
+    "abort()",
+    "assertion failed",
+    "***",  # ESP-IDF "*** something" panic prefix
+    "panic",
+    "stack overflow",
+    "load prohibited",
+    "store prohibited",
+    "illegalinstr",
+    "watchdog got triggered",
+]
+
+
+@pytest.mark.timeout(180)
+def test_boot_log_no_panic(
+    baked_mesh: dict[str, Any],
+    serial_capture,
+    wait_until,
+) -> None:
+    """Reboot the device, then watch ~60s of boot log for panic markers."""
+    target = "esp32s3"
+    if target not in baked_mesh:
+        pytest.skip(f"role {target!r} not on hub")
+    port = baked_mesh[target]["port"]
+
+    env = os.environ.get("MESHTASTIC_MCP_ENV_ESP32S3", "t-beam-1w")
+
+    # Start monitor BEFORE reboot so we catch the reset banner + early boot
+    cap = serial_capture(target, env=env)
+    time.sleep(1.0)
+
+    # Trigger reboot
+    admin.reboot(port=port, confirm=True, seconds=3)
+    # Wait through the reboot+boot window
+    time.sleep(60.0)
+
+    lines = cap.snapshot(max_lines=4000)
+    assert lines, "serial capture returned no log lines — monitor may have failed"
+    blob = "\n".join(lines).lower()
+
+    hits = [marker for marker in _PANIC_MARKERS if marker in blob]
+    assert (
+        not hits
+    ), f"panic markers in boot log: {hits!r}\n\n" f"last 60 lines:\n" + "\n".join(
+        lines[-60:]
+    )

mcp-server/tests/monitor/test_placeholders.py

@@ -0,0 +1,22 @@
+"""Monitor placeholders: v2 roadmap entries, skipped in v2.0."""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.skip(reason="placeholder — implement in v2.1")
+
+
+def test_env_selects_correct_filter() -> None:
+    """Open `serial_open(env='t-beam-1w')`; assert `resolved_filters` includes
+    `esp32_exception_decoder`. Proves `pio device monitor -e <env>` correctly
+    applies per-variant monitor_filters from platformio.ini."""
+    pass
+
+
+def test_dropped_lines_reported() -> None:
+    """Force a flood of log output (e.g. via a debug flag); read the session
+    with a long delay; assert `serial_read.dropped > 0` surfaces correctly
+    when the ring buffer overflows. Operators relying on serial capture for
+    post-mortem need to know when they missed data."""
+    pass

mcp-server/tests/provisioning/test_admin_key_baked.py

@@ -0,0 +1,78 @@
+"""Provisioning: baked admin keys end up in the device's security config.
+
+Fleet operators pre-bake an `USERPREFS_USE_ADMIN_KEY_0` into firmware so that
+remote-admin messages from a central controller are accepted. This test
+verifies the key bytes make the round-trip: USERPREFS → build-time `-D` flag
+→ firmware → `localConfig.security.admin_key`.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import pytest
+from meshtastic_mcp import admin, flash
+
+# Deterministic 32-byte "admin key" — just the byte values 0..31 for easy
+# recognition in the output, formatted as a C brace-init.
+_ADMIN_KEY_BYTES = list(range(32))
+_ADMIN_KEY_BRACE = "{ " + ", ".join(f"0x{b:02x}" for b in _ADMIN_KEY_BYTES) + " }"
+
+
+@pytest.mark.timeout(600)
+def test_admin_key_baked(
+    hub_devices: dict[str, str],
+    test_profile: dict[str, Any],
+) -> None:
+    """Bake test_profile + admin key 0; verify `security.admin_key` contains
+    the baked bytes after boot. Re-bakes session profile (without admin key)
+    on teardown so downstream tests see baseline state.
+    """
+    target = "esp32s3"
+    if target not in hub_devices:
+        pytest.skip(f"role {target!r} not on hub")
+    port = hub_devices[target]
+    env = os.environ.get("MESHTASTIC_MCP_ENV_ESP32S3", "t-beam-1w")
+
+    augmented = dict(test_profile)
+    augmented["USERPREFS_USE_ADMIN_KEY_0"] = _ADMIN_KEY_BRACE
+
+    try:
+        result = flash.erase_and_flash(
+            env=env,
+            port=port,
+            confirm=True,
+            userprefs_overrides=augmented,
+        )
+        assert result["exit_code"] == 0
+
+        security = admin.get_config(section="security", port=port)["config"]["security"]
+        # `admin_key` may be a list of byte-sequences under newer protobuf, or
+        # a single bytes field under older. We accept either as long as the
+        # baked bytes appear somewhere in the serialization.
+        key_field = security.get("admin_key")
+        import base64
+        import json
+
+        serialized = json.dumps(security)
+
+        # Protobuf→JSON typically base64-encodes bytes fields. Encode our
+        # expected bytes and look for them (or a substring) in the serialized
+        # security config.
+        b64 = base64.b64encode(bytes(_ADMIN_KEY_BYTES)).decode("ascii").rstrip("=")
+        assert (
+            b64[:40] in serialized or "admin_key" in serialized
+        ), f"admin_key bytes not visible in security config: {security!r}"
+        assert (
+            key_field is not None
+        ), "security.admin_key field absent — baking key 0 didn't stick"
+    finally:
+        # Restore session profile (no admin key)
+        restore = flash.erase_and_flash(
+            env=env,
+            port=port,
+            confirm=True,
+            userprefs_overrides=test_profile,
+        )
+        assert restore["exit_code"] == 0

mcp-server/tests/provisioning/test_bake_region_modem_slot.py

@@ -0,0 +1,48 @@
+"""Provisioning: the pre-bake recipe (US/LONG_FAST/slot 88/private channel)
+lands on the device exactly as specified.
+
+This is THE test that proves the MCP's core value prop — flashing firmware
+with a preset USERPREFS produces a device in the expected radio config without
+any post-flash admin steps.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from meshtastic_mcp import admin, info
+
+
+@pytest.mark.timeout(60)
+def test_bake_sets_region_preset_and_slot(
+    baked_mesh: dict[str, Any],
+    test_profile: dict[str, Any],
+) -> None:
+    """After test_00_bake, both devices must report the exact region, modem
+    preset, slot, and channel name that the profile specified."""
+    for role, state in baked_mesh.items():
+        port = state["port"]
+        live = info.device_info(port=port, timeout_s=8.0)
+        lora = admin.get_config(section="lora", port=port)["config"]["lora"]
+
+        expected_region = test_profile["USERPREFS_CONFIG_LORA_REGION"].rsplit("_", 1)[
+            -1
+        ]
+        expected_preset = test_profile["USERPREFS_LORACONFIG_MODEM_PRESET"].rsplit(
+            "_", 2
+        )[-2:]
+        expected_preset_str = "_".join(expected_preset)
+
+        assert (
+            live["region"] == expected_region
+        ), f"{role}: region={live['region']!r}, expected {expected_region!r}"
+        assert lora.get("modem_preset") in (
+            expected_preset_str,
+            expected_preset_str.upper(),
+        ), f"{role}: modem_preset={lora.get('modem_preset')!r}, expected {expected_preset_str!r}"
+        assert (
+            int(lora.get("channel_num", 0))
+            == test_profile["USERPREFS_LORACONFIG_CHANNEL_NUM"]
+        ), f"{role}: channel_num={lora.get('channel_num')!r}"
+        assert live["primary_channel"] == test_profile["USERPREFS_CHANNEL_0_NAME"]

mcp-server/tests/provisioning/test_placeholders.py

@@ -0,0 +1,37 @@
+"""Provisioning placeholders: v2 roadmap entries, skipped in v2.
+
+Each test documents intent so `pytest --collect-only` surfaces the complete
+planned suite. Implementations land in v2.1+ as hardware coverage expands.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.skip(reason="placeholder — implement in v2.1")
+
+
+def test_firmware_edition_surfaces() -> None:
+    """Bake `USERPREFS_FIRMWARE_EDITION=meshtastic_FirmwareEdition_BURNING_MAN`;
+    verify `iface.myInfo.firmware_edition == BURNING_MAN`. Relevant for event
+    firmware drops."""
+    pass
+
+
+def test_oem_text_in_boot_log() -> None:
+    """Bake `USERPREFS_OEM_TEXT="Lab Bench"`; open serial at boot; assert the
+    OEM string appears in the splash log lines."""
+    pass
+
+
+def test_tz_applied() -> None:
+    """Bake `USERPREFS_TZ_STRING="PST8PDT,M3.2.0,M11.1.0"`; verify
+    `localConfig.device.tzdef` matches and clock-display lines reflect the TZ."""
+    pass
+
+
+def test_full_factory_reset_regenerates_identity() -> None:
+    """Before: capture `my_node_num`. Call `factory_reset(full=True)`. After
+    reboot: `my_node_num` must differ (new identity), AND baked USERPREFS
+    defaults (region/channel) still come back."""
+    pass

mcp-server/tests/provisioning/test_unset_region_blocks_tx.py

@@ -0,0 +1,103 @@
+"""Provisioning (negative): firmware baked WITHOUT
+`USERPREFS_CONFIG_LORA_REGION` must refuse to transmit.
+
+Real operator concern: FCC compliance. A device shipped without an explicit
+region setting must not emit RF until the operator sets a region — this test
+proves the firmware honors that invariant when the USERPREFS bake deliberately
+omits the region key.
+
+Teardown re-bakes the session `test_profile` so downstream shared-state
+tiers (admin/mesh/telemetry) still see a correctly configured mesh.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from meshtastic_mcp import admin, flash, info
+
+
+@pytest.mark.timeout(600)
+def test_unset_region_blocks_tx(
+    hub_devices: dict[str, str],
+    no_region_profile: dict[str, Any],
+    test_profile: dict[str, Any],
+    serial_capture,
+) -> None:
+    """Bake a device with no LoRa region, then assert:
+      1. `config.lora.region` reads as "UNSET" (or 0).
+      2. An attempt to `send_text` surfaces a refusal — either the meshtastic
+         SDK raises, or the serial log contains a clear "region unset" marker.
+
+    Always re-bakes the session test_profile in the finalizer so downstream
+    categories are not left with a broken device.
+    """
+    target = "esp32s3"
+    if target not in hub_devices:
+        pytest.skip(f"role {target!r} not on hub")
+    port = hub_devices[target]
+
+    # Pick the right env for this role — must match what test_00_bake used.
+    import os
+
+    env = os.environ.get("MESHTASTIC_MCP_ENV_ESP32S3", "t-beam-1w")
+
+    # Capture serial before the bake to see the "region unset" log line on boot
+    cap = serial_capture(target, env=env)
+
+    # Bake without region
+    result = flash.erase_and_flash(
+        env=env,
+        port=port,
+        confirm=True,
+        userprefs_overrides=no_region_profile,
+    )
+    assert (
+        result["exit_code"] == 0
+    ), f"bake of no_region_profile failed:\n{result.get('stderr_tail', '')}"
+
+    try:
+        # After bake, device should boot with region=UNSET
+        live = info.device_info(port=port, timeout_s=12.0)
+        assert live.get("region") in (None, "UNSET", "UNSET_0", ""), (
+            f"expected region UNSET after baking without region pref; "
+            f"got {live.get('region')!r}"
+        )
+
+        # Attempting to send a message should either raise or be logged as
+        # refused. The meshtastic SDK's sendText may raise in this condition,
+        # or it may accept the call but the firmware rejects on air.
+        send_failed = False
+        try:
+            admin.send_text(text="should not transmit", port=port)
+        except Exception:
+            send_failed = True
+
+        # Give the firmware a moment to log anything
+        import time as _time
+
+        _time.sleep(3.0)
+        log = "\n".join(cap.snapshot(max_lines=2000))
+        # We expect EITHER the send raised at the Python layer, OR the serial
+        # log explicitly says region is unset.
+        log_says_unset = any(
+            marker in log.lower()
+            for marker in ("region unset", "region is unset", "no region set")
+        )
+        assert send_failed or log_says_unset, (
+            "expected send to fail or log 'region unset'; neither happened.\n"
+            f"log tail:\n{log[-2000:]}"
+        )
+    finally:
+        # Re-bake the session profile so downstream tests work.
+        restore = flash.erase_and_flash(
+            env=env,
+            port=port,
+            confirm=True,
+            userprefs_overrides=test_profile,
+        )
+        assert restore["exit_code"] == 0, (
+            "CRITICAL: failed to re-bake session profile after "
+            "no-region test; downstream tests will fail."
+        )

mcp-server/tests/provisioning/test_userprefs_survive_factory_reset.py

@@ -0,0 +1,80 @@
+"""Provisioning: after a non-full factory_reset, USERPREFS defaults come back.
+
+Real operator concern: "if someone resets my fleet device, will it come back
+on my private mesh or on Meshtastic defaults?" A baked USERPREFS recipe
+should be the factory floor for the device — reset goes back to THAT state,
+not to stock Meshtastic.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import pytest
+from meshtastic_mcp import admin, info
+
+
+@pytest.mark.timeout(120)
+def test_baked_prefs_survive_factory_reset(
+    baked_mesh: dict[str, Any],
+    test_profile: dict[str, Any],
+    wait_until,
+) -> None:
+    """Flow:
+    1. Change owner name to a known-non-default value.
+    2. Trigger factory_reset(full=False).
+    3. Wait for device to come back.
+    4. Confirm owner is back to USERPREFS-baked default (or blank default if
+       not baked), and primary channel/region/slot are still the baked values.
+    """
+    # Use esp32s3 — typically more robust across reset cycles.
+    target = "esp32s3"
+    if target not in baked_mesh:
+        pytest.skip(f"role {target!r} not on hub")
+    port = baked_mesh[target]["port"]
+
+    # Snapshot pre-reset config
+    pre_reset = info.device_info(port=port, timeout_s=8.0)
+    original_long_name = pre_reset.get("long_name")
+
+    # Poison the owner name with a non-default marker
+    admin.set_owner(long_name="PoisonMarker", short_name="POIZ", port=port)
+    time.sleep(2.0)
+
+    # Confirm poison stuck before reset
+    poisoned = info.device_info(port=port, timeout_s=8.0)
+    assert poisoned.get("long_name") == "PoisonMarker"
+
+    # Trigger non-full factory reset
+    admin.factory_reset(port=port, confirm=True, full=False)
+
+    # Wait for device to come back (serial reappears)
+    time.sleep(10.0)  # reset takes a moment
+    wait_until(
+        lambda: info.device_info(port=port, timeout_s=5.0).get("my_node_num")
+        is not None,
+        timeout=60,
+        backoff_start=1.0,
+    )
+
+    post = info.device_info(port=port, timeout_s=8.0)
+    # The key assertion: channel + region are STILL the USERPREFS-baked values,
+    # NOT Meshtastic stock defaults (which would be "LongFast" and the region
+    # the device shipped with).
+    assert post["primary_channel"] == test_profile["USERPREFS_CHANNEL_0_NAME"], (
+        f"after factory_reset, primary_channel reverted to "
+        f"{post['primary_channel']!r}, not baked {test_profile['USERPREFS_CHANNEL_0_NAME']!r}"
+    )
+    expected_region = test_profile["USERPREFS_CONFIG_LORA_REGION"].rsplit("_", 1)[-1]
+    assert post.get("region") == expected_region
+
+    # Owner name should NOT be "PoisonMarker" anymore
+    assert (
+        post.get("long_name") != "PoisonMarker"
+    ), "factory_reset did not wipe the poisoned owner name"
+
+    # If we had an original_long_name, restore it so downstream tests see
+    # the same baseline.
+    if original_long_name and post.get("long_name") != original_long_name:
+        admin.set_owner(long_name=original_long_name, port=port)

mcp-server/tests/telemetry/test_device_telemetry_broadcast.py

@@ -0,0 +1,42 @@
+"""Telemetry: device metrics (battery, voltage, channel util) arrive at the peer.
+
+After ~2× the telemetry interval, B's entry in A's node DB should carry a
+populated `deviceMetrics` block. This is the happy-path "my fleet is
+reporting health data" operator test.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from meshtastic_mcp.connection import connect
+
+
+@pytest.mark.timeout(360)
+def test_device_telemetry_broadcast(baked_mesh: dict[str, Any], wait_until) -> None:
+    """Wait up to 5 minutes for B's device telemetry to land in A's DB.
+
+    Firmware default telemetry interval is 900s; on a fresh mesh the first
+    device-metrics broadcast happens within ~30-120s of boot because devices
+    broadcast once on startup. We only require that some telemetry is present,
+    not that we see multiple cycles.
+    """
+    if "nrf52" not in baked_mesh or "esp32s3" not in baked_mesh:
+        pytest.skip("both roles required")
+
+    a_port = baked_mesh["nrf52"]["port"]
+    b_node_num = baked_mesh["esp32s3"]["my_node_num"]
+
+    def b_has_telemetry() -> bool:
+        with connect(port=a_port) as iface:
+            rec = (iface.nodesByNum or {}).get(b_node_num, {})
+            metrics = rec.get("deviceMetrics") or {}
+            # Any one of these being non-None is sufficient evidence that
+            # telemetry arrived.
+            return any(
+                metrics.get(k) is not None
+                for k in ("batteryLevel", "voltage", "channelUtilization", "airUtilTx")
+            )
+
+    wait_until(b_has_telemetry, timeout=300, backoff_start=5.0, backoff_max=15.0)

mcp-server/tests/telemetry/test_placeholders.py

@@ -0,0 +1,22 @@
+"""Telemetry placeholders: v2 roadmap entries, skipped in v2.0."""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.skip(reason="placeholder — implement in v2.1")
+
+
+def test_position_broadcast_precision() -> None:
+    """Bake A with `USERPREFS_CHANNEL_0_PRECISION=10` (low-precision channel);
+    A sets a fixed position; B's `list_nodes` entry for A shows truncated
+    coordinates (lower bits zeroed relative to what A transmitted). Validates
+    the privacy-precision knob operators tune for event deployments."""
+    pass
+
+
+def test_fixed_position_round_trip() -> None:
+    """`set_fixed_position(lat=40.7128, lon=-74.0060, alt=10)` on A; wait for
+    broadcast; assert B's node DB shows A's position within 1e-6° tolerance
+    AND `position_config.fixed_position=true` on A persists across reboot."""
+    pass

mcp-server/tests/test_00_bake.py

@@ -0,0 +1,117 @@
+"""Session-bake module — runs first (alphabetical collection) to flash both hub
+roles with the session `test_profile`.
+
+Skipped entirely when `--assume-baked` is passed. All downstream hardware
+tests either depend on `baked_mesh` (which verifies state) or do their own
+per-test bake (provisioning/fleet tiers), so failing here gives one clear
+actionable failure instead of a cascade of mismatches.
+
+Hardware-specific env names live in a small role→env map at the top of this
+file; override by setting `MESHTASTIC_MCP_ENV_<ROLE>` env vars (e.g.
+`MESHTASTIC_MCP_ENV_NRF52=heltec-mesh-node-t114`).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import pytest
+from meshtastic_mcp import flash, info
+
+# Default envs for a common lab setup. Override per-role via env var.
+_DEFAULT_ENVS = {
+    "nrf52": "heltec-mesh-node-t114",
+    "esp32s3": "t-beam-1w",
+}
+
+
+def _env_for(role: str) -> str:
+    override = os.environ.get(f"MESHTASTIC_MCP_ENV_{role.upper()}")
+    if override:
+        return override
+    if role not in _DEFAULT_ENVS:
+        pytest.fail(
+            f"no default PlatformIO env for role {role!r}. "
+            f"Set MESHTASTIC_MCP_ENV_{role.upper()} to the env name."
+        )
+    return _DEFAULT_ENVS[role]
+
+
+def _bake_role(
+    role: str,
+    port: str,
+    test_profile: dict[str, Any],
+    force_bake: bool,
+) -> None:
+    """Bake + boot + verify for a single role. Skips if already baked unless
+    `--force-bake` was passed."""
+    env = _env_for(role)
+
+    # If not forcing, check if already baked with session profile.
+    if not force_bake:
+        try:
+            live = info.device_info(port=port, timeout_s=8.0)
+            # Quick heuristic: region matches and primary channel matches.
+            expected_region_short = test_profile["USERPREFS_CONFIG_LORA_REGION"].rsplit(
+                "_", 1
+            )[-1]
+            if (
+                live.get("region") == expected_region_short
+                and live.get("primary_channel")
+                == test_profile["USERPREFS_CHANNEL_0_NAME"]
+            ):
+                pytest.skip(
+                    f"{role} at {port} already baked with session profile "
+                    f"(pass --force-bake to reflash)"
+                )
+        except Exception:
+            # If we can't query, fall through and bake anyway.
+            pass
+
+    result = flash.erase_and_flash(
+        env=env,
+        port=port,
+        confirm=True,
+        skip_build=False,
+        userprefs_overrides=test_profile,
+    )
+    assert result["exit_code"] == 0, (
+        f"{role} bake failed: exit={result['exit_code']}\n"
+        f"stdout tail:\n{result.get('stdout_tail', '')}\n"
+        f"stderr tail:\n{result.get('stderr_tail', '')}"
+    )
+
+
+@pytest.mark.timeout(600)
+def test_bake_nrf52(
+    hub_devices: dict[str, str],
+    test_profile: dict[str, Any],
+    request: pytest.FixtureRequest,
+) -> None:
+    """Flash the nRF52840 role with the session test profile."""
+    if "nrf52" not in hub_devices:
+        pytest.skip("nRF52 not detected on hub")
+    _bake_role(
+        role="nrf52",
+        port=hub_devices["nrf52"],
+        test_profile=test_profile,
+        force_bake=request.config.getoption("--force-bake"),
+    )
+
+
+@pytest.mark.timeout(600)
+def test_bake_esp32s3(
+    hub_devices: dict[str, str],
+    test_profile: dict[str, Any],
+    request: pytest.FixtureRequest,
+) -> None:
+    """Flash the ESP32-S3 role with the session test profile."""
+    if "esp32s3" not in hub_devices:
+        pytest.skip("ESP32-S3 not detected on hub")
+    _bake_role(
+        role="esp32s3",
+        port=hub_devices["esp32s3"],
+        test_profile=test_profile,
+        force_bake=request.config.getoption("--force-bake"),
+    )

mcp-server/tests/tool_coverage.py

@@ -0,0 +1,124 @@
+"""Tool-surface coverage: track which MCP tools the test suite actually exercises.
+
+This is NOT line coverage (that's `coverage.py`). This measures which of the
+37 public MCP tools in `meshtastic_mcp.server` got invoked during a pytest
+run — a quick signal for "where are the test-coverage gaps".
+
+Approach: introspect `meshtastic_mcp.server.app` for registered tools, find
+the underlying handler functions in their source modules, and wrap each with
+a counting shim. At session end, emit `tool_coverage.json` mapping each tool
+name to its call count. Tools never called show `count=0`.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import Any, Callable
+
+_counts: dict[str, int] = {}
+_installed = False
+
+
+def _bump(name: str) -> None:
+    _counts[name] = _counts.get(name, 0) + 1
+
+
+def _wrap(module: Any, attr: str, tool_name: str) -> None:
+    original = getattr(module, attr, None)
+    if original is None or not callable(original):
+        return
+
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        _bump(tool_name)
+        return original(*args, **kwargs)
+
+    wrapper.__wrapped__ = original  # type: ignore[attr-defined]
+    wrapper.__name__ = attr
+    wrapper.__doc__ = original.__doc__
+    setattr(module, attr, wrapper)
+
+
+# Mapping: MCP tool name → (module, function name). Mirrors the wiring in
+# `meshtastic_mcp.server`. Keep synchronized manually — adding a tool without
+# updating this map means it shows as count=0 in reports even if exercised.
+_TOOL_MAP: dict[str, tuple[str, str]] = {
+    # Discovery & metadata
+    "list_devices": ("meshtastic_mcp.devices", "list_devices"),
+    "list_boards": ("meshtastic_mcp.boards", "list_boards"),
+    "get_board": ("meshtastic_mcp.boards", "get_board"),
+    # Build & flash
+    "build": ("meshtastic_mcp.flash", "build"),
+    "clean": ("meshtastic_mcp.flash", "clean"),
+    "pio_flash": ("meshtastic_mcp.flash", "flash"),
+    "erase_and_flash": ("meshtastic_mcp.flash", "erase_and_flash"),
+    "update_flash": ("meshtastic_mcp.flash", "update_flash"),
+    "touch_1200bps": ("meshtastic_mcp.flash", "touch_1200bps"),
+    # Serial log sessions — module-level functions on serial_session
+    "serial_open": ("meshtastic_mcp.serial_session", "open_session"),
+    "serial_read": ("meshtastic_mcp.serial_session", "read_session"),
+    "serial_close": ("meshtastic_mcp.serial_session", "close_session"),
+    # Device reads
+    "device_info": ("meshtastic_mcp.info", "device_info"),
+    "list_nodes": ("meshtastic_mcp.info", "list_nodes"),
+    # Device writes
+    "set_owner": ("meshtastic_mcp.admin", "set_owner"),
+    "get_config": ("meshtastic_mcp.admin", "get_config"),
+    "set_config": ("meshtastic_mcp.admin", "set_config"),
+    "get_channel_url": ("meshtastic_mcp.admin", "get_channel_url"),
+    "set_channel_url": ("meshtastic_mcp.admin", "set_channel_url"),
+    "send_text": ("meshtastic_mcp.admin", "send_text"),
+    "reboot": ("meshtastic_mcp.admin", "reboot"),
+    "shutdown": ("meshtastic_mcp.admin", "shutdown"),
+    "factory_reset": ("meshtastic_mcp.admin", "factory_reset"),
+    # USERPREFS
+    "userprefs_manifest": ("meshtastic_mcp.userprefs", "build_manifest"),
+    "userprefs_get": ("meshtastic_mcp.userprefs", "read_state"),
+    "userprefs_set": ("meshtastic_mcp.userprefs", "merge_active"),
+    "userprefs_reset": ("meshtastic_mcp.userprefs", "reset"),
+    "userprefs_testing_profile": ("meshtastic_mcp.userprefs", "build_testing_profile"),
+    # Vendor hardware tools
+    "esptool_chip_info": ("meshtastic_mcp.hw_tools", "esptool_chip_info"),
+    "esptool_erase_flash": ("meshtastic_mcp.hw_tools", "esptool_erase_flash"),
+    "esptool_raw": ("meshtastic_mcp.hw_tools", "esptool_raw"),
+    "nrfutil_dfu": ("meshtastic_mcp.hw_tools", "nrfutil_dfu"),
+    "nrfutil_raw": ("meshtastic_mcp.hw_tools", "nrfutil_raw"),
+    "picotool_info": ("meshtastic_mcp.hw_tools", "picotool_info"),
+    "picotool_load": ("meshtastic_mcp.hw_tools", "picotool_load"),
+    "picotool_raw": ("meshtastic_mcp.hw_tools", "picotool_raw"),
+}
+
+
+def install() -> None:
+    """Wrap every mapped tool function with the counting shim. Idempotent."""
+    global _installed
+    if _installed:
+        return
+    import importlib
+
+    for tool_name, (module_path, attr) in _TOOL_MAP.items():
+        try:
+            mod = importlib.import_module(module_path)
+        except ImportError:
+            continue
+        _wrap(mod, attr, tool_name)
+        _counts.setdefault(tool_name, 0)
+    _installed = True
+
+
+def write_report(path: pathlib.Path) -> None:
+    """Emit `tool_coverage.json` with call counts for every mapped tool."""
+    exercised = sum(1 for c in _counts.values() if c > 0)
+    total = len(_counts)
+    payload = {
+        "total_tools": total,
+        "exercised": exercised,
+        "coverage_pct": round(100.0 * exercised / total, 1) if total else 0.0,
+        "counts": dict(sorted(_counts.items())),
+        "unexercised": sorted(k for k, v in _counts.items() if v == 0),
+    }
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def snapshot() -> dict[str, int]:
+    return dict(_counts)

mcp-server/tests/unit/test_boards.py

@@ -0,0 +1,72 @@
+"""`boards.py` filter and enumeration correctness.
+
+Runs against the real `pio project config` output of this firmware repo —
+validates that filter predicates match expected envs and don't drift if
+variants get reorganized.
+"""
+
+from __future__ import annotations
+
+import pytest
+from meshtastic_mcp import boards
+
+
+def test_list_boards_returns_many() -> None:
+    all_boards = boards.list_boards()
+    assert len(all_boards) >= 50, "expected at least 50 PlatformIO envs"
+
+
+def test_tbeam_is_canonical_esp32() -> None:
+    """The default env in platformio.ini is `tbeam`; it must always be present
+    and flagged as esp32."""
+    rec = boards.get_board("tbeam")
+    assert rec["architecture"] == "esp32"
+    assert rec["hw_model_slug"] == "TBEAM"
+    assert rec["actively_supported"] is True
+    assert rec["board"] == "ttgo-tbeam"
+
+
+def test_filter_by_architecture() -> None:
+    esp32s3 = boards.list_boards(architecture="esp32s3")
+    assert len(esp32s3) >= 1
+    assert all(b["architecture"] == "esp32s3" for b in esp32s3)
+
+
+def test_filter_by_actively_supported() -> None:
+    supported = boards.list_boards(actively_supported_only=True)
+    unsupported = [b for b in boards.list_boards() if not b["actively_supported"]]
+    assert supported, "at least one board should be actively supported"
+    assert all(b["actively_supported"] for b in supported)
+    # Quick sanity: the set difference is non-empty in this repo (there are
+    # boards marked actively_supported=false).
+    assert unsupported, "expected at least one actively_supported=false board"
+
+
+def test_filter_by_query_substring_matches_display_name() -> None:
+    heltec = boards.list_boards(query="heltec")
+    assert heltec, "expected at least one Heltec env"
+    # Case-insensitive across display_name, env name, or hw_model_slug
+    for b in heltec:
+        blob = " ".join(
+            filter(
+                None,
+                [
+                    b.get("display_name") or "",
+                    b["env"],
+                    b.get("hw_model_slug") or "",
+                ],
+            )
+        ).lower()
+        assert "heltec" in blob
+
+
+def test_get_board_unknown_env_raises() -> None:
+    with pytest.raises(KeyError, match="Unknown env"):
+        boards.get_board("definitely-not-a-real-env")
+
+
+def test_get_board_surfaces_raw_config() -> None:
+    rec = boards.get_board("tbeam")
+    assert "raw_config" in rec
+    assert "custom_meshtastic_architecture" in rec["raw_config"]
+    assert rec["raw_config"]["custom_meshtastic_architecture"] == "esp32"

mcp-server/tests/unit/test_pio_wrapper.py

@@ -0,0 +1,61 @@
+"""`pio.py` subprocess wrapper: error paths, tailing, JSON parsing.
+
+Uses a real `pio` install only for the happy-path `--version`; error paths are
+exercised with a deliberately-broken `MESHTASTIC_PIO_BIN` override.
+"""
+
+from __future__ import annotations
+
+import pytest
+from meshtastic_mcp import pio
+
+
+def test_tail_lines_keeps_last_n() -> None:
+    text = "\n".join(f"line-{i}" for i in range(1, 11))
+    assert pio.tail_lines(text, 3) == "line-8\nline-9\nline-10"
+    assert pio.tail_lines(text, 100) == text  # more lines requested than exist
+    assert pio.tail_lines("", 5) == ""
+
+
+def test_tail_lines_handles_trailing_newline() -> None:
+    assert pio.tail_lines("a\nb\nc\n", 2) == "b\nc"
+
+
+def test_pio_version_runs(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Happy path: `pio --version` exits 0 and prints a version string.
+
+    This exercises subprocess spawn, timeout default, and the PioResult shape.
+    Skipped if pio isn't installed (CI would need pio preinstalled).
+    """
+    try:
+        result = pio.run(["--version"], timeout=30)
+    except pio.PioError:
+        pytest.skip("pio not available in this environment")
+    assert result.returncode == 0
+    assert "PlatformIO" in result.stdout or "platformio" in result.stdout.lower()
+    assert result.duration_s > 0
+
+
+def test_pio_bad_command_raises_pio_error() -> None:
+    """`pio` returning non-zero must surface as PioError with stderr captured."""
+    with pytest.raises(pio.PioError) as excinfo:
+        pio.run(["this-subcommand-does-not-exist"], timeout=10)
+    # PioError includes returncode + a tail of stderr/stdout.
+    assert excinfo.value.returncode != 0
+
+
+def test_pio_timeout_raises_pio_timeout(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Extremely short timeout on a command that takes longer must raise PioTimeout."""
+    # `pio` startup alone typically takes ~200-500ms; a 1ms timeout reliably trips.
+    with pytest.raises(pio.PioTimeout):
+        pio.run(["--help"], timeout=0.001)
+
+
+def test_run_json_parses_device_list() -> None:
+    """`pio device list --json-output` is a known-valid JSON producer."""
+    try:
+        data = pio.run_json(["device", "list"], timeout=15)
+    except pio.PioError:
+        pytest.skip("pio not available in this environment")
+    # Always a list; may be empty if nothing is plugged in.
+    assert isinstance(data, list)

mcp-server/tests/unit/test_testing_profile.py

@@ -0,0 +1,120 @@
+"""`userprefs.build_testing_profile` / `generate_psk` correctness.
+
+The testing-profile generator is the critical primitive for automated test
+labs: it must produce deterministic PSKs for a given seed (so every device
+baked in a CI run joins the same mesh) and different PSKs for different seeds
+(so concurrent labs don't collide).
+"""
+
+from __future__ import annotations
+
+import pytest
+from meshtastic_mcp import userprefs
+
+
+def test_generate_psk_is_32_bytes_formatted() -> None:
+    psk = userprefs.generate_psk(seed="deterministic")
+    # Format: "{ 0x.., 0x.., ... }" with 32 comma-separated hex bytes.
+    assert psk.startswith("{ ") and psk.endswith(" }")
+    bytes_part = psk.removeprefix("{ ").removesuffix(" }")
+    hex_bytes = [b.strip() for b in bytes_part.split(",")]
+    assert len(hex_bytes) == 32
+    for b in hex_bytes:
+        assert b.startswith("0x")
+        int(b, 16)  # raises if not valid hex
+
+
+def test_generate_psk_deterministic_under_same_seed() -> None:
+    a = userprefs.generate_psk(seed="pytest-session-123")
+    b = userprefs.generate_psk(seed="pytest-session-123")
+    assert a == b, "same seed must produce same PSK"
+
+
+def test_generate_psk_varies_with_seed() -> None:
+    seeds = ["a", "b", "pytest-1", "pytest-2", "prod-fleet-alpha"]
+    psks = {userprefs.generate_psk(seed=s) for s in seeds}
+    assert len(psks) == len(seeds), "seed → PSK map must be injective"
+
+
+def test_generate_psk_random_when_seedless() -> None:
+    a = userprefs.generate_psk(seed=None)
+    b = userprefs.generate_psk(seed=None)
+    # Not strictly guaranteed (birthday paradox), but 256-bit randomness makes
+    # a collision astronomically unlikely.
+    assert a != b
+
+
+def test_testing_profile_contains_expected_keys() -> None:
+    profile = userprefs.build_testing_profile(psk_seed="ci-run-1")
+
+    required = {
+        "USERPREFS_CONFIG_LORA_REGION",
+        "USERPREFS_LORACONFIG_MODEM_PRESET",
+        "USERPREFS_LORACONFIG_CHANNEL_NUM",
+        "USERPREFS_CHANNELS_TO_WRITE",
+        "USERPREFS_CHANNEL_0_NAME",
+        "USERPREFS_CHANNEL_0_PSK",
+        "USERPREFS_CHANNEL_0_PRECISION",
+        "USERPREFS_CONFIG_LORA_IGNORE_MQTT",
+        "USERPREFS_MQTT_ENABLED",
+        "USERPREFS_CHANNEL_0_UPLINK_ENABLED",
+        "USERPREFS_CHANNEL_0_DOWNLINK_ENABLED",
+    }
+    assert required <= set(profile.keys())
+
+    # Defaults from the plan
+    assert profile["USERPREFS_CONFIG_LORA_REGION"].endswith("_US")
+    assert profile["USERPREFS_LORACONFIG_MODEM_PRESET"].endswith("_LONG_FAST")
+    assert profile["USERPREFS_LORACONFIG_CHANNEL_NUM"] == 88
+    assert profile["USERPREFS_CHANNEL_0_NAME"] == "McpTest"
+
+
+def test_testing_profile_rejects_unknown_region() -> None:
+    with pytest.raises(ValueError, match="Unknown region"):
+        userprefs.build_testing_profile(region="ATLANTIS")
+
+
+def test_testing_profile_rejects_unknown_modem_preset() -> None:
+    with pytest.raises(ValueError, match="Unknown modem_preset"):
+        userprefs.build_testing_profile(modem_preset="WARP_9")
+
+
+def test_testing_profile_rejects_oversized_channel_name() -> None:
+    with pytest.raises(ValueError, match="11-char max"):
+        userprefs.build_testing_profile(channel_name="WayTooLongChannelName")
+
+
+def test_testing_profile_rejects_oversized_short_name() -> None:
+    with pytest.raises(ValueError, match="≤4 chars"):
+        userprefs.build_testing_profile(short_name="TOOLONG")
+
+
+def test_disable_mqtt_false_drops_mqtt_keys() -> None:
+    profile = userprefs.build_testing_profile(psk_seed="x", disable_mqtt=False)
+    # When disable_mqtt is False, the MQTT-gating keys should NOT be in the
+    # profile (device uses firmware defaults, whatever those are).
+    assert "USERPREFS_MQTT_ENABLED" not in profile
+    assert "USERPREFS_CHANNEL_0_UPLINK_ENABLED" not in profile
+
+
+def test_disable_position_adds_gps_disabled() -> None:
+    profile = userprefs.build_testing_profile(psk_seed="x", disable_position=True)
+    assert profile["USERPREFS_CONFIG_GPS_MODE"].endswith("_DISABLED")
+    assert profile["USERPREFS_CONFIG_SMART_POSITION_ENABLED"] is False
+
+
+def test_owner_names_included_when_provided() -> None:
+    profile = userprefs.build_testing_profile(
+        psk_seed="x", long_name="Lab Bench 1", short_name="LB1"
+    )
+    assert profile["USERPREFS_CONFIG_OWNER_LONG_NAME"] == "Lab Bench 1"
+    assert profile["USERPREFS_CONFIG_OWNER_SHORT_NAME"] == "LB1"
+
+
+def test_psk_seed_isolation_across_ci_runs() -> None:
+    """The core claim: two test labs running concurrently with different
+    session seeds produce different PSKs — their meshes cannot decode each
+    other's traffic."""
+    lab_a = userprefs.build_testing_profile(psk_seed="lab-A-nightly")
+    lab_b = userprefs.build_testing_profile(psk_seed="lab-B-nightly")
+    assert lab_a["USERPREFS_CHANNEL_0_PSK"] != lab_b["USERPREFS_CHANNEL_0_PSK"]

mcp-server/tests/unit/test_userprefs_parse.py

@@ -0,0 +1,116 @@
+"""Unit tests for `userprefs.py`: jsonc parse, type inference, round-trip
+write, and the `temporary_overrides` context manager's byte-for-byte restore.
+
+None of these require hardware. They validate the contract that the flash/
+testing-profile tools rely on — if these fail, the provisioning tier will
+produce confusing mismatches.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import pytest
+from meshtastic_mcp import userprefs
+
+
+@pytest.fixture
+def sample_jsonc(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Write a minimal userPrefs.jsonc into tmp_path and point config at it."""
+    content = """{
+  "USERPREFS_CONFIG_LORA_REGION": "meshtastic_Config_LoRaConfig_RegionCode_US",
+  "USERPREFS_LORACONFIG_CHANNEL_NUM": "88",
+  // "USERPREFS_CHANNEL_0_NAME": "McpTest",
+  "USERPREFS_CHANNEL_0_PSK": "{ 0x01, 0x02, 0x03 }",
+  // "USERPREFS_MQTT_ENABLED": "0",
+  "USERPREFS_CONFIG_LORA_IGNORE_MQTT": "true"
+}
+"""
+    # Fake firmware root with a userPrefs.jsonc + platformio.ini (needed for
+    # `config.firmware_root()`'s walk-up detection).
+    (tmp_path / "platformio.ini").write_text("[platformio]\n", encoding="utf-8")
+    jsonc = tmp_path / "userPrefs.jsonc"
+    jsonc.write_text(content, encoding="utf-8")
+    monkeypatch.setenv("MESHTASTIC_FIRMWARE_ROOT", str(tmp_path))
+    return jsonc
+
+
+def test_read_state_separates_active_and_commented(sample_jsonc: Path) -> None:
+    state = userprefs.read_state()
+    assert set(state["active"]) == {
+        "USERPREFS_CONFIG_LORA_REGION",
+        "USERPREFS_LORACONFIG_CHANNEL_NUM",
+        "USERPREFS_CHANNEL_0_PSK",
+        "USERPREFS_CONFIG_LORA_IGNORE_MQTT",
+    }
+    assert set(state["commented"]) == {
+        "USERPREFS_CHANNEL_0_NAME",
+        "USERPREFS_MQTT_ENABLED",
+    }
+
+
+def test_infer_type_matches_platformio_custom_py() -> None:
+    # Mirrors the branch order in `bin/platformio-custom.py:222-235`.
+    assert userprefs.infer_type("{ 0x01, 0x02 }") == "brace"
+    assert userprefs.infer_type("88") == "number"
+    assert userprefs.infer_type("-1.5") == "number"
+    assert userprefs.infer_type("true") == "bool"
+    assert userprefs.infer_type("false") == "bool"
+    assert userprefs.infer_type("meshtastic_Config_DeviceConfig_Role_ROUTER") == "enum"
+    assert userprefs.infer_type("plain string value") == "string"
+    assert userprefs.infer_type(None) == "unknown"
+
+
+def test_temporary_overrides_restores_byte_for_byte(sample_jsonc: Path) -> None:
+    """The context manager MUST leave the file bit-identical on exit, even on
+    exception — this is the safety guarantee build/flash tools rely on."""
+    original = sample_jsonc.read_bytes()
+
+    with userprefs.temporary_overrides({"USERPREFS_CHANNEL_0_NAME": "OverrideTest"}):
+        # During the context, the override is written.
+        during = userprefs.read_state()
+        assert "USERPREFS_CHANNEL_0_NAME" in during["active"]
+        assert during["active"]["USERPREFS_CHANNEL_0_NAME"] == "OverrideTest"
+
+    # After: byte-identical restore.
+    assert sample_jsonc.read_bytes() == original
+
+
+def test_temporary_overrides_restores_after_exception(sample_jsonc: Path) -> None:
+    original = sample_jsonc.read_bytes()
+
+    with pytest.raises(RuntimeError, match="simulated"):
+        with userprefs.temporary_overrides({"USERPREFS_CHANNEL_0_NAME": "Failing"}):
+            raise RuntimeError("simulated mid-build failure")
+
+    assert sample_jsonc.read_bytes() == original
+
+
+def test_temporary_overrides_none_is_noop(sample_jsonc: Path) -> None:
+    original = sample_jsonc.read_bytes()
+    with userprefs.temporary_overrides(None) as effective:
+        # No file write, and `effective` still reflects the active set.
+        assert "USERPREFS_CONFIG_LORA_REGION" in effective
+    assert sample_jsonc.read_bytes() == original
+
+
+def test_temporary_overrides_rejects_non_userprefs_keys(sample_jsonc: Path) -> None:
+    with pytest.raises(ValueError, match="USERPREFS_"):
+        with userprefs.temporary_overrides({"RANDOM_KEY": "value"}):
+            pass
+
+
+def test_build_manifest_surfaces_all_keys(sample_jsonc: Path) -> None:
+    """Manifest should union the jsonc set with firmware-src consumers.
+
+    In the sample tmpdir there's no `src/` so `consumed_by` is empty for all
+    entries; that's fine — the manifest still lists every jsonc key.
+    """
+    manifest = userprefs.build_manifest()
+    keys = {e["key"] for e in manifest["entries"]}
+    # All 6 keys from sample_jsonc should be present.
+    assert "USERPREFS_CONFIG_LORA_REGION" in keys
+    assert "USERPREFS_CHANNEL_0_NAME" in keys  # commented but still listed
+    assert manifest["active_count"] == 4
+    assert manifest["commented_count"] == 2