Embedded Debug MCP Server

架构

                         ┌────────────────────────┐
                         │    Ethernet Switch     │
                         └─┬──────┬──────┬──────┬┘
                           │      │      │      │
                  Ethernet │      │      │      │ Ethernet
                           │      │      │      │
          ┌────────────────┘      │      │      └──-───────────────────────────┐
          │                       │      └───-───-───┐                         │
          ▼                       ▼                  ▼                         ▼

┌──────────────────┐   ┌──────────────────┐   ┌───────────────┐         ┌──────────────────┐
│ Windows PC       │   │ Build Machine    │   │ ARM           │──UART───│ Target Board     │
│                  │   │ Linux x86        │   │               │──USB────│                  │
│ SSH / Client     │   │                  │   │               │.........│ ○ RECOVERY       │
│                  │   │ Claude Code      │   │ ser2net       │─────────│ ○ RESET          │
│                  │   │ MCP Server       │   │ USB Host      │.........│ ○ Power          │
└──────────────────┘   └──────────────────┘   └───────────────┘         └──────▲────▲──────┘

工作流

1. 构建         cargo install --git https://github.com/bitshelf/sermcp --locked --target x86_64-unknown-linux-musl
2. 配置         dutabo init              (在项目根目录；或 vi .target.jsonc)
3. 部署         vi .mcp.json             (或依赖 hook)
4. 启动         claude                   (Claude Code 自动 spawn MCP Server)
5. 使用         serial_send_command "uname -a"
6. 查看日志     tail -f .dut-serial/mcp.log

Related MCP server: Board Terminal Skill

使用方法

在项目根目录创建 .target.jsonc，用 dutabo init 交互式创建/更新, 可以使用图形界面进行测试。 .mcp.json 缺失或没有sermcp 条目时，dutabo init 会自动创建/补齐该条目（已有条目则原样保留）。

• .mcp.json

{
  "mcpServers": {
    "sermcp": {
      "command": "sermcp",
      "args": []
    }
  }
}

# 确认项目有 .target.jsonc
ls -la .target.jsonc .mcp.json

# 启动 Claude Code 后查看状态栏
# 成功时会显示: ● serial:active 或 ● serial:disconnected

日志

• 运行时日志写入 {project}/.dut-serial/mcp.log。

• 串口数据日志写入 {project}/.dut-serial/logs/boot-NNN_*.log。

多 Agent 共享与占用状态（busy / dutabo）

多个代码 Agent 在同一项目打开时共享一个 MCP server。第一个 Agent 会话是 Owner，后续会话是 ReadOnly guest。

• dutabo — dutabo serial 交互会话持有串口；对所有会话生效（引擎状态 机真实转移到 Dutabo）；

• busy — 另一个 Agent 会话持有 MCP，本会话只读（控制类工具被 agent_read_only 拒绝）；

故障排除

构建

rustup target add x86_64-unknown-linux-musl
cargo musl

测试

# 运行全部单元测试（在仓库根目录执行）
cargo test -p sermcp

# 运行特定模块测试
cargo test -p sermcp boot_detector
cargo test -p sermcp command_queue
cargo test -p sermcp mcp

# 查看测试覆盖率报告
cargo test -p sermcp -- --nocapture

dutabo serial 日志回滚

交互模式连接 MCP 时，会先回放 MCP 内存中最近至多 512 KiB 的串口日志，再接收实时输出。本地终端保留最多 10,000 行滚动历史；MCP 重启前或超出窗口的日志请查看 full.serial.log。直接连接 ser2net 时，仅能回滚本次连接收到的输出。

• 鼠标滚轮或 Alt+PgUp/PgDn：向上/向下查看日志。

• Alt+Home/End：最早的历史/实时输出。

• 主机拦截翻页键时，使用 Ctrl-T 后按 u/d 翻页，按 g/G 跳到最早历史/实时输出。

• Ctrl-T q：退出；原有 Ctrl-T PgUp/PgDn 和 Shift+PgUp/PgDn 仍可用。

向上滚动后，新输出默认保持阅读位置。普通 PgUp/PgDn 仍发送给设备；设备上的 vim/less 等全屏程序仍由滚轮控制。非交互管道输出不回放历史。历史回放需要配套更新 MCP 服务端。

串口日志分段

current.serial.log 保存当前启动周期的原始输出，full.serial.log 连续追加。收到下一次启动的 DDR/SPL 前缀时，前一个周期归档为 boot-NNN_*.log，前缀归入新的当前日志；文件名时间是归档时刻。连接时设备已运行的首段可能只有部分周期。dutabo serial 直接接管 ser2net 的路径也保存到该 DUT 的日志目录。dutabo serial 占用期间仍保存和分段，但不会执行 Agent 自动登录等动作。

归档读取完整磁盘文件，不受 2 MiB 内存缓冲限制；MCP 重启继续追加当前文件。重置请求本身不切段，按实际收到的启动前缀划分；没有可识别前缀的启动无法保证自动分段。默认只保留最近 10 个归档，可用 .target.jsonc 的 monitor.max_archived_logs 调整；full.serial.log 不参与归档清理。

Supply power and the sleep/wake key

Relay power_ch controls supply OFF/ON. serial_power_cycle cuts supply power, waits for power_off_time_ms (at least 3000 ms), then restores it. Relay power_key_ch (alias power_key_channel) controls the separate momentary power key used for sleep/wake. Configure it on its own relay channel, for example:

"relay": {
  "type": "ch340-relay",
  "port": 2000,
  "power_ch": 3,
  "power_key_ch": 4,
  "power_off_time_ms": 3000
}

Use dutabo button power_key pulse 500 for a short key press, or call serial_button with {"button":"power_key","action":"pulse","delay_ms":500}. press and release are also supported. Key pulses use the requested duration (default 500 ms) without the supply-off minimum. The board's OS determines whether the press sleeps, wakes, or performs another configured power-key action; a successful relay operation does not confirm the OS state. dutabo init provides separate power and power key rows. Channel 0 inherits the global channel, consistent with the other relay channels. dev_ctrl=none or disabled disables both controls. Restart the MCP server after changing its configuration.