Serial Console MCP: AI for telecom equipment and any serial device

Start writing this connection's traffic to a file until capture_stop. Args: path: File to write. Empty = an auto-named file in the app's captures folder. A bare name goes in that folder; an absolute path is used as is. Existing files are appended to. format: "raw" writes received bytes exactly as they arrive (a terminal log; echo included). "annotated" writes timestamped lines marked TX or RX, which is better for protocol debugging. connection: Which open connection (name). Default: the current one.

Stop the capture started by capture_start and report the file and size.

Build a ';'-terminated text CAT command (Kenwood, Elecraft, Yaesu) for query_text or send_text with line_ending="NONE". Common commands: ID (rig id), FA/FB (VFO A/B frequency; empty value = read), MD (mode; read, or set with the family's code), IF (full status), PS (power), TX/RX, AI0 (silence auto-info), SM0 (S-meter), PC (output power). Args: command: Two letters, e.g. "FA". value: Digits/letters to append for a set, e.g. "2" for MD2 (USB). Empty = read. frequency_mhz: For FA/FB sets: the frequency; formatted as 11 digits of Hz (Kenwood/Elecraft) or 9 (Yaesu). flavor: Which family's conventions: "kenwood" (default), "elecraft", "yaesu".

Decode ';'-terminated text CAT replies: rig id to model, FA/FB to MHz, MD to mode name, IF to frequency/mode/VFO/split/TX state, and the ?; E; O; error answers. Pass the text returned by query_text.

Build an Icom CI-V frame as hex, ready for send_hex. Args: command: Command byte(s) as hex, e.g. "03" read frequency, "04" read mode, "05" set frequency, "06" set mode, "1C 00" PTT, "19 00" read rig address. data: Data bytes as hex. For frequencies use civ_freq: set 14.070 MHz is command "05" with data "00 00 07 14 00" (BCD, low byte first). rig: The rig's CI-V address (IC-7300 94, IC-7610 98, IC-9700 A2, IC-705 A4). controller: Our address, conventionally E0.

Convert between a frequency in MHz and CI-V BCD data bytes. Give `mhz` to get the 5 data bytes for a set-frequency command (05), or `bcd_hex` (5 bytes from a reply) to get the frequency.

Decode Icom CI-V frames from hex (as returned by read_available). Splits the bytes into frames, tells our own echoed command apart from the rig's reply, and decodes frequencies (BCD), modes, OK/NG and PTT state.

Discard any buffered received data. Handy right before sending a command so the next read starts clean (drops old echo, prior output, or syslog noise).

Open a serial port and start its background reader. Defaults are 9600 baud, 8 data bits, no parity, 1 stop bit, no flow control ("9600 8N1"), CR line ending, which is what most console/craft ports expect. Give `preset` (see list_presets) to load a device family's usual settings, and override any field explicitly, e.g. "38400 with XON/XOFF" -> baud=38400, xonxoff=True. Several ports can be open at once; each gets a `name` and later tools default to the most recently used one. Nothing is specific to telecom gear: any device on a serial port works, including IoT gateways, alarm and control panels, UPS and PDU menus and lab instruments; choose `terminal` by what the device prints. Args: port: System port name, e.g. "COM4" (Windows), "/dev/cu.usbserial-10" (macOS), or "/dev/ttyUSB0" (Linux). Get exact names from `list_serial_ports`. preset: Device preset name such as "cisco-console", "juniper-craft", "kenwood-cat", "icom-civ", "yaesu-rotator", "arduino", "nmea-gps". name: Nickname for this connection ("rig", "rotator"). Defaults to the port's short name. Use it in other tools' `connection` argument. baud: Baud rate. Common values: 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200. Unknown? Use detect_baud first. bytesize: Data bits: 5, 6, 7, or 8. Almost always 8. parity: "N" none, "E" even, "O" odd. Almost always "N". stopbits: 1, 1.5, or 2. Almost always 1. rtscts: Hardware (RTS/CTS) flow control. Off unless the manual says so and the cable carries those lines. xonxoff: Software (XON/XOFF) flow control. Off by default. Never for binary protocols (it swallows 0x11 / 0x13 bytes). line_ending: Default line ending for send_text/query_text on this connection: "CR" (most rigs, consoles), "LF" (Unix, Arduino), "CRLF", or "NONE" (Kenwood-style CAT ending in ';'). prompt: Default prompt for read_until_prompt/query_text on this connection, e.g. "# ", "…

Try common baud rates on a closed port and rank them by how readable the reply is. Use when the user doesn't know the device's rate. Each candidate is opened briefly, `probe` (default: a bare return) is sent, and whatever comes back is scored by its share of printable text. The right rate yields clean text; wrong rates yield garbage or nothing. Note: opening a port resets many Arduinos (DTR), and some devices (Kenwood CAT) only answer a real command, so pass e.g. probe="ID;" with probe_line_ending="NONE". Args: port: The port to probe (must not be open here). probe: Text to send at each rate. Empty sends only the line ending. probe_line_ending: Line ending appended to the probe ("NONE" for CAT). candidates: Rates to try. Default: 9600, 115200, 19200, 38400, 57600, 4800, 2400, 1200, 230400. settle: Seconds to wait for a reply at each rate.

Close a serial port and free it for other programs. Args: connection: Which connection to close (name from connect). Default: the current one. all_connections: Close every open port.

Run a scripted sequence of send-and-wait steps in one call, like `expect`. Use it for login flows and multi-step commands instead of one tool call per line: [{send: "", expect: "login: "}, {send: "admin", expect: "Password:"}, {send: "<pw>", expect: "> "}, {send: "show version", expect: "> "}]. Each step's output is returned. A step with no `send` just waits; one with no `expect` just sends. Args: steps: The steps, in order. auto_reply: Triggers answered automatically while waiting, e.g. {"--More--": " "}. stop_on_timeout: Stop at the first step whose `expect` isn't seen. connection: Which open connection (name). Default: the current one.

Return the tail of everything received on a connection since it was opened. This is a rolling record (last 256 KB) kept regardless of what the read tools consumed, so you can re-read output that an earlier call already returned or that arrived between calls. Also available as the MCP resource serial://transcript/{name}.

Show the device presets `connect(preset=...)` understands, with their settings. A preset supplies baud, data bits, parity, stop bits, flow control, the line ending the device expects, and the prompt that ends a reply. Anything you pass explicitly to connect overrides the preset. Families: network consoles (Cisco, Juniper, Linux), text CAT radios (Kenwood, Elecraft, Yaesu), Icom CI-V, rotators, Arduino, NMEA GPS.

List every serial port the computer can currently see. Call this FIRST whenever the user wants to connect to a device but hasn't given an exact port name, or when a connection fails. Returns each port's system name (what you pass to `connect`), a human description, and the USB hardware id, so you can guess which one is the user's gear. Ports already open here are marked.

Report which program currently holds a serial port (macOS/Linux, via lsof). Use when connect says the port is in use, or before asking the user to close something. On Windows the OS doesn't expose this; the usual suspects are a terminal (PuTTY), WSJT-X, a logger, or the Arduino Serial Monitor.

Drive DTR or RTS to `level` for `ms` milliseconds, then restore it. Uses: reset an Arduino (DTR, 100 ms), enter a bootloader, or key a rig's PTT for a timed transmission (RTS or DTR per the interface's wiring). The line is always restored, even if the wait is interrupted. Refused in read-only mode.

Convenience: clear the buffer, send an ASCII command, and read the reply. For the common "ask the device something and read its answer" case. Reads until `prompt` (or the connection's prompt) appears; with no prompt anywhere, or prompt="", reads until the device goes idle for a short beat (best for line-based rigs/CAT that reply with a terminated string and no shell prompt). Args: data: Command text, e.g. "show version" or "ID". line_ending: "CR", "CRLF", "LF", or "NONE" (see send_text). Default: the connection's line ending. prompt: Literal prompt to read until, e.g. "# " or ";". "" forces an idle-terminated read even if the connection has a prompt. read_timeout: How long to wait overall, in seconds. connection: Which open connection (name). Default: the current one.

Drain and return whatever the device has sent, without transmitting anything. Use for unsolicited/streaming output (syslog on a console, GPS, a sensor, a rig in auto-info mode), or to grab a binary reply after `send_hex`. Waits up to `read_timeout` for the first bytes, then briefly settles so a full chunk is captured, then returns everything buffered, as text and as hex.

Read accumulated output until a prompt appears, or until timeout. This is the right tool for interactive CLI sessions (routers, switches, shells). It reads from the background buffer until `prompt` is seen, then returns everything up to and including it, leaving anything after the prompt in the buffer for the next read. Because the reader runs continuously, large multi-page outputs are captured in full rather than being cut off by a fixed delay. Typical flow: send_text("show version", clear_buffer_first=True) read_until_prompt(prompt="# ") Args: prompt: The text that marks the end of output. Literal by default, e.g. "# ", "> ", "login: ", "$ ", "Password:". Prefer a prompt with its trailing space over a bare "#": the match is searched in everything received, including the echo of your own command. Default: the connection's prompt (from connect/preset), else "ends with #, >, $ or %". timeout: Max seconds to wait for the prompt to appear. regex: Treat `prompt` as a Python regular expression (e.g. r"[\w.-]+[#>] ?$" for a hostname-style prompt). auto_reply: Text to send automatically when a trigger shows up while waiting, e.g. {"--More--": " "} to page through long output, or {"[confirm]": "\r"}. Each occurrence is answered once. connection: Which open connection (name). Default: the current one.

Reconnect to a remembered port with the same settings as last time. Every successful connect is remembered by name across sessions (port, baud, flow control, line ending, prompt, preset). With no `name`, reopens the most recently used one. Handy at the start of a chat so the user doesn't repeat the port and baud rate. If nothing is remembered, says to use `connect` instead.

Build a Yaesu GS-232A/B rotator command for send_text (CR) or query_text. Actions: "azimuth" (C, read), "position" (C2, read az+el), "elevation" (B), "move" (M<az>), "move_azel" (W<az> <el>), "stop"/"stop_azimuth"/ "stop_elevation", "left"/"right"/"up"/"down" (run until stop), "speed" (X1..X4), "help". Reads reply immediately; moves reply nothing, so read the position afterwards to confirm.

Decode a GS-232 reply into azimuth/elevation degrees ("+0180", "+0180+0045", "AZ=180 EL=045") or the ?> rejection.

Show the current terminal screen of a vt100/xterm connection: what a person at a real terminal would see right now, as rows of text, plus the cursor position. This is how to read full-screen interfaces (BIOS setup, RAID/BMC consoles, menu-driven switches, vi, top): press keys with send_keys, then look at the screen again. Args: reset: Clear the screen model first (after garbage, or a resize). connection: Which open connection (name). Default: the current one.

Send a BREAK condition (TX held low) for `ms` milliseconds. Some consoles use BREAK to enter ROMMON or interrupt boot; some serial devices use it as an attention signal. Refused in read-only mode.

Send raw bytes given as hex. Writes to TX only; does NOT read. Use for binary protocols — notably Icom CI-V, which is all hex (e.g. "FE FE 94 E0 03 FD"; civ_build makes these). Spaces in the hex string are ignored. To see a binary reply, call `read_available` afterward and hand the hex to civ_parse (binary replies rarely have a text prompt, so read_until_prompt usually isn't the right tool for these). Args: hex_bytes: Bytes as hex, e.g. "FE FE 94 E0 03 FD". clear_buffer_first: Discard buffered RX before sending. connection: Which open connection (name). Default: the current one.

Press keys by name, encoded the way a VT100/xterm terminal sends them. Use it for what send_text can't type: Ctrl-C to interrupt a running command (ping, monitor, a stuck process), Ctrl-Z, Esc, Tab (completion), arrows (history, menus), Enter alone, function keys, Page Up/Down. Each item is a key name ("ctrl-c", "esc", "tab", "enter", "up", "down", "left", "right", "home", "end", "pgup", "pgdn", "backspace", "delete", "f1".."f12", "space"), a single character, or "text:..." for a literal run. Nothing is read; follow with read_until_prompt, read_available, or screen.

Send an ASCII command to the device. Writes to TX only; does NOT read. On an interactive console the device will ECHO this text back and then print its output; call `read_until_prompt` (or `read_available`) afterward to see it. Use `clear_buffer_first=True` to discard any stale/unsolicited output so the next read starts clean. Args: data: The command text, e.g. "show version", "FA014250000", or "ID". Non-ASCII characters are sent as "?"; use send_hex for raw bytes. line_ending: What to append — "CR" (\r, most rigs), "CRLF" (\r\n), "LF" (\n, most Unix-style consoles), or "NONE". Default: the connection's line ending (from connect or its preset). clear_buffer_first: Discard buffered RX before sending. connection: Which open connection (name). Default: the current one.

Set the DTR and/or RTS output lines and hold them. Uses: key a transmitter whose PTT is wired to RTS or DTR (set it True to transmit, False to stop; pulse_line is safer for that), hold an Arduino in reset (DTR False), or tell a modem you're present. Leave a line at None to keep it unchanged. Refused in read-only mode.

Report every open port: settings, reader state, buffered bytes, control-line states, capture, and which connection is current. With nothing open, lists what reconnect_last remembers.