EM-Debug

Next-Generation Embedded Debugger Suite Built on probe-rs

A unified, zero-toolchain debugging solution: Full-featured VS Code extension for humans + 37 MCP tools for AI agents.

🌟 Highlights

• Zero-Toolchain Setup: Powered by an automatic cross-platform probe-rs binary resolver (ProbeRsBinaryManager). No external GDB, OpenOCD, Python, or proprietary vendor drivers required.

• Single-Connection Session Hub: Eliminates the classic USB probe exclusivity conflict (Device is busy). Human developers in VS Code and AI Agents over MCP share the exact same hardware session.

• 37 Production-Grade MCP Tools: Full suite inherited and upgraded from cortex-debug-mcp, providing execution control, memory inspection, live CoreSight AP access, and firmware-free peripheral bringup.

• Intelligent Crash Diagnostics: Native ARMv7-M capture_fault tool decodes EXC_RETURN, stacked exception frames, and SCB fault status registers (CFSR, HFSR, MMFAR, BFAR) to pinpoint the exact crash source line in milliseconds.

• Dual-Mode Operation:

  • Collaborative Mode: Embedded within the VS Code extension host; F5 debug sessions are instantly queryable by connected AI agents.

  • Headless Mode: Standalone CLI runtime (npx @em-debug/mcp-server) for automated CI/CD and terminal agents.

• Broad Hardware Support: First-class support for ARM Cortex-M (M0 through M55) and RISC-V (RV32/RV64) via J-Link, CMSIS-DAP/DAPLink, ST-Link (v2/v3), FTDI, and ESP32 USB-JTAG.

Related MCP server: dbgprobe-mcp-server

🏗️ Architecture

                       +-----------------------------------+
                       |         Target Board (MCU)        |
                       |       (ARM Cortex-M / RISC-V)     |
                       +-----------------+-----------------+
                                         | SWD / JTAG
                       +-----------------+-----------------+
                       |    Hardware Probe (J-Link / DAP)   |
                       +-----------------+-----------------+
                                         | USB (Exclusive Owner)
                       +-----------------+-----------------+
                       |       probe-rs dap-server         |
                       +-----------------+-----------------+
                                         | DAP JSON-RPC
                       +-----------------+-----------------+
                       |   Session Hub (Single State Hub)  |
                       +--------+-----------------+--------+
                                |                 |
                 Internal DAP   |                 | MCP JSON-RPC
                                v                 v
              +-------------------+     +-------------------+
              |  VS Code Extension|     |     MCP Server    |
              |  - SVD Tree View  |     |  - Streamable HTTP|
              |  - RTT Terminal   |     |  - stdio proxy    |
              |  - Debug Adapter  |     |  - 37 AI Tools    |
              +-------------------+     +-------------------+

🚀 Quick Start

1. Prerequisites

• Node.js >= 20.0.0

• pnpm >= 9.0.0

2. Build from Source

git clone https://github.com/RoadToSea/em-probe.git
cd em-debug
pnpm install
pnpm build
pnpm test

3. Launching the Headless MCP Server

Streamable HTTP (Default: http://127.0.0.1:7580/mcp)

node packages/mcp-server/bin/em-debug-mcp.js --port=7580

Stdio Mode (for Claude Code, Cursor, etc.)

node packages/mcp-server/bin/em-debug-mcp.js --stdio

🔌 Connecting AI Agents

Claude Code CLI

Add to your ~/.claude.json or project configuration:

{
  "mcpServers": {
    "em-debug": {
      "command": "node",
      "args": ["D:/Vscode/code/em-debug/packages/mcp-server/bin/em-debug-mcp.js", "--stdio"]
    }
  }
}

Cursor / Windsurf / Antigravity (Streamable HTTP)

Connect to the loopback HTTP endpoint when the VS Code extension or headless server is running:

{
  "mcpServers": {
    "em-debug": {
      "url": "http://127.0.0.1:7580/mcp"
    }
  }
}

📦 Package Workspace Structure

📖 Documentation

• 📐 DESIGN.md — Comprehensive architecture design specification and protocol contracts.

• 🗺️ docs/ARCHITECTURE.md — Architectural component mapping and sequence flows.

• 🔬 docs/PROBE_RS_ANALYSIS.md — In-depth comparison with official probe-rs ecosystem and design pattern adoption.

• 🛠️ docs/TOOLS.md — Complete reference manual for all 37 MCP tools with schemas and examples.

• 💻 docs/DEVELOPMENT.md — Local development environment setup and extension packaging.

• 🤝 CONTRIBUTING.md — Contribution guidelines and pull request process.

• 📜 CHANGELOG.md — Project release history and upgrade notices.

📄 License

This project is licensed under the MIT License.