MCP GDB Server

Instructions

Implementation Reference

• src/index.ts:560-600 (handler)

  The handleGdbCommand method implements the core logic for the 'gdb_command' tool. It validates the session ID, retrieves the GDB session, executes the provided command using the executeGdbCommand helper, and formats the output response.

  private async handleGdbCommand(args: any) {
    const { sessionId, command } = 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 {
      const output = await this.executeGdbCommand(session, command);
      
      return {
        content: [
          {
            type: 'text',
            text: `Command: ${command}\n\nOutput:\n${output}`
          }
        ]
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: 'text',
            text: `Failed to execute command: ${errorMessage}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:106-119 (schema)

  Input schema for the 'gdb_command' tool defining the required parameters: sessionId (string) and command (string).

  inputSchema: {
    type: 'object',
    properties: {
      sessionId: {
        type: 'string',
        description: 'GDB session ID'
      },
      command: {
        type: 'string',
        description: 'GDB command to execute'
      }
    },
    required: ['sessionId', 'command']
  }

• src/index.ts:103-120 (registration)

  Registration of the 'gdb_command' tool in the ListToolsRequestSchema handler, providing name, description, and input schema.

  {
    name: 'gdb_command',
    description: 'Execute a GDB command',
    inputSchema: {
      type: 'object',
      properties: {
        sessionId: {
          type: 'string',
          description: 'GDB session ID'
        },
        command: {
          type: 'string',
          description: 'GDB command to execute'
        }
      },
      required: ['sessionId', 'command']
    }
  },

• src/index.ts:363-364 (registration)

  Routing registration in the CallToolRequestSchema switch statement that dispatches 'gdb_command' calls to the handleGdbCommand method.

  case 'gdb_command':
    return await this.handleGdbCommand(request.params.arguments);

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

  Core helper function executeGdbCommand that communicates with the GDB process via stdin/stdout, captures output until response markers like '(gdb)', '^done', or '^error', with timeout and error handling.

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