GDB MCP Server

Instructions

Implementation Reference

• server.py:72-77 (handler)

  The main handler function for the 'debugger_command' MCP tool. It takes session_id and command as string parameters, validates that debugger_tools is available, and delegates execution to debugger_tools.execute_command(). The @mcp.tool() decorator on line 72 registers this as an MCP tool.

  @mcp.tool()
  def debugger_command(session_id: str, command: str) -> str:
      """Execute an arbitrary debugger command."""
      if not debugger_tools:
          return "Error: No debuggers are available on this system"
      return debugger_tools.execute_command(session_id, command)

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

  The GDB-specific implementation of execute_command. It retrieves the GDB session by ID, sends the command to GDB via gdb.write(), formats the response, and handles broken pipe errors by cleaning up dead sessions.

  @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/lldb/lldbTools.py:85-99 (handler)

  The LLDB-specific implementation of execute_command. It retrieves the LLDB debugger session, uses the command interpreter to handle the command, and returns formatted output or error messages.

  @handle_lldb_errors("executing command")
  def execute_command(self, session_id: str, command: str) -> str:
      debugger = self.session_manager.get_session(session_id)
      
      interpreter = debugger.GetCommandInterpreter()
      result = lldb.SBCommandReturnObject()
      
      interpreter.HandleCommand(command, result)
      
      if result.Succeeded():
          output = result.GetOutput() or result.GetError() or "Command executed"
          return format_lldb_response(output)
      else:
          error_msg = result.GetError() or "Command failed"
          return f"Error: {error_msg}"

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

  Abstract method definition for execute_command in the base DebuggerTools class. Defines the interface contract that all debugger implementations must follow: takes session_id and command as string parameters and returns a string result.

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

• server.py:72-72 (registration)

  The @mcp.tool() decorator registers the debugger_command function as an MCP tool. FastMCP uses the function signature (session_id: str, command: str) -> str as the schema definition for the tool's input/output validation.

  @mcp.tool()