adancurusul/serial-mcp-server

serial-mcp-server provides serial port access for AI workflows in two forms:
- MCP stdio server for clients that support MCP tools.
- Scriptable CLI for direct use, CI, and agent skills without MCP setup.
Current release target: 0.3.0.
Language versions: English | Chinese
0.3.0 Update Brief
- Added JSON Macro DSL automation for repeatable serial procedures.
- Added CLI macro commands: macro validate, macro list, macro plan, and macro run.
- Added MCP macro tools for runtime in-memory pack load/list/unload, plan, and run.
- Added explicit no-hardware simulation for macro validation, planning, and executor smoke tests.
- Kept Quick out of the public API. Quick-style use cases should be represented as macros.
Macro Automation
Use macros when a serial workflow is more than a single read or write. Many devices require a timed sequence: send a command, wait a few milliseconds, read until a prompt or acknowledgement appears, then send the next command. A macro pack records that procedure as JSON so a human, CLI script, or AI agent can validate it, inspect the plan, simulate it without hardware, and run it against a real port when a device is attached.
Typical macro use cases:
- Boot or provisioning flows that need ordered commands and delays.
- Protocol handshakes that must wait for OK, READY, PONG, prompts, or other expected responses.
- Regression smoke tests where the same serial procedure should run repeatedly.
- AI-assisted debugging where the agent should review the full send/delay/expect plan before touching hardware.
The v0.3 DSL is intentionally small:
- send: write UTF-8, hex, or base64 bytes.
- delay: wait for a fixed number of milliseconds.
- expect: read until the response contains or equals expected bytes.
- assembly: compose named macros into a longer workflow.
AI agents can discover macro support from this README, from the bundled skills/serial-debug skill, by running serial-mcp-server macro --help, or through MCP tool discovery when the server is configured. Agents that do not use MCP can still use the CLI plus the skill docs.
Requirements
- Rust 1.74 or newer.
- A serial device or USB-to-serial adapter when running hardware operations.
- Device drivers and OS permissions for the selected serial port.
Install From Source
The binary is built at:
To install the CLI onto your PATH from a checkout:
CLI Usage
Use the CLI when you want direct serial operations without an MCP client.
Capture Window Reads
timeout-ms keeps its original one-read meaning: wait up to that many
milliseconds for one read operation, then return as soon as bytes are available.
Use --duration-ms when an AI or script needs one bounded collection window.
Capture mode keeps reading internally and returns one combined response with
completion_reason, waited_ms, elapsed_ms, and per-chunk metadata.
Capture options:
- --duration-ms: collection window length after capture starts.
- --start-trigger first-byte: wait for the first byte before starting the
duration clock. This is the default for capture mode.
- --start-trigger immediate: start the duration clock when the command starts.
- --initial-timeout-ms: maximum wait for the first byte in first-byte mode.
If omitted, the command uses --timeout-ms.
- --idle-timeout-ms: stop after this many quiet milliseconds once capture has
started.
- --max-bytes: hard cap on the combined response bytes.
write --read accepts the same capture options after the write: