wsjtx-mcp 0.1.0__tar.gz

wsjtx_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest

wsjtx_mcp-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments / uv
+.venv/
+venv/
+
+# Tooling caches
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/
+
+# Packaged desktop-extension build artifact (attach to a GitHub Release instead)
+*.mcpb
+
+# Generated icon size variants (only icon.png is tracked)
+icon_*.png
+
+# Local live-test scratch scripts (never committed)
+livecheck.py
+probe.py
+captures/

wsjtx_mcp-0.1.0/.mcpbignore

@@ -0,0 +1,21 @@
+# Files excluded from the packaged .mcpb bundle
+.git/
+.github/
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+tests/
+*.egg-info/
+build/
+dist/
+.DS_Store
+icon_*.png
+livecheck.py
+probe.py
+smoke_test.py
+make_icon.py
+captures/

wsjtx_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to **wsjtx-mcp** are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-06-26
+
+Initial **experimental** release.
+
+### Added
+- Standard-library Qt `QDataStream` codec (schema 3 / Qt_5_4, big-endian,
+  double-precision floats) covering ints, bool, double, utf8/QByteArray
+  (null vs. empty), `QTime`, `QDateTime`, and `QColor`.
+- Full WSJT-X message catalog (types 0–15): decoders for the broadcast messages
+  (Heartbeat, Status, Decode, Clear, QSOLogged, WSPRDecode, LoggedADIF, Close)
+  and builders for the control messages (Heartbeat, Clear, Reply, Close, Replay,
+  HaltTx, FreeText, Location, HighlightCallsign, SwitchConfiguration, Configure).
+- Background UDP listener tracking the latest Status, a Decode ring buffer with
+  drain-since-last-poll semantics, completed QSOs (QSOLogged paired with ADIF),
+  and a per-instance registry (Id → source address) for targeting control.
+- Grouped MCP tools: `status`, `diagnostics`, `decodes`, `log`, `reply`,
+  `free_text`, `transmit`, `configure`, `clear`, `highlight`, `location`,
+  `switch_config`, and the `wsjtx_call` escape hatch.
+- **Callsign transmit gate**: with `WSJTX_CALLSIGN` blank the server is
+  receive-only and refuses every transmit-initiating message.
+- `udp_relay.py` (mcp-host-bridge, UDP edition) for reaching a WSJT-X on another
+  host from a loopback-only MCP client.
+- Verified live against WSJT-X (reported version 3.0.2, schema 2 header / max
+  schema 3): receive + decode of real Status/Heartbeat datagrams, target
+  resolution, and an accepted control round-trip (Replay). Golden byte fixtures
+  from that session are checked in.
+
+### Known limitations
+- No dial-frequency control over UDP (QSY is a rig-control concern).
+- Cannot "Enable Tx" over UDP — transmission is initiated by `reply` or
+  `free_text` send, and only halted via `transmit`.
+- `Configure` cannot express "no change" for its two booleans (`fast_mode`,
+  `generate_messages`), so they are always sent.

wsjtx_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for your interest in **wsjtx-mcp**.
+
+## Development setup
+
+```sh
+uv sync
+uv run ruff check .
+uv run pytest
+```
+
+The protocol layer (`qdatastream.py`, `protocol.py`, `methods.py`) is pure
+standard library and unit-tested against byte fixtures — including **golden
+fixtures captured from a live WSJT-X** (`tests/test_golden.py`). The tests need no
+running WSJT-X.
+
+To verify against your own station, run `uv run python smoke_test.py 22 --save`:
+it binds the UDP port, decodes whatever WSJT-X broadcasts, and (with `--save`)
+writes raw datagrams to `captures/` you can turn into new fixtures.
+
+## House style
+
+- Python 3.10+, `uv`, FastMCP, `src/` layout.
+- `ruff` with `line-length = 100` (run it before pushing).
+- Grouped-tools pattern: one tool per functional area taking an `operation`
+  argument, plus the `wsjtx_call` escape hatch.
+- Standard-library-only at runtime where possible (the only dependency is `mcp`).
+
+## Safety
+
+Anything that can key a transmitter must stay behind the **callsign transmit
+gate**. New transmit-initiating paths must call `_require_tx(...)` and be covered
+by a test that proves they are refused when `WSJTX_CALLSIGN` is blank.
+
+## Reporting protocol discrepancies
+
+If a field decodes wrong against your WSJT-X build, please open an issue with a
+captured datagram (hex or base64) and your WSJT-X version — that is the fastest
+path to a fix, and may become a new golden fixture.

wsjtx_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefan Brunner (AE5VG)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wsjtx_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: wsjtx-mcp
+Version: 0.1.0
+Summary: An MCP server that controls WSJT-X (FT8/FT4/etc.) over its UDP message protocol.
+Project-URL: Homepage, https://github.com/sbrunner-atx/wsjtx-mcp
+Project-URL: Repository, https://github.com/sbrunner-atx/wsjtx-mcp
+Project-URL: Issues, https://github.com/sbrunner-atx/wsjtx-mcp/issues
+Author-email: "Stefan Brunner (AE5VG)" <me@stefanbrunner.org>
+License: MIT
+License-File: LICENSE
+Keywords: amateur-radio,ft4,ft8,ham-radio,mcp,model-context-protocol,weak-signal,wsjtx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Ham Radio
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.2.0
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.sbrunner-atx/wsjtx-mcp -->
+
+# wsjtx-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that controls **WSJT-X**
+(FT8/FT4/JT65/MSK144/Q65/WSPR…) from MCP clients such as Claude Desktop and the
+MCP Inspector.
+
+It is the weak-signal leg of an "operate → log" trio for amateur radio:
+
+- **[fldigi-mcp](https://github.com/sbrunner-atx/fldigi-mcp)** — operate broad
+  digital modes via fldigi (XML-RPC).
+- **[contest-mcp](https://github.com/sbrunner-atx/contest-mcp)** — log QSOs to
+  N3FJP (TCP API).
+- **wsjtx-mcp** *(this one)* — operate the FT8/FT4 weak-signal world via WSJT-X
+  (UDP message protocol).
+
+> ⚠️ **Experimental (v0.1).** Transmit is gated behind your callsign and you keep
+> the operator in command. Read the [Transmit safety](#transmit-safety) section.
+
+## How it is different
+
+WSJT-X does **not** offer a request/response API. It *broadcasts* state over UDP
+(`Status`, `Decode`, `QSOLogged`, `Heartbeat`, …) and honours a small set of
+inbound *control* messages. So this server runs a **background UDP listener** that
+continuously parses datagrams and keeps the latest status, a buffer of decodes,
+and completed QSOs — you read those, and nudge WSJT-X with control messages.
+
+Two consequences worth knowing up front:
+
+- **No dial-frequency control over UDP.** You can read the dial frequency from
+  `Status`, and set mode/sub-mode/Rx DF/T-R period via `configure`, but **QSY is a
+  rig-control concern** (Hamlib/CAT or the UI), not this server.
+- **You can halt Tx but not "Enable Tx".** Transmission is *started* by answering
+  a CQ (`reply`) or by `free_text` with `send=true`; it is *stopped* by
+  `transmit halt`. There is no UDP command to press "Enable Tx".
+
+## Requirements
+
+- WSJT-X 2.x (verified against the 2.7 message schema, **schema 3 / Qt_5_4**).
+- In WSJT-X: **Settings → Reporting → UDP Server**
+  - **UDP Server** = the host running this server (default `127.0.0.1`), **port
+    `2237`**.
+  - **Accept UDP requests** = **ON** to allow *control* (it is OFF by default).
+    Observing decodes/status works without it; commanding does not.
+
+## Install (Claude Desktop)
+
+Download the `wsjtx-mcp.mcpb` from the
+[latest release](https://github.com/sbrunner-atx/wsjtx-mcp/releases) and
+double-click it, or drag it onto Claude Desktop → Settings → Extensions. Fill in
+the settings form (callsign, host, port). See [docs/INSTALL.md](docs/INSTALL.md).
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `WSJTX_HOST` | `127.0.0.1` | UDP address to **bind/listen** on. |
+| `WSJTX_PORT` | `2237` | WSJT-X UDP Server port. |
+| `WSJTX_CALLSIGN` | _(empty)_ | Operator callsign — **the single transmit gate**. Blank = receive-only. |
+| `WSJTX_MULTICAST` | _(off)_ | Optional multicast group to join (coexist with other UDP consumers). |
+| `WSJTX_INSTANCE` | _(auto)_ | Target a specific WSJT-X `Id` when several instances broadcast. |
+
+Host/port are **where this server listens**; control replies are sent back to the
+address each datagram arrived from.
+
+## Tools
+
+| Tool | Kind | What it does |
+| --- | --- | --- |
+| `status` | observe | Latest `Status` snapshot + listener/instance health. |
+| `diagnostics` | observe | Host/network + bind status + datagram counts + gate state. |
+| `decodes` | observe/nudge | `read` / `drain` (poll new) / `clear_local` / `replay`. The RX plane. |
+| `log` | observe | Buffered completed QSOs (`QSOLogged` + `LoggedADIF`) → feed N3FJP. |
+| `reply` | **transmit** | Answer a buffered CQ/QRZ decode (auto-sequences the QSO). |
+| `free_text` | **transmit** if `send` | Set the Tx5 free-text message; `send=true` keys the radio. |
+| `transmit` | control | `halt` / `halt_auto` — stop transmitting (UDP can't *enable* Tx). |
+| `configure` | control | Mode/sub-mode/Rx DF/T-R period/freq-tol/DX call+grid. **No dial freq.** |
+| `clear` | control | Clear the Band Activity / Rx Frequency windows. |
+| `highlight` | control | Colour or clear a callsign in Band Activity. |
+| `location` | control | Override the session Maidenhead grid. |
+| `switch_config` | control | Switch to a named WSJT-X configuration. |
+| `wsjtx_call` | escape hatch | Build & send any message type by name (gate still applies). |
+
+## Transmit safety
+
+The **callsign is the single transmit gate**, exactly as in fldigi-mcp. With
+`WSJTX_CALLSIGN` blank the server is **receive-only**: it refuses every
+transmit-initiating message — `reply`, `free_text` with `send=true`, and any
+keying message via `wsjtx_call`. `transmit halt`, `clear`, `configure`,
+`highlight`, `location`, `replay`, and all reads are always available (they don't
+put you on the air; halt takes you *off*).
+
+Beyond that gate:
+
+- Per-transmit approval comes from the Claude Desktop tool-permission prompt —
+  lean on it for human-in-the-loop control.
+- WSJT-X's own **Tx Watchdog** and the `Tx Enabled` / `Transmitting` flags
+  (surfaced in `status`) are extra safety signals.
+- Operating under **Part 97 automatic/remote control** is the operator's
+  responsibility: ensure station identification and a control operator who can
+  intervene.
+
+## Running alongside other UDP tools
+
+Only one process can normally own UDP `2237` on a host. If JTAlert, GridTracker,
+or N1MM already consume it, either point WSJT-X's *secondary* UDP server here, use
+a **multicast** group (`WSJTX_MULTICAST`) so several listeners coexist, or run
+this server on a different host. See [docs/REMOTE-HOST.md](docs/REMOTE-HOST.md)
+for reaching a WSJT-X on another machine (it requires a small UDP forwarder
+because sandboxed MCP clients reach only loopback).
+
+## Development
+
+```sh
+uv sync
+uv run ruff check .
+uv run pytest
+```
+
+The protocol codec is pure standard library and unit-tested against byte
+fixtures, so the tests need no running WSJT-X. A `smoke_test.py` proves a live
+WSJT-X is reachable receive-only. The field-tested message reference lives in
+[docs/WSJTX-API.md](docs/WSJTX-API.md).
+
+## License
+
+MIT © 2026 Stefan Brunner (AE5VG)

wsjtx_mcp-0.1.0/README.md

@@ -0,0 +1,128 @@
+<!-- mcp-name: io.github.sbrunner-atx/wsjtx-mcp -->
+
+# wsjtx-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that controls **WSJT-X**
+(FT8/FT4/JT65/MSK144/Q65/WSPR…) from MCP clients such as Claude Desktop and the
+MCP Inspector.
+
+It is the weak-signal leg of an "operate → log" trio for amateur radio:
+
+- **[fldigi-mcp](https://github.com/sbrunner-atx/fldigi-mcp)** — operate broad
+  digital modes via fldigi (XML-RPC).
+- **[contest-mcp](https://github.com/sbrunner-atx/contest-mcp)** — log QSOs to
+  N3FJP (TCP API).
+- **wsjtx-mcp** *(this one)* — operate the FT8/FT4 weak-signal world via WSJT-X
+  (UDP message protocol).
+
+> ⚠️ **Experimental (v0.1).** Transmit is gated behind your callsign and you keep
+> the operator in command. Read the [Transmit safety](#transmit-safety) section.
+
+## How it is different
+
+WSJT-X does **not** offer a request/response API. It *broadcasts* state over UDP
+(`Status`, `Decode`, `QSOLogged`, `Heartbeat`, …) and honours a small set of
+inbound *control* messages. So this server runs a **background UDP listener** that
+continuously parses datagrams and keeps the latest status, a buffer of decodes,
+and completed QSOs — you read those, and nudge WSJT-X with control messages.
+
+Two consequences worth knowing up front:
+
+- **No dial-frequency control over UDP.** You can read the dial frequency from
+  `Status`, and set mode/sub-mode/Rx DF/T-R period via `configure`, but **QSY is a
+  rig-control concern** (Hamlib/CAT or the UI), not this server.
+- **You can halt Tx but not "Enable Tx".** Transmission is *started* by answering
+  a CQ (`reply`) or by `free_text` with `send=true`; it is *stopped* by
+  `transmit halt`. There is no UDP command to press "Enable Tx".
+
+## Requirements
+
+- WSJT-X 2.x (verified against the 2.7 message schema, **schema 3 / Qt_5_4**).
+- In WSJT-X: **Settings → Reporting → UDP Server**
+  - **UDP Server** = the host running this server (default `127.0.0.1`), **port
+    `2237`**.
+  - **Accept UDP requests** = **ON** to allow *control* (it is OFF by default).
+    Observing decodes/status works without it; commanding does not.
+
+## Install (Claude Desktop)
+
+Download the `wsjtx-mcp.mcpb` from the
+[latest release](https://github.com/sbrunner-atx/wsjtx-mcp/releases) and
+double-click it, or drag it onto Claude Desktop → Settings → Extensions. Fill in
+the settings form (callsign, host, port). See [docs/INSTALL.md](docs/INSTALL.md).
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `WSJTX_HOST` | `127.0.0.1` | UDP address to **bind/listen** on. |
+| `WSJTX_PORT` | `2237` | WSJT-X UDP Server port. |
+| `WSJTX_CALLSIGN` | _(empty)_ | Operator callsign — **the single transmit gate**. Blank = receive-only. |
+| `WSJTX_MULTICAST` | _(off)_ | Optional multicast group to join (coexist with other UDP consumers). |
+| `WSJTX_INSTANCE` | _(auto)_ | Target a specific WSJT-X `Id` when several instances broadcast. |
+
+Host/port are **where this server listens**; control replies are sent back to the
+address each datagram arrived from.
+
+## Tools
+
+| Tool | Kind | What it does |
+| --- | --- | --- |
+| `status` | observe | Latest `Status` snapshot + listener/instance health. |
+| `diagnostics` | observe | Host/network + bind status + datagram counts + gate state. |
+| `decodes` | observe/nudge | `read` / `drain` (poll new) / `clear_local` / `replay`. The RX plane. |
+| `log` | observe | Buffered completed QSOs (`QSOLogged` + `LoggedADIF`) → feed N3FJP. |
+| `reply` | **transmit** | Answer a buffered CQ/QRZ decode (auto-sequences the QSO). |
+| `free_text` | **transmit** if `send` | Set the Tx5 free-text message; `send=true` keys the radio. |
+| `transmit` | control | `halt` / `halt_auto` — stop transmitting (UDP can't *enable* Tx). |
+| `configure` | control | Mode/sub-mode/Rx DF/T-R period/freq-tol/DX call+grid. **No dial freq.** |
+| `clear` | control | Clear the Band Activity / Rx Frequency windows. |
+| `highlight` | control | Colour or clear a callsign in Band Activity. |
+| `location` | control | Override the session Maidenhead grid. |
+| `switch_config` | control | Switch to a named WSJT-X configuration. |
+| `wsjtx_call` | escape hatch | Build & send any message type by name (gate still applies). |
+
+## Transmit safety
+
+The **callsign is the single transmit gate**, exactly as in fldigi-mcp. With
+`WSJTX_CALLSIGN` blank the server is **receive-only**: it refuses every
+transmit-initiating message — `reply`, `free_text` with `send=true`, and any
+keying message via `wsjtx_call`. `transmit halt`, `clear`, `configure`,
+`highlight`, `location`, `replay`, and all reads are always available (they don't
+put you on the air; halt takes you *off*).
+
+Beyond that gate:
+
+- Per-transmit approval comes from the Claude Desktop tool-permission prompt —
+  lean on it for human-in-the-loop control.
+- WSJT-X's own **Tx Watchdog** and the `Tx Enabled` / `Transmitting` flags
+  (surfaced in `status`) are extra safety signals.
+- Operating under **Part 97 automatic/remote control** is the operator's
+  responsibility: ensure station identification and a control operator who can
+  intervene.
+
+## Running alongside other UDP tools
+
+Only one process can normally own UDP `2237` on a host. If JTAlert, GridTracker,
+or N1MM already consume it, either point WSJT-X's *secondary* UDP server here, use
+a **multicast** group (`WSJTX_MULTICAST`) so several listeners coexist, or run
+this server on a different host. See [docs/REMOTE-HOST.md](docs/REMOTE-HOST.md)
+for reaching a WSJT-X on another machine (it requires a small UDP forwarder
+because sandboxed MCP clients reach only loopback).
+
+## Development
+
+```sh
+uv sync
+uv run ruff check .
+uv run pytest
+```
+
+The protocol codec is pure standard library and unit-tested against byte
+fixtures, so the tests need no running WSJT-X. A `smoke_test.py` proves a live
+WSJT-X is reachable receive-only. The field-tested message reference lives in
+[docs/WSJTX-API.md](docs/WSJTX-API.md).
+
+## License
+
+MIT © 2026 Stefan Brunner (AE5VG)

wsjtx_mcp-0.1.0/docs/INSTALL.md

@@ -0,0 +1,76 @@
+# Installing wsjtx-mcp
+
+## 1. Enable WSJT-X's UDP Server
+
+In WSJT-X: **Settings → Reporting → UDP Server**.
+
+- **UDP Server**: the host running wsjtx-mcp. For a local setup leave it at
+  `127.0.0.1`.
+- **UDP Server port number**: `2237` (the default).
+- **Accept UDP requests**: **tick this** if you want wsjtx-mcp to *control*
+  WSJT-X (answer CQs, set free text, configure, etc.). It is **off by default**.
+  Observing decodes and status works without it; commanding does not.
+
+> Tip: if JTAlert / GridTracker / N1MM already use port 2237, see
+> [Running alongside other UDP tools](#running-alongside-other-udp-tools).
+
+## 2a. Install as a Claude Desktop extension (.mcpb)
+
+1. Download `wsjtx-mcp.mcpb` from the
+   [latest release](https://github.com/sbrunner-atx/wsjtx-mcp/releases).
+2. If you previously installed an older build, **remove it first** (Settings →
+   Extensions → uninstall, and wait for its tile to disappear) so the swap takes
+   effect.
+3. Double-click the `.mcpb`, or drag it onto Claude Desktop → Settings →
+   Extensions.
+4. Fill in the settings form:
+   - **Operator callsign** — your licensed callsign. Leave **blank for
+     receive-only**; set it to enable transmit.
+   - **Listen host / port** — usually `127.0.0.1` / `2237`.
+5. **Quit and reopen Claude Desktop** (Cmd-Q) so the new tools load.
+
+## 2b. Install from PyPI (any MCP client)
+
+```sh
+uvx wsjtx-mcp        # or: pipx run wsjtx-mcp
+```
+
+Add it to your client's MCP config with the environment variables from the
+[README configuration table](../README.md#configuration), e.g.:
+
+```json
+{
+  "mcpServers": {
+    "wsjtx-mcp": {
+      "command": "uvx",
+      "args": ["wsjtx-mcp"],
+      "env": { "WSJTX_CALLSIGN": "", "WSJTX_HOST": "127.0.0.1", "WSJTX_PORT": "2237" }
+    }
+  }
+}
+```
+
+## 3. Verify
+
+Ask your client to run the **`status`** tool. You should see the current dial
+frequency, mode, and the discovered instance within ~15 seconds (WSJT-X sends a
+Heartbeat every 15 s plus a Status on each state change). If nothing appears, run
+**`diagnostics`** — it reports whether the UDP listener bound and how many
+datagrams have arrived.
+
+## Running alongside other UDP tools
+
+Only one process can own UDP `2237` on a host. Options:
+
+- Point WSJT-X's **secondary** UDP server at wsjtx-mcp's host:port.
+- Use a **multicast** group: set the same group in WSJT-X's UDP Server and in
+  `WSJTX_MULTICAST`, so several listeners coexist.
+- Run wsjtx-mcp on a different host (see [REMOTE-HOST.md](REMOTE-HOST.md)).
+
+## Transmit safety
+
+The **callsign is the single transmit gate**. With it blank, wsjtx-mcp is
+receive-only and refuses every transmit-initiating message. Per-transmit approval
+also comes from your client's tool-permission prompt. You — the licensed control
+operator — remain responsible for lawful operation (station ID, ability to
+intervene, Part 97 automatic/remote-control rules).

wsjtx_mcp-0.1.0/docs/REMOTE-HOST.md

@@ -0,0 +1,89 @@
+# Reaching a WSJT-X on another computer (UDP host bridge)
+
+Sandboxed MCP clients — notably Claude Desktop — let their connector subprocess
+reach only `127.0.0.1` (loopback), **not LAN IP addresses**, even with macOS
+*Privacy & Security → Local Network* toggled on. So if WSJT-X runs on a different
+machine than wsjtx-mcp, the server cannot talk to it directly.
+
+The fix is a small **UDP relay** that runs *outside* the sandbox on the
+wsjtx-mcp host, bridges the LAN to loopback, and routes WSJT-X's broadcasts in
+and your control replies back out. WSJT-X's protocol is connectionless and
+*bidirectional*, so this needs a UDP-aware relay (`tools/udp_relay.py` in this
+repo, the UDP sibling of the TCP `mcp-host-bridge` relay used by fldigi-mcp /
+contest-mcp).
+
+## Topology
+
+```
+  remote WSJT-X                  bridge host (Mac)                 wsjtx-mcp
+  Settings → Reporting           udp_relay.py                      (loopback only)
+  UDP Server =          ──►   --listen 0.0.0.0:2237   ──►   --deliver 127.0.0.1:2238
+  <bridge-LAN-IP> : 2237     (LAN socket A)                 WSJTX_HOST=127.0.0.1
+                             (loopback socket B)            WSJTX_PORT=2238
+  control replies       ◄──   B → A → back to the remote WSJT-X
+```
+
+- WSJT-X (remote) sends its UDP datagrams to the **bridge host's LAN IP**, port
+  `2237`.
+- The relay learns the remote peer from the first datagram and forwards
+  everything to wsjtx-mcp on `127.0.0.1:2238`.
+- wsjtx-mcp's control replies go back to the relay's loopback socket, which sends
+  them on to the remote WSJT-X — exactly the address each datagram came from.
+
+## Run it
+
+```sh
+python3 ~/.mcp-host-bridge/udp_relay.py run \
+  --listen 0.0.0.0:2237 \
+  --deliver 127.0.0.1:2238
+```
+
+Then set wsjtx-mcp's config to `WSJTX_HOST=127.0.0.1`, `WSJTX_PORT=2238`, and in
+the remote WSJT-X set **UDP Server** to the bridge host's LAN IP, port `2237`
+(and tick **Accept UDP requests** for control).
+
+## Run it under launchd (macOS, auto-start)
+
+Save as `~/Library/LaunchAgents/com.mcp-host-bridge.wsjtx.plist` and
+`launchctl load` it (mirrors the existing TCP bridge agents; uses the system
+`/usr/bin/python3`, so no venv/PATH dependency):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key><string>com.mcp-host-bridge.wsjtx</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/bin/python3</string>
+        <string>/Users/YOU/.mcp-host-bridge/udp_relay.py</string>
+        <string>run</string>
+        <string>--listen</string>
+        <string>0.0.0.0:2237</string>
+        <string>--deliver</string>
+        <string>127.0.0.1:2238</string>
+    </array>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+    <key>StandardOutPath</key><string>/tmp/mcp-host-bridge-wsjtx.log</string>
+    <key>StandardErrorPath</key><string>/tmp/mcp-host-bridge-wsjtx.err</string>
+</dict>
+</plist>
+```
+
+```sh
+launchctl load ~/Library/LaunchAgents/com.mcp-host-bridge.wsjtx.plist
+# to update args later:
+launchctl unload ~/Library/LaunchAgents/com.mcp-host-bridge.wsjtx.plist && \
+launchctl load   ~/Library/LaunchAgents/com.mcp-host-bridge.wsjtx.plist
+```
+
+## Notes
+
+- Run the relay on a **different loopback port** (`2238`) than the LAN port
+  (`2237`) so the relay's LAN socket and wsjtx-mcp's listener don't collide.
+- For a **local** WSJT-X (same machine), you don't need the relay at all — point
+  wsjtx-mcp straight at `127.0.0.1:2237`.
+- Multicast is an alternative to the relay when every consumer is on the same
+  LAN segment: set `WSJTX_MULTICAST` and WSJT-X's UDP Server to the same group.