debug-mcp 0.1.2

data/lib/debug_mcp/tools/read_file.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "../rails_helper"
+
+module DebugMcp
+  module Tools
+    class ReadFile < MCP::Tool
+      MAX_LINES = 500
+      # Max lines to fetch per chunk via debug session (keeps output within debug gem's width limit)
+      REMOTE_CHUNK_SIZE = 50
+
+      description "[Investigation] Read a source file from the debug session's machine. " \
+                  "Use this to view code around a breakpoint or understand the surrounding logic. " \
+                  "Relative paths are resolved against the debugged process's working directory."
+
+      annotations(
+        title: "Read Source File",
+        read_only_hint: true,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {
+          path: {
+            type: "string",
+            description: "File path (relative to working directory or absolute)",
+          },
+          start_line: {
+            type: "integer",
+            description: "Start line number (1-indexed, optional)",
+          },
+          end_line: {
+            type: "integer",
+            description: "End line number (1-indexed, optional)",
+          },
+        },
+        required: ["path"],
+      )
+
+      class << self
+        def call(path:, start_line: nil, end_line: nil, server_context:)
+          # Check if we should read via the debug session (remote/Docker connection)
+          client = get_client(server_context)
+          if client&.remote
+            return read_remote_file(client, path, start_line, end_line)
+          end
+
+          full_path = resolve_path(path, server_context)
+
+          unless File.exist?(full_path)
+            return MCP::Tool::Response.new([{ type: "text", text: "Error: File not found: #{path}" }])
+          end
+
+          lines = File.readlines(full_path)
+          total_lines = lines.length
+
+          if start_line || end_line
+            start_idx = [(start_line || 1) - 1, 0].max
+            end_idx = [(end_line || total_lines) - 1, total_lines - 1].min
+            end_idx = [end_idx, start_idx + MAX_LINES - 1].min
+            selected = lines[start_idx..end_idx]
+            content = selected.map.with_index(start_idx + 1) { |line, num| "#{num}: #{line}" }.join
+            header = "#{full_path} (lines #{start_idx + 1}-#{end_idx + 1} of #{total_lines})"
+          else
+            if lines.length > MAX_LINES
+              content = lines.first(MAX_LINES).map.with_index(1) { |line, num| "#{num}: #{line}" }.join
+              header = "#{full_path} (lines 1-#{MAX_LINES} of #{total_lines}, truncated)"
+            else
+              content = lines.map.with_index(1) { |line, num| "#{num}: #{line}" }.join
+              header = "#{full_path} (#{total_lines} lines)"
+            end
+          end
+
+          MCP::Tool::Response.new([{ type: "text", text: "#{header}\n\n#{content}" }])
+        rescue FileNotFoundError => e
+          MCP::Tool::Response.new([{ type: "text", text:
+            "Error: File not found: #{e.message}\n\n" \
+            "This is a relative path but no active debug session is available to resolve it. " \
+            "Use an absolute path, or connect to a debug session first." }])
+        rescue StandardError => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.class}: #{e.message}" }])
+        end
+
+        private
+
+        # Get the debug client, or nil if no active session.
+        def get_client(server_context)
+          server_context[:session_manager].client
+        rescue DebugMcp::Error
+          nil
+        end
+
+        # Read a file via the debug session (for remote/Docker connections).
+        # Uses eval_expr to call File operations in the target process.
+        def read_remote_file(client, path, start_line, end_line)
+          client.auto_repause!
+
+          # Resolve relative path via remote cwd
+          full_path = if path.start_with?("/")
+            path
+          else
+            cwd = RailsHelper.eval_expr(client, "Dir.pwd")
+            cwd ? File.join(cwd, path) : path
+          end
+
+          # Check file existence
+          exists = RailsHelper.eval_expr(client, "File.exist?(#{full_path.inspect})")
+          unless exists == "true"
+            return MCP::Tool::Response.new([{ type: "text",
+              text: "Error: File not found on remote process: #{full_path}" }])
+          end
+
+          # Get total line count
+          count_str = RailsHelper.eval_expr(client, "File.readlines(#{full_path.inspect}).size")
+          unless count_str
+            return MCP::Tool::Response.new([{ type: "text",
+              text: "Error reading remote file: failed to get line count for #{full_path}" }])
+          end
+          total_lines = count_str.to_i
+
+          # Determine line range
+          if start_line || end_line
+            start_idx = [(start_line || 1) - 1, 0].max
+            end_idx = [(end_line || total_lines) - 1, total_lines - 1].min
+            end_idx = [end_idx, start_idx + MAX_LINES - 1].min
+          else
+            start_idx = 0
+            end_idx = [total_lines - 1, MAX_LINES - 1].min
+          end
+
+          # Fetch lines in chunks to stay within debug gem output width limits
+          all_lines = []
+          pos = start_idx
+          while pos <= end_idx
+            chunk_end = [pos + REMOTE_CHUNK_SIZE - 1, end_idx].min
+            chunk = RailsHelper.eval_expr(client,
+              "File.readlines(#{full_path.inspect})[#{pos}..#{chunk_end}].join")
+            break unless chunk
+
+            all_lines << chunk
+            pos = chunk_end + 1
+          end
+
+          content_raw = all_lines.join
+          lines = content_raw.lines
+          content = lines.map.with_index(start_idx + 1) { |line, num| "#{num}: #{line}" }.join
+
+          # Detect partial fetch (chunk returned nil before all lines were retrieved)
+          actual_end = start_idx + lines.length - 1
+          partial = actual_end < end_idx
+
+          if start_line || end_line
+            if partial
+              header = "#{full_path} (lines #{start_idx + 1}-#{actual_end + 1} of #{total_lines}, " \
+                       "partial: fetch failed after line #{actual_end + 1}) [remote]"
+            else
+              header = "#{full_path} (lines #{start_idx + 1}-#{end_idx + 1} of #{total_lines}) [remote]"
+            end
+          elsif partial
+            header = "#{full_path} (lines 1-#{actual_end + 1} of #{total_lines}, " \
+                     "partial: fetch failed after line #{actual_end + 1}) [remote]"
+          elsif total_lines > MAX_LINES
+            header = "#{full_path} (lines 1-#{MAX_LINES} of #{total_lines}, truncated) [remote]"
+          else
+            header = "#{full_path} (#{total_lines} lines) [remote]"
+          end
+
+          MCP::Tool::Response.new([{ type: "text", text: "#{header}\n\n#{content}" }])
+        rescue DebugMcp::Error => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error reading remote file: #{e.message}" }])
+        end
+
+        # Resolve relative paths against the debugged process's working directory.
+        # Falls back to MCP server's working directory if no active session.
+        def resolve_path(path, server_context)
+          return File.expand_path(path) if path.start_with?("/") || path.start_with?("~")
+
+          # Try to get the debugged process's working directory
+          cwd = remote_cwd(server_context)
+          if cwd
+            File.join(cwd, path)
+          else
+            # No active session — try local resolution but warn in error message
+            local_path = File.expand_path(path)
+            return local_path if File.exist?(local_path)
+
+            # File doesn't exist locally either — raise with helpful context
+            raise FileNotFoundError, path
+          end
+        end
+
+        # Custom error to distinguish "no session for relative path" from other errors
+        class FileNotFoundError < StandardError; end
+
+        def remote_cwd(server_context)
+          client = server_context[:session_manager].client
+          client.auto_repause!
+          result = client.send_command("p Dir.pwd")
+          cleaned = result.strip.sub(/\A=> /, "")
+          return nil if cleaned == "nil" || cleaned.empty?
+
+          if cleaned.start_with?('"') && cleaned.end_with?('"')
+            cleaned = cleaned[1..-2]
+          end
+          cleaned.empty? ? nil : cleaned
+        rescue DebugMcp::Error
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/remove_breakpoint.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module DebugMcp
+  module Tools
+    class RemoveBreakpoint < MCP::Tool
+      description "[Control] Remove breakpoints. Can specify: " \
+                  "(1) all: true to remove ALL breakpoints at once, " \
+                  "(2) file + line for line breakpoints, " \
+                  "(3) method for method breakpoints (e.g., 'User#save', 'User.find'), " \
+                  "(4) exception_class for catch breakpoints (e.g., 'NoMethodError'), or " \
+                  "(5) breakpoint_number as a fallback. " \
+                  "Using named parameters is recommended over breakpoint_number, " \
+                  "as numbers can shift when breakpoints are deleted. " \
+                  "Use 'get_context' to see current breakpoints."
+
+      annotations(
+        title: "Remove Breakpoint",
+        read_only_hint: false,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {
+          all: {
+            type: "boolean",
+            description: "If true, remove ALL breakpoints at once. " \
+                         "This clears all line, method, and catch breakpoints in a single operation.",
+          },
+          breakpoint_number: {
+            type: "integer",
+            description: "Breakpoint number to remove (shown in breakpoint listing). " \
+                         "Use this as a fallback when file+line, method, or exception_class don't apply.",
+          },
+          file: {
+            type: "string",
+            description: "File path of the breakpoint to remove (e.g., 'app/models/user.rb'). " \
+                         "Must be used together with 'line'.",
+          },
+          line: {
+            type: "integer",
+            description: "Line number of the breakpoint to remove. Must be used together with 'file'.",
+          },
+          method: {
+            type: "string",
+            description: "Method name to remove breakpoints for (e.g., 'User#save', 'DataPipeline#validate'). " \
+                         "Matches against method breakpoints set with set_breakpoint(method: ...).",
+          },
+          exception_class: {
+            type: "string",
+            description: "Exception class name to remove catch breakpoints for (e.g., 'NoMethodError'). " \
+                         "Removes all catch breakpoints matching this class.",
+          },
+          session_id: {
+            type: "string",
+            description: "Debug session ID (uses default session if omitted)",
+          },
+        },
+      )
+
+      class << self
+        def call(all: nil, breakpoint_number: nil, file: nil, line: nil, method: nil, exception_class: nil, session_id: nil, server_context:)
+          client = server_context[:session_manager].client(session_id)
+          manager = server_context[:session_manager]
+          client.auto_repause!
+
+          if all
+            remove_all_breakpoints(client, manager)
+          elsif exception_class
+            remove_catch_breakpoint(client, manager, exception_class)
+          elsif method
+            remove_method_breakpoint(client, manager, method)
+          elsif file && line
+            remove_by_location(client, manager, file, line)
+          elsif breakpoint_number
+            output = client.send_command("delete #{breakpoint_number}")
+            MCP::Tool::Response.new([{ type: "text", text: output }])
+          else
+            MCP::Tool::Response.new([{ type: "text",
+              text: "Error: Provide 'all: true', 'file' + 'line', 'method', 'exception_class', or 'breakpoint_number'." }])
+          end
+        rescue DebugMcp::Error => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.message}" }])
+        end
+
+        private
+
+        def remove_all_breakpoints(client, manager)
+          bp_list = client.send_command("info breakpoints")
+          nums = collect_matching_bp_numbers(bp_list) { |_| true }
+
+          if nums.empty?
+            return MCP::Tool::Response.new([{ type: "text", text: "No breakpoints to remove." }])
+          end
+
+          delete_breakpoints_reversed(client, nums)
+          manager.clear_breakpoint_specs
+
+          MCP::Tool::Response.new([{ type: "text",
+            text: "Deleted all #{nums.size} breakpoint(s)." }])
+        end
+
+        def remove_by_location(client, manager, file, line)
+          bp_list = client.send_command("info breakpoints")
+          target = "#{file}:#{line}"
+
+          nums = collect_matching_bp_numbers(bp_list) { |bp_line| bp_line.include?(target) }
+          delete_breakpoints_reversed(client, nums)
+
+          if nums.any?
+            manager.remove_breakpoint_specs_matching(target)
+            "Deleted breakpoint ##{nums.join(', #')} at #{target}."
+          else
+            "No breakpoint found at #{target}.\n\nCurrent breakpoints:\n#{bp_list}"
+          end.then { |text| MCP::Tool::Response.new([{ type: "text", text: text }]) }
+        end
+
+        def remove_method_breakpoint(client, manager, method)
+          bp_list = client.send_command("info breakpoints")
+
+          nums = collect_matching_bp_numbers(bp_list) do |bp_line|
+            bp_line.include?("BP - Method") && bp_line.match?(/BP - Method\s+#{Regexp.escape(method)}\b/)
+          end
+          delete_breakpoints_reversed(client, nums)
+
+          if nums.any?
+            manager.remove_breakpoint_specs_matching(method)
+            "Deleted method breakpoint ##{nums.join(', #')} for '#{method}'."
+          else
+            "No method breakpoint found for '#{method}'.\n\nCurrent breakpoints:\n#{bp_list}"
+          end.then { |text| MCP::Tool::Response.new([{ type: "text", text: text }]) }
+        end
+
+        def remove_catch_breakpoint(client, manager, exception_class)
+          bp_list = client.send_command("info breakpoints")
+
+          nums = collect_matching_bp_numbers(bp_list) do |bp_line|
+            bp_line.include?("BP - Catch") && bp_line.include?("\"#{exception_class}\"")
+          end
+          delete_breakpoints_reversed(client, nums)
+
+          if nums.any?
+            manager.remove_breakpoint_specs_matching("catch #{exception_class}")
+            "Deleted catch breakpoint ##{nums.join(', #')} for '#{exception_class}'."
+          else
+            "No catch breakpoint found for '#{exception_class}'.\n\nCurrent breakpoints:\n#{bp_list}"
+          end.then { |text| MCP::Tool::Response.new([{ type: "text", text: text }]) }
+        end
+
+        # Collect breakpoint numbers from info output that match the given block condition.
+        def collect_matching_bp_numbers(bp_list)
+          nums = []
+          bp_list.each_line do |bp_line|
+            next unless (match = bp_line.match(/#(\d+)/))
+            next unless yield(bp_line)
+
+            nums << match[1].to_i
+          end
+          nums
+        end
+
+        # Delete breakpoints in reverse numerical order to prevent number shifting.
+        # The debug gem renumbers breakpoints after each deletion, so deleting
+        # higher numbers first ensures lower numbers remain stable.
+        def delete_breakpoints_reversed(client, nums)
+          nums.sort.reverse_each { |num| client.send_command("delete #{num}") }
+        end
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/run_debug_command.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module DebugMcp
+  module Tools
+    class RunDebugCommand < MCP::Tool
+      description "[Control] Execute a raw debugger command for advanced operations not covered " \
+                  "by other tools. Examples: 'up'/'down' (move stack frames), " \
+                  "'info threads', 'watch @name'. " \
+                  "Note: For catching exceptions, prefer set_breakpoint(exception_class: 'NoMethodError') instead."
+
+      annotations(
+        title: "Run Debug Command",
+        read_only_hint: false,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {
+          command: {
+            type: "string",
+            description: "Debugger command to execute (e.g., 'finish', 'up', 'down', " \
+                         "'frame 3', 'info threads', 'watch @name', 'catch NoMethodError')",
+          },
+          session_id: {
+            type: "string",
+            description: "Debug session ID (uses default session if omitted)",
+          },
+        },
+        required: ["command"],
+      )
+
+      class << self
+        def call(command:, session_id: nil, server_context:)
+          manager = server_context[:session_manager]
+          client = manager.client(session_id)
+          client.auto_repause!
+
+          output = client.send_command(command)
+
+          # Track catch breakpoints for preservation across sessions
+          if command.strip =~ /\Acatch\s+(\S+)/
+            manager.record_breakpoint(command.strip)
+          end
+
+          MCP::Tool::Response.new([{ type: "text", text: output }])
+        rescue DebugMcp::Error => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.message}" }])
+        end
+      end
+    end
+  end
+end