Plugins/Protocol/MCP/Tool.cpp

Go to the documentation of this file.

//===- Tool.cpp -----------------------------------------------------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
 
#include "Tool.h"
#include "lldb/Core/Debugger.h"
#include "lldb/Host/File.h"
#include "lldb/Host/FileSystem.h"
#include "lldb/Interpreter/CommandInterpreter.h"
#include "lldb/Interpreter/CommandReturnObject.h"
#include "lldb/Protocol/MCP/Protocol.h"
#include "lldb/Utility/FileSpec.h"
#include "lldb/Utility/UriParser.h"
#include "llvm/ADT/StringRef.h"
#include "llvm/Support/Error.h"
#include <cstdint>
#include <optional>
 
using namespace lldb_private;
using namespace lldb_protocol;
using namespace lldb_private::mcp;
using namespace lldb;
using namespace llvm;
 
namespace {
 
static constexpr StringLiteral kSchemeAndHost = "lldb-mcp://debugger/";
 
struct CommandToolArguments {
  /// Either an id like '1' or a uri like 'lldb-mcp://debugger/1'.
  std::string debugger;
  std::string command;
};
 
bool fromJSON(const json::Value &V, CommandToolArguments &A, json::Path P) {
  json::ObjectMapper O(V, P);
  return O && O.mapOptional("debugger", A.debugger) &&
         O.mapOptional("command", A.command);
}
 
/// Helper function to create a CallToolResult from a string output.
static lldb_protocol::mcp::CallToolResult
createTextResult(std::string output, bool is_error = false) {
  lldb_protocol::mcp::CallToolResult text_result;
  text_result.content.emplace_back(
      lldb_protocol::mcp::TextContent{{std::move(output)}});
  text_result.isError = is_error;
  return text_result;
}
 
std::string to_uri(DebuggerSP debugger) {
  return (kSchemeAndHost + std::to_string(debugger->GetID())).str();
}
 
} // namespace
 
Expected<lldb_protocol::mcp::CallToolResult>
CommandTool::Call(const lldb_protocol::mcp::ToolArguments &args) {
  if (!std::holds_alternative<json::Value>(args))
    return createStringError("CommandTool requires arguments");
 
  json::Path::Root root;
 
  CommandToolArguments arguments;
  if (!fromJSON(std::get<json::Value>(args), arguments, root))
    return root.getError();
 
  lldb::DebuggerSP debugger_sp;
 
  if (!arguments.debugger.empty()) {
    llvm::StringRef debugger_specifier = arguments.debugger;
    debugger_specifier.consume_front(kSchemeAndHost);
    uint32_t debugger_id = 0;
    if (debugger_specifier.consumeInteger(10, debugger_id))
      return createStringError(
          formatv("malformed debugger specifier {0}", arguments.debugger));
 
    debugger_sp = Debugger::FindDebuggerWithID(debugger_id);
  } else {
    for (size_t i = 0; i < Debugger::GetNumDebuggers(); i++) {
      debugger_sp = Debugger::GetDebuggerAtIndex(i);
      if (debugger_sp)
        break;
    }
  }
 
  if (!debugger_sp)
    return createStringError("no debugger found");
 
  // FIXME: Disallow certain commands and their aliases.
  CommandReturnObject result(/*colors=*/false);
  debugger_sp->GetCommandInterpreter().HandleCommand(arguments.command.c_str(),
                                                     eLazyBoolYes, result);
 
  std::string output;
  StringRef output_str = result.GetOutputString();
  if (!output_str.empty())
    output += output_str.str();
 
  std::string err_str = result.GetErrorString();
  if (!err_str.empty()) {
    if (!output.empty())
      output += '\n';
    output += err_str;
  }
 
  return createTextResult(output, !result.Succeeded());
}
 
std::optional<json::Value> CommandTool::GetSchema() const {
  using namespace llvm::json;
  Object properties{
      {"debugger",
       Object{{"type", "string"},
              {"description",
               "The debugger ID or URI to a specific debug session. If not "
               "specified, the first debugger will be used."}}},
      {"command",
       Object{{"type", "string"}, {"description", "An lldb command to run."}}}};
  Object schema{{"type", "object"}, {"properties", std::move(properties)}};
  return schema;
}
 
Expected<lldb_protocol::mcp::CallToolResult>
DebuggerListTool::Call(const lldb_protocol::mcp::ToolArguments &args) {
  llvm::json::Path::Root root;
 
  // Return a nested Markdown list with debuggers and target.
  // Example output:
  //
  // - lldb-mcp://debugger/1
  // - lldb-mcp://debugger/2
  //
  // FIXME: Use Structured Content when we adopt protocol version 2025-06-18.
  std::string output;
  llvm::raw_string_ostream os(output);
 
  const size_t num_debuggers = Debugger::GetNumDebuggers();
  for (size_t i = 0; i < num_debuggers; ++i) {
    lldb::DebuggerSP debugger_sp = Debugger::GetDebuggerAtIndex(i);
    if (!debugger_sp)
      continue;
 
    os << "- " << to_uri(debugger_sp) << '\n';
  }
 
  return createTextResult(output);
}
 
/// Opens the platform null device with the given options, or nullptr on error.
static lldb::FileSP openNull(File::OpenOptions options) {
  llvm::Expected<lldb::FileUP> file =
      FileSystem::Instance().Open(FileSpec(FileSystem::DEV_NULL), options);
  if (!file) {
    llvm::consumeError(file.takeError());
    return nullptr;
  }
  return std::move(*file);
}
 
Expected<lldb_protocol::mcp::CallToolResult>
DebuggerCreateTool::Call(const lldb_protocol::mcp::ToolArguments &) {
  // Redirect the new debugger's stdio to the null device so its prompt and
  // async output can't corrupt an MCP stream sharing the host's stdout. Command
  // results flow through CommandReturnObject and are unaffected. Open the null
  // files first so a failure can't leave a created debugger on the real stdio.
  // The single write-only null file backs both stdout and stderr.
  lldb::FileSP in = openNull(File::eOpenOptionReadOnly);
  lldb::FileSP out = openNull(File::eOpenOptionWriteOnly);
  if (!in || !out)
    return createStringError(
        "failed to open the null device for debugger stdio");
 
  lldb::DebuggerSP debugger_sp = Debugger::CreateInstance();
  if (!debugger_sp)
    return createStringError("failed to create debugger");
 
  debugger_sp->SetInputFile(in);
  debugger_sp->SetOutputFile(out);
  debugger_sp->SetErrorFile(out);
 
  // A debugger driven over MCP has no event loop to service asynchronous
  // stops, so a resume must not return before the process has stopped.
  debugger_sp->SetAsyncExecution(false);
 
  return createTextResult(to_uri(debugger_sp));
}
 
Expected<lldb_protocol::mcp::CallToolResult>
DebuggerDeleteTool::Call(const lldb_protocol::mcp::ToolArguments &args) {
  if (!std::holds_alternative<json::Value>(args))
    return createStringError("DebuggerDeleteTool requires arguments");
 
  const json::Object *arguments = std::get<json::Value>(args).getAsObject();
  if (!arguments)
    return createStringError("DebuggerDeleteTool requires arguments");
 
  std::optional<StringRef> debugger = arguments->getString("debugger");
  if (!debugger)
    return createStringError("DebuggerDeleteTool requires a debugger");
 
  StringRef specifier = *debugger;
  specifier.consume_front(kSchemeAndHost);
  uint32_t debugger_id = 0;
  if (specifier.consumeInteger(10, debugger_id))
    return createStringError(
        formatv("malformed debugger specifier {0}", *debugger));
 
  lldb::DebuggerSP debugger_sp = Debugger::FindDebuggerWithID(debugger_id);
  if (!debugger_sp)
    return createStringError("no debugger found");
 
  Debugger::Destroy(debugger_sp);
  return createTextResult(formatv("deleted {0}", *debugger).str());
}
 
std::optional<json::Value> DebuggerDeleteTool::GetSchema() const {
  using namespace llvm::json;
  Object properties{
      {"debugger",
       Object{{"type", "string"},
              {"description", "The debugger ID or URI to destroy."}}}};
  Object schema{{"type", "object"},
                {"properties", std::move(properties)},
                {"required", Array{"debugger"}}};
  return schema;
}