aidbg

A collection of lightweight debugging tools, each exposing its own MCP server so an AI can help you debug live hardware/systems over the Model Context Protocol.

Each tool is a standalone process: you start it, and the AI connects to its MCP endpoint as a client. The AI does not start anything by itself.

Layout

aidbg/
├── xserial/          # serial-port interactive terminal + MCP server
├── xrelay/           # 4-channel USB relay board MCP server
├── xcamera/          # camera MCP server (local preview + photo/frame capture)
└── ...               # more tools coming

Each subdirectory is self-contained (own README.md, own dependencies).

Hardware

The tools run against a physical debugging rig — the AIDBG 调试器 (AIDBG debugger): a fully-automatic debug fixture DIYed from off-the-shelf modules inside a 3D-printed enclosure. On the outside it only needs an external 12 V DC supply and a single USB Type-C cable to the host.

Internals:

• 12 V → 5 V DC-DC module
• 7-port USB hub — 2 ports are used by the devices below, the rest are free for the board under test (e.g. a USB-UART adapter for xserial)
• 4-channel USB relay board, driven by xrelay
• USB camera on a flexible gooseneck arm, driven by xcamera

Relay channels:

• 2 channels switch the external 12 V / 5 V power outputs (screw terminals on the front) to power-cycle the board under test
• 2 channels are reserved for simulating key presses and similar triggers

With xserial (serial console) + xrelay (power switching / key simulation)

• xcamera (visual feedback) over MCP, the AI can power-cycle a board, watch it through the camera and drive its console — fully automatic debugging.

MCP endpoints

Server	Description	Default endpoint
xserial	Shared serial session + interactive terminal	http://127.0.0.1:30000/mcp
xrelay	4-channel USB relay board (auto-finds its node)	http://127.0.0.1:30001/mcp
xcamera	Camera capture (photo + frame sequences)	http://127.0.0.1:30002/mcp (preview http://127.0.0.1:30003/)

Every server binds 0.0.0.0 by default, so it is reachable both locally and from other machines on your LAN. From another machine, replace 127.0.0.1 with this host's LAN IP, e.g. http://192.168.x.x:30002/mcp. Start any server with --host 127.0.0.1 to restrict it to this machine. There is no auth, so only expose these on networks you trust.

Connect an AI (opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "xserial": {
      "type": "remote",
      "url": "http://127.0.0.1:30000/mcp",
      "enabled": true
    },
    "xrelay": {
      "type": "remote",
      "url": "http://127.0.0.1:30001/mcp",
      "enabled": true
    },
    "xcamera": {
      "type": "remote",
      "url": "http://127.0.0.1:30002/mcp",
      "enabled": true
    }
  }
}

If a service isn't running, opencode can't fetch its tools. Have the AI call that server's status tool first (e.g. serial_info) to confirm it's up; if it fails, tell the AI to ask you to start the server.

Getting started

Pick a tool and follow its own README, e.g.:

cd aidbg
python3 -m venv .venv
.venv/bin/pip install mcp pyserial
.venv/bin/python xserial/xserial.py /dev/ttyUSB0 115200

Relay board (auto-finds the USB node; --device pins it):

.venv/bin/python xrelay/xrelay.py

Camera debugging (needs ffmpeg on PATH). Start it, then open the local preview to aim the camera at your board:

.venv/bin/pip install mcp
.venv/bin/python xcamera/xcamera.py    # preview: http://127.0.0.1:30003/

License

MIT, see LICENSE.