List available serial ports on the system.

Open a serial port connection. Returns a connection_id for use with other serial tools. The port stays open across tool calls until serial.close is called or the server exits. Defaults are 115200 baud, 8N1, \r\n line terminator — the most common settings. If you don't know the correct settings, check for a protocol spec with serial.spec.list or ask the user. Wrong baud rate is the most common cause of garbled data. After opening: 1) Use serial.spec.list to check for a matching protocol spec. If a match is found, attach it with serial.spec.attach. 2) Use serial.plugin.list to check for a plugin that matches the device. If a matching plugin is loaded, its tools are available to use directly. 3) Do a serial.read to check for any buffered data — many devices send a boot banner, prompt, or status message on connection.

Close a serial port connection and release the port.

Check whether a serial connection is still open and return its configuration.

Read up to nbytes from a serial port. Returns immediately with whatever data is available within the timeout. Use serial.readline or serial.read_until for line-oriented reads.

Write data to a serial port. Returns the number of bytes written.

Read a line from the serial port (reads until the newline character is received or max_bytes is reached). Uses the connection's newline setting by default.

Read from the serial port until a delimiter string is received or max_bytes is reached.

Flush serial port buffers (discard pending input/output data).

Set the DTR (Data Terminal Ready) control line. Usage is device-specific — check the protocol spec or ask the user.

Set the RTS (Request To Send) control line. Usage is device-specific — check the protocol spec or ask the user.

Pulse the DTR line: sets low, waits duration_ms, then sets high. Commonly used to reset microcontrollers (e.g. Arduino, ESP32). Check the protocol spec or ask the user before pulsing — effect is device-specific.

Pulse the RTS line: sets low, waits duration_ms, then sets high. Some devices use RTS to enter bootloader mode. Check the protocol spec or ask the user before pulsing — effect is device-specific.

List all open serial connections with their status, port, configuration, and timestamps. Useful for recovering connection IDs after context loss.

Return a markdown template for a new serial protocol spec. Optionally pre-fill with a device name.

Register a spec file in the index. Validates YAML front-matter (requires kind: serial-protocol and name). The file path can be absolute or relative to CWD.

List all registered specs with their metadata and matching hints.

Attach a registered spec to a connection session (in-memory only). The spec will be available via serial.spec.get for the duration of this connection. After attaching, check serial.plugin.list for a matching plugin, then present the user with their options: interact with the device using the spec (send commands, execute flows), use plugin shortcut tools if a plugin is loaded, extend an existing plugin with new tools, or create a new plugin using serial.plugin.template.

Get the attached spec for a connection (returns null if none attached).

Read full spec content, file path, and metadata by spec_id.

Full-text search over a spec's content. Returns matching snippets with line numbers and surrounding context.

Return tracing config and event count.

Return last N trace events (default 50).

List loaded plugins with their tool names and metadata. Each plugin may include a 'meta' dict with matching hints like device_name_contains or description — use these to determine which plugin fits the connected device. Also returns whether plugins are enabled and the current policy. Plugins require SERIAL_MCP_PLUGINS env var — set to 'all' for all or 'name1,name2' to allow specific plugins. If disabled, tell the user to set this variable when adding the MCP server.

Hot-reload a plugin by name. Re-imports the module and refreshes tools. Requires SERIAL_MCP_PLUGINS env var to be set.

Return a Python plugin template. Use this when creating a new plugin. Optionally pre-fill with a device name. Save the result to .serial_mcp/plugins/.py, fill in the tools and handlers, then load with serial.plugin.load.

Load a new plugin from a file or directory path. Requires SERIAL_MCP_PLUGINS env var to be set.