Node.js Debugger MCP Server

Instructions

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 });