devtools-debugger-mcp-nodejs

# devtools-debugger-mcp-nodejs > Skill by [ara.so](https://ara.so) — Devtools Skills collection. An MCP (Model Context Protocol) server that exposes comprehensive Node.js debugging capabilities through the Chrome DevTools Protocol. Enables AI assistants to set breakpoints, step through code, inspect variables, evaluate expressions, analyze call stacks, and work with source maps — all programmatically. ## What It Does This MCP server launches Node.js applications with the built-in inspector (`--inspect-brk=0`), connects via WebSocket to the Chrome DevTools Protocol, and exposes debugging operations as MCP tools. It handles: - **Session management**: Launch/stop Node.js processes with debugging enabled - **Breakpoints**: Set line breakpoints, conditional breakpoints, logpoints, and pause-on-exceptions - **Execution control**: Resume, step over/into/out, continue to location, restart frames - **Inspection**: Explore scopes (locals, closures, `this`), drill into object properties - **Evaluation**: Execute JavaScript expressions in paused call frames - **Console capture**: Buffer and retrieve console output between pauses - **Source maps**: Full TypeScript and transpiled code debugging support - **Script management**: List loaded scripts, fetch sources, blackbox patterns ## Installation ```bash npm install devtools-debugger-mcp ``` Or globally: ```bash npm install -g devtools-debugger-mcp ``` ## Configuration ### MCP Settings Add to your MCP client configuration (e.g., Claude Desktop's `claude_desktop_config.json`): ```json { "mcpServers": { "devtools-debugger": { "command": "node", "args": ["/path/to/devtools-debugger-mcp/dist/index.js"] } } } ``` Or if installed globally: ```json { "mcpServers": { "devtools-debugger": { "command": "devtools-debugger-mcp" } } } ``` ### Output Format Set default response format (`text`, `json`, or `both`): ```javascript // Via set_output_format tool (defaults to 'text') { "tool": "set_output_format", "params": { "format": "json" } } ``` Individual tools can override with their own `format` parameter. ## Core Debugging Workflow ### 1. Start Debug Session ```javascript // Launch Node.js script with inspector { "tool": "start_node_debug", "params": { "scriptPath": "/absolute/path/to/app.js", "format": "text" // optional: 'text' | 'json' | 'both' } } ``` Returns initial pause at first line with `pauseId` and top frame info. **With arguments and environment:** ```javascript { "tool": "start_node_debug", "params": { "scriptPath": "/path/to/server.js", "args": ["--port", "3000"], "env": { "NODE_ENV": "development", "DEBUG": "*" } } } ``` ### 2. Set Breakpoints **File path + line (1-based):** ```javascript { "tool": "set_breakpoint", "params": { "filePath": "/path/to/app.js", "line": 42 } } ``` **Conditional breakpoint:** ```javascript { "tool": "set_breakpoint_condition", "params": { "filePath": "/path/to/users.js", "line": 15, "condition": "user.age > 18" } } ``` **URL regex breakpoint (for modules/packages):** ```javascript { "tool": "set_breakpoint_condition", "params": { "urlRegex": ".*express.*", "line": 100, "condition": "req.method === 'POST'" } } ``` **Logpoint (logs message without pausing):** ```javascript { "tool": "add_logpoint", "params": { "filePath": "/path/to/api.js", "line": 28, "message": "Request received: {req.url}" } } ``` ### 3. Exception Breakpoints ```javascript { "tool": "set_exception_breakpoints", "params": { "state": "uncaught" // 'none' | 'uncaught' | 'all' } } ``` ### 4. Resume and Step **Resume to next breakpoint:** ```javascript { "tool": "resume_execution", "params": { "includeScopes": true, "includeStack": true, "includeConsole": true, "format": "text" } } ``` **Step over current line:** ```javascript { "tool": "step_over", "params": { "includeScopes": true, "includeConsole": true } } ``` **Step into function:** ```javascript { "tool": "step_into", "params": { "includeStack": true } } ``` **Step out of current function:** ```javascript { "tool": "step_out", "params": { "includeScopes": true } } ``` **Continue to specific location:** ```javascript { "tool": "continue_to_location", "params": { "filePath": "/path/to/app.js", "line": 55, "column": 10 // optional } } ``` ### 5. Inspect Variables and Scopes **Current scope (locals, closures, this):** ```javascript { "tool": "inspect_scopes", "params": { "maxProps": 20, // max properties per object "pauseId": "pause123", // optional, defaults to current "frameIndex": 0, // optional, defaults to 0 (top frame) "includeThisPreview": true, "format": "text" } } ``` **Drill into object properties:** ```javascript // First get objectId from inspect_scopes or evaluate_expression { "tool": "get_object_properties", "params": { "objectId": "object:123", "maxProps": 50 } } ``` ### 6. Evaluate Expressions ```javascript { "tool": "evaluate_expression", "params": { "expr": "user.profile.email", "pauseId": "pause123", // optional "frameIndex": 0, // optional, which frame to eval in "returnByValue": true, // optional, serialize result "format": "json" } } ``` **Evaluate with side effects:** ```javascript { "tool": "evaluate_expression", "params": { "expr": "items.push({ id: 5, name: 'test' }); items.length" } } ``` ### 7. Call Stack Inspection ```javascript { "tool": "list_call_stack", "params": { "depth": 10, // optional, max frames "pauseId": "pause123", // optional "includeThis": true, // optional, include 'this' preview "format": "text" } } ``` ### 8. Pause Information ```javascript { "tool": "get_pause_info", "params": { "pauseId": "pause123", // optional, defaults to current "format": "text" } } ``` Returns pause reason (breakpoint, exception, step, etc.) and location. ### 9. Console Output ```javascript { "tool": "read_console", "params": { "format": "text" } } ``` Retrieves console messages buffered since last step/resume. Console is also auto-included when `includeConsole: true` on step/resume tools. ### 10. Stop Session ```javascript { "tool": "stop_debug_session" } ``` Kills the Node.js process and cleans up CDP connection. ## Script Management ### List Loaded Scripts ```javascript { "tool": "list_scripts" } ``` Returns all scripts loaded by Node.js (app files, node_modules, builtins). ### Get Script Source ```javascript // By scriptId { "tool": "get_script_source", "params": { "scriptId": "42" } } // By URL { "tool": "get_script_source", "params": { "url": "file:///path/to/app.js" } } ``` ### Blackbox Scripts (Skip During Debugging) ```javascript { "tool": "blackbox_scripts", "params": { "patterns": [ "node_modules/express/*", "internal/*" ] } } ``` Frames matching these patterns won't pause during step-into. ## Restart Frame Re-execute a specific call frame: ```javascript { "tool": "restart_frame", "params": { "frameIndex": 2, // which frame to restart (0 = top) "pauseId": "pause123", // optional "format": "text" } } ``` ## Advanced Patterns ### Debug TypeScript with Source Maps Source maps are automatically detected and used. Just launch your compiled JS: ```javascript { "tool": "start_node_debug", "params": { "scriptPath": "/path/to/dist/app.js" } } // Set breakpoints using original .ts file paths { "tool": "set_breakpoint", "params": { "filePath": "/path/to/src/app.ts", "line": 42 } } ``` ### Conditional Debugging Loop ```javascript // 1. Start session start_node_debug({ scriptPath: "/path/to/app.js" }) // 2. Set conditional breakpoint set_breakpoint_condition({ filePath: "/path/to/app.js", line: 25, condition: "count > 100" }) // 3. Resume until condition met resume_execution({ includeScopes: true, includeConsole: true }) // 4. Inspect when paused inspect_scopes({ maxProps: 15 }) evaluate_expression({ expr: "count" }) // 5. Continue resume_execution() ``` ### Capture All Console Output ```javascript // Resume with console capture const result = await resume_execution({ includeConsole: true }); // Or read explicitly const consoleOutput = await read_console({ format: "text" }); ``` ### Multi-Frame Inspection