MCP GDB Server

Instructions

Implementation Reference

• src/index.ts:701-748 (handler)

  Implements the gdb_load_core tool by loading the specified program and core dump file into an active GDB session using 'file' and 'core-file' commands, then displaying the backtrace.

  private async handleGdbLoadCore(args: any) {
    const { sessionId, program, corePath } = 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 {
      // First load the program
      const fileOutput = await this.executeGdbCommand(session, `file "${program}"`);
      
      // Then load the core file
      const coreOutput = await this.executeGdbCommand(session, `core-file "${corePath}"`);
      
      // Get backtrace to show initial state
      const backtraceOutput = await this.executeGdbCommand(session, "backtrace");
      
      return {
        content: [
          {
            type: 'text',
            text: `Core file loaded: ${corePath}\n\nOutput:\n${fileOutput}\n${coreOutput}\n\nBacktrace:\n${backtraceOutput}`
          }
        ]
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: 'text',
            text: `Failed to load core file: ${errorMessage}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:162-181 (schema)

  Defines the input schema and metadata for the gdb_load_core tool, specifying required parameters: sessionId, program, and corePath.

  name: 'gdb_load_core',
  description: 'Load a core dump file',
  inputSchema: {
    type: 'object',
    properties: {
      sessionId: {
        type: 'string',
        description: 'GDB session ID'
      },
      program: {
        type: 'string',
        description: 'Path to the program executable'
      },
      corePath: {
        type: 'string',
        description: 'Path to the core dump file'
      }
    },
    required: ['sessionId', 'program', 'corePath']
  }

• src/index.ts:371-372 (registration)

  Registers the gdb_load_core tool in the CallToolRequestSchema handler switch statement, routing calls to the handleGdbLoadCore method.

  case 'gdb_load_core':
    return await this.handleGdbLoadCore(request.params.arguments);

• src/index.ts:59-354 (registration)

  The tool is registered in the ListToolsRequestSchema response, making it discoverable by MCP clients.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'gdb_start',
        description: 'Start a new GDB session',
        inputSchema: {
          type: 'object',
          properties: {
            gdbPath: {
              type: 'string',
              description: 'Path to the GDB executable (optional, defaults to "gdb")'
            },
            workingDir: {
              type: 'string',
              description: 'Working directory for GDB (optional)'
            }
          }
        }
      },
      {
        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']
        }
      },
      {
        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']
        }
      },
      {
        name: 'gdb_terminate',
        description: 'Terminate a GDB session',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            }
          },
          required: ['sessionId']
        }
      },
      {
        name: 'gdb_list_sessions',
        description: 'List all active GDB sessions',
        inputSchema: {
          type: 'object',
          properties: {}
        }
      },
      {
        name: 'gdb_attach',
        description: 'Attach to a running process',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            },
            pid: {
              type: 'number',
              description: 'Process ID to attach to'
            }
          },
          required: ['sessionId', 'pid']
        }
      },
      {
        name: 'gdb_load_core',
        description: 'Load a core dump file',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            },
            program: {
              type: 'string',
              description: 'Path to the program executable'
            },
            corePath: {
              type: 'string',
              description: 'Path to the core dump file'
            }
          },
          required: ['sessionId', 'program', 'corePath']
        }
      },
      {
        name: 'gdb_set_breakpoint',
        description: 'Set a breakpoint',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            },
            location: {
              type: 'string',
              description: 'Breakpoint location (e.g., function name, file:line)'
            },
            condition: {
              type: 'string',
              description: 'Breakpoint condition (optional)'
            }
          },
          required: ['sessionId', 'location']
        }
      },
      {
        name: 'gdb_continue',
        description: 'Continue program execution',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            }
          },
          required: ['sessionId']
        }
      },
      {
        name: 'gdb_step',
        description: 'Step program execution',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            },
            instructions: {
              type: 'boolean',
              description: 'Step by instructions instead of source lines (optional)'
            }
          },
          required: ['sessionId']
        }
      },
      {
        name: 'gdb_next',
        description: 'Step over function calls',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            },
            instructions: {
              type: 'boolean',
              description: 'Step by instructions instead of source lines (optional)'
            }
          },
          required: ['sessionId']
        }
      },
      {
        name: 'gdb_finish',
        description: 'Execute until the current function returns',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            }
          },
          required: ['sessionId']
        }
      },
      {
        name: 'gdb_backtrace',
        description: 'Show call stack',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            },
            full: {
              type: 'boolean',
              description: 'Show variables in each frame (optional)'
            },
            limit: {
              type: 'number',
              description: 'Maximum number of frames to show (optional)'
            }
          },
          required: ['sessionId']
        }
      },
      {
        name: 'gdb_print',
        description: 'Print value of expression',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            },
            expression: {
              type: 'string',
              description: 'Expression to evaluate'
            }
          },
          required: ['sessionId', 'expression']
        }
      },
      {
        name: 'gdb_examine',
        description: 'Examine memory',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            },
            expression: {
              type: 'string',
              description: 'Memory address or expression'
            },
            format: {
              type: 'string',
              description: 'Display format (e.g., "x" for hex, "i" for instruction)'
            },
            count: {
              type: 'number',
              description: 'Number of units to display'
            }
          },
          required: ['sessionId', 'expression']
        }
      },
      {
        name: 'gdb_info_registers',
        description: 'Display registers',
        inputSchema: {
          type: 'object',
          properties: {
            sessionId: {
              type: 'string',
              description: 'GDB session ID'
            },
            register: {
              type: 'string',
              description: 'Specific register to display (optional)'
            }
          },
          required: ['sessionId']
        }
      }
    ],
  }));