MCP GDB Server

Instructions

Implementation Reference

• src/index.ts:501-558 (handler)

  The handler function that executes the gdb_load tool logic: loads a program into an existing GDB session using the 'file' GDB command and sets program arguments if provided.

  private async handleGdbLoad(args: any) {
    const { sessionId, program, arguments: programArgs = [] } = args;
    
    if (!activeSessions.has(sessionId)) {
      return {
        content: [
          {
            type: 'text',
            text: `No active GDB session with ID: ${sessionId}`
          }
        ],
        isError: true
      };
    }
    
    const session = activeSessions.get(sessionId)!;
    
    try {
      // Normalize path if working directory is set
      const normalizedPath = session.workingDir && !path.isAbsolute(program) 
        ? path.resolve(session.workingDir, program)
        : program;
      
      // Update session target
      session.target = normalizedPath;
      
      // Execute file command to load program
      const loadCommand = `file "${normalizedPath}"`;
      const loadOutput = await this.executeGdbCommand(session, loadCommand);
      
      // Set program arguments if provided
      let argsOutput = '';
      if (programArgs.length > 0) {
        const argsCommand = `set args ${programArgs.join(' ')}`;
        argsOutput = await this.executeGdbCommand(session, argsCommand);
      }
      
      return {
        content: [
          {
            type: 'text',
            text: `Program loaded: ${normalizedPath}\n\nOutput:\n${loadOutput}${argsOutput ? '\n' + argsOutput : ''}`
          }
        ]
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: 'text',
            text: `Failed to load program: ${errorMessage}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:79-101 (schema)

  Tool schema definition including name, description, and input schema with required sessionId and program, optional arguments array.

  name: 'gdb_load',
  description: 'Load a program into GDB',
  inputSchema: {
    type: 'object',
    properties: {
      sessionId: {
        type: 'string',
        description: 'GDB session ID'
      },
      program: {
        type: 'string',
        description: 'Path to the program to debug'
      },
      arguments: {
        type: 'array',
        items: {
          type: 'string'
        },
        description: 'Command-line arguments for the program (optional)'
      }
    },
    required: ['sessionId', 'program']
  }

• src/index.ts:361-362 (registration)

  Registration of the gdb_load tool handler in the CallToolRequestSchema switch statement.

  case 'gdb_load':
    return await this.handleGdbLoad(request.params.arguments);

• src/index.ts:1159-1217 (helper)

  Helper function executeGdbCommand used by gdb_load to send commands to GDB and capture output.

  private executeGdbCommand(session: GdbSession, command: string): Promise<string> {
    return new Promise<string>((resolve, reject) => {
      if (!session.ready) {
        reject(new Error('GDB session is not ready'));
        return;
      }
      
      // Write command to GDB's stdin
      if (session.process.stdin) {
        session.process.stdin.write(command + '\n');
      } else {
        reject(new Error('GDB stdin is not available'));
        return;
      }
      
      let output = '';
      let responseComplete = false;
      
      // Create a one-time event handler for GDB output
      const onLine = (line: string) => {
        output += line + '\n';
        
        // Check if this line indicates the end of the GDB response
        if (line.includes('(gdb)') || line.includes('^done') || line.includes('^error')) {
          responseComplete = true;
          
          // If we've received the complete response, resolve the promise
          if (responseComplete) {
            // Remove the listener to avoid memory leaks
            session.rl.removeListener('line', onLine);
            resolve(output);
          }
        }
      };
      
      // Add the line handler to the readline interface
      session.rl.on('line', onLine);
      
      // Set a timeout to prevent hanging
      const timeout = setTimeout(() => {
        session.rl.removeListener('line', onLine);
        reject(new Error('GDB command timed out'));
      }, 10000); // 10 second timeout
      
      // Handle GDB errors
      const errorHandler = (data: Buffer) => {
        const errorText = data.toString();
        output += `[stderr] ${errorText}\n`;
      };
      
      // Add error handler
      if (session.process.stderr) {
        session.process.stderr.once('data', errorHandler);
      }
      
      // Clean up event handlers when the timeout expires
      timeout.unref();
    });
  }