rsp2k/mcserial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcserial/README.md
Ryan Malloy dc8caddb8f Add Starlight documentation site with full content 
Astro 5 + Starlight docs site with 17 pages covering all 30 mcserial
tools. Structured using Diataxis framework: tutorials, guides, reference,
and concepts. Includes Docker + caddy-docker-proxy deployment for
mcserial.l.zmesh.systems with HMR support behind reverse proxy.

Content pages:
- Landing page with feature overview and quick start
- Tutorials: getting started, loopback testing (loop://)
- Guides: RS-232 basics, RS-485/Modbus, file transfers, network ports
- Reference: common tools, RS-232 tools, RS-485 tools, file transfer
  tools, URL schemes, MCP resources, environment variables
- Concepts: RS-232 vs RS-485, flow control
2026-02-02 22:01:48 -07:00

191 lines
6.2 KiB
Markdown
Raw Blame History

# MCP Serial Server
FastMCP server for serial port access via Model Context Protocol.
## Features
- **RS-232 Mode**: Full modem control (RTS, DTR, CTS, DSR, RI, CD, break condition)
- **RS-485 Mode**: Half-duplex bus communication with auto direction control
- **File Transfer**: X/Y/ZMODEM protocols for reliable file transfers
- **Auto-baud Detection**: Smart detection using 0x55 sync pattern analysis
- **URL Handlers**: Open remote/virtual ports (`socket://`, `rfc2217://`, `loop://`, `spy://`, `cp2110://`)
- **Dynamic Resources**: Read data via `serial://{port}/data`
- Full pyserial support (baudrate, parity, stop bits, flow control)
## Installation
```bash
# With uvx (recommended)
uvx mcserial
# Or install directly
uv pip install mcserial
# With CP2110 HID-to-UART support
uv pip install mcserial[cp2110]
```
## Usage with Claude Code
```bash
# Add to Claude Code
claude mcp add mcserial "uvx mcserial"
```
## Modes
Ports open in **RS-232 mode** by default. Switch with `set_port_mode()`:
| Mode | Use Case | Tools |
|------|----------|-------|
| RS-232 | Point-to-point serial | `get_modem_lines`, `set_modem_lines`, `pulse_line`, `send_break` |
| RS-485 | Multi-drop bus (Modbus) | `set_rs485_mode`, `rs485_transact`, `rs485_scan_addresses` |
## Tools
### Common (both modes)
| Tool | Description |
|------|-------------|
| `list_serial_ports` | Discover available ports (supports `grep` regex filtering) |
| `open_serial_port` | Open connection — local device or URL scheme (auto-detects baud if not specified) |
| `close_serial_port` | Close a connection |
| `set_port_mode` | Switch between RS-232 and RS-485 modes |
| `write_serial` | Send text data |
| `write_serial_bytes` | Send raw bytes (atomic single-syscall write) |
| `read_serial` | Read available data |
| `read_serial_line` | Read until newline |
| `read_serial_lines` | Batch read multiple lines |
| `read_until` | Read until custom terminator |
| `configure_serial` | Change port settings |
| `flush_serial` | Clear buffers |
| `cancel_read` | Interrupt pending read operation |
| `cancel_write` | Interrupt pending write operation |
| `set_flow_control` | Manually gate XON/XOFF or RTS/CTS flow |
| `set_low_latency_mode` | Enable kernel low-latency mode (Linux) |
| `get_connection_status` | List open connections with mode |
| `detect_baud_rate` | Auto-detect baud rate |
### RS-232 Mode
| Tool | Description |
|------|-------------|
| `get_modem_lines` | Read CTS, DSR, RI, CD, RTS, DTR states + break condition |
| `set_modem_lines` | Control RTS and DTR outputs |
| `pulse_line` | Pulse RTS/DTR for reset sequences |
| `send_break` | Send timed break signal |
| `set_break_condition` | Hold/release break state |
### RS-485 Mode
| Tool | Description |
|------|-------------|
| `set_rs485_mode` | Configure hardware RS-485 (DE/RE control) |
| `check_rs485_support` | Detect hardware RS-485 capability |
| `rs485_transact` | Send/receive with automatic turnaround |
| `rs485_scan_addresses` | Scan bus for responding devices |
### File Transfer
| Tool | Description |
|------|-------------|
| `file_transfer_send` | Send file via XMODEM/YMODEM/ZMODEM |
| `file_transfer_receive` | Receive file via XMODEM/YMODEM/ZMODEM |
| `file_transfer_send_batch` | Send multiple files (YMODEM/ZMODEM) |
**Protocols:**
- `xmodem` - 128-byte blocks, simple (1977)
- `xmodem1k` - 1024-byte blocks
- `ymodem` - Batch mode with filename/size
- `zmodem` - Streaming, auto-resume (recommended)
## URL Handlers
The `open_serial_port` tool accepts URL schemes in addition to local device paths:
| Scheme | Description | Example |
|--------|-------------|---------|
| `socket://` | Raw TCP socket — serial-to-ethernet bridges | `socket://192.168.1.100:4001` |
| `rfc2217://` | Telnet COM Port Control — remote baud/flow config | `rfc2217://192.168.1.100:2217` |
| `loop://` | Loopback — writes echo back as reads (testing) | `loop://` |
| `spy://` | Debug wrapper — logs all traffic to stderr | `spy:///dev/ttyUSB0` |
| `cp2110://` | Silicon Labs HID-to-UART (requires `[cp2110]` extra) | `cp2110://` |
| `hwgrep://` | Open first port matching hardware pattern | `hwgrep://FTDI` |
| `alt://` | Alternate port backend | `alt:///dev/ttyUSB0` |
URL-opened ports skip auto-baud detection and exclusive access (not applicable to virtual/network ports).
## Resources
| URI | Description |
|-----|-------------|
| `serial://ports` | List available ports |
| `serial://{port}/data` | Read data from open port |
| `serial://{port}/status` | Port config and mode |
| `serial://{port}/raw` | Read as hex dump |
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `MCSERIAL_DEFAULT_BAUDRATE` | 9600 | Default baud rate |
| `MCSERIAL_DEFAULT_TIMEOUT` | 1.0 | Read timeout (seconds) |
| `MCSERIAL_MAX_CONNECTIONS` | 10 | Max concurrent ports |
## Example Workflows
### Basic RS-232
```
1. list_serial_ports() → find /dev/ttyUSB0
2. open_serial_port(port="/dev/ttyUSB0") # auto-detects baud
3. write_serial_bytes(port="/dev/ttyUSB0", data=[65, 84, 13, 10]) # AT\r\n
4. read_serial_lines(port="/dev/ttyUSB0") # batch read response
5. close_serial_port(port="/dev/ttyUSB0")
```
### Filter Ports by Hardware
```
1. list_serial_ports(grep="FTDI") # find all FTDI devices
2. list_serial_ports(grep="CP210") # find Silicon Labs adapters
3. list_serial_ports(grep="VID:PID=0403:6001") # exact USB ID match
```
### RS-485 Modbus
```
1. open_serial_port(port="/dev/ttyUSB0", baudrate=9600)
2. set_port_mode(port="/dev/ttyUSB0", mode="rs485")
3. rs485_scan_addresses(port="/dev/ttyUSB0") # discover devices
4. rs485_transact(port="/dev/ttyUSB0", data="\x01\x03...")
```
### Network Serial (serial-to-ethernet bridge)
```
1. open_serial_port(port="socket://192.168.1.100:4001", baudrate=115200)
2. write_serial(port="socket://192.168.1.100:4001", data="AT\r\n")
3. read_serial(port="socket://192.168.1.100:4001")
```
### Loopback Testing (no hardware needed)
```
1. open_serial_port(port="loop://", baudrate=9600)
2. write_serial(port="loop://", data="hello")
3. read_serial(port="loop://") # → "hello"
4. close_serial_port(port="loop://")
```
### File Transfer
```
1. open_serial_port(port="/dev/ttyUSB0", baudrate=115200)
2. file_transfer_send(port="/dev/ttyUSB0", file_path="firmware.bin")
```
## License
MIT
Reference in New Issue View Git Blame Copy Permalink