Embedded AI Debug

A VSCode extension with two features for embedded development:

1. MCP Bridge — exposes a local MCP server so AI assistants like Claude Code can read live debug state (variables, registers, memory) from Cortex-Debug and PlatformIO sessions.
2. Peripheral Tester — configure and drive GPIO, SPI, I2C, USART, CAN, RTC, PWM directly via OpenOCD, without any firmware on the chip.

STM32 / ARM MCU  ──(ST-Link/JTAG)──  Cortex-Debug  ──(DAP)──  Extension  ──(MCP/SSE)──  Claude Code

Quick Start

1. Install the extension from the VS Code Marketplace (Embedded AI Debug — publisher: paulopalaoro)
2. Create a .mcp.json file in your project root (or run Ctrl+Shift+P → AI Debug: Copy .mcp.json config to clipboard)
3. Start the MCP server manually: Ctrl+Shift+P → AI Debug: Start Bridge Server
4. Start a Cortex-Debug or PlatformIO debug session — the server starts automatically from this point on
5. Verify: status bar shows $(debug-alt) MCP :7580 and http://localhost:7580/health returns {"status":"ok"}

Note: The server starts automatically on VS Code startup and on every debug session. Use AI Debug: Start Bridge Server only if you need to start it manually.

Available Commands (Ctrl+Shift+P)

What it does

When you pause the target at a breakpoint, Claude Code can call these tools directly:

Requirements

• VSCode 1.85+
• Cortex-Debug or PlatformIO IDE
• Claude Code (or any MCP-compatible client)
• An ST-Link, J-Link, or CMSIS-DAP probe connected to your target

Installation

Option A — Build from source

git clone https://github.com/your-org/cortex-mcp-bridge
cd cortex-mcp-bridge
npm install
npm run build
npm run package         # creates cortex-mcp-bridge-0.1.0.vsix
code --install-extension cortex-mcp-bridge-0.1.0.vsix

Option B — Install from VSIX

Download the .vsix from the Releases page and run:

code --install-extension cortex-mcp-bridge-0.1.0.vsix

Setup

1. Create .mcp.json in your project root

{
  "mcpServers": {
    "cortex-debug": {
      "type": "sse",
      "url": "http://localhost:7580/sse"
    }
  }
}

Tip: Run Ctrl+Shift+P → AI Debug: Copy .mcp.json config to clipboard to generate this snippet automatically with the correct port.

2. Start a debug session

The extension starts the MCP server automatically when a Cortex-Debug or PlatformIO debug session begins. You can also start it manually via:

Ctrl+Shift+P → AI Debug: Start Bridge Server

3. Verify

Check the status bar — it shows $(debug-alt) MCP :7580 when the server is running.

Open a browser and visit http://localhost:7580/health — you should see {"status":"ok"}.

Usage with Claude Code

Once connected, Claude Code can interact with your hardware directly. Examples:

"What are the current values of pitch, roll, and yaw_rate?"
→ Claude calls get_variables → reads live RAM values

"Read 16 bytes from rxBuf"
→ Claude calls evaluate("&rxBuf[0]") to get address, then get_memory

"Set a breakpoint at line 59 of main.cpp and continue"
→ Claude calls set_breakpoint + continue_execution

"Step through the loop 5 times and report how rxLen changes"
→ Claude calls step + get_variables in a loop

Settings

Architecture

extension.ts          — VSCode lifecycle, commands, status bar
mcpServer.ts          — HTTP server with SSE transport (MCP protocol)
dapBridge.ts          — All DAP calls via vscode.debug.activeDebugSession
tools/
  getSessionInfo.ts   — Session status check
  getCallStack.ts     — stackTrace DAP request
  getVariables.ts     — scopes + variables DAP requests
  expandVariable.ts   — variables (children) DAP request
  getRegisters.ts     — read-registers (Cortex-Debug custom)
  getMemory.ts        — read-memory (Cortex-Debug custom)
  evaluate.ts         — evaluate DAP request
  setBreakpoint.ts    — setBreakpoints DAP request
  continueExecution   — continue DAP request
  pauseExecution      — pause DAP request
  stepOver.ts         — next / stepIn / stepOut DAP requests
  gdbCommand.ts       — execute-command (Cortex-Debug custom)

Limitations

• Most tools require the target to be paused (halted at a breakpoint or manually paused). The Cortex-Debug adapter rejects read requests while the MCU is running.
• The get_registers and get_memory tools use Cortex-Debug custom DAP commands — they work with cortex-debug and platformio-debug session types only.
• Tested with STM32 targets. Should work with any ARM Cortex-M target supported by Cortex-Debug.

License

MIT