DebuggerAI

DebuggerAI is a VS Code extension that exposes the Debug Adapter Protocol (DAP) as a tool interface via MCP, enabling AI agents ( Claude Code, Cline, Cursor, Copilot Workspace, local LLMs) can set breakpoints, inspect state, and drive a live debug session without knowing VS Code internals.

Universal debugger control for any AI agent.as a generic tool

Positioningicon to readme

Most AI coding agents can read and write files. None can control the debugger. DebuggerAI bridges that gap — agent-agnostic, runtime-agnostic, built on VS Code's native debug API and the Debug Adapter Protocol.

Agent (Claude / Cline / any)
        ↓
  DebuggerAI extension   ←  also accepts manual gutter clicks
        ↓  DAP
  debugpy / node / delve / dart …
        ↓
  Your running program

Clients

MCP server (Claude Desktop, Cline, any MCP-capable agent)

The MCP server wraps every HTTP command as a typed MCP tool. No curl, no JSON wrangling — the agent sees named tools with descriptions and calls them directly.

1. Build

npm install
npm run compile

2. Register the MCP server

Claude Code (CLI)

# local Node.js (stdio transport — default when using --)
claude mcp add debuggerai -- node /absolute/path/to/DebuggerAI/out/clients/mcp/index.js

# Docker (no local Node.js required)
claude mcp add debuggerai -- docker run --rm -i \
  -e DEBUGAI_HOST=host.docker.internal \
  pitronot/debuggerai:latest node out/clients/mcp/index.js

# With custom port
claude mcp add --env DEBUGAI_PORT=9000 debuggerai -- node /absolute/path/to/DebuggerAI/out/clients/mcp/index.js

Claude Desktop / Cline / Cursor — claude_desktop_config.json

The config file is at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A — local Node.js (server running in VS Code or standalone):

{
  "mcpServers": {
    "debuggerai": {
      "command": "node",
      "args": ["/absolute/path/to/DebuggerAI/out/clients/mcp/index.js"]
    }
  }
}

Option B — Docker (no local Node.js required):

{
  "mcpServers": {
    "debuggerai": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "DEBUGAI_HOST=host.docker.internal",
        "pitronot/debuggerai:latest",
        "node", "out/clients/mcp/index.js"
      ]
    }
  }
}

Note: host.docker.internal lets the container reach the DebuggerAI server running on your host machine (macOS/Windows). On Linux, use --network host and omit DEBUGAI_HOST.

3. Start the DebuggerAI server

The VS Code extension auto-starts the server when it activates. Or start it manually:

node out/bin/server.js          # default port 7890
DEBUGAI_PORT=9000 node out/bin/server.js

The MCP server connects to localhost:7890 by default. Override with DEBUGAI_PORT:

DEBUGAI_PORT=9000 node out/clients/mcp/index.js

Available MCP tools

Tool	What it does
set_breakpoint	Set a breakpoint at file:line, optional condition
list_breakpoints	List all breakpoints
clear_breakpoint	Remove a breakpoint by ID
clear_all_breakpoints	Remove all breakpoints
start_session	Start a debug session by launch.json config name
stop_session	Stop the active session
restart_session	Restart the active session
session_status	Get current status (idle / running / paused)
continue	Resume until next breakpoint
next	Step over
step	Step into
step_out	Step out
run_until	Run until a specific line
jump_to	Jump execution to a line
print	Evaluate and print an expression
whatis	Show the type of an expression
exec	Execute a statement in the current frame
watch	Register an expression to watch
unwatch	Remove a watched expression
show_args	Show current frame arguments
show_return_value	Show last return value

Docker (headless server, no VS Code)

Run the standalone HTTP + WebSocket server in a container. Useful when the debugger and AI agent run on different machines or in CI.

docker run -p 7890:7890 pitronot/debuggingai:latest

The server listens on 0.0.0.0:7890 inside the container. Connect a debug client (VS Code extension or MCP server) to http://host-ip:7890.

HTTP API (curl / any HTTP client)

All commands use a single endpoint: POST / with a JSON body containing command and any required parameters.

# List breakpoints
curl -X POST http://localhost:7890/ \
  -H 'Content-Type: application/json' \
  -d '{"command":"list"}'

# Set a breakpoint
curl -X POST http://localhost:7890/ \
  -H 'Content-Type: application/json' \
  -d '{"command":"set","file":"/path/to/app.py","line":42}'

# Start a debug session
curl -X POST http://localhost:7890/ \
  -H 'Content-Type: application/json' \
  -d '{"command":"start","config":"Debug App"}'

# Print an expression
curl -X POST http://localhost:7890/ \
  -H 'Content-Type: application/json' \
  -d '{"command":"print","expression":"my_var"}'

Feature set

Breakpoints

Command	What it does
set	Set breakpoint at file:line, optional condition
edit	Change condition or enabled state
list	List all breakpoints as JSON
clear	Remove one breakpoint by ID
clearAll	Remove all breakpoints

Session lifecycle

Command	What it does
start	Launch a launch.json config by name
quit	Stop the active session
restart	Restart the active session
status	Active session info

Execution control

Command	What it does
continue	Resume until next breakpoint
next	Step over
step	Step into
return	Step out
until	Run until line
jump	Jump to line

Inspection

Command	What it does
print	Evaluate and print
prettyPrint	Pretty-print
whatis	Type of expression
display	Watch an expression
undisplay	Remove watch
args	Current frame args
retval	Last return value

Roadmap

Sprint	Feature
✅ 1	Breakpoint management
✅ 2	Session lifecycle
✅ 3	Execution control
✅ 4	Inspection — print, pp, whatis, display, args, retval
✅ —	MCP server — all commands as typed MCP tools
✅ —	Docker image — headless server, no VS Code required
5	Shared debug session bus — multi-client pub/sub, session replay
6	Stack navigation — backtrace, up, down

Works with

Claude Desktop · Claude Code · Cline · Cursor · GitHub Copilot Workspace · any MCP-capable agent · any agent that can make HTTP requests.

Development

npm install
npm run compile   # TypeScript → out/  (extension + server + MCP client)
npm test          # Jest unit tests (no VS Code required)
npm run test:vscode  # VS Code integration tests

Press F5 in VS Code to launch the Extension Development Host.