MCP JS Debugger

An MCP (Model Context Protocol) server that exposes Chrome 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

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

# 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

Licence

Apache-2.0

Installation

npm install
npm run build

Claude Code integration

Add to your Claude Code configuration:

claude mcp add mcp-js-debugger -- npx mcp-js-debugger

Or add to .mcp.json:

{
  "mcpServers": {
    "mcp-js-debugger": {
      "command": "npx",
      "args": ["mcp-js-debugger"]
    }
  }
}

Usage

Starting a debug target

Start your Node.js application with the inspector:

# 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

Example workflow

1. Start your application with --inspect-brk:

   Copy

   node --inspect-brk=9229 app.js

2. Get the WebSocket URL:

   Copy

   curl http://localhost:9229/json

3. Connect the debugger:

   Copy

   connect_debugger(websocket_url: "ws://localhost:9229/<id>")

4. Set breakpoints:

   Copy

   set_breakpoint(session_id: "...", url: "file:///path/to/app.js", line_number: 10)

5. Resume execution to hit the breakpoint:

   Copy

   resume_execution(session_id: "...")

6. Inspect state when paused:

   Copy

   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:

   Copy

   step_over(session_id: "...")
   resume_execution(session_id: "...")

Requirements

• Node.js 18.0.0 or later
• A CDP-compatible debug target (Node.js, Chrome, Edge, etc.)