debug-mcp 0.1.2

data/lib/debug_mcp/tools/run_script.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "mcp"
+require "tempfile"
+
+module DebugMcp
+  module Tools
+    class RunScript < MCP::Tool
+      description "[Entry Point] Launch a Ruby script under the debugger and automatically connect to it. " \
+                  "The script starts and pauses at breakpoints or 'binding.break' in the source. " \
+                  "Use breakpoints parameter to set initial breakpoints before execution starts " \
+                  "(e.g., breakpoints: ['User#save', 'app/models/user.rb:10']). " \
+                  "This is the easiest way to start debugging a script from scratch. " \
+                  "Use restore_breakpoints: true to re-run with the same breakpoints after a crash."
+
+      annotations(
+        title: "Run Ruby Script",
+        read_only_hint: false,
+        destructive_hint: false,
+        open_world_hint: true,
+      )
+
+      input_schema(
+        properties: {
+          file: {
+            type: "string",
+            description: "Path to the Ruby script to run",
+          },
+          args: {
+            type: "array",
+            items: { type: "string" },
+            description: "Command-line arguments to pass to the script",
+          },
+          port: {
+            type: "integer",
+            description: "TCP port for debug connection (auto-assigned if omitted)",
+          },
+          breakpoints: {
+            type: "array",
+            items: { type: "string" },
+            description: "Breakpoints to set before execution starts. Each entry is a breakpoint spec: " \
+                         "'file.rb:10' for line, 'Class#method' for method, or 'catch ExceptionClass' for exception. " \
+                         "The script pauses at line 1, breakpoints are set, then execution continues.",
+          },
+          restore_breakpoints: {
+            type: "boolean",
+            description: "If true, restores breakpoints saved from previous sessions. " \
+                         "Useful for re-running the same script after a crash with identical breakpoints. " \
+                         "Default: false (starts fresh without inheriting previous breakpoints).",
+          },
+        },
+        required: ["file"],
+      )
+
+      class << self
+        def call(file:, args: [], port: nil, breakpoints: nil, restore_breakpoints: nil, server_context:)
+          manager = server_context[:session_manager]
+
+          # Clean up dead sessions from previous runs
+          cleaned = manager.cleanup_dead_sessions
+          # Check if there are still active sessions
+          still_active = manager.active_sessions.select { |s| s[:connected] }
+
+          # Clear saved breakpoints unless explicitly restoring.
+          # Explicit breakpoints parameter takes precedence over restore.
+          manager.clear_breakpoint_specs if !restore_breakpoints || breakpoints&.any?
+
+          unless File.exist?(file)
+            return MCP::Tool::Response.new([{ type: "text", text: "Error: File not found: #{file}" }])
+          end
+
+          # Verify rdbg is available
+          unless system("which rdbg > /dev/null 2>&1")
+            return MCP::Tool::Response.new([{ type: "text", text:
+              "Error: 'rdbg' command not found. Install the debug gem: gem install debug" }])
+          end
+
+          # Start rdbg with --open so we can connect to it.
+          # When initial breakpoints are specified, omit --nonstop so the program
+          # pauses at line 1, giving us time to set breakpoints before execution.
+          debug_port = port || find_available_port
+          has_initial_bps = breakpoints&.any?
+          cmd = ["rdbg", "--open", "--port=#{debug_port}"]
+          cmd << "--nonstop" unless has_initial_bps
+          cmd += ["--", file, *args]
+
+          # Capture stdout/stderr to temp files for post-mortem diagnostics
+          stdout_tmpfile = Tempfile.create(["debug-mcp-stdout-", ".log"])
+          stdout_path = stdout_tmpfile.path
+          stdout_tmpfile.close
+
+          stderr_tmpfile = Tempfile.create(["debug-mcp-stderr-", ".log"])
+          stderr_path = stderr_tmpfile.path
+          stderr_tmpfile.close
+
+          pid = spawn(*cmd, out: stdout_path, err: stderr_path)
+          wait_thread = Process.detach(pid)
+
+          # Wait for the debug server to be ready
+          connected = false
+          10.times do
+            sleep 0.5
+
+            # Check if the process is still alive
+            unless process_alive?(pid)
+              return MCP::Tool::Response.new([{ type: "text", text:
+                "Error: Script exited immediately (PID: #{pid}). " \
+                "Check the script for syntax errors or missing dependencies." }])
+            end
+
+            begin
+              result = manager.connect(host: "localhost", port: debug_port)
+              connected = true
+
+              # Store metadata on the client for post-mortem diagnostics and rerun
+              client = manager.client(result[:session_id])
+              client.stdout_file = stdout_path
+              client.stderr_file = stderr_path
+              client.wait_thread = wait_thread
+              client.script_file = file
+              client.script_args = args
+
+              initial_output = result[:output]
+
+              # Auto-skip if stopped at internal Ruby code (e.g., bundled_gems.rb due to SIGURG)
+              initial_output, skipped = skip_internal_code(client, initial_output)
+
+              # Set initial breakpoints and continue past the line-1 stop
+              bp_results = []
+              deferred_bps = []
+              if has_initial_bps
+                breakpoints.each do |bp|
+                  bp_cmd = bp.start_with?("catch ") ? bp : "break #{bp}"
+                  bp_output = client.send_command(bp_cmd)
+                  first_line = bp_output.lines.first&.strip || ""
+
+                  if first_line.include?("Unknown") || first_line.include?("not found")
+                    # Class not defined yet at line 1 — defer until after continue
+                    deferred_bps << { spec: bp, cmd: bp_cmd, reason: first_line }
+                  else
+                    display = first_line.include?("duplicated") ? "Already set (reused existing)" : first_line
+                    bp_results << { spec: bp, output: display }
+                    manager.record_breakpoint(bp_cmd)
+                  end
+                rescue DebugMcp::Error => e
+                  bp_results << { spec: bp, error: e.message }
+                end
+
+                # Continue past the initial line-1 stop (loads class definitions)
+                begin
+                  initial_output = client.send_continue
+                  initial_output, skipped = skip_internal_code(client, initial_output) unless skipped
+                rescue DebugMcp::SessionError => e
+                  # Program exited before hitting any breakpoint
+                  text = DebugMcp::ExitMessageBuilder.build_exit_message(
+                    "Program finished before hitting any breakpoint.", e.final_output, client,
+                  )
+                  return MCP::Tool::Response.new([{ type: "text", text: text }])
+                end
+
+                # Retry deferred breakpoints now that classes should be defined.
+                # Don't continue again — the program is already stopped at a useful
+                # point (debugger statement or an immediate breakpoint).
+                deferred_bps.each do |db|
+                  bp_output = client.send_command(db[:cmd])
+                  first_line = bp_output.lines.first&.strip || ""
+                  display = first_line.include?("duplicated") ? "Already set (reused existing)" : first_line
+                  bp_results << { spec: db[:spec], output: display, deferred: true }
+                  manager.record_breakpoint(db[:cmd])
+                rescue DebugMcp::Error => e
+                  bp_results << { spec: db[:spec], error: e.message }
+                end
+              end
+
+              session_notes = []
+              if cleaned.any?
+                session_notes << "Cleaned up #{cleaned.size} previous session(s): " \
+                                 "#{cleaned.map { |c| c[:session_id] }.join(", ")}"
+              end
+              if still_active.any?
+                session_notes << "Note: #{still_active.size} other session(s) still active " \
+                                 "(#{still_active.map { |s| s[:session_id] }.join(", ")})"
+              end
+
+              text = ""
+              text += session_notes.join("\n") + "\n\n" if session_notes.any?
+              text += "Script started (PID: #{pid}) and connected via port #{debug_port}.\n" \
+                      "Session ID: #{result[:session_id]}"
+              text += "\n(auto-skipped internal code stop)" if skipped
+              text += "\n\n#{initial_output}"
+
+              # Show initial breakpoint results
+              if bp_results.any?
+                text += "\n\nSet #{bp_results.size} initial breakpoint(s):"
+                bp_results.each do |r|
+                  text += if r[:error]
+                    "\n  #{r[:spec]} -> Error: #{r[:error]}"
+                  elsif r[:deferred]
+                    "\n  #{r[:spec]} -> #{r[:output]} (set after class loaded)"
+                  else
+                    "\n  #{r[:spec]} -> #{r[:output]}"
+                  end
+                end
+              end
+
+              # Restore breakpoints from previous sessions (skip when initial BPs were provided)
+              restored = has_initial_bps ? [] : manager.restore_breakpoints(client)
+              if restored.any?
+                text += "\n\nRestored #{restored.size} breakpoint(s) from previous session:"
+                restored.each do |r|
+                  text += if r[:error]
+                    "\n  #{r[:spec]} -> Error: #{r[:error]}"
+                  else
+                    "\n  #{r[:spec]} -> #{r[:output]}"
+                  end
+                end
+              end
+
+              return MCP::Tool::Response.new([{ type: "text", text: text }])
+            rescue DebugMcp::Error
+              next
+            end
+          end
+
+          unless connected
+            Process.kill("TERM", pid) rescue nil
+            # Read any captured output for diagnostics
+            stdout_output = File.read(stdout_path, encoding: "UTF-8").strip rescue nil
+            stderr_output = File.read(stderr_path, encoding: "UTF-8").strip rescue nil
+            File.delete(stdout_path) rescue nil
+            File.delete(stderr_path) rescue nil
+            msg = "Error: Script started (PID: #{pid}) but could not connect to debug session " \
+                  "on port #{debug_port} within 5 seconds. The script may have exited early."
+            msg += "\n\nProgram output (stdout):\n#{stdout_output}" if stdout_output && !stdout_output.empty?
+            msg += "\n\nProcess stderr:\n#{stderr_output}" if stderr_output && !stderr_output.empty?
+            return MCP::Tool::Response.new([{ type: "text", text: msg }])
+          end
+        rescue Errno::ENOENT => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: Command not found: #{e.message}" }])
+        rescue StandardError => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.class}: #{e.message}" }])
+        end
+
+        private
+
+        # Patterns indicating the debugger stopped at internal Ruby/gem code
+        # rather than user code. This can happen due to SIGURG or other signals.
+        INTERNAL_CODE_PATTERNS = [
+          %r{/bundled_gems\.rb}i,
+          %r{/rubygems/}i,
+          %r{/ruby/lib/}i,
+          %r{/lib/ruby/\d}i,
+          %r{<internal:}i,
+        ].freeze
+
+        MAX_SKIP_ATTEMPTS = 5
+
+        # Check if the debugger stopped at internal code and auto-continue if so.
+        # Loops up to MAX_SKIP_ATTEMPTS times to skip through multiple internal stops.
+        # Returns [output, skipped] where skipped is true if we continued past internal code.
+        def skip_internal_code(client, output)
+          skipped = false
+
+          MAX_SKIP_ATTEMPTS.times do
+            break unless INTERNAL_CODE_PATTERNS.any? { |pattern| output.match?(pattern) }
+
+            output = client.send_continue
+            skipped = true
+          end
+
+          [output, skipped]
+        rescue DebugMcp::Error
+          # If continue fails (e.g., program exited), return what we have
+          [output, skipped || false]
+        end
+
+        def find_available_port
+          server = TCPServer.new("127.0.0.1", 0)
+          port = server.addr[1]
+          server.close
+          port
+        end
+
+        def process_alive?(pid)
+          Process.kill(0, pid)
+          true
+        rescue Errno::ESRCH, Errno::EPERM
+          false
+        end
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/set_breakpoint.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "mcp"
+require "base64"
+
+module DebugMcp
+  module Tools
+    class SetBreakpoint < MCP::Tool
+      description "[Control] Set a breakpoint. Three modes are available:\n" \
+                  "1. Line breakpoint: provide file + line. Pauses when the line is reached. " \
+                  "Use condition to break only when criteria are met (e.g., condition: \"user.id == 1\"). " \
+                  "Use one_shot: true to fire only once and auto-remove (useful in loops/blocks).\n" \
+                  "2. Method breakpoint: provide method (e.g., 'DataPipeline#validate', 'User.find'). " \
+                  "Pauses when the method is called. Use 'Class#method' for instance methods, " \
+                  "'Class.method' for class methods. No need to know the file or line number.\n" \
+                  "3. Exception breakpoint: provide exception_class (e.g., 'NoMethodError') to pause " \
+                  "when that exception is raised, BEFORE it crashes the process."
+
+      annotations(
+        title: "Set Breakpoint",
+        read_only_hint: false,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {
+          file: {
+            type: "string",
+            description: "File path (e.g., 'app/controllers/users_controller.rb'). Required for line breakpoints.",
+          },
+          line: {
+            type: "integer",
+            description: "Line number to break at. Required for line breakpoints.",
+          },
+          method: {
+            type: "string",
+            description: "Method name to break on (e.g., 'DataPipeline#validate' for instance method, " \
+                         "'User.find' for class method). Pauses when the method is called. " \
+                         "No need to know the file path or line number.",
+          },
+          exception_class: {
+            type: "string",
+            description: "Exception class to catch (e.g., 'NoMethodError', 'RuntimeError', 'ArgumentError'). " \
+                         "When this exception is raised anywhere, execution pauses BEFORE the exception propagates. " \
+                         "This is the best way to debug crashes — set it before calling continue_execution.",
+          },
+          condition: {
+            type: "string",
+            description: "Optional condition expression for line/method breakpoints (e.g., 'user.id == 1')",
+          },
+          one_shot: {
+            type: "boolean",
+            description: "If true, the breakpoint fires only once and is automatically removed after " \
+                         "the first hit. Useful for stopping inside a block/loop without repeated stops. " \
+                         "Applies to line and method breakpoints.",
+          },
+          session_id: {
+            type: "string",
+            description: "Debug session ID (uses default session if omitted)",
+          },
+        },
+      )
+
+      class << self
+        def call(file: nil, line: nil, method: nil, exception_class: nil, condition: nil, one_shot: nil, session_id: nil, server_context:)
+          manager = server_context[:session_manager]
+          client = manager.client(session_id)
+          client.auto_repause!
+
+          if exception_class
+            set_catch_breakpoint(client, manager, exception_class)
+          elsif method
+            set_method_breakpoint(client, manager, method, condition: condition, one_shot: one_shot)
+          elsif file && line
+            set_line_breakpoint(client, manager, file, line, condition: condition, one_shot: one_shot)
+          else
+            MCP::Tool::Response.new([{ type: "text",
+              text: "Error: Provide 'file' + 'line' for a line breakpoint, " \
+                    "'method' for a method breakpoint (e.g., 'User#save'), " \
+                    "or 'exception_class' for an exception breakpoint." }])
+          end
+        rescue DebugMcp::Error => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.message}" }])
+        end
+
+        private
+
+        def set_line_breakpoint(client, manager, file, line, condition: nil, one_shot: nil)
+          command = "break #{file}:#{line}"
+          command += " if: #{condition}" if condition
+
+          output = client.send_command(command)
+          output = DebugMcp::StopEventAnnotator.annotate_breakpoint_set(output)
+
+          # Detect duplicate breakpoint
+          if output.include?("duplicated")
+            return MCP::Tool::Response.new([{ type: "text", text: annotate_duplicate(output) }])
+          end
+
+          # Detect line adjustment by debug gem
+          if (bp_match = output.match(/#\d+\s+BP - Line\s+.+:(\d+)/))
+            actual_line = bp_match[1].to_i
+            if actual_line != line
+              output += "\n\nNote: Breakpoint was set on line #{actual_line} instead of the requested " \
+                        "line #{line}. The debugger adjusted to the nearest breakable line."
+            end
+          end
+
+          # Record for preservation across sessions (skip one-shot breakpoints)
+          manager.record_breakpoint(command) unless one_shot
+
+          if one_shot
+            # Parse breakpoint number from output like "#3  BP - Line  /path:47"
+            if (match = output.match(/#(\d+)/))
+              bp_num = match[1].to_i
+              client.register_one_shot(bp_num)
+              output += "\n(one-shot: will be auto-removed after first hit)"
+            end
+          end
+
+          output = append_condition_warning(client, condition, output)
+          MCP::Tool::Response.new([{ type: "text", text: output }])
+        end
+
+        def set_method_breakpoint(client, manager, method, condition: nil, one_shot: nil)
+          command = "break #{method}"
+          command += " if: #{condition}" if condition
+
+          output = client.send_command(command)
+          output = DebugMcp::StopEventAnnotator.annotate_breakpoint_set(output)
+
+          # Detect duplicate breakpoint
+          if output.include?("duplicated")
+            return MCP::Tool::Response.new([{ type: "text", text: annotate_duplicate(output) }])
+          end
+
+          manager.record_breakpoint(command) unless one_shot
+
+          if one_shot
+            if (match = output.match(/#(\d+)/))
+              bp_num = match[1].to_i
+              client.register_one_shot(bp_num)
+              output += "\n(one-shot: will be auto-removed after first hit)"
+            end
+          end
+
+          output = append_condition_warning(client, condition, output)
+          MCP::Tool::Response.new([{ type: "text", text: output }])
+        end
+
+        # Validate condition syntax and append warning if invalid.
+        def append_condition_warning(client, condition, output)
+          return output unless condition
+
+          warning = validate_condition(client, condition)
+          warning ? "#{output}\n\n#{warning}" : output
+        end
+
+        # Check condition syntax via RubyVM::InstructionSequence.compile in the target process.
+        # Uses Base64 encoding to safely pass arbitrary condition strings without escaping issues.
+        # Returns a warning string if syntax error detected, nil otherwise.
+        def validate_condition(client, condition)
+          encoded = Base64.strict_encode64(condition.encode(Encoding::UTF_8))
+          result = client.send_command(
+            "p begin; require 'base64'; " \
+            "RubyVM::InstructionSequence.compile(Base64.decode64('#{encoded}')); " \
+            "nil; rescue SyntaxError => e; e.message; rescue LoadError; " \
+            "RubyVM::InstructionSequence.compile(#{condition.inspect}); nil; " \
+            "rescue SyntaxError => e; e.message; end",
+          )
+          cleaned = result.strip.sub(/\A=> /, "")
+          return nil if cleaned == "nil" || cleaned.empty?
+
+          # Remove surrounding quotes
+          cleaned = cleaned[1..-2] if cleaned.start_with?('"') && cleaned.end_with?('"')
+          return nil if cleaned == "nil" || cleaned.empty?
+
+          "WARNING: Condition may have a syntax error: #{cleaned}\n" \
+          "The breakpoint was set but will never fire if the condition is invalid."
+        rescue DebugMcp::Error
+          nil
+        end
+
+        # Annotate a "duplicated" breakpoint response with a clearer message.
+        # Debug gem output example: "#0  BP - Line  app/models/user.rb:10 (line) (duplicated)"
+        def annotate_duplicate(output)
+          bp_id = output.match(/#(\d+)/)&.then { |m| m[1] }
+          if bp_id
+            "Already set: breakpoint ##{bp_id} exists at this location. No new breakpoint created.\n\n#{output}"
+          else
+            "Already set: a breakpoint already exists at this location. No new breakpoint created.\n\n#{output}"
+          end
+        end
+
+        def set_catch_breakpoint(client, manager, exception_class)
+          command = "catch #{exception_class}"
+          output = client.send_command(command)
+          manager.record_breakpoint(command)
+
+          MCP::Tool::Response.new([{ type: "text", text: output }])
+        end
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/step.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module DebugMcp
+  module Tools
+    class Step < MCP::Tool
+      description "[Control] Step into the next method call. Enters called methods to trace " \
+                  "execution in detail. Use 'next' instead to stay in the current method. " \
+                  "Use 'finish' to run until the current method/block returns. " \
+                  "If an exception is raised and rescued during the step, it will be reported automatically."
+
+      annotations(
+        title: "Step Into",
+        read_only_hint: false,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {
+          session_id: {
+            type: "string",
+            description: "Debug session ID (uses default session if omitted)",
+          },
+        },
+      )
+
+      class << self
+        def call(session_id: nil, server_context:)
+          client = server_context[:session_manager].client(session_id)
+
+          output = client.send_command("step")
+
+          if output.strip.empty? && client.process_finished?
+            text = DebugMcp::ExitMessageBuilder.build_exit_message(
+              "Program exited during step.", output, client,
+            )
+            return MCP::Tool::Response.new([{ type: "text", text: text }])
+          end
+
+          client.cleanup_one_shot_breakpoints(output)
+          output = DebugMcp::StopEventAnnotator.annotate_breakpoint_hit(output)
+          output = DebugMcp::StopEventAnnotator.enrich_stop_context(output, client)
+
+          MCP::Tool::Response.new([{ type: "text", text: output }])
+        rescue DebugMcp::SessionError => e
+          text = if e.message.include?("session ended") || e.message.include?("finished execution")
+            DebugMcp::ExitMessageBuilder.build_exit_message("Program exited during step.", e.final_output, client)
+          else
+            "Error: #{e.message}"
+          end
+          MCP::Tool::Response.new([{ type: "text", text: text }])
+        rescue DebugMcp::ConnectionError => e
+          text = if e.message.include?("Connection lost") || e.message.include?("connection closed")
+            DebugMcp::ExitMessageBuilder.build_exit_message("Program exited during step.", e.final_output, client)
+          else
+            "Error: #{e.message}"
+          end
+          MCP::Tool::Response.new([{ type: "text", text: text }])
+        rescue DebugMcp::Error => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.message}" }])
+        end
+      end
+    end
+  end
+end