attach_debugger
Connect a debugger to an active Node.js process for debugging by specifying the debug port. This enables code inspection and troubleshooting of running applications.
Instructions
Attach debugger to a running Node.js process
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| port | Yes | Debug port to connect to |
Implementation Reference
- src/index.ts:412-497 (handler)Core handler function implementing the attach_debugger tool. Connects to Node.js debug port using Chrome DevTools Protocol (CDP), sets up event listeners for pause/resume/execution context, enables Debugger and Runtime domains, initializes debug session state, handles --inspect-brk waiting state, and returns success/error messages.private async attachDebugger(args: { port: number }) { try { // Close existing connection if any if (this.debugSession.client) { await this.debugSession.client.close(); } // Connect to the Node.js inspector using Chrome DevTools Protocol const client = await CDP({ port: args.port }); const { Debugger, Runtime } = client; // Set up event handlers first Debugger.paused((params: any) => { this.debugSession.callStack = params.callFrames; this.debugSession.isPaused = true; }); Debugger.resumed(() => { this.debugSession.isPaused = false; this.debugSession.callStack = []; }); Runtime.executionContextCreated((params: any) => { this.debugSession.currentExecutionContext = params.context.id; }); // Enable debugging domains await Debugger.enable(); await Runtime.enable(); // Initialize session this.debugSession = { connected: true, port: args.port, client, callStack: [], variables: {}, breakpoints: new Map(), isPaused: false, currentExecutionContext: undefined }; // For --inspect-brk, the runtime is waiting for debugger // We need to handle this special case try { // First, let's try to pause to ensure we're in a debuggable state await Debugger.pause(); // Small delay for pause event await new Promise(resolve => setTimeout(resolve, 100)); } catch (error) { // Process might already be paused or not yet ready } // Now handle the waiting for debugger state try { // This will allow execution to continue from the initial --inspect-brk pause // But since we called pause() above, it should remain paused await Runtime.runIfWaitingForDebugger(); } catch (error) { // If this fails, the process might not be waiting } // Small delay to allow all events to fire await new Promise(resolve => setTimeout(resolve, 200)); return { content: [ { type: "text", text: `Successfully attached debugger to port ${args.port}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error attaching debugger: ${error}`, }, ], isError: true, }; } }
- src/index.ts:176-186 (registration)Tool registration in ListToolsRequestSchema response, defining the tool name, description, and input schema for the MCP protocol.{ name: "attach_debugger", description: "Attach debugger to a running Node.js process", inputSchema: { type: "object", properties: { port: { type: "number", description: "Debug port to connect to" } }, required: ["port"], }, },
- src/index.ts:179-185 (schema)JSON schema defining the input parameters for the attach_debugger tool: requires a 'port' number.inputSchema: { type: "object", properties: { port: { type: "number", description: "Debug port to connect to" } }, required: ["port"], },
- src/index.ts:253-254 (registration)Dispatcher switch case in CallToolRequestSchema handler that routes calls to the attachDebugger method.case "attach_debugger": return await this.attachDebugger(args as { port: number });