Skip to main content
Glama
bitshelf

Embedded Debug MCP

by bitshelf
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Remote

sermcp

Rust MCP server for embedded Linux DUT debugging. TCP direct to ser2net, strsim-based boot stage detection, self-learning reference log, relay/PDU power control, multi-DUT support, exponential backoff reconnect.

Hardware Setup — Dev Host

ser2net Configuration (no udev rules)

Serial access goes through ser2net on the dev host — its plain TCP-port → serial-device mapping, nothing else. No udev rules are needed.

# /etc/ser2net.yaml — port → serial device mapping (plain /dev/tty* paths)
connection: &con2000
    accepter: tcp,0.0.0.0,2000
    enable: on
    options:
      kickolduser: true          # prevent zombie connections
      telnet-brk-on-sync: true
    connector: serialdev,
              /dev/ttyACM0,
              115200n81,local                      # RK3576 default baud

Related MCP server: silotek-serial-mcp

Configuration Reference (.target.jsonc)

JSONC (JSON with // comments). A DUT nests inside its dev host and inherits ip/user/pass from the parent — names are display-only; the host ip is the linking key. Top-level sections (serial/relay/monitor/...) are global fallbacks; a DUT value overrides them. Unknown keys are rejected at parse time (typos fail loudly).

Full annotated schema: references/.target.jsonc.example. Create/update interactively with dutabo init — it preserves your comments.

Single Board

{
  "dev_hosts": [
    {
      "ip": "192.168.1.105",
      "user": "linaro",
      "duts": [
        {
          "dut_name": "rk3576-board1",
          "serial": { "port": 2000 },
          "target": {
            "login_user": "root",
            "login_prompt": ""         // custom login regex (empty = default: `login:\s*$`)
          },
          "uboot": {
            "interrupt_char": "ctrl_c",
            "interrupt_strategy": "flood"
          },
          "relay": {
            "type": "usb-relay",
            "port": 2001,
            "reset_ch": 1,
            // "maskrom_ch": 2,
            "reset_time_ms": 3000      // minimum USB relay reset pulse (default: 3000)
          },
          "monitor": {
            "hang_timeout": 60,
            "boot_window_secs": 30,   // booting → active deadline (default 30)
            "max_archived_logs": 10,
            "reference_log": ".dut-serial/rk3576-board1/reference-boot.log",
            // StageLearner similarity thresholds (0.0–1.0). Defaults from Cargo.toml.
            "learner_stage_threshold": 0.45,   // boot stage classification
            "learner_crash_threshold": 0.50    // crash pattern detection
          },
          "flash": {
            "tool": "upgrade_tool",
            "upload_dir": "/tmp",
            "full_image_cmd": "uf {image}",
            "kernel_image_cmd": "di -k {image}",
            "loader_bin": "/path/to/MiniLoaderAll.bin",
            "loader_cmd": "db {loader}"
          }
        }
      ]
    }
  ]
}

Multiple Boards

Add more entries to a host's duts array (or add another host). Each DUT gets:

  • Independent .dut-serial/<dut_name>/ directory

  • Independent target-state, statusline-cache, logs

  • Independent relay configuration

{
  "dev_hosts": [
    {
      "ip": "192.168.1.105",
      "user": "linaro",
      "duts": [
        {
          "dut_name": "rk3576-board1",
          "serial": { "port": 2000 }
          // ... config ...
        },
        {
          "dut_name": "rk3576-board2",
          "serial": { "port": 2008 },    // different port!
          "target": { "login_user": "root" },
          "monitor": { "reference_log": ".dut-serial/rk3576-board2/reference-boot.log" }
        }
      ]
    }
  ]
}

CLI (dutabo)

dutabo is a manual CLI tool for interactive debug. Install both binaries as static musl executables on x86_64 Linux:

rustup target add x86_64-unknown-linux-musl
cargo install --git https://github.com/bitshelf/sermcp --locked \
  --target x86_64-unknown-linux-musl --force

cargo install --git ignores the repository's .cargo/config.toml, so the explicit --target is required on GNU hosts. The musl target links its C runtime statically by default; the installed binaries do not require the system glibc or a dynamic loader. See Cargo configuration discovery. Verify with readelf -l ~/.cargo/bin/{sermcp,dutabo} (no INTERP) and readelf -d ~/.cargo/bin/{sermcp,dutabo} (no NEEDED).

Commands:

dutabo init                    # interactive JSONC config wizard (also creates/merges the sermcp entry in .mcp.json)
dutabo list                    # DUT table (name/host/user@ip/port/state) from .target.jsonc
dutabo list --json             # same data as machine-readable JSON (inventory schema)
dutabo serial [--dut <dut_name>]  # interactive serial console
dutabo reset [--dut <dut_name>]   # hardware reset
dutabo uf <image> [--dut]      # flash firmware
dutabo uboot [--dut <dut_name>]   # enter U-Boot
dutabo status [--dut <board_name>] # show board status

dutabo status also prints the code-agent sessions registered for the project, including each session ID, its owner/guest role, and start time.

Each project directory runs exactly one MCP process. Multiple code agents share that engine through HTTP sessions: the first code-agent session can operate the DUT, while later sessions can only call tools explicitly marked read-only and read resources, prompts, and task state. Mutating tool calls and task update/cancel requests return agent_read_only. dutabo remains the human control path and does not consume the code-agent owner slot.

Reference

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • serial-mcp

    alxgmpr
    A
    license
    A
    quality
    A
    maintenance
    MCP server that lets LLMs talk to serial devices: microcontrollers, routers, modems, embedded Linux, anything with a UART.
    23
    66 PyPI
    5
    MIT

  • silotek-serial-mcp

    JOCOIN94
    F
    license
    A
    quality
    B
    maintenance
    A headless MCP server that enables AI tools (like Claude Code) to read and analyze serial logs from embedded boards (ESP32, STM32) for firmware debugging, with read-only tools for log retrieval and a built-in web viewer.
    6
    -
  • sbl-probe by soundbytelabs

    sbl-probeofficial

    soundbytelabs
    A
    license
    Not graded
    quality
    C
    maintenance
    Serial communication and protocol analysis MCP server that gives AI coding assistants direct access to serial ports for reading, writing, decoding, and capturing embedded device output.
    MIT