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.

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-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).

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.

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.

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.

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.

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.

Escape hatch: send any raw N3FJP command and return the parsed reply.

command may be a bare command id ("PROGRAM"), a full envelope (""), or the inner form ("") — 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.