Node.js Debugger MCP Server

Instructions

Implementation Reference

• src/index.ts:274-351 (handler)

  The primary handler function that implements the 'start_node_process' tool. Validates the script path, finds an available debug port, spawns a Node.js process using 'spawn' with --inspect-brk, registers it in managedProcesses, sets up exit cleanup, and returns a success or error message.
  private async startNodeProcess(args: { script: string; args?: string[]; cwd?: string }) { const workingDir = args.cwd || process.cwd(); const scriptPath = resolve(workingDir, args.script); // Validate script exists if (!existsSync(scriptPath)) { return { content: [{ type: "text", text: `Script not found: ${scriptPath}`, }], isError: true, }; } // Find available port const port = await this.findAvailablePort(); const nodeArgs = [`--inspect-brk=${port}`, args.script, ...(args.args || [])]; try { const child = spawn("node", nodeArgs, { cwd: args.cwd || process.cwd(), stdio: ["pipe", "pipe", "pipe"], detached: false, }); if (!child.pid) { throw new Error("Failed to start process"); } const managedProcess: ManagedProcess = { pid: child.pid, port, command: "node", args: nodeArgs, process: child, startTime: new Date(), scriptPath, }; this.usedPorts.add(port); this.managedProcesses.set(child.pid, managedProcess); child.on("exit", (code) => { if (child.pid) { const process = this.managedProcesses.get(child.pid); if (process) { this.usedPorts.delete(process.port); this.managedProcesses.delete(child.pid); // Clean up debug session if it was connected to this process if (this.debugSession.port === process.port) { this.debugSession = { connected: false }; } } } }); return { content: [ { type: "text", text: `Started Node.js process with PID ${child.pid} on debug port ${port}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error starting process: ${error}`, }, ], isError: true, }; } }
• src/index.ts:147-155 (schema)

  The input schema for the 'start_node_process' tool, defining the expected parameters: 'script' (required string), 'args' (optional string array), 'cwd' (optional string).
  inputSchema: { type: "object", properties: { script: { type: "string", description: "Path to the Node.js script to run" }, args: { type: "array", items: { type: "string" }, description: "Arguments to pass to the script" }, cwd: { type: "string", description: "Working directory (optional)" } }, required: ["script"], },
• src/index.ts:144-156 (registration)

  Registration of the 'start_node_process' tool in the ListToolsRequestSchema response, including name, description, and input schema.
  { name: "start_node_process", description: "Start a Node.js process with debugging enabled", inputSchema: { type: "object", properties: { script: { type: "string", description: "Path to the Node.js script to run" }, args: { type: "array", items: { type: "string" }, description: "Arguments to pass to the script" }, cwd: { type: "string", description: "Working directory (optional)" } }, required: ["script"], }, },
• src/index.ts:244-245 (registration)

  Dispatch case in the CallToolRequestSchema handler that routes calls to the startNodeProcess handler.
  case "start_node_process": return await this.startNodeProcess(args as { script: string; args?: string[]; cwd?: string });
• src/index.ts:723-730 (helper)

  Helper method used by startNodeProcess to dynamically find an available debug port starting from 9229.
  private async findAvailablePort(): Promise<number> { let port = this.nextPort; while (this.usedPorts.has(port) || !(await this.isPortAvailable(port))) { port++; } this.nextPort = port + 1; return port; }