GDB MCP Server

Instructions

Implementation Reference

• server.py:104-110 (handler)

  The gdb_command tool handler function registered with @mcp.tool() decorator. Takes session_id and command as parameters, calls _get_gdb_tools().execute_command() to execute the GDB command.

  @mcp.tool()
  def gdb_command(session_id: str, command: str) -> str:
      """Execute any arbitrary GDB command. Use this for all GDB operations."""
      try:
          return _get_gdb_tools().execute_command(session_id, command)
      except Exception as e:
          return f"Error: {str(e)}"

• modules/gdb/gdbTools.py:93-101 (handler)

  The core implementation of execute_command in GDBTools class. Gets the GDB session, executes the command via gdb.write(), formats the response, and handles BrokenPipeError with session cleanup.

  @handle_gdb_errors("executing command")
  def execute_command(self, session_id: str, command: str) -> str:
      gdb = self.sessionManager.get_session(session_id)
      try:
          response = gdb.write(command)
          return format_gdb_response(response)
      except BrokenPipeError:
          self.sessionManager._cleanup_dead_session(session_id)
          raise BrokenPipeError("GDB session connection lost")

• modules/base/debuggerBase.py:62-65 (schema)

  Abstract method signature for execute_command in DebuggerTools base class, defining the interface contract with session_id and command parameters returning a string.

  @abstractmethod
  def execute_command(self, session_id: str, command: str) -> str:
      """Execute an arbitrary debugger command."""
      pass

• modules/gdb/gdbTools.py:33-59 (helper)

  Helper function format_gdb_response that formats GDB MI (Machine Interface) responses into human-readable output by parsing console, log, target, and result message types.

  def format_gdb_response(response: List[Dict[str, Any]]) -> str:
      """Format GDB response for better readability."""
      if not response:
          return "No response from GDB"
      
      formatted_lines = []
      for msg in response:
          msg_type = msg.get('type', 'unknown')
          payload = msg.get('payload', '')
          
          if msg_type == 'console':
              formatted_lines.append(f"Console: {payload}")
          elif msg_type == 'log':
              formatted_lines.append(f"Log: {payload}")
          elif msg_type == 'target':
              formatted_lines.append(f"Target: {payload}")
          elif msg_type == 'result':
              message = msg.get('message', '')
              if message == 'done':
                  payload_str = str(payload) if payload else "Command completed successfully"
                  formatted_lines.append(f"Result: {payload_str}")
              else:
                  formatted_lines.append(f"Result ({message}): {payload}")
          else:
              formatted_lines.append(f"{msg_type.title()}: {payload}")
      
      return '\n'.join(formatted_lines) if formatted_lines else "Command executed"

• modules/debuggerFactory.py:84-102 (helper)

  DebuggerFactory.create_tools() method that instantiates GDBTools with the appropriate session manager, enabling the tool handler to access GDB functionality.

  @staticmethod
  def create_tools(debugger_type: Optional[str] = None) -> Tuple[DebuggerTools, str]:
      """
      Create debugger tools.
      
      Args:
          debugger_type: 'gdb', 'lldb', or None for auto-detection
          
      Returns:
          Tuple of (tools, actual_debugger_type)
      """
      session_manager, actual_type = DebuggerFactory.create_session_manager(debugger_type)
      
      if actual_type == 'gdb':
          return GDBTools(session_manager), 'gdb'
      elif actual_type == 'lldb':
          return LLDBTools(session_manager), 'lldb'
      
      raise RuntimeError(f"Unknown debugger type: {actual_type}")