gdb-multiarch-mcp

Instructions

Implementation Reference

• src/gdb_multiarch_mcp/gdb_interface.py:548-628 (handler)

  The `execute_command` method in `GDBSession` is the core handler that executes raw GDB/MI or CLI commands. It wraps CLI commands with `-interpreter-exec console` and executes them using the GDB/MI protocol.

  def execute_command(
      self, command: str, timeout_sec: int = DEFAULT_TIMEOUT_SEC
  ) -> dict[str, Any]:
      """
      Execute a GDB command and return the parsed response.
  
      Uses the GDB/MI protocol properly by sending commands with tokens and waiting
      for the (gdb) prompt. Automatically handles both MI commands (starting with '-')
      and CLI commands. CLI commands are wrapped with -interpreter-exec for proper
      output capture.
  
      Args:
          command: GDB command to execute (MI or CLI command)
          timeout_sec: Timeout for command execution (default: 30s)
  
      Returns:
          Dict containing the command result and output
      """
      if not self.controller:
          return {"status": "error", "message": "No active GDB session"}
  
      # Check if GDB process is still alive before trying to send command
      if not self._is_gdb_alive():
          logger.error(f"GDB process is not running when trying to execute: {command}")
          return {
              "status": "error",
              "message": "GDB process has exited - cannot execute command",
              "command": command,
          }
  
      # Detect if this is a CLI command (doesn't start with '-')
      # CLI commands need to be wrapped with -interpreter-exec
      is_cli_command = not command.strip().startswith("-")
      actual_command = command
  
      if is_cli_command:
          # Escape backslashes and quotes in the command
          escaped_command = command.replace("\\", "\\\\").replace('"', '\\"')
          actual_command = f'-interpreter-exec console "{escaped_command}"'
          logger.debug(f"Wrapping CLI command: {command} -> {actual_command}")
  
      # Send command and wait for (gdb) prompt using the proper MI protocol
      result = self._send_command_and_wait_for_prompt(actual_command, timeout_sec)
  
      # Check for errors
      if "error" in result:
          error_response = {
              "status": "error",
              "message": result["error"],
              "command": command,
          }
          # Propagate fatal flag if present (indicates GDB internal error)
          if result.get("fatal"):
              error_response["fatal"] = True
          return error_response
  
      if result.get("timed_out"):
          return {
              "status": "error",
              "message": f"Timeout waiting for command response after {timeout_sec}s",
              "command": command,
          }
  
      # Parse command responses
      command_responses = result.get("command_responses", [])
      parsed = self._parse_responses(command_responses)
  
      # For CLI commands, format the output more clearly
      if is_cli_command:
          # Combine all console output
          console_output = "".join(parsed.get("console", []))
  
          return {
              "status": "success",
              "command": command,
              "output": console_output.strip() if console_output else "(no output)",
          }
      else:
          # For MI commands, return structured result
          return {"status": "success", "command": command, "result": parsed}

• src/gdb_multiarch_mcp/server.py:454-457 (handler)

  The `call_tool` function in `server.py` dispatches the `gdb_execute_command` tool call to the `session.execute_command()` method.

  elif name == "gdb_execute_command":
      a = ExecuteCommandArgs(**arguments)
      result = session.execute_command(command=a.command)

• src/gdb_multiarch_mcp/server.py:126-128 (schema)

  The input schema for `gdb_execute_command` is defined by the `ExecuteCommandArgs` Pydantic model.

  class ExecuteCommandArgs(BaseModel):
      command: str = Field(..., description="GDB command to execute")

• src/gdb_multiarch_mcp/server.py:229-240 (registration)

  The `gdb_execute_command` tool is registered in the `list_tools` function within `server.py`.

  Tool(
      name="gdb_execute_command",
      description=(
          "Execute a raw GDB command (CLI or MI). "
          "For Switch-specific operations, prefer the dedicated switch_* tools. "
          "IMPORTANT: Do NOT use 'target remote' or 'target extended-remote' — "
          "the session auto-connects to the Switch on first use. "
          "Do NOT use 'attach' or 'monitor wait application' — handled automatically. "
          "$main is already set to the base address of the game executable."
      ),
      inputSchema=ExecuteCommandArgs.model_json_schema(),
  ),