<!-- mcp-name: io.github.soundbytelabs/probe -->

sbl-probe

Serial communication and protocol analysis MCP server. Gives AI coding assistants direct access to serial ports for reading, writing, decoding, and capturing embedded device output — no more copy-pasting from picocom.

Part of the Sound Byte Labs embedded tooling suite, alongside sbl-debugger for hardware debugging.

Installation

Create a virtual environment and install the package:

python3 -m venv .venv
source .venv/bin/activate

# Install
pip install -e .

# Or with test dependencies
pip install -e ".[dev]"

MCP Configuration

Register the server in your MCP client's config. For most clients, add to .mcp.json in your project root:

{
  "mcpServers": {
    "sbl-probe": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "sbl_probe"]
    }
  }
}

Important: Use the absolute path to the Python binary inside your virtual environment. For example: /home/you/sbl-probe-mcp/.venv/bin/python

Restart your MCP client and the tools are available immediately.

Tools

Connection Management

Tool	Description
list_ports	List available serial ports with USB metadata and by-id paths
open	Open a serial connection (port, baud, optional name)
close	Close a named connection
connections	List active connections with stats

Data I/O

Tool	Description
read	Read decoded frames using the active decoder (line-oriented by default)
read_raw	Read raw bytes in utf8, hex, or base64
write	Write data to a connection

Protocol Analysis

Tool	Description
set_decoder	Change the active decoder on a connection
decode_buffer	Run a decoder over a raw data buffer
list_decoders	List available decoder names
probe_baud	Auto-detect baud rate by scoring printable text across common rates

Capture & Replay

Tool	Description
capture_start	Start background capture into a ring buffer (with optional filter, trigger, pretrigger)
capture_stop	Stop capture, return summary stats
capture_read	Query captured frames (filter by regex, time range, last N)
capture_stats	Get frame counts grouped by pattern without reading all frames
capture_save	Save capture buffer to a JSON Lines file
capture_load	Load a previously saved capture

Architecture

sbl_probe/
├── server.py          # FastMCP server, tool wiring
├── transport/
│   ├── base.py        # Transport protocol (structural typing)
│   ├── serial.py      # pyserial wrapper
│   └── manager.py     # Named connection registry
├── decoders/
│   ├── base.py        # Frame dataclass + Decoder protocol
│   └── raw.py         # Line-oriented decoder
├── capture/
│   ├── buffer.py      # Thread-safe ring buffer with query support
│   ├── engine.py      # Background reader thread
│   └── storage.py     # JSON Lines save/load
└── tools/
    ├── connection.py   # list_ports, open, close, connections
    ├── data.py         # read, read_raw, write
    ├── protocol.py     # set_decoder, decode_buffer, list_decoders
    ├── capture.py      # capture_start/stop/read/stats/save/load
    └── diagnostics.py  # probe_baud

Key design decisions:

• Threaded pyserial with asyncio.to_thread() — keeps the MCP event loop responsive without the complexity of pyserial-asyncio
• Pluggable decoders — register new decoders by name, swap at runtime via set_decoder
• Background capture — daemon thread feeds decoded frames into a ring buffer; query with regex, time range, or tail the last N frames
• Ingress filtering — filter and trigger patterns on capture_start keep the buffer focused on what matters
• Error dicts, not exceptions — tools return {"error": "..."} instead of crashing the server

Adding a Custom Decoder

from sbl_probe.decoders.base import Frame, Decoder
from sbl_probe.decoders import registry

class MyDecoder:
    @property
    def name(self) -> str:
        return "my_proto"

    def feed(self, data: bytes, timestamp: float) -> list[Frame]:
        # Parse data, return frames
        ...

    def reset(self) -> None:
        ...

registry.register("my_proto", MyDecoder)

Running Tests

pytest                    # 113 tests
pytest -v                 # verbose
pytest tests/test_capture.py  # just capture tests

Dependencies

• mcp — Official Python MCP SDK (FastMCP)
• pyserial — Serial port access
• Python >= 3.11