io.github.sbrunner-atx/wsjtx-mcp

Set a Fox/Hound sort-order annotation for a DX call (no transmit). Niche DXpedition feature (AnnotationInfo): lets a server "score" callers so the Hound queue can be sorted by it. `sort_order` is a number (lower sorts first); omit it to send "no sort order"; pass 4294967295 (0xFFFFFFFF) to remove a call's entry from WSJT-X's internal table.

Clear a WSJT-X decode window (no transmit). window: 'band' (Band Activity, default), 'rx' (Rx Frequency), or 'both'.

Set operating parameters via a ``Configure`` message (no transmit). Sets: mode, submode, frequency tolerance, fast mode, T/R period, Rx DF, DX call, DX grid, and whether to regenerate the standard messages. Empty string = "no change" for text fields; ``None`` = "no change" for the numeric fields. IMPORTANT caveats: - There is **no dial-frequency control** over UDP. QSY is a rig-control concern (Hamlib/CAT or the WSJT-X UI), not this tool. - The protocol has no "no change" for the two booleans, so `fast_mode` and `generate_messages` are **always sent** (defaulting to false). Pass them explicitly if you care about their state.

The RX data plane: buffered ``Decode`` / ``WSPRDecode`` lines. operations: - read (limit): the most recent N decodes (default 50). - drain: every decode seen since the last drain — the polling primitive for automation. Advances an internal cursor so each line is returned once. - clear_local: empty our local buffer (does not touch WSJT-X). - replay: ask WSJT-X to re-broadcast its current Band-Activity decodes (each with New=false) followed by a Status — useful to backfill state on connect. (No transmit; safe.) Each decode carries: kind (decode/wspr), New, time, snr, delta_time, delta_frequency, mode, message, low_confidence, off_air, and a `seq` you can pass to the `reply` tool.

Host + network + listener diagnostics for troubleshooting connectivity. Does NOT command WSJT-X. Reports the resolved WSJTX_HOST/PORT, whether the UDP listener is bound (and any bind error), datagram counts by message type, the discovered instances, the transmit-gate state, and this host's network interfaces — so you can tell whether this process can even receive WSJT-X's broadcasts (e.g. host-side vs. sandboxed, or a port already owned by JTAlert / GridTracker).

Set the free-text (Tx5) message; with ``send=true`` **initiates TX** (gated). Setting the text alone (send=false) is safe and always allowed. With send=true the message is transmitted — that keys the radio, so it requires WSJTX_CALLSIGN. An empty `text` with send=true sends the *current* free text unchanged; empty text with send=false clears it.

Colour (or clear) a callsign in the Band Activity panel (no transmit). operations: - set (callsign, background, foreground, highlight_last): apply colours. Colours accept a name (red, yellow, …), '#RRGGBB', or [r,g,b]. - clear (callsign): cancel highlighting for one callsign (sends an invalid colour). - clear_all: cancel every highlight at once. Keep the number of active highlights modest (a rough cap of ~100) so WSJT-X decoding performance isn't impacted.

Override the session Maidenhead grid (4- or 6-character). No transmit. Session-lifetime only — does not change the persistent setting. Intended for mobile/portable operation where the grid changes during a session.

Read buffered completed QSOs (``QSOLogged`` paired with ``LoggedADIF``). Observe-only: WSJT-X emits these when the operator accepts its "Log QSO" dialog. Each entry has the structured QSO record (call, grids, frequency, mode, reports, times, exchanges, propagation mode) and the one-record ADIF document — ready to forward to N3FJP via contest-mcp.

Answer a buffered decode — **initiates a transmission** (gated by callsign). Equivalent to double-clicking that decode in the Band Activity window. WSJT-X only acts if the message **exactly** matches a prior decode that is a CQ or QRZ. If WSJT-X's "Auto Seq" is on (the usual FT8/FT4 default) it then sequences the rest of the QSO to completion on its own; if Auto Seq is off this starts only the first transmission (Auto Seq is a UI setting, not UDP-controllable). Identify the decode by `seq` (from the `decodes` tool) or by exact `message` text (the most recent matching buffered decode is used). `modifiers` may be a name or list (shift, ctrl/cmd, alt, meta, keypad, group) to mimic modifier-clicks.

Latest WSJT-X state snapshot plus listener/connection health. Returns the most recent ``Status`` broadcast — dial frequency, mode/sub-mode, Tx Enabled / Transmitting / Decoding, DE/DX call & grid, Rx/Tx DF, T/R period, special-operation mode (e.g. FIELD DAY), configuration name, current Tx message — together with the discovered instances and the transmit-gate state. If no ``Status`` has arrived yet, that is reported with guidance (WSJT-X must have its UDP Server pointed at this host:port).

Switch WSJT-X to a named configuration (which must already exist). No transmit.

Stop transmitting. (WSJT-X's UDP protocol can halt but cannot *enable* Tx.) operations: - halt: stop immediately (takes you off the air now). - halt_auto: stop at the end of the current transmission period. Always allowed — halting only ever takes you *off* the air. To *start* a transmission use `reply` (answer a CQ) or `free_text` with send=true.

Escape hatch: build and send any WSJT-X message type by name. `message` is a type name (heartbeat, clear, reply, close, replay, halt_tx, free_text, location, highlight, switch_configuration, configure). `fields` is a dict of builder arguments for that type (see protocol.build_* signatures), e.g. message="configure", fields={"mode":"FT8","rx_df":1500}. The same transmit gate applies: a keying message — `reply`, or `free_text` with send=true — is refused unless WSJTX_CALLSIGN is set.