# Debugger MCP

A VS Code extension that exposes an MCP (Model Context Protocol) server, allowing AI agents like Claude Code and Claude Desktop to control VS Code's debugger. Language-agnostic — works with any debug adapter (Node.js, Python, C++, Go, Rust, Java, etc.).

## Features

- **22 MCP tools** for full debugger control
- **Works with any debugger** that implements the Debug Adapter Protocol
- **Zero-config for Claude Code** — auto-updates `~/.claude.json` on activation
- **Execution commands block until the debugger stops** and return the stop location + local variables in a single response
- **Captures program output** (stdout/stderr) for inspection

## Architecture

```
Claude Code / Desktop / any MCP client
       |  (HTTP: Streamable HTTP transport)
       v
VS Code Extension (MCP server on localhost:<port>/mcp)
       |  (vscode.debug.* API)
       v
Debug Adapter Protocol → Any Debugger
```

The extension hosts the MCP server directly inside the VS Code process — no separate server or sidecar needed. On activation it starts a localhost HTTP server (default port `45557`) and automatically writes the connection URL to `~/.claude.json`.

## Installation

### VS Code Marketplace

Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=speakeasy.debugger-mcp), or search for **"Debugger MCP"** in the Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`).

Or from the command line:

```bash
code --install-extension speakeasy.debugger-mcp
```

The extension activates automatically on startup — no manual setup required. It starts the MCP server and auto-configures Claude Code.

### From source (development)

```bash
git clone git@github.com:speakeasy-api/debugger-mcp.git
cd debugger-mcp
npm install
npm run compile
```

Then press `F5` in VS Code to launch the Extension Development Host.

## MCP Client Configuration

### Claude Code (zero-config)

The extension automatically registers itself in `~/.claude.json` on activation. **No manual setup needed** — just install the extension, reload VS Code, and start using Claude Code.

To verify it's configured, run:

```bash
claude mcp list
```

You should see `vscode-debugger` listed as an HTTP server.

If you prefer to configure manually, or if auto-config is disabled:

```bash
claude mcp add --transport http vscode-debugger http://localhost:45557/mcp
```

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "vscode-debugger": {
      "type": "http",
      "url": "http://localhost:45557/mcp"
    }
  }
}
```

### VS Code (Copilot / other MCP clients)

Add to `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "vscode-debugger": {
      "type": "http",
      "url": "http://localhost:45557/mcp"
    }
  }
}
```

### Alternative: stdio transport

A standalone MCP server process is also available for clients that only support stdio transport. See the extension's `dist/mcp-server.js` — it discovers the running extension via a port file and proxies MCP requests over HTTP.

## Settings

| Setting | Default | Description |
|---------|---------|-------------|
| `debuggerMcp.port` | `45557` | Preferred port for the MCP server. Falls back to a random port if taken. |
| `debuggerMcp.autoConfigureClaude` | `true` | Automatically update `~/.claude.json` with the MCP server URL on activation. |

## Tools

### Session Management

| Tool | Description |
|------|-------------|
| `debug_start` | Start a debug session from a launch.json config name or inline configuration |
| `debug_stop` | Stop a debug session |
| `debug_restart` | Restart a debug session |
| `debug_list_sessions` | List active debug sessions |
| `debug_list_configurations` | List available launch.json configurations |

### Execution Control

| Tool | Description |
|------|-------------|
| `debug_continue` | Resume execution until next breakpoint or exit. Returns stop location + locals |
| `debug_pause` | Pause a running program. Returns stop location + locals |
| `debug_step_over` | Step over (next line). Supports `count` for batch stepping |
| `debug_step_into` | Step into function calls. Supports `count` for batch stepping |
| `debug_step_out` | Step out of current function. Supports `count` for batch stepping |

### Breakpoints

| Tool | Description |
|------|-------------|
| `debug_set_breakpoint` | Set a source breakpoint (supports condition, hit count, logpoint) |
| `debug_set_function_breakpoint` | Set a function-name breakpoint |
| `debug_remove_breakpoint` | Remove by ID, file+line, all in file, or all |
| `debug_list_breakpoints` | List all breakpoints with details |
| `debug_toggle_breakpoint` | Enable/disable a breakpoint without removing it |

### State Inspection

| Tool | Description |
|------|-------------|
| `debug_get_threads` | List threads |
| `debug_get_stack_trace` | Get call stack for a thread |
| `debug_get_scopes` | Get variable scopes for a stack frame |
| `debug_get_variables` | Get variables in a scope or expand a structured variable |
| `debug_evaluate` | Evaluate an expression in the debug context |

### Status & Output

| Tool | Description |
|------|-------------|
| `debug_status` | Quick "where am I?" — session, stop location, and locals |
| `debug_get_output` | Get captured program output (stdout/stderr) |

## Build Scripts

| Script | Description |
|--------|-------------|
| `npm run compile` | Type-check and build both bundles |
| `npm run build` | Production build (minified, no source maps) |
| `npm run watch` | Watch mode for development |
| `npm run package` | Production build + package into `.vsix` |
| `npm run check-types` | Type-check only (no emit) |

## How It Works

1. **Extension activates** on VS Code startup and starts an HTTP server on `localhost:45557`
2. **MCP endpoint** at `/mcp` uses the Streamable HTTP transport protocol — each client gets its own session
3. **Auto-config** writes the server URL to `~/.claude.json` so Claude Code discovers it automatically
4. **Debug commands** are forwarded to the VS Code debug API via an in-process `DirectClient`
5. **DAP message interception** captures stopped events, program output, and exit codes in real-time
6. **Execution commands** (continue, step) block until the debugger pauses, then automatically gather the stop location and local variables

## Security

- HTTP server binds to `127.0.0.1` only (no network exposure)
- MCP endpoint uses the standard Streamable HTTP transport protocol
- Port file (for legacy stdio transport) includes random auth token and PID for stale-file detection

## License

MIT