GDB MCP Server

Instructions

Implementation Reference

• server.py:81-86 (handler)

  The main handler function for the 'gdb_start' tool. Registered with @mcp.tool() decorator, it calls _get_gdb_tools().start_session(gdb_path) to start a new GDB debugging session and returns a success message with the session ID or an error message.

  def gdb_start(gdb_path: str = "gdb") -> str:
      """Start a new GDB debugging session."""
      try:
          return _get_gdb_tools().start_session(gdb_path)
      except Exception as e:
          return f"Error: {str(e)}"

• modules/gdb/gdbTools.py:69-71 (handler)

  The actual implementation of start_session in the GDBTools class. Creates a GDB session by calling sessionManager.create_session(gdb_path) and returns a formatted success message with the session ID. Wrapped with @handle_gdb_errors decorator for error handling.

  def start_session(self, gdb_path: str = "gdb") -> str:
      session_id = self.sessionManager.create_session(gdb_path)
      return f"GDB session started successfully. Session ID: {session_id}"

• server.py:80-86 (registration)

  Registration point where the gdb_start tool is registered with the MCP server using the @mcp.tool() decorator from FastMCP. The decorator automatically creates the tool schema from the function signature (gdb_path: str = 'gdb', returns str).

  @mcp.tool()
  def gdb_start(gdb_path: str = "gdb") -> str:
      """Start a new GDB debugging session."""
      try:
          return _get_gdb_tools().start_session(gdb_path)
      except Exception as e:
          return f"Error: {str(e)}"

• server.py:31-39 (helper)

  Helper function _get_gdb_tools that implements a singleton pattern to get a GDBTools instance. Uses DebuggerFactory.create_tools('gdb') to create the tools instance on first call and caches it for subsequent calls.

  def _get_gdb_tools():
      """Helper function to get GDB tools with error handling and singleton pattern."""
      global _gdb_tools_instance
      if _gdb_tools_instance is None:
          try:
              _gdb_tools_instance, _ = DebuggerFactory.create_tools('gdb')
          except Exception as e:
              raise RuntimeError(f"GDB not available: {str(e)}")
      return _gdb_tools_instance

• modules/gdb/sessionManager.py:16-25 (handler)

  The create_session method in GDBSessionManager that actually creates a GDB session. Generates a unique session ID, creates a GdbController instance with the GDB interpreter, stores it in the sessions dictionary, and returns the session ID.

  def create_session(self, gdb_path: str = "gdb") -> str:
      session_id = str(uuid.uuid4())
      try:
          gdb_controller = GdbController(command=[gdb_path, "--interpreter=mi3"])
          self.sessions[session_id] = gdb_controller
          logger.info(f"Started GDB session: {session_id}")
          return session_id
      except Exception as e:
          logger.error(f"Failed to start GDB session: {e}")
          raise