lldb_examine_variables

Instructions

Runs the program until the specified breakpoint, then displays
the values of local variables and function arguments.

Args:
    params: ExamineVariablesInput with executable, breakpoint, and optional variable names

Returns:
    str: Variable values at the breakpoint

Implementation Reference

• lldb_mcp_server.py:661-708 (handler)

  The async handler function implementing the core logic of the lldb_examine_variables tool. It constructs LLDB commands to set a breakpoint, run the program, examine variables, and formats the output as Markdown or JSON.

  async def lldb_examine_variables(params: ExamineVariablesInput) -> str:
      """Examine local variables and arguments at a breakpoint.
  
      Runs the program until the specified breakpoint, then displays
      the values of local variables and function arguments.
  
      Args:
          params: ExamineVariablesInput with executable, breakpoint, and optional variable names
  
      Returns:
          str: Variable values at the breakpoint
      """
      commands = [
          f"target create {params.executable}",
          f"breakpoint set --name {params.breakpoint}",
          "run" + (" " + " ".join(params.args) if params.args else ""),
      ]
  
      if params.variables:
          for var in params.variables:
              commands.append(f"frame variable {var}")
      else:
          commands.append("frame variable")
  
      commands.append("quit")
  
      result = _run_lldb_script(commands)
  
      if params.response_format == ResponseFormat.JSON:
          return json.dumps(
              {
                  "success": result["success"],
                  "breakpoint": params.breakpoint,
                  "output": result["output"],
                  "error": result.get("error"),
              },
              indent=2,
          )
  
      lines = [
          f"## Variables at `{params.breakpoint}`",
          "",
          "```",
          result["output"].strip() if result["success"] else result.get("error", "Unknown error"),
          "```",
      ]
  
      return "\n".join(lines)

• lldb_mcp_server.py:225-241 (schema)

  Pydantic BaseModel defining the input schema (parameters) for the lldb_examine_variables tool.

  class ExamineVariablesInput(BaseModel):
      """Input for examining variables."""
  
      model_config = ConfigDict(str_strip_whitespace=True)
  
      executable: str = Field(..., description="Path to the executable", min_length=1)
      breakpoint: str = Field(..., description="Breakpoint location to stop at", min_length=1)
      variables: list[str] | None = Field(
          default=None, description="Specific variable names to examine (if None, shows all locals)"
      )
      args: list[str] | None = Field(
          default=None, description="Command-line arguments to pass to the program"
      )
      response_format: ResponseFormat = Field(
          default=ResponseFormat.MARKDOWN, description="Output format"
      )

• lldb_mcp_server.py:651-660 (registration)

  The @mcp.tool decorator that registers the lldb_examine_variables function as an MCP tool with specified name and annotations.

  @mcp.tool(
      name="lldb_examine_variables",
      annotations={
          "title": "Examine Variables",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": False,
      },
  )

• lldb_mcp_server.py:118-156 (helper)

  Helper utility function used by the tool (and others) to execute a list of LLDB commands in batch mode and return structured results.

  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}