LLDB MCP Server

Instructions

This tool:
1. Loads the executable
2. Sets any specified breakpoints
3. Runs the program (optionally stopping at entry)
4. Returns the state when stopped

Args:
    params: RunProgramInput with executable, args, and breakpoints

Returns:
    str: Program state after stopping (backtrace, variables)

Implementation Reference

• lldb_mcp_server.py:1096-1151 (handler)

  The main handler function for the 'lldb_run' tool, including decorator. It sets up LLDB commands to load the target, set breakpoints and environment, run the program, capture backtrace and frame variables, and formats the output.

  @mcp.tool(
      name="lldb_run",
      annotations={
          "title": "Run Program",
          "readOnlyHint": False,
          "destructiveHint": False,
          "idempotentHint": False,
          "openWorldHint": True,
      },
  )
  async def lldb_run(params: RunProgramInput) -> str:
      """Run a program under the debugger with optional breakpoints.
  
      This tool:
      1. Loads the executable
      2. Sets any specified breakpoints
      3. Runs the program (optionally stopping at entry)
      4. Returns the state when stopped
  
      Args:
          params: RunProgramInput with executable, args, and breakpoints
  
      Returns:
          str: Program state after stopping (backtrace, variables)
      """
      commands = [f"target create {params.executable}"]
  
      # Set environment variables
      if params.environment:
          for key, value in params.environment.items():
              commands.append(f"settings set target.env-vars {key}={value}")
  
      # Set breakpoints
      if params.breakpoints:
          for bp in params.breakpoints:
              if ":" in bp and not bp.startswith("0x"):
                  parts = bp.rsplit(":", 1)
                  commands.append(f"breakpoint set --file {parts[0]} --line {parts[1]}")
              else:
                  commands.append(f"breakpoint set --name {bp}")
      elif params.stop_at_entry:
          commands.append("breakpoint set --name main")
  
      # Prepare run command
      run_cmd = "run"
      if params.args:
          run_cmd += " " + " ".join(params.args)
  
      commands.extend([run_cmd, "thread backtrace", "frame variable", "quit"])
  
      result = _run_lldb_script(commands, working_dir=params.working_dir)
  
      return (
          f"## Program Run: `{Path(params.executable).name}`\n\n```\n{result['output'].strip()}\n```"
      )

• lldb_mcp_server.py:379-396 (schema)

  Pydantic BaseModel defining the input parameters for the lldb_run tool, including executable path, arguments, breakpoints, environment, stop_at_entry flag, and working directory.

  class RunProgramInput(BaseModel):
      """Input for running a program with debugging."""
  
      model_config = ConfigDict(str_strip_whitespace=True)
  
      executable: str = Field(..., description="Path to the executable to run", min_length=1)
      args: list[str] | None = Field(
          default=None, description="Command-line arguments to pass to the program"
      )
      breakpoints: list[str] | None = Field(
          default=None, description="List of breakpoint locations to set before running"
      )
      environment: dict[str, str] | None = Field(
          default=None, description="Environment variables to set"
      )
      stop_at_entry: bool = Field(default=True, description="Stop at the entry point (main function)")
      working_dir: str | None = Field(default=None, description="Working directory for the program")

• lldb_mcp_server.py:1096-1105 (registration)

  MCP tool registration decorator specifying the name 'lldb_run' and annotations for the tool.

  @mcp.tool(
      name="lldb_run",
      annotations={
          "title": "Run Program",
          "readOnlyHint": False,
          "destructiveHint": False,
          "idempotentHint": False,
          "openWorldHint": True,
      },
  )

• lldb_mcp_server.py:118-156 (helper)

  Helper function used by lldb_run to execute a sequence of LLDB commands in batch mode via subprocess.

  def _run_lldb_script(
      commands: list[str],
      target: str | None = None,
      working_dir: str | None = None,
      timeout: int = 60,
  ) -> dict[str, Any]:
      """
      Execute multiple LLDB commands in sequence.
      """
      cmd = [LLDB_EXECUTABLE]
  
      if target:
          cmd.extend(["--file", target])
  
      cmd.append("--batch")
  
      for command in commands:
          cmd.extend(["-o", command])
  
      try:
          result = subprocess.run(
              cmd, capture_output=True, text=True, timeout=timeout, cwd=working_dir or os.getcwd()
          )
          return {
              "success": result.returncode == 0,
              "output": result.stdout,
              "error": result.stderr if result.returncode != 0 else None,
              "return_code": result.returncode,
          }
      except subprocess.TimeoutExpired:
          return {
              "success": False,
              "output": "",
              "error": f"Commands timed out after {timeout} seconds",
              "return_code": -1,
          }
      except Exception as e:
          return {"success": False, "output": "", "error": str(e), "return_code": -1}