# EM-Debug

<div align="center">

**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.*

[![CI](https://github.com/RoadToSea/em-probe/actions/workflows/ci.yml/badge.svg)](https://github.com/RoadToSea/em-probe/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js Version](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
[![pnpm](https://img.shields.io/badge/pnpm-%3E%3D9.0.0-orange.svg)](https://pnpm.io/)
[![probe-rs](https://img.shields.io/badge/probe--rs-v0.27.0-purple.svg)](https://probe-rs.com/)
[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP%20%7C%20stdio-cyan.svg)](https://modelcontextprotocol.io/)

</div>

---

## 🌟 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](https://github.com/your-username/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.

---

## 🏗️ 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
```bash
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`)
```bash
node packages/mcp-server/bin/em-debug-mcp.js --port=7580
```

#### Stdio Mode (for Claude Code, Cursor, etc.)
```bash
node packages/mcp-server/bin/em-debug-mcp.js --stdio
```

---

## 🔌 Connecting AI Agents

### Claude Code CLI
Add to your `~/.claude.json` or project configuration:
```json
{
  "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:
```json
{
  "mcpServers": {
    "em-debug": {
      "url": "http://127.0.0.1:7580/mcp"
    }
  }
}
```

---

## 📦 Package Workspace Structure

| Package | Directory | Description |
| :--- | :--- | :--- |
| **`@em-debug/probe-rs-core`** | [`packages/probe-rs-core`](packages/probe-rs-core) | Core probe-rs binary resolution, DAP protocol client, and session management hub. |
| **`@em-debug/svd-parser`** | [`packages/svd-parser`](packages/svd-parser) | CMSIS-SVD XML model parser with peripheral inheritance and bitfield decoder. |
| **`@em-debug/mcp-server`** | [`packages/mcp-server`](packages/mcp-server) | Standalone and embedded MCP server exposing 37 embedded debugging tools. |
| **`em-debug`** | [`packages/vscode-extension`](packages/vscode-extension) | VS Code frontend extension hosting the DAP proxy, SVD TreeView, and RTT terminal. |

---

## 📖 Documentation

* 📐 **[DESIGN.md](DESIGN.md)** — Comprehensive architecture design specification and protocol contracts.
* 🗺️ **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — Architectural component mapping and sequence flows.
* 🔬 **[docs/PROBE_RS_ANALYSIS.md](docs/PROBE_RS_ANALYSIS.md)** — In-depth comparison with official probe-rs ecosystem and design pattern adoption.
* 🛠️ **[docs/TOOLS.md](docs/TOOLS.md)** — Complete reference manual for all 37 MCP tools with schemas and examples.
* 💻 **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** — Local development environment setup and extension packaging.
* 🤝 **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution guidelines and pull request process.
* 📜 **[CHANGELOG.md](CHANGELOG.md)** — Project release history and upgrade notices.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).