debug-mcp 0.1.2

data/lib/debug_mcp/tools/finish.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module DebugMcp
+  module Tools
+    class Finish < MCP::Tool
+      description "[Control] Run until the current method or block returns, then pause. " \
+                  "After finish, execution stops at the CALLER's frame (the line that invoked the method). " \
+                  "The line shown with => has already been executed. " \
+                  "This exits the current block/method entirely — for iterators like each/map, " \
+                  "this skips ALL remaining iterations. " \
+                  "To skip to just the NEXT ITERATION instead, use set_breakpoint with one_shot: true " \
+                  "on the first line of the block body, then continue_execution."
+
+      annotations(
+        title: "Finish Method/Block",
+        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("finish", timeout: DebugClient::CONTINUE_TIMEOUT)
+
+          if output.strip.empty? && client.process_finished?
+            text = DebugMcp::ExitMessageBuilder.build_exit_message(
+              "Program exited during finish.", 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)
+
+          location = parse_stop_location(output)
+          header = if location
+            "Method/block returned. Now at: #{location}"
+          else
+            "Method/block returned (stopped at caller's frame)."
+          end
+          MCP::Tool::Response.new([{ type: "text", text: "#{header}\n\n#{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 finish.", 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 finish.", 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
+
+        private
+
+        def parse_stop_location(output)
+          # Debug gem output: "=>#0  Class#method at /path/to/file.rb:10"
+          match = output&.match(/=>#\d+\s+.+\s+at\s+(.+:\d+)/)
+          match ? match[1] : nil
+        end
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/get_context.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "../pending_http_helper"
+
+module DebugMcp
+  module Tools
+    class GetContext < MCP::Tool
+      description "[Investigation] Get the full execution context of the paused Ruby process: " \
+                  "current source location, local variables, instance variables, call stack, " \
+                  "and breakpoints. " \
+                  "Best used: (1) after connecting/run_script to understand the initial state, " \
+                  "(2) after continue_execution hits a breakpoint to see variable values, " \
+                  "(3) when you need to check what breakpoints are set. " \
+                  "Not needed after every next/step — those already include source listing in their output. " \
+                  "Note: Variable values may be truncated. " \
+                  "Use 'evaluate_code' or 'inspect_object' for full details on specific variables."
+
+      annotations(
+        title: "Get Execution Context",
+        read_only_hint: true,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {
+          session_id: {
+            type: "string",
+            description: "Debug session ID (uses default session if omitted)",
+          },
+        },
+      )
+
+      # Pattern for detecting truncated values in debug gem output.
+      # Matches lines where the value portion ends with "..." possibly followed
+      # by closing delimiters like ], }, ", or >.
+      TRUNCATION_PATTERN = /\.\.\.[\]}"'>)]*\s*\z/
+
+      # Pattern for detecting framework/gem frames in call stack.
+      FRAMEWORK_PATH_PATTERN = %r{/gems/|/\.rbenv/|/\.bundle/|/vendor/bundle/|\[C\]|/ruby/\d}
+
+      class << self
+        def call(session_id: nil, server_context:)
+          client = server_context[:session_manager].client(session_id)
+          client.auto_repause!
+
+          parts = []
+          total_truncated = 0
+
+          # Show trap context warning as the first section.
+          # Use cached value if available to avoid an extra round-trip.
+          in_trap = if client.respond_to?(:trap_context) && !client.trap_context.nil?
+            client.trap_context
+          elsif client.respond_to?(:in_trap_context?)
+            client.in_trap_context?
+          end
+          if in_trap
+            parts << "=== Context: Signal Trap ===\n" \
+                     "Restricted: DB queries, require, autoloading, method breakpoints\n" \
+                     "Available: evaluate_code (simple expressions), set_breakpoint (file:line), rails_routes\n" \
+                     "To escape: set_breakpoint(file, line) + trigger_request"
+          end
+
+          # Collect each section independently so partial results are still useful
+          variable_commands = %w[info\ locals info\ ivars]
+          sections = [
+            ["Current Location", "list"],
+            ["Local Variables", "info locals"],
+            ["Instance Variables", "info ivars"],
+            ["Call Stack", "bt"],
+            ["Breakpoints", "info breakpoints"],
+          ]
+
+          bt_raw = nil
+          sections.each do |title, command|
+            output = client.send_command(command)
+
+            # For variable sections, detect and annotate truncated values
+            if variable_commands.include?(command)
+              output, truncated_count = annotate_truncated_values(output)
+              if truncated_count > 0
+                total_truncated += truncated_count
+                title += " (#{truncated_count} truncated)"
+              end
+            end
+
+            # Summarize long call stacks by collapsing framework frames
+            if command == "bt"
+              bt_raw = output
+              output = summarize_call_stack(output)
+            end
+
+            parts << "=== #{title} ===\n#{output}"
+          rescue DebugMcp::TimeoutError
+            parts << "=== #{title} ===\n(timed out)"
+          end
+
+          # Annotate return events: the return value is shown in bt output (#=>)
+          # and in local variables (%return). Add a note so the agent understands
+          # the current line has already executed.
+          if bt_raw && return_event_frame?(bt_raw)
+            return_note = "=== Stop Event: Return ===\n" \
+                          "The current line (=>) has ALREADY been executed. " \
+                          "You are seeing the state AFTER this line ran.\n" \
+                          "Return value is shown in Call Stack (#=>) and Local Variables (%return)."
+
+            # Check if the return is due to an exception
+            begin
+              if (exception_info = client.check_current_exception)
+                return_note += "\n\nException in scope: #{exception_info}\n" \
+                               "This method/block is returning due to an exception, not a normal return."
+              end
+            rescue DebugMcp::Error
+              # Best-effort
+            end
+
+            parts << return_note
+          end
+
+          if total_truncated > 0
+            parts << "---\n#{total_truncated} variable(s) have truncated values. " \
+                     "Use 'inspect_object' to see full contents (e.g., inspect_object(expression: 'variable_name'))."
+          else
+            parts << "---\nTip: Use 'evaluate_code' or 'inspect_object' for detailed variable inspection."
+          end
+
+          if (http_note = PendingHttpHelper.pending_http_note(client))
+            parts << http_note
+          end
+
+          MCP::Tool::Response.new([{ type: "text", text: parts.join("\n\n") }])
+        rescue DebugMcp::Error => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.message}" }])
+        end
+
+        private
+
+        # Check if the current frame (=>) in bt output indicates a return event.
+        # The debug gem appends "#=>" to the frame line at return/b_return/c_return events:
+        #   =>#0  Class#method at file.rb:10 #=> return_value
+        def return_event_frame?(bt_output)
+          bt_output.each_line do |line|
+            return line.include?("#=>") if line.include?("=>#")
+          end
+          false
+        end
+
+        # Summarize a long call stack by collapsing consecutive framework frames.
+        # App code frames are preserved; gem/internal frames are collapsed into
+        # summary lines like "  ... 12 framework frames (actionpack, rack, puma) ..."
+        def summarize_call_stack(output)
+          lines = output.lines
+          return output if lines.size <= 15
+
+          result = []
+          gem_group = []
+
+          lines.each do |line|
+            if framework_frame?(line)
+              gem_group << line
+            else
+              if gem_group.any?
+                result << collapse_gem_frames(gem_group)
+                gem_group = []
+              end
+              result << line
+            end
+          end
+          result << collapse_gem_frames(gem_group) if gem_group.any?
+
+          result.join
+        end
+
+        def framework_frame?(line)
+          line.match?(FRAMEWORK_PATH_PATTERN)
+        end
+
+        def collapse_gem_frames(frames)
+          # Extract gem names from paths like /gems/actionpack-7.0.0/lib/...
+          # Gem names always start with a letter, so we skip numeric directories
+          # like /gems/3.3.0/ in paths such as ruby/gems/3.3.0/gems/actionpack-7.0.0/
+          gem_names = frames.filter_map { |f|
+            if (m = f.match(%r{/gems/([a-zA-Z][^/]*?)(?:-\d[\d.]*)?/}))
+              m[1]
+            elsif f.include?("[C]")
+              "C"
+            end
+          }.uniq.sort
+
+          label = gem_names.empty? ? "framework" : gem_names.join(", ")
+          count_label = frames.size == 1 ? "1 framework frame" : "#{frames.size} framework frames"
+          "  ... #{count_label} (#{label}) ...\n"
+        end
+
+        # Annotate truncated variable lines with [truncated] marker.
+        # Returns [annotated_output, truncated_count].
+        def annotate_truncated_values(output)
+          truncated_count = 0
+          annotated = output.each_line.map do |line|
+            # Variable lines in `info locals`/`info ivars` follow the pattern:
+            #   name = value
+            # Only check lines that contain " = " (variable assignments)
+            if line.include?(" = ") && line.match?(TRUNCATION_PATTERN)
+              truncated_count += 1
+              "#{line.chomp}  [truncated]\n"
+            else
+              line
+            end
+          end.join
+
+          [annotated, truncated_count]
+        end
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/get_source.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "../rails_helper"
+
+module DebugMcp
+  module Tools
+    class GetSource < MCP::Tool
+      MAX_SOURCE_LINES = 50
+
+      description "[Investigation] Get the source code of a method or class from the running process. " \
+                  "Use 'Class#method' for instance methods, 'Class.method' for class methods, " \
+                  "or 'Class' for class info including ancestors and method lists."
+
+      annotations(
+        title: "Get Source Code",
+        read_only_hint: true,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {
+          target: {
+            type: "string",
+            description: "Method or class to get source for (e.g., 'User#save', 'User.find', 'User')",
+          },
+          session_id: {
+            type: "string",
+            description: "Debug session ID (uses default session if omitted)",
+          },
+        },
+        required: ["target"],
+      )
+
+      class << self
+        def call(target:, session_id: nil, server_context:)
+          client = server_context[:session_manager].client(session_id)
+          client.auto_repause!
+
+          if target.include?("#") || target.include?(".")
+            get_method_source(client, target)
+          else
+            get_class_info(client, target)
+          end
+        rescue DebugMcp::Error => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.message}" }])
+        end
+
+        private
+
+        def get_method_source(client, target)
+          if target.include?("#")
+            class_name, method_name = target.split("#", 2)
+            method_ref = "#{class_name}.instance_method(:#{method_name})"
+          else
+            class_name, method_name = target.split(".", 2)
+            method_ref = "#{class_name}.method(:#{method_name})"
+          end
+
+          # Get source_location and parameters in one eval
+          info_code = "[#{method_ref}.source_location, #{method_ref}.parameters]"
+          raw = client.send_command("p #{info_code}").strip.sub(/\A=>\s*/, "")
+
+          if raw == "nil" || raw.start_with?("[nil")
+            return MCP::Tool::Response.new([{
+              type: "text",
+              text: "#{target}: source not available (native or C extension method)",
+            }])
+          end
+
+          # Parse source_location from output: [["file.rb", 26], [[:req, :name], ...]]
+          # Use a second eval to get clean values
+          file_output = client.send_command("p #{method_ref}.source_location[0]").strip.sub(/\A=>\s*/, "")
+          line_output = client.send_command("p #{method_ref}.source_location[1]").strip.sub(/\A=>\s*/, "")
+          params_output = client.send_command("p #{method_ref}.parameters").strip.sub(/\A=>\s*/, "")
+
+          file = file_output.delete('"')
+          line = line_output.to_i
+
+          # Read source directly from filesystem, or via remote if Docker/remote connection
+          source = read_method_source(client, file, line)
+
+          parts = [target]
+          parts << "  File: #{file}:#{line}"
+          parts << "  Parameters: #{params_output}" unless params_output.empty?
+          if source
+            parts << ""
+            parts << source
+          end
+
+          MCP::Tool::Response.new([{ type: "text", text: parts.join("\n") }])
+        end
+
+        def get_class_info(client, target)
+          parts = []
+
+          name = client.send_command("p #{target}.name").strip.sub(/\A=>\s*/, "")
+          parts << "Class: #{name}"
+
+          ancestors = client.send_command("p #{target}.ancestors.first(10).map(&:to_s)").strip.sub(/\A=>\s*/, "")
+          parts << "Ancestors: #{ancestors}"
+
+          imethods = client.send_command("p #{target}.instance_methods(false).sort.first(30)").strip.sub(/\A=>\s*/, "")
+          parts << "Instance methods: #{imethods}"
+
+          cmethods = client.send_command("p (#{target}.methods - Class.methods).sort.first(30)").strip.sub(/\A=>\s*/, "")
+          parts << "Class methods: #{cmethods}"
+
+          MCP::Tool::Response.new([{ type: "text", text: parts.join("\n") }])
+        end
+
+        def read_method_source(client, file, start_line)
+          if File.exist?(file)
+            read_method_source_local(file, start_line)
+          elsif client.remote
+            read_method_source_remote(client, file, start_line)
+          end
+        rescue StandardError
+          nil
+        end
+
+        def read_method_source_local(file, start_line)
+          lines = File.readlines(file)
+          return nil if start_line < 1 || start_line > lines.length
+
+          end_line = find_method_end(lines, start_line - 1)
+          selected = lines[(start_line - 1)..end_line]
+
+          selected.map.with_index(start_line) { |line, num| "  #{num.to_s.rjust(4)}| #{line}" }.join
+        end
+
+        # Max lines to fetch per chunk via debug session
+        REMOTE_CHUNK_SIZE = 50
+
+        def read_method_source_remote(client, file, start_line)
+          return nil if start_line < 1
+
+          # Get total line count from remote
+          count_str = RailsHelper.eval_expr(client, "File.readlines(#{file.inspect}).size")
+          return nil unless count_str
+
+          total_lines = count_str.to_i
+          return nil if start_line > total_lines
+
+          # Fetch enough lines to find method end (start_line through start_line + MAX_SOURCE_LINES)
+          fetch_start = start_line - 1
+          fetch_end = [fetch_start + MAX_SOURCE_LINES, total_lines - 1].min
+
+          all_lines = []
+          pos = fetch_start
+          while pos <= fetch_end
+            chunk_end = [pos + REMOTE_CHUNK_SIZE - 1, fetch_end].min
+            chunk = RailsHelper.eval_expr(client,
+              "File.readlines(#{file.inspect})[#{pos}..#{chunk_end}].join")
+            break unless chunk
+
+            all_lines << chunk
+            pos = chunk_end + 1
+          end
+
+          return nil if all_lines.empty?
+
+          lines = all_lines.join.lines
+          end_index = find_method_end(lines, 0)
+          selected = lines[0..end_index]
+
+          selected.map.with_index(start_line) { |line, num| "  #{num.to_s.rjust(4)}| #{line}" }.join
+        end
+
+        # girb本家のロジックを流用: インデント解析でメソッド終端を探す
+        # NOTE: girb-core切り出し時の共通化候補
+        def find_method_end(lines, start_index)
+          return [start_index + MAX_SOURCE_LINES, lines.length - 1].min if start_index >= lines.length
+
+          base_indent = lines[start_index][/^\s*/].length
+
+          (start_index + 1).upto([start_index + MAX_SOURCE_LINES, lines.length - 1].min) do |i|
+            line = lines[i]
+            next if line.strip.empty? || line.strip.start_with?("#")
+
+            current_indent = line[/^\s*/].length
+            if current_indent <= base_indent && line.strip.start_with?("end")
+              return i
+            end
+          end
+
+          [start_index + MAX_SOURCE_LINES, lines.length - 1].min
+        end
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/inspect_object.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "../pending_http_helper"
+
+module DebugMcp
+  module Tools
+    class InspectObject < MCP::Tool
+      description "[Investigation] Deep-inspect a Ruby object in the paused process. " \
+                  "Returns the value, class, and instance variables. " \
+                  "More detailed than evaluate_code — use this to understand an object's internal state."
+
+      annotations(
+        title: "Inspect Object",
+        read_only_hint: true,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {
+          expression: {
+            type: "string",
+            description: "Variable name or Ruby expression to inspect (e.g., 'user', '@items.first')",
+          },
+          session_id: {
+            type: "string",
+            description: "Debug session ID (uses default session if omitted)",
+          },
+        },
+        required: ["expression"],
+      )
+
+      class << self
+        def call(expression:, session_id: nil, server_context:)
+          client = server_context[:session_manager].client(session_id)
+          client.auto_repause!
+
+          parts = []
+
+          # RT 1: Get the pretty-printed value (primary - if this fails, expression is invalid)
+          value_output = client.send_command("pp #{expression}")
+          parts << "Value:\n#{value_output}"
+
+          # RT 2: Get class + instance variables (+ class variables if Module) in a single command
+          begin
+            meta_output = client.send_command(
+              "p [(#{expression}).class.to_s, (#{expression}).instance_variables, " \
+              "(#{expression}).is_a?(Module) ? (#{expression}).class_variables : nil]",
+            )
+            class_name, ivars, cvars = parse_meta(meta_output)
+            parts << "Class: #{class_name}" if class_name
+            parts << "Instance variables: #{ivars}" if ivars
+
+            # RT 3: Get class variable values (only for Module/Class with class variables)
+            if cvars && cvars != "[]"
+              begin
+                cvar_values = client.send_command(
+                  "pp Hash[(#{expression}).class_variables.map{|v|" \
+                  "[v,begin;(#{expression}).class_variable_get(v);rescue;'(error)';end]}]",
+                )
+                parts << "Class variables:\n#{cvar_values}"
+              rescue DebugMcp::TimeoutError
+                parts << "Class variables: #{cvars}"
+              end
+            elsif cvars
+              parts << "Class variables: #{cvars}"
+            end
+          rescue DebugMcp::TimeoutError
+            parts << "Class: (timed out)"
+            parts << "Instance variables: (timed out)"
+          end
+
+          text = parts.join("\n\n")
+          text = append_trap_context_note(client, text)
+          if (http_note = PendingHttpHelper.pending_http_note(client))
+            text = "#{text}\n\n#{http_note}"
+          end
+          MCP::Tool::Response.new([{ type: "text", text: text }])
+        rescue DebugMcp::Error => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.message}" }])
+        end
+
+        private
+
+        # Parse combined meta output: => ["ClassName", [:@ivar1, :@ivar2], [:@@cvar1] or nil]
+        # Returns [class_name, ivars_string, cvars_string_or_nil] or falls back to raw output.
+        def parse_meta(output)
+          cleaned = output.strip.sub(/\A=> /, "")
+          # Match: ["ClassName", [...], [...] or nil]
+          if (match = cleaned.match(/\A\["([^"]*)",\s*(\[.*?\]),\s*(nil|\[.*?\])\]\z/))
+            cvars = match[3] == "nil" ? nil : match[3]
+            [match[1], match[2], cvars]
+          else
+            # Fallback: return raw output as class info
+            [cleaned, nil, nil]
+          end
+        end
+
+        def append_trap_context_note(client, text)
+          return text unless client.respond_to?(:trap_context) && client.trap_context
+          "#{text}\n\n[trap context]"
+        end
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/list_debug_sessions.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module DebugMcp
+  module Tools
+    class ListDebugSessions < MCP::Tool
+      description "[Discovery] List available Ruby debug sessions on this machine. " \
+                  "Shows running Ruby processes started with 'rdbg --open' that can be " \
+                  "connected to. Use this first to find sessions before calling 'connect'."
+
+      annotations(
+        title: "List Debug Sessions",
+        read_only_hint: true,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {},
+      )
+
+      class << self
+        def call(server_context:)
+          unix_sessions = DebugClient.list_sessions
+          tcp_sessions = TcpSessionDiscovery.discover
+
+          if unix_sessions.empty? && tcp_sessions.empty?
+            text = "No debug sessions found.\n\n" \
+                   "To start a debuggable Ruby process:\n" \
+                   "  rdbg --open <script.rb>\n" \
+                   "  rdbg --open --port=12345 <script.rb>\n" \
+                   "  RUBY_DEBUG_OPEN=true ruby <script.rb>\n\n" \
+                   "For Docker containers:\n" \
+                   "  docker run -e RUBY_DEBUG_OPEN=true -e RUBY_DEBUG_HOST=0.0.0.0 " \
+                   "-e RUBY_DEBUG_PORT=12345 -p 12345:12345 <image>"
+          else
+            lines = []
+
+            unix_sessions.each do |s|
+              name_info = s[:name] ? " (#{s[:name]})" : ""
+              lines << "  PID #{s[:pid]}#{name_info}: #{s[:path]}"
+            end
+
+            tcp_sessions.each do |s|
+              source_label = s[:source] == :docker ? "Docker" : "TCP"
+              lines << "  #{source_label} \"#{s[:name]}\": #{s[:host]}:#{s[:port]} " \
+                       "(connect with port: #{s[:port]})"
+            end
+
+            total = unix_sessions.size + tcp_sessions.size
+            text = "Found #{total} debug session(s):\n#{lines.join("\n")}"
+          end
+
+          MCP::Tool::Response.new([{ type: "text", text: text }])
+        end
+      end
+    end
+  end
+end