Cortex-Debug AI

Built on top of Cortex-Debug — this extension extends the excellent work of Marcel Ball and the Cortex-Debug contributors (MIT-licensed) with AI-specific integrations. Cortex-Debug remains the foundation that handles the ARM Cortex debug protocol; Cortex-Debug AI adds an MCP bridge and a peripheral tester on top. Full attribution and licence text: see NOTICE.

A VSCode extension with two AI-focused features for embedded development:

1. MCP Bridge for Claude Code — exposes a local Model Context Protocol server so AI assistants can read live debug state (variables, registers, memory, call stack) from an active Cortex-Debug session.
2. Peripheral Tester — drive GPIO, SPI, I2C, USART, CAN, RTC, PWM through a persistent GDB/MI channel (same one Cortex-Debug uses), letting Claude Code configure and test peripherals directly.

STM32 / ARM MCU  ──(ST-Link/JTAG)──  Cortex-Debug  ──(GDB-MI)──  Cortex-Debug AI  ──(MCP)──  Claude Code

Quick Start

1. Install Cortex-Debug (required dependency).
2. Install Cortex-Debug AI from the VS Code Marketplace (publisher: paulopalaoro).
3. Create a .mcp.json file in your project root (or run Ctrl+Shift+P → AI Debug: Copy .mcp.json config to clipboard).
4. Start the MCP server manually: Ctrl+Shift+P → AI Debug: Start Bridge Server.
5. Start a Cortex-Debug or PlatformIO debug session — the server connects automatically.
6. 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/paulopalaoro/cortex-mcp-bridge
cd cortex-mcp-bridge
npm install
npm run build
npm run package         # creates embedded-ai-debug-x.y.z.vsix
code --install-extension embedded-ai-debug-x.y.z.vsix

Option B — Install from VSIX

Download the .vsix from the Releases page and run:

code --install-extension embedded-ai-debug-x.y.z.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.

Credits & Acknowledgments

Cortex-Debug AI stands on the shoulders of giants. In particular:

• Cortex-Debug by Marcel Ball and contributors — this project's foundation. Cortex-Debug AI extends Cortex-Debug's architecture and re-uses adapted portions of its GDB/MI backend code. See NOTICE for the full MIT licence text and attribution.
• OpenOCD — the open-source on-chip debugger.
• PlatformIO — development environment that makes STM32 accessible.
• Model Context Protocol by Anthropic — the protocol that lets Claude Code speak to external debug state.

If you appreciate this extension, please also star Cortex-Debug — none of this would exist without their work.

License

MIT — see LICENSE.txt.

This project includes code derived from Cortex-Debug (MIT, © Marcel Ball). See NOTICE for the full attribution.