@h2loop/uav 1.0.0

package/bridge/uav_mavlink_bridge.py

@@ -0,0 +1,799 @@
+#!/usr/bin/env python3
+"""UAV Pack — Live-Link MCP Bridge (Tier R read-only + Tier C param read/write).
+
+A firmware-agnostic MCP server (stdio transport, FastMCP) that exposes
+ArduPilot / PX4 telemetry and parameters to an MCP client (Hydron's `uav`
+persona). It speaks MAVLink via ``pymavlink.mavutil``, so it serves every UAV
+lab — ArduPilot *and* PX4 — and works against a live link (udp/tcp/serial) or
+an offline log replay (a ``.bin`` DataFlash log or ``.tlog`` telemetry log).
+
+Spec: internal-docs/wiki/.../uav/10-live-link-mcp-bridge.md
+
+============================ READ-ONLY BY CONSTRUCTION ============================
+By default this server implements ONLY the Tier R (read-only) tool contract:
+
+    read_params, get_messages, tail_telemetry, get_flight_mode, get_status
+
+It registers NO flight command/control tools. There is no arm/disarm, no
+set_mode, no takeoff/land/goto, and no mission upload — EVER, in any mode. A tool
+that is not registered cannot be called *or* sit in the client's context — that
+is the strongest gate.
+
+============================ TIER C — PARAMETER READ/WRITE ============================
+A SECOND, GATED tier exposes PARAMETER read/write — and ONLY parameter
+read/write. This is the on-ramp to the *firmware track*: the param-upload +
+retest loop (e.g. pushing an ``INS_HNTCH_*`` notch-filter tune, then re-flying
+and comparing). It is deliberately NOT flight command-and-control:
+
+    param_get, param_get_all, param_set, param_set_batch
+
+These are registered ONLY when the server is started WITHOUT ``--read-only`` AND
+WITH the explicit ``--allow-param-write`` flag (default OFF, defense-in-depth).
+With the gate off, the write tools (param_set / param_set_batch) either are not
+registered at all, or return a clear "param write disabled" error — never a
+silent or accidental write. The persona must ALSO allow-list these tool names
+(``mavlink_param_set`` / ``mavlink_param_set_batch``) in its permission ruleset;
+the server gate and the persona allow-list are independent layers.
+
+Flight command/control (arm/takeoff/land/mission/goto/set_mode) remains
+INTENTIONALLY ABSENT regardless of any flag. Param write is the firmware-track
+on-ramp; it is not, and will not become, a live-C2 flight surface.
+
+Design note: the MCP tool functions are thin wrappers that delegate to a small
+``MavlinkSource`` class holding all read/write logic, so tests can drive
+``MavlinkSource(path).read_params()`` directly without starting the server.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from pymavlink import mavutil
+
+# Default per-tool recv budget so a tool can never hang the server forever.
+DEFAULT_TOOL_TIMEOUT = 8.0
+# How long to wait on any single recv_match() call (live links only).
+RECV_TIMEOUT = 1.0
+# Hard cap on messages pulled while replaying a file, so a huge log can't stall.
+FILE_SCAN_CAP = 2_000_000
+
+# DataFlash (.bin) log message types vs. live/MAVLink network message types.
+# The bridge supports both transparently.
+_PARAM_TYPES = ("PARM", "PARAM_VALUE")
+_GPS_TYPES = ("GPS", "GPS_RAW_INT")
+_BATTERY_TYPES = ("BAT", "BATTERY_STATUS", "SYS_STATUS")
+_ARM_TYPES = ("ARM",)
+
+
+def _msg_to_dict(msg: Any) -> Dict[str, Any]:
+    """Convert a pymavlink message to a plain dict, with a best-effort timestamp."""
+    d: Dict[str, Any]
+    try:
+        d = dict(msg.to_dict())
+    except Exception:
+        d = {"_type": msg.get_type()}
+    ts = getattr(msg, "_timestamp", None)
+    if ts is not None and "_timestamp" not in d:
+        d["_timestamp"] = ts
+    return d
+
+
+class MavlinkSource:
+    """Wraps a single ``mavutil`` connection and implements the Tier R reads.
+
+    Accepts any connection string ``mavutil.mavlink_connection`` understands:
+    ``udp:127.0.0.1:14550``, ``tcp:host:port``, ``/dev/ttyUSB0``, or a FILE PATH
+    (``.bin`` / ``.tlog``) for offline replay.
+
+    Not thread-safe: a single underlying connection is reused. The MCP server
+    creates one shared instance; concurrent tool calls are effectively
+    serialized by the recv loop. For the read-only analysis workload this is
+    fine and keeps the link single-owner.
+    """
+
+    def __init__(self, conn: str, dialect: Optional[str] = None):
+        self.conn = conn
+        self.dialect = dialect or os.environ.get("MAVLINK_DIALECT") or None
+        self.is_file = self._looks_like_file(conn)
+        kwargs: Dict[str, Any] = {}
+        if self.dialect:
+            kwargs["dialect"] = self.dialect
+        self.master = mavutil.mavlink_connection(conn, **kwargs)
+
+    @staticmethod
+    def _looks_like_file(conn: str) -> bool:
+        lowered = conn.lower()
+        for proto in ("udp:", "udpin:", "udpout:", "tcp:", "tcpin:", "com", "/dev/"):
+            if lowered.startswith(proto):
+                return False
+        return os.path.exists(conn)
+
+    def _recv(self, **kwargs):
+        """recv_match with sensible defaults for file vs live links."""
+        if self.is_file:
+            # Files replay synchronously; non-blocking returns None at EOF.
+            return self.master.recv_match(blocking=False, **kwargs)
+        kwargs.setdefault("timeout", RECV_TIMEOUT)
+        return self.master.recv_match(blocking=True, **kwargs)
+
+    # ------------------------------------------------------------------ Tier R
+
+    def read_params(self, timeout: float = 30.0) -> Dict[str, float]:
+        """Return the current parameter set as a ``name -> value`` map.
+
+        File source: scan PARM / PARAM_VALUE messages (last value wins).
+        Live source: request a full param fetch and collect PARAM_VALUE until the
+        expected count arrives or the timeout elapses.
+        """
+        params: Dict[str, float] = {}
+
+        if self.is_file:
+            count = 0
+            while count < FILE_SCAN_CAP:
+                msg = self.master.recv_match(type=list(_PARAM_TYPES), blocking=False)
+                if msg is None:
+                    break
+                count += 1
+                name, value = self._param_kv(msg)
+                if name is not None:
+                    params[name] = value
+            return params
+
+        # Live link: ask the vehicle to stream every parameter.
+        try:
+            self.master.wait_heartbeat(timeout=RECV_TIMEOUT)
+        except Exception:
+            pass
+        self.master.mav.param_request_list_send(
+            self.master.target_system, self.master.target_component
+        )
+        deadline = time.time() + timeout
+        expected: Optional[int] = None
+        while time.time() < deadline:
+            msg = self.master.recv_match(type="PARAM_VALUE", blocking=True, timeout=RECV_TIMEOUT)
+            if msg is None:
+                if expected is not None and len(params) >= expected:
+                    break
+                continue
+            name, value = self._param_kv(msg)
+            if name is not None:
+                params[name] = value
+            expected = getattr(msg, "param_count", expected) or expected
+            if expected and len(params) >= expected:
+                break
+        return params
+
+    @staticmethod
+    def _param_kv(msg: Any):
+        t = msg.get_type()
+        if t == "PARM":  # DataFlash
+            return getattr(msg, "Name", None), float(getattr(msg, "Value", 0.0))
+        if t == "PARAM_VALUE":  # live MAVLink
+            name = getattr(msg, "param_id", None)
+            if isinstance(name, bytes):
+                name = name.decode("utf-8", "replace")
+            if name is not None:
+                name = name.rstrip("\x00")
+            return name, float(getattr(msg, "param_value", 0.0))
+        return None, None
+
+    # ------------------------------------------------- Tier C: param read/write
+
+    def param_get_all(self, timeout: float = 30.0) -> Dict[str, float]:
+        """Explicit live form of the full param fetch (PARAM_REQUEST_LIST).
+
+        Returns a ``name -> value`` map. This shares the exact read path as
+        ``read_params`` (file scan or live PARAM_REQUEST_LIST), so it works for
+        offline replay too — it is the read half of the param read/write tier.
+        """
+        return self.read_params(timeout=timeout)
+
+    def param_get(self, name: str, timeout: float = 10.0) -> Dict[str, Any]:
+        """Read a single parameter by name via PARAM_REQUEST_READ (live).
+
+        Returns ``{"name", "value", "found"}``. On a file source there is no
+        live request channel, so we scan the log for the last value seen.
+        """
+        name = (name or "").strip()
+        if not name:
+            return {"name": name, "value": None, "found": False, "reason": "empty name"}
+
+        if self.is_file:
+            # No live request on a log; fall back to the full scan and look up.
+            params = self.read_params(timeout=timeout)
+            if name in params:
+                return {"name": name, "value": params[name], "found": True}
+            return {"name": name, "value": None, "found": False}
+
+        try:
+            self.master.wait_heartbeat(timeout=RECV_TIMEOUT)
+        except Exception:
+            pass
+        # param_index = -1 means "look up by name".
+        self.master.mav.param_request_read_send(
+            self.master.target_system,
+            self.master.target_component,
+            name.encode("utf-8"),
+            -1,
+        )
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            msg = self.master.recv_match(type="PARAM_VALUE", blocking=True, timeout=RECV_TIMEOUT)
+            if msg is None:
+                continue
+            n, v = self._param_kv(msg)
+            if n == name:
+                return {"name": name, "value": v, "found": True}
+        return {"name": name, "value": None, "found": False, "reason": "timeout"}
+
+    def _can_write(self) -> Optional[str]:
+        """Return a reason string if a write is NOT possible, else None.
+
+        A file/log replay is not a live vehicle; there is no writable target, so
+        param_set must be a structured no-op rather than a crash.
+        """
+        if self.is_file:
+            return "source is an offline log replay; no live vehicle to write to"
+        return None
+
+    def param_set(self, name: str, value: float, timeout: float = 10.0) -> Dict[str, Any]:
+        """Set a single parameter, then read back to confirm via PARAM_VALUE echo.
+
+        Returns ``{name, requested, confirmed, ok, ts}`` (plus ``reason`` on
+        failure). Confirmation tolerates float rounding from the autopilot's
+        param storage. This is param write ONLY — never a flight command.
+        """
+        name = (name or "").strip()
+        ts = time.time()
+        if not name:
+            return {"name": name, "requested": value, "confirmed": None,
+                    "ok": False, "ts": ts, "reason": "empty name"}
+
+        blocked = self._can_write()
+        if blocked is not None:
+            return {"name": name, "requested": value, "confirmed": None,
+                    "ok": False, "ts": ts, "reason": blocked}
+
+        try:
+            req = float(value)
+        except (TypeError, ValueError):
+            return {"name": name, "requested": value, "confirmed": None,
+                    "ok": False, "ts": ts, "reason": "value is not numeric"}
+
+        try:
+            self.master.wait_heartbeat(timeout=RECV_TIMEOUT)
+        except Exception:
+            pass
+
+        # mavutil.param_set_send packs PARAM_SET (handles name encoding + type).
+        self.master.param_set_send(name, req)
+
+        # Read back the PARAM_VALUE echo to confirm the write took.
+        confirmed: Optional[float] = None
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            msg = self.master.recv_match(type="PARAM_VALUE", blocking=True, timeout=RECV_TIMEOUT)
+            if msg is None:
+                continue
+            n, v = self._param_kv(msg)
+            if n == name:
+                confirmed = v
+                break
+
+        ok = confirmed is not None and self._close_enough(req, confirmed)
+        result: Dict[str, Any] = {
+            "name": name,
+            "requested": req,
+            "confirmed": confirmed,
+            "ok": ok,
+            "ts": ts,
+        }
+        if not ok:
+            result["reason"] = "no PARAM_VALUE echo" if confirmed is None else "echo mismatch"
+        return result
+
+    @staticmethod
+    def _close_enough(a: float, b: float) -> bool:
+        """Confirm a param echo, tolerating float storage rounding."""
+        try:
+            return abs(float(a) - float(b)) <= max(1e-4, abs(float(a)) * 1e-4)
+        except (TypeError, ValueError):
+            return False
+
+    def param_set_batch(self, params: Dict[str, float], timeout: float = 10.0) -> Dict[str, Any]:
+        """Set several parameters, confirming each (e.g. the INS_HNTCH_* notch push).
+
+        Returns a structured result carrying enough for the caller (the
+        uav-tuning subagent) to TAG A RETEST: the per-param outcomes, the set of
+        confirmed name->value pairs, and start/end timestamps. Hydron attaches
+        these to the next flight's tags. This writes files NOWHERE — it only
+        returns structured data.
+        """
+        started = time.time()
+        if not isinstance(params, dict) or not params:
+            return {"ok": False, "count": 0, "results": [], "set_params": {},
+                    "started_ts": started, "finished_ts": time.time(),
+                    "reason": "params must be a non-empty {name: value} dict"}
+
+        blocked = self._can_write()
+        if blocked is not None:
+            # Single clear blocked result rather than per-param noise.
+            return {"ok": False, "count": len(params), "results": [], "set_params": {},
+                    "started_ts": started, "finished_ts": time.time(), "reason": blocked}
+
+        results: List[Dict[str, Any]] = []
+        set_params: Dict[str, float] = {}
+        for name, value in params.items():
+            r = self.param_set(name, value, timeout=timeout)
+            results.append(r)
+            if r.get("ok"):
+                set_params[r["name"]] = r["confirmed"]
+
+        all_ok = bool(results) and all(r.get("ok") for r in results)
+        return {
+            "ok": all_ok,
+            "count": len(results),
+            "ok_count": sum(1 for r in results if r.get("ok")),
+            "results": results,
+            "set_params": set_params,   # confirmed name->value, for retest tagging
+            "started_ts": started,
+            "finished_ts": time.time(),
+        }
+
+    def get_messages(
+        self,
+        types: Union[str, List[str]],
+        limit: int = 100,
+    ) -> List[Dict[str, Any]]:
+        """Return up to ``limit`` recent messages of the given type(s) as dicts."""
+        if isinstance(types, str):
+            type_list = [types]
+        else:
+            type_list = list(types)
+        type_list = [t.strip() for t in type_list if t and t.strip()]
+        if not type_list:
+            return []
+        if limit <= 0:
+            return []
+
+        out: List[Dict[str, Any]] = []
+
+        if self.is_file:
+            # Keep only the most recent `limit` per requested type so we return
+            # *recent* messages regardless of where they sit in the log.
+            from collections import deque
+
+            buffers = {t: deque(maxlen=limit) for t in type_list}
+            count = 0
+            while count < FILE_SCAN_CAP:
+                msg = self.master.recv_match(type=type_list, blocking=False)
+                if msg is None:
+                    break
+                count += 1
+                buffers[msg.get_type()].append(_msg_to_dict(msg))
+            for t in type_list:
+                out.extend(buffers[t])
+            return out
+
+        # Live link: collect until we have `limit` total or run out of budget.
+        deadline = time.time() + DEFAULT_TOOL_TIMEOUT
+        while len(out) < limit and time.time() < deadline:
+            msg = self._recv(type=type_list)
+            if msg is None:
+                continue
+            out.append(_msg_to_dict(msg))
+        return out
+
+    def tail_telemetry(self, seconds: float = 5.0) -> Dict[str, Any]:
+        """Poll telemetry for ~N seconds; return accumulated recent values.
+
+        Returns a dict with the latest value seen per message type plus a count
+        and a flat sample list. For a file, we replay up to N seconds of log time
+        (or a message cap) rather than wall-clock waiting.
+        """
+        seconds = max(0.0, float(seconds))
+        latest: Dict[str, Dict[str, Any]] = {}
+        samples: List[Dict[str, Any]] = []
+        total = 0
+
+        if self.is_file:
+            cap = int(min(FILE_SCAN_CAP, max(1000, seconds * 4000)))
+            start_ts: Optional[float] = None
+            while total < cap:
+                msg = self.master.recv_match(blocking=False)
+                if msg is None:
+                    break
+                d = _msg_to_dict(msg)
+                ts = d.get("_timestamp")
+                if ts is not None:
+                    if start_ts is None:
+                        start_ts = ts
+                    elif seconds > 0 and (ts - start_ts) > seconds:
+                        break
+                t = msg.get_type()
+                latest[t] = d
+                samples.append(d)
+                total += 1
+        else:
+            deadline = time.time() + seconds
+            while time.time() < deadline:
+                msg = self._recv()
+                if msg is None:
+                    continue
+                d = _msg_to_dict(msg)
+                t = msg.get_type()
+                latest[t] = d
+                samples.append(d)
+                total += 1
+
+        return {
+            "seconds": seconds,
+            "count": total,
+            "types": sorted(latest.keys()),
+            "latest": latest,
+            "samples": samples[-200:],  # cap payload size
+        }
+
+    def get_flight_mode(self) -> Dict[str, Any]:
+        """Return the current / last-seen flight mode."""
+        # Replay/advance the connection so mavutil's internal mode tracking
+        # (`self.master.flightmode`) is populated. For a file this consumes it,
+        # so we read MODE/HEARTBEAT directly too.
+        mode_str: Optional[str] = None
+        mode_num: Optional[int] = None
+
+        if self.is_file:
+            count = 0
+            last = None
+            while count < FILE_SCAN_CAP:
+                msg = self.master.recv_match(type=["MODE", "HEARTBEAT"], blocking=False)
+                if msg is None:
+                    break
+                count += 1
+                last = msg
+            if last is not None:
+                mode_num = getattr(last, "ModeNum", getattr(last, "Mode", None))
+            mode_str = getattr(self.master, "flightmode", None)
+        else:
+            try:
+                self.master.wait_heartbeat(timeout=RECV_TIMEOUT)
+            except Exception:
+                pass
+            msg = self._recv(type="HEARTBEAT")
+            mode_str = getattr(self.master, "flightmode", None)
+            if msg is not None:
+                mode_num = getattr(msg, "custom_mode", None)
+
+        return {
+            "mode": mode_str or "UNKNOWN",
+            "mode_num": mode_num,
+        }
+
+    def get_status(self) -> Dict[str, Any]:
+        """Best-effort armed state, GPS fix, battery, and link health.
+
+        Pulls from HEARTBEAT/SYS_STATUS/GPS_RAW_INT on a live link, or the
+        DataFlash equivalents (ARM/GPS/BAT/MODE) on a file replay.
+        """
+        armed: Optional[bool] = None
+        gps: Optional[Dict[str, Any]] = None
+        battery: Optional[Dict[str, Any]] = None
+        link: Dict[str, Any] = {"healthy": None, "messages_seen": 0}
+
+        wanted = list(
+            set(("HEARTBEAT", "MODE") + _GPS_TYPES + _BATTERY_TYPES + _ARM_TYPES)
+        )
+
+        if self.is_file:
+            count = 0
+            while count < FILE_SCAN_CAP:
+                msg = self.master.recv_match(type=wanted, blocking=False)
+                if msg is None:
+                    break
+                count += 1
+                self._fold_status(msg, locals_ref=None)
+                t = msg.get_type()
+                if t == "ARM":
+                    armed = bool(getattr(msg, "ArmState", 0))
+                elif t == "HEARTBEAT":
+                    base = getattr(msg, "base_mode", 0)
+                    armed = bool(base & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED)
+                elif t in _GPS_TYPES:
+                    gps = self._gps_dict(msg)
+                elif t in _BATTERY_TYPES:
+                    battery = self._battery_dict(msg) or battery
+                link["messages_seen"] += 1
+            link["healthy"] = link["messages_seen"] > 0
+        else:
+            deadline = time.time() + DEFAULT_TOOL_TIMEOUT
+            seen = 0
+            while time.time() < deadline and (armed is None or gps is None or battery is None):
+                msg = self._recv(type=wanted)
+                if msg is None:
+                    continue
+                seen += 1
+                t = msg.get_type()
+                if t == "HEARTBEAT":
+                    base = getattr(msg, "base_mode", 0)
+                    armed = bool(base & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED)
+                elif t in _GPS_TYPES:
+                    gps = self._gps_dict(msg)
+                elif t in _BATTERY_TYPES:
+                    b = self._battery_dict(msg)
+                    if b:
+                        battery = b
+            link["messages_seen"] = seen
+            link["healthy"] = seen > 0
+
+        return {
+            "armed": armed,
+            "gps": gps,
+            "battery": battery,
+            "link": link,
+        }
+
+    def _fold_status(self, msg, locals_ref=None):  # placeholder kept for clarity
+        return None
+
+    @staticmethod
+    def _gps_dict(msg) -> Dict[str, Any]:
+        t = msg.get_type()
+        if t == "GPS":  # DataFlash
+            return {
+                "fix_type": getattr(msg, "Status", None),
+                "satellites": getattr(msg, "NSats", None),
+                "hdop": getattr(msg, "HDop", None),
+                "lat": getattr(msg, "Lat", None),
+                "lon": getattr(msg, "Lng", None),
+                "alt": getattr(msg, "Alt", None),
+            }
+        # GPS_RAW_INT (live, scaled ints)
+        lat = getattr(msg, "lat", None)
+        lon = getattr(msg, "lon", None)
+        return {
+            "fix_type": getattr(msg, "fix_type", None),
+            "satellites": getattr(msg, "satellites_visible", None),
+            "hdop": (getattr(msg, "eph", None) or 0) / 100.0 if getattr(msg, "eph", None) else None,
+            "lat": lat / 1e7 if lat is not None else None,
+            "lon": lon / 1e7 if lon is not None else None,
+            "alt": (getattr(msg, "alt", None) or 0) / 1000.0 if getattr(msg, "alt", None) is not None else None,
+        }
+
+    @staticmethod
+    def _battery_dict(msg) -> Optional[Dict[str, Any]]:
+        t = msg.get_type()
+        if t == "BAT":  # DataFlash
+            return {
+                "voltage": getattr(msg, "Volt", None),
+                "current": getattr(msg, "Curr", None),
+                "remaining_pct": getattr(msg, "RemPct", None),
+                "consumed_mah": getattr(msg, "CurrTot", None),
+            }
+        if t == "SYS_STATUS":  # live
+            v = getattr(msg, "voltage_battery", None)
+            c = getattr(msg, "current_battery", None)
+            return {
+                "voltage": v / 1000.0 if v not in (None, 0xFFFF) else None,
+                "current": c / 100.0 if c not in (None, -1) else None,
+                "remaining_pct": getattr(msg, "battery_remaining", None),
+                "consumed_mah": None,
+            }
+        if t == "BATTERY_STATUS":  # live
+            volts = getattr(msg, "voltages", None)
+            v = None
+            if volts:
+                first = volts[0]
+                v = first / 1000.0 if first not in (None, 0xFFFF) else None
+            return {
+                "voltage": v,
+                "current": (getattr(msg, "current_battery", None) or 0) / 100.0,
+                "remaining_pct": getattr(msg, "battery_remaining", None),
+                "consumed_mah": getattr(msg, "current_consumed", None),
+            }
+        return None
+
+    def close(self) -> None:
+        try:
+            self.master.close()
+        except Exception:
+            pass
+
+
+# --------------------------------------------------------------------------- #
+# MCP server. The tools are thin wrappers around a shared MavlinkSource and    #
+# each catches everything, returning a structured error dict instead of        #
+# crashing the stdio server.                                                   #
+# --------------------------------------------------------------------------- #
+
+def _err(tool: str, exc: Exception) -> Dict[str, Any]:
+    return {"error": True, "tool": tool, "type": type(exc).__name__, "message": str(exc)}
+
+
+def build_server(
+    conn: str,
+    dialect: Optional[str] = None,
+    read_only: bool = True,
+    allow_param_write: bool = False,
+):
+    """Construct the FastMCP server bound to one source.
+
+    Always registers the Tier R reads and the Tier C param *reads*
+    (``param_get`` / ``param_get_all``). The Tier C param *writes*
+    (``param_set`` / ``param_set_batch``) are registered ONLY when the gate is
+    open: ``read_only`` is False AND ``allow_param_write`` is True. When the gate
+    is closed, the write tools are NOT registered (the strongest hide) — calling
+    them is impossible, not merely refused.
+
+    No flight command/control tool is ever registered, in any mode.
+    """
+    from mcp.server.fastmcp import FastMCP
+
+    mcp = FastMCP("mavlink")
+    source = MavlinkSource(conn, dialect=dialect)
+    param_write_enabled = (not read_only) and bool(allow_param_write)
+
+    @mcp.tool()
+    def read_params() -> Dict[str, Any]:
+        """Dump current vehicle parameters as a {name: value} map (read-only)."""
+        try:
+            params = source.read_params()
+            return {"count": len(params), "params": params}
+        except Exception as exc:  # noqa: BLE001
+            return _err("read_params", exc)
+
+    @mcp.tool()
+    def get_messages(types: Union[str, List[str]], limit: int = 100) -> Dict[str, Any]:
+        """Return recent MAVLink messages of the given type(s) as a list of dicts."""
+        try:
+            msgs = source.get_messages(types, limit=limit)
+            return {"count": len(msgs), "messages": msgs}
+        except Exception as exc:  # noqa: BLE001
+            return _err("get_messages", exc)
+
+    @mcp.tool()
+    def tail_telemetry(seconds: float = 5.0) -> Dict[str, Any]:
+        """Poll telemetry for N seconds and return accumulated recent values."""
+        try:
+            return source.tail_telemetry(seconds=seconds)
+        except Exception as exc:  # noqa: BLE001
+            return _err("tail_telemetry", exc)
+
+    @mcp.tool()
+    def get_flight_mode() -> Dict[str, Any]:
+        """Return the current / last-seen flight mode."""
+        try:
+            return source.get_flight_mode()
+        except Exception as exc:  # noqa: BLE001
+            return _err("get_flight_mode", exc)
+
+    @mcp.tool()
+    def get_status() -> Dict[str, Any]:
+        """Return armed state, GPS fix, battery, and link health (best-effort)."""
+        try:
+            return source.get_status()
+        except Exception as exc:  # noqa: BLE001
+            return _err("get_status", exc)
+
+    # ------------------------------------------------ Tier C: param read/write
+    # Param READS are always available (read-only, no vehicle side effects).
+    @mcp.tool()
+    def param_get(name: str) -> Dict[str, Any]:
+        """Read one parameter by name via PARAM_REQUEST_READ (read-only)."""
+        try:
+            return source.param_get(name)
+        except Exception as exc:  # noqa: BLE001
+            return _err("param_get", exc)
+
+    @mcp.tool()
+    def param_get_all() -> Dict[str, Any]:
+        """Explicit live full-param dump via PARAM_REQUEST_LIST (read-only)."""
+        try:
+            params = source.param_get_all()
+            return {"count": len(params), "params": params}
+        except Exception as exc:  # noqa: BLE001
+            return _err("param_get_all", exc)
+
+    # Param WRITES are GATED: registered only with the gate open.
+    # The persona MUST also allow-list `mavlink_param_set` / `mavlink_param_set_batch`.
+    if param_write_enabled:
+        @mcp.tool()
+        def param_set(name: str, value: float) -> Dict[str, Any]:
+            """Set one parameter and confirm via PARAM_VALUE echo (Tier C write).
+
+            On-ramp to the firmware track (param-upload + retest). NOT a flight
+            command. Returns {name, requested, confirmed, ok, ts}.
+            """
+            try:
+                return source.param_set(name, value)
+            except Exception as exc:  # noqa: BLE001
+                return _err("param_set", exc)
+
+        @mcp.tool()
+        def param_set_batch(params: Dict[str, float]) -> Dict[str, Any]:
+            """Set several params, confirm each (e.g. the INS_HNTCH_* notch tune).
+
+            Returns per-param results plus confirmed `set_params` and
+            start/finish timestamps so the uav-tuning subagent can tag the next
+            flight as a retest. NOT a flight command. Writes no files.
+            """
+            try:
+                return source.param_set_batch(params)
+            except Exception as exc:  # noqa: BLE001
+                return _err("param_set_batch", exc)
+    else:
+        # Gate closed: register stubs that explain how to enable, so a caller
+        # gets a clear, structured error instead of an unknown-tool failure.
+        _DISABLED = (
+            "param write disabled (start the bridge WITHOUT --read-only AND "
+            "WITH --allow-param-write, and allow-list the tool in the persona)"
+        )
+
+        @mcp.tool()
+        def param_set(name: str, value: float) -> Dict[str, Any]:
+            """Disabled: param write is gated off (Tier C). See message."""
+            return {"name": name, "requested": value, "confirmed": None,
+                    "ok": False, "ts": time.time(), "error": True,
+                    "tool": "param_set", "reason": _DISABLED, "message": _DISABLED}
+
+        @mcp.tool()
+        def param_set_batch(params: Dict[str, float]) -> Dict[str, Any]:
+            """Disabled: param write is gated off (Tier C). See message."""
+            return {"ok": False, "count": 0, "results": [], "set_params": {},
+                    "started_ts": time.time(), "finished_ts": time.time(),
+                    "error": True, "tool": "param_set_batch",
+                    "reason": _DISABLED, "message": _DISABLED}
+
+    # NOTE: No FLIGHT command/control tools (arm/takeoff/land/mission/set_mode)
+    # are registered here, by design — in ANY mode. Tier C is param read/write
+    # only; it is the firmware-track on-ramp, not a live-C2 flight surface.
+    return mcp
+
+
+def _parse_args(argv=None):
+    p = argparse.ArgumentParser(
+        description="MAVLink -> MCP bridge (Tier R reads + gated Tier C param read/write)"
+    )
+    p.add_argument(
+        "--connect",
+        default=os.environ.get("MAVLINK_CONNECT", "udp:127.0.0.1:14550"),
+        help="connection string: udp:host:port | tcp:host:port | /dev/ttyUSB0 | FILE.bin/.tlog",
+    )
+    p.add_argument("--dialect", default=os.environ.get("MAVLINK_DIALECT"))
+    # Read-only mode: the default. Tier R reads + Tier C param reads only; the
+    # Tier C param WRITE tools are not registered. Use --no-read-only (or simply
+    # omit and pass --allow-param-write) to open the write tier.
+    p.add_argument(
+        "--read-only",
+        dest="read_only",
+        action="store_true",
+        default=True,
+        help="read-only: no param-write tools registered (DEFAULT)",
+    )
+    p.add_argument(
+        "--no-read-only",
+        dest="read_only",
+        action="store_false",
+        help="drop read-only; REQUIRED (with --allow-param-write) to enable param writes",
+    )
+    p.add_argument(
+        "--allow-param-write",
+        dest="allow_param_write",
+        action="store_true",
+        default=False,
+        help="enable Tier C param WRITE tools (only takes effect WITH --no-read-only; default OFF)",
+    )
+    return p.parse_args(argv)
+
+
+if __name__ == "__main__":
+    args = _parse_args()
+    server = build_server(
+        args.connect,
+        dialect=args.dialect,
+        read_only=args.read_only,
+        allow_param_write=args.allow_param_write,
+    )
+    server.run()  # stdio transport