@h2loop/uav 1.1.0 → 1.2.1

package/README.md

@@ -59,7 +59,9 @@ skills/uav/             # on-demand `uav` skill + references
 data/                   # bundled apm-params.json + built-in defaults
 bridge/                 # optional MAVLink→MCP Python bridge
 plugins/                # BUILT bundle (index.js + worker/) — generated
-mcp.json                # exa + mavlink MCP servers (disabled by default)
+mcp.json                # exa MCP server (disabled by default); mavlink is registered
+                        #   from src/index.ts's config hook — it needs a resolved
+                        #   interpreter + an ABSOLUTE script path, which static JSON can't give
 ```
 
 ## Run standalone
@@ -235,30 +237,29 @@ project KG.
 
 A local Python stdio server. Read-only tools: `read_params`, `param_get`, `param_get_all`,
 `get_messages`, `tail_telemetry`, `get_flight_mode`, `get_status`. The write tier
-(`param_set` / `param_set_batch`) is **off by default** — see below.
+(`param_set` / `param_set_batch`) is **on by default** so tune→push→retest works out of the
+box — see below.
 
 **Requires:**
-- Python ≥ 3.10 with `pymavlink>=2.4.49` and `mcp[cli]>=1.0.0` installed. The pack does **not**
+- Python ≥ 3.10 with `pymavlink>=2.4.49` and `mcp[cli]>=1.0.0,<2` installed. The pack does **not**
   auto-provision a venv — install the deps yourself: `pip install -r bridge/requirements.txt`
   (ideally into a venv), and point the command's `python3` at that interpreter.
 - A reachable MAVLink endpoint (e.g. `udp:127.0.0.1:14550` from SITL or a telemetry radio),
   or a `.tlog`/`.log` file for offline replay.
 - The `bridge/` directory ships with the plugin (the `mcp.json` references it).
 
-Enable per-project in your Hydron config. **Param writes are OFF by default** (the bridge
-defaults to `--read-only`). To enable the tune→push→retest write tier, the command must pass
-**both** `--no-read-only` **and** `--allow-param-write`. ⚠ this lets the agent write params to
-a **live vehicle** — prefer SITL/bench.
-```jsonc
-"mcp": {
-  "mavlink": {
-    "enabled": true,
-    "command": ["python3", "<plugin-path>/bridge/uav_mavlink_bridge.py",
-                "--connect", "udp:127.0.0.1:14550",
-                "--no-read-only", "--allow-param-write"]
-  }
-}
+Ships **enabled**, with param writes **on** — the command passes `--no-read-only`
+`--allow-param-write`, so `param_set` / `param_set_batch` are registered and the tuning loop
+works with no configuration. ⚠ this lets the agent write params to a **live vehicle** — prefer
+SITL/bench. To ship read-only, drop both flags.
+
+No `--connect` is passed, so the target comes from the **`MAVLINK_CONNECT`** env var, falling
+back to `udp:127.0.0.1:14550`:
+```bash
+export MAVLINK_CONNECT=serial:/dev/ttyUSB0:57600      # COM3:57600 on Windows
 ```
+Don't put it in the server's `environment` block — Hydron spreads that *over* `process.env`, so
+it would shadow your export instead of defaulting to it.
 
 Connect-target forms: `udp:HOST:PORT` (default `udp:127.0.0.1:14550` = SITL/MAVProxy) |
 `tcp:HOST:PORT` | `serial:/dev/ttyUSB0:BAUD` | `/path/log.tlog` (offline replay); can also be

package/USAGE.md

@@ -12,11 +12,12 @@ covers getting it running on **macOS, Linux, and Windows**, validating it works,
 - **Bun** — *only* needed to build the bundle from source or run the pack's tests; **not**
   needed to use a published pack.
 - **Python ≥ 3.10** — *only* for the optional live MAVLink bridge (`pymavlink>=2.4.49` +
-  `mcp[cli]>=1.0.0`). The pack does **not** auto-provision a venv; you install the deps
+  `mcp[cli]>=1.0.0,<2`). The pack does **not** auto-provision a venv; you install the deps
   yourself (see §6). Plain `.bin` log analysis needs no Python.
 - *Optional:* `export EXA_API_KEY=…` for web grounding of bounds.
-- macOS/Linux are native; on **Windows** use **WSL2** for the bridge's Python (the bridge is
-  POSIX-oriented).
+- **macOS, Linux, and Windows are all native** — no WSL required. The pack resolves the Python
+  interpreter per-platform (`python3` / `python` / the `py -3` launcher); override it with
+  `UAV_PYTHON=<full path to python>` if you keep one in a venv.
 
 ---
 
@@ -41,14 +42,27 @@ hydron plugin add /path/to/uav-pack            #   add --project to scope it to
 Native. Nothing extra needed to use a published pack. Python ≥ 3.10 is only required for the
 optional MAVLink bridge (§6).
 
-### Windows — use WSL2 for the bridge
-The `hydron plugin add` command itself is cross-platform. The MAVLink bridge, however, is
-POSIX-oriented Python, so run it (and ideally Hydron) inside **WSL2** (Ubuntu):
+### Windows
+Native — run the same `hydron plugin add` in PowerShell. `.bin` log analysis, the checks, param
+audit, tuning, plots and compare need no Python at all.
+
+The Python-backed features (`uav_python`, `.tlog`/`.ulog` decode, the MAVLink bridge) need a
+real Python ≥ 3.10 — install it from **python.org** and tick **“Add python.exe to PATH”**. The
+pack finds it via the `py -3` launcher or `python`; there is no `python3` on Windows.
+
+> Windows pre-installs *stub* `python.exe` / `python3.exe` aliases that only open the Microsoft
+> Store. The pack ignores them (it probes by running code, not by looking on PATH), but if
+> `python --version` opens the Store rather than printing a version, turn the stubs off under
+> **Settings → Apps → Advanced app settings → App execution aliases**.
+
+Pinning a specific interpreter (e.g. a venv) works everywhere:
 ```powershell
-wsl --install -d Ubuntu        # PowerShell (admin), one-time; then open the Ubuntu shell
+$env:UAV_PYTHON = "C:\path\to\.venv\Scripts\python.exe"
 ```
-Use the **VS Code "WSL" remote** (or Hydron's CLI inside WSL) so Hydron and the bridge share
-the same environment.
+
+WSL2 also works and stays fully supported — but if you use it, install the pack **and** run
+Hydron inside WSL (VS Code's **WSL** remote). A Windows-side Hydron cannot see a WSL-side
+install; that mismatch is the usual cause of "the UAV tools didn't appear".
 
 ### Uninstall (any OS)
 ```bash
@@ -113,57 +127,84 @@ See `skills/uav/references/project-config.md` for the full list (`uav-thresholds
 A **MAVLink→MCP bridge**: a local Python stdio server Hydron spawns so the agent can query a
 live vehicle / SITL / log replay. Read-only tools: `get_status`, `get_flight_mode`,
 `read_params`, `param_get`, `param_get_all`, `get_messages`, `tail_telemetry`. The **write**
-tools `param_set`/`param_set_batch` are **off by default** (see the ⚠ note below).
+tools `param_set`/`param_set_batch` are **on by default**, so tune→push→retest works out of
+the box (see the ⚠ note below to turn them off).
 
-### Install the Python deps yourself
+### Install the Python deps (the only manual step)
 The pack does **not** auto-provision a venv. The bridge needs Python ≥ 3.10 with
-`pymavlink>=2.4.49` and `mcp[cli]>=1.0.0`:
+`pymavlink>=2.4.49` and `mcp[cli]>=1.0.0,<2`:
 ```bash
 pip install -r bridge/requirements.txt     # ideally into a venv
 ```
-Then point the `mavlink` command's `python3` at that interpreter.
-
-### Enable and configure (per-project in opencode.jsonc)
-The `mavlink` server ships in `mcp.json` **disabled by default**. Enable it per-project:
-```jsonc
-"mcp": {
-  "mavlink": {
-    "enabled": true,
-    "command": ["python3", "<plugin-path>/bridge/uav_mavlink_bridge.py",
-                "--connect", "udp:127.0.0.1:14550"]
-  }
-}
+> The `<2` bound is required, not cosmetic: the MCP Python SDK **removed `mcp.server.fastmcp`
+> in 2.x**, so the bridge fails at import on `mcp>=2`. Verified working on 1.29.0.
+
+You do **not** need to edit any command. The plugin registers the `mavlink` server itself at
+startup, resolving:
+
+- **the interpreter** — via the same probe-by-execution resolver the `.tlog`/`.ulog` decoders
+  use, so `python3` / `python` / the Windows `py -3` launcher are all handled and Windows'
+  Microsoft-Store alias stubs are rejected. Pin a specific one with `UAV_PYTHON` (e.g. a venv:
+  `export UAV_PYTHON=/path/.venv/bin/python`, or `…\Scripts\python.exe` on Windows).
+- **the script path** — absolute, inside the installed plugin bundle. This matters: Hydron
+  spawns local MCP servers with the cwd set to *your project*, so a bundle-relative path can
+  never resolve. That is why the server is no longer declared in `mcp.json`.
+
+If no usable Python is found the server is not registered at all; if Python is found but can't
+`import mcp, pymavlink`, it is registered **disabled** — so you see it listed rather than
+getting a failed server on every launch. Check with `hydron mcp list`.
+
+### Point it at your vehicle
+The `mavlink` server is registered **enabled**, with param writes on, so nothing needs enabling.
+The one thing you may need to change is the connect target.
+
+The command passes **no** `--connect`, so the bridge falls back to its own default —
+which reads the **`MAVLINK_CONNECT`** environment variable, then `udp:127.0.0.1:14550`. So for
+anything other than local SITL/MAVProxy, just export the target:
+```bash
+export MAVLINK_CONNECT=serial:/dev/ttyUSB0:57600      # or COM3:57600 on Windows
 ```
 Connect-target forms: `udp:HOST:PORT` (default `udp:127.0.0.1:14550` = SITL/MAVProxy) |
-`tcp:HOST:PORT` | `serial:/dev/ttyUSB0:BAUD` | `/path/log.tlog` (offline replay). Can also be
-set via the `MAVLINK_CONNECT` env on the server.
+`tcp:HOST:PORT` | `serial:/dev/ttyUSB0:BAUD` (on Windows a COM port, e.g. `COM3` or
+`COM3:57600`) | `/path/log.tlog` (offline replay).
+
+> Set it in the environment, **not** in the server's `environment` block: Hydron spawns local
+> MCP servers with `{...process.env, ...environment}`, so a server-level entry *shadows* your
+> export rather than acting as a default. That is why the plugin sets neither.
 
 > **"Connected" ≠ a live vehicle.** The panel shows `mavlink Connected` once the bridge *process*
 > starts. The tools only return data while something is **actually publishing MAVLink** at the
 > connect target. With no source, calls return empty / time out (`-32001`). Start your SITL/vehicle
 > (or leave it — log analysis via `uav_analyze` doesn't need the live bridge).
 
-> **Param writes are OFF by default.** The bridge defaults to `--read-only`. To enable the
-> tune→push→retest write tier (`param_set` / `param_set_batch`), the command must pass **both**
-> `--no-read-only` **and** `--allow-param-write`:
-> ```jsonc
-> "command": ["python3", "<plugin-path>/bridge/uav_mavlink_bridge.py",
->             "--connect", "udp:127.0.0.1:14550",
->             "--no-read-only", "--allow-param-write"]
+> **⚠ Param writes are ON by default.** The shipped command passes `--no-read-only`
+> `--allow-param-write`, which registers the tune→push→retest write tier (`param_set` /
+> `param_set_batch`). This lets the agent **write parameters to a live vehicle**. Prefer
+> SITL/bench, and point `MAVLINK_CONNECT` at a real airframe only when you intend that.
+>
+> To ship read-only, remove both flags from the `config` hook in `src/index.ts` — the bridge's own defaults are
+> `read_only=True` / `allow_param_write=False`, and the write tools are then never registered:
+> ```ts
+> command: [...py, script],   // no --no-read-only / --allow-param-write
 > ```
-> ⚠ this lets the agent **write parameters to a live vehicle** — prefer SITL/bench, and point
-> `--connect` at a real airframe only when you intend that.
+> Reads (`param_get`, `param_get_all`, `read_params`, telemetry) are unaffected either way.
 
 ---
 
 ## 7. Troubleshooting
 
 - **UAV tools don't appear** → you didn't *fully* restart Hydron (a window reload isn't enough); the
-  plugin loads once per process. Confirm it's installed with `hydron plugin list`. On Windows make
-  sure Hydron is running in the **same WSL env** you're using.
-- **`mavlink` shows Disabled** → the `python3` in the `mavlink` command lacks `pymavlink`+`mcp`, or
-  it isn't Python ≥ 3.10. Install the deps (`pip install -r bridge/requirements.txt`, ideally into a
-  venv) and point the command at that interpreter.
+  plugin loads once per process. Confirm it's installed with `hydron plugin list`. If you install
+  under WSL, Hydron must also **run** under WSL — a Windows-side Hydron cannot see a WSL-side
+  install (check for the green `WSL: Ubuntu` badge in VS Code's bottom-left corner).
+- **`uav_python` / `.ulog` decode → "no working Python 3 interpreter found"** → no runnable Python
+  on PATH. On Windows, install from python.org with **“Add python.exe to PATH”** ticked — the
+  pre-installed Store *stubs* don't count. Then reopen the terminal, or set `UAV_PYTHON` to the
+  interpreter's full path.
+- **`mavlink` shows Disabled** → the interpreter in the `mavlink` command lacks `pymavlink`+`mcp`,
+  or it isn't Python ≥ 3.10. Install the deps (`pip install -r bridge/requirements.txt`, ideally
+  into a venv) and point the command at that interpreter. Note `mcp.json` ships `python3`, which
+  does not exist on Windows — change it to `python` or an absolute path.
 - **Every mavlink tool → `MCP error -32001: Request timed out`** → the bridge is Connected but **no
   MAVLink source is live** at the connect target. Start SITL / point `--connect` at a live link.
 - **`MCP error -32000: Connection closed`** → the bridge crashed at startup: usually the wrong Python

package/bridge/requirements.txt

@@ -1,2 +1,6 @@
 pymavlink>=2.4.49
-mcp[cli]>=1.0.0
+# Pinned below 2.0: the MCP Python SDK removed `mcp.server.fastmcp` in 2.x (FastMCP is gone,
+# replaced by a different MCPServer API), so this bridge fails at import on mcp>=2. The
+# unpinned `>=1.0.0` silently floated into that breaking major. Porting to the 2.x server API
+# is a separate change; until then this range is the supported one (verified on 1.29.0).
+mcp[cli]>=1.0.0,<2

package/mcp.json

@@ -4,12 +4,6 @@
     "url": "https://mcp.exa.ai/mcp",
     "headers": { "x-api-key": "${EXA_API_KEY}" },
     "enabled": false
-  },
-  "mavlink": {
-    "type": "local",
-    "enabled": false,
-    "command": ["python3", "./bridge/uav_mavlink_bridge.py", "--connect", "udp:127.0.0.1:14550"],
-    "environment": { "MAVLINK_DIALECT": "ardupilotmega" },
-    "timeout": 10000
   }
 }
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h2loop/uav",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "UAV domain pack for Hydron — ArduPilot/PX4 flight-log intelligence (analyze, triage, compare, tune)",
   "type": "module",
   "private": false,