# MCP JS Debugger
An MCP (Model Context Protocol) server that exposes
[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
debugging capabilities, enabling AI assistants to debug JavaScript and
TypeScript applications.
## Features
- Connect to any CDP-compatible debugger (Node.js, Chrome, Edge)
- Set, list, and remove breakpoints
- Step through code (over, into, out)
- Inspect call stacks with source map support
- Evaluate expressions in any stack frame
- View and modify variables
- Pause on exceptions
- Full source map support for debugging transpiled code
## Installation
```bash
npm install
npm run build
```
### Claude Code integration
Add to your Claude Code configuration:
```bash
claude mcp add mcp-js-debugger -- npx mcp-js-debugger
```
Or add to `.mcp.json`:
```json
{
"mcpServers": {
"mcp-js-debugger": {
"command": "npx",
"args": ["mcp-js-debugger"]
}
}
}
```
## Usage
### Starting a debug target
Start your Node.js application with the inspector:
```bash
# Pause on first line (recommended for setting initial breakpoints)
node --inspect-brk=9229 your-script.js
# Or start without pausing
node --inspect=9229 your-script.js
```
### Available tools
| Tool | Description |
|---------------------------|--------------------------------------------------|
| `connect_debugger` | Connect to a CDP endpoint via WebSocket URL |
| `disconnect_debugger` | Disconnect from a debugging session |
| `set_breakpoint` | Set a breakpoint by URL and line number |
| `remove_breakpoint` | Remove a breakpoint by ID |
| `list_breakpoints` | List all breakpoints in a session |
| `resume_execution` | Resume execution after pause |
| `step_over` | Step over the current statement |
| `step_into` | Step into a function call |
| `step_out` | Step out of the current function |
| `pause_execution` | Pause running execution |
| `get_call_stack` | Get the current call stack with source locations |
| `evaluate_expression` | Evaluate a JavaScript expression |
| `get_scope_variables` | Get variables in a scope |
| `set_variable_value` | Modify a variable's value |
| `set_pause_on_exceptions` | Configure exception handling |
| `get_original_location` | Map generated to original source location |
| `get_script_source` | Get script source code |
| `list_scripts` | List loaded scripts |
### Example workflow
1. Start your application with `--inspect-brk`:
```bash
node --inspect-brk=9229 app.js
```
2. Get the WebSocket URL:
```bash
curl http://localhost:9229/json
```
3. Connect the debugger:
```
connect_debugger(websocket_url: "ws://localhost:9229/<id>")
```
4. Set breakpoints:
```
set_breakpoint(session_id: "...", url: "file:///path/to/app.js", line_number: 10)
```
5. Resume execution to hit the breakpoint:
```
resume_execution(session_id: "...")
```
6. Inspect state when paused:
```
get_call_stack(session_id: "...")
get_scope_variables(session_id: "...", call_frame_id: "...", scope_index: 0)
evaluate_expression(session_id: "...", expression: "myVariable")
```
7. Continue debugging:
```
step_over(session_id: "...")
resume_execution(session_id: "...")
```
## Source map support
The server automatically loads source maps for transpiled code (TypeScript,
bundled JavaScript, etc.). When source maps are available:
- Call stacks show original source locations
- Breakpoints can be set on original source files
- `get_original_location` maps generated positions to original source
- `get_script_source` can return original source content
## Development
```bash
# Build
npm run build
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Watch mode for development
npm run dev
```
## Architecture
- **cdp-client.ts** - Low-level Chrome DevTools Protocol client wrapper
- **session-manager.ts** - Manages multiple debugging sessions
- **source-map-manager.ts** - Handles source map loading and position mapping
- **server.ts** - MCP server implementation with tool handlers
- **types.ts** - TypeScript type definitions
## Requirements
- Node.js 18.0.0 or later
- A CDP-compatible debug target (Node.js, Chrome, Edge, etc.)
## Licence
Apache-2.0
