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