io.github.sbrunner-atx/n3fjp-mcp

Change band, mode, and frequency before logging. operations: - change_freq (value=Hz): set the frequency (and thus band) via the rig interface. Use suppress_mode_default=true to keep the current mode rather than letting CW/phone segments flip it. - set_band (value=band, e.g. "20"): write the band box (rig interface OFF only). - set_mode (value=mode, e.g. "DIG"): write the mode box (rig interface OFF only). - ignore_rig_polls (value=bool): pause rig polling so band/mode boxes can be written while a rig is connected. Remember to set it back to false. Always make sure the program is on the correct band and mode before ENTER.

Direct database operations on individual records. These are ordinary writes (the *Needs Approval* tier — same as logging), so they can be globally allowed in the client for automation. The ONLY hard block is a whole-database wipe/overwrite, gated by N3FJP_ALLOW_DB_WIPE. operations: - add_direct (fields={fldCall:..., fldBand:...}, exclude_dupes): insert a record directly, bypassing N3FJP's scoring. Prefer log's log_qso/ENTER. - delete (where="fldPrimaryID=123"): delete matching records. A missing or empty WHERE would clear the whole table and is refused unless N3FJP_ALLOW_DB_WIPE is on. - sql (sql="..."): run a raw SQL statement against the Access database. Only statements that could wipe/overwrite the whole database (DROP, TRUNCATE, unscoped DELETE/UPDATE) are refused unless N3FJP_ALLOW_DB_WIPE is on; scoped statements run normally. - checklog / openlog: ask N3FJP to reload new / all records. - sqlclose: close the SQL connection.

Host + network diagnostics for troubleshooting connectivity. Does NOT connect to N3FJP. Reports the resolved N3FJP_HOST/PORT, this process's Python and hostname, and the host's network interfaces — so you can tell whether the process can even see the target's network (e.g. when running host-side vs. sandboxed).

Read entry-box (text field) values. operations: - read (field=name): read one box. `field` may be a friendly name (call, rst_rcvd, class, section, name, …) or a raw control id (TXTENTRY…). - visible: every field the current contest shows, with values. - all: every field (regardless of visibility), with values. Derived fields (country_worked, cq_zone, itu_zone, continent, prefix) are readable here but are computed by N3FJP from the call — never write them.

Logbook entry: set fields, run Call-tab, and ENTER a QSO. The headline tool. operations: - log_qso: the automatic-logging flow. Provide `call` (and usually `exchange`, a dict of friendly field names → values, e.g. {"class": "2A", "section": "CT"}). Sets the call, runs CALLTAB (dupe check + lookups) unless calltab=false, sets the exchange, then ENTER. Returns the number of records added and any dupe response. - set (field, value): write one entry box. - set_many (fields={...}): write several entry boxes. - calltab: run CALLTAB (after setting the call). - enter: log the current form. Returns records_added plus a `logged` boolean derived from the QSO-count delta / ENTEREVENT — trust `logged`, not records_added, which can report 0 on success in networked mode. Do not retry when logged=true (creates duplicates). - clear: clear the entry form. - focus (field): move focus to a box (e.g. to auto-fill default RST). Tip: `contest` (e.g. "field_day", "cq_wpx") lets the tool warn if the exchange is missing a field that contest needs.

Escape hatch: send any raw N3FJP command and return the parsed reply. `command` may be a bare command id ("PROGRAM"), a full envelope ("<CMD><PROGRAM></CMD>"), or the inner form ("<PROGRAM>") — it is normalised and CRLF-terminated for you. `expect` is the response id to wait for. This reaches anything not surfaced by a group tool, including newer commands. Like the group tools, it runs at the *Needs Approval* tier; the only hard block is a raw SQL statement that could wipe/overwrite the whole database, which still requires the N3FJP_ALLOW_DB_WIPE switch.

Opt-in push events from N3FJP (field updates, enter/calltab, dupes). operations: - enable: turn on all-field-update notifications. - disable: turn them off. - drain: return and clear the buffered notification blocks received so far. MCP is request/response, so events are buffered and you pull them with drain rather than receiving a live stream.

Read-only program queries. operations: program (name/version/API version), qso_count, next_serial, log_path, settings_path, shared_path, qso_rate (contest stats), band_mode_freq (current band/mode/frequency).

Search and list the log (read-only). operations: - list (count, include_all): the most recent QSOs (primary fields, or every field with include_all=true). - search (call/band/mode/dxcc/country/confirmed, include_all, max_records): find matching QSOs. Prefer dxcc (ADIF number) over country (must match N3FJP's spelling exactly). mode is normalized to CW/PH/DIG. - dupecheck (call): is this call a dupe? Returns previous-contact detail or empty if new. (No side effects, unlike the log tool's calltab.) - entity (call, band, mode): all-time-new/worked/confirmed status.

Snapshot: program, version, API version, QSO count, band/mode/frequency, log path. A quick health check that also confirms the connection and which N3FJP program/contest is loaded.