debug-mcp 0.1.2

data/lib/debug_mcp/tools/list_files.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "../rails_helper"
+
+module DebugMcp
+  module Tools
+    class ListFiles < MCP::Tool
+      MAX_ENTRIES = 500
+
+      description "[Investigation] List files and directories in a path from the debug session's machine. " \
+                  "Use this to explore directory structure, find source files, or locate configuration. " \
+                  "Relative paths are resolved against the debugged process's working directory."
+
+      annotations(
+        title: "List Files",
+        read_only_hint: true,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {
+          path: {
+            type: "string",
+            description: "Directory path to list (relative to working directory or absolute)",
+          },
+          pattern: {
+            type: "string",
+            description: "Optional glob pattern to filter entries (e.g., '*.rb', '**/*.yml'). " \
+                         "When omitted, lists immediate children of the directory.",
+          },
+          session_id: {
+            type: "string",
+            description: "Debug session ID (uses default session if omitted)",
+          },
+        },
+        required: ["path"],
+      )
+
+      class << self
+        def call(path:, pattern: nil, session_id: nil, server_context:)
+          client = get_client(server_context, session_id)
+
+          if client&.remote
+            return list_remote(client, path, pattern)
+          end
+
+          full_path = resolve_path(path, server_context, session_id)
+          list_local(full_path, pattern)
+        rescue DebugMcp::Error => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.message}" }])
+        end
+
+        private
+
+        def get_client(server_context, session_id)
+          if session_id
+            server_context[:session_manager].get(session_id).client
+          else
+            server_context[:session_manager].client
+          end
+        rescue DebugMcp::Error
+          nil
+        end
+
+        def resolve_path(path, server_context, session_id)
+          return File.expand_path(path) if path.start_with?("/") || path.start_with?("~")
+
+          cwd = remote_cwd(server_context, session_id)
+          if cwd
+            File.join(cwd, path)
+          else
+            File.expand_path(path)
+          end
+        end
+
+        def remote_cwd(server_context, session_id)
+          client = if session_id
+            server_context[:session_manager].get(session_id).client
+          else
+            server_context[:session_manager].client
+          end
+          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
+
+        def list_local(full_path, pattern)
+          unless Dir.exist?(full_path)
+            return MCP::Tool::Response.new([{ type: "text",
+              text: "Error: Directory not found: #{full_path}" }])
+          end
+
+          if pattern
+            glob_path = File.join(full_path, pattern)
+            entries = Dir.glob(glob_path).sort
+          else
+            entries = Dir.children(full_path).sort.map { |name| File.join(full_path, name) }
+          end
+
+          format_entries(full_path, entries, pattern)
+        end
+
+        def list_remote(client, path, pattern)
+          client.auto_repause!
+
+          # Resolve relative path
+          full_path = if path.start_with?("/")
+            path
+          else
+            cwd = RailsHelper.eval_expr(client, "Dir.pwd")
+            cwd ? File.join(cwd, path) : path
+          end
+
+          # Check directory exists
+          exists = RailsHelper.eval_expr(client, "Dir.exist?(#{full_path.inspect})")
+          unless exists == "true"
+            return MCP::Tool::Response.new([{ type: "text",
+              text: "Error: Directory not found on remote process: #{full_path}" }])
+          end
+
+          if pattern
+            expr = "Dir.glob(File.join(#{full_path.inspect}, #{pattern.inspect})).sort.first(#{MAX_ENTRIES + 1})" \
+                   ".map{|f| (File.directory?(f) ? 'd:' : 'f:') + f }.join(\"\\n\")"
+          else
+            expr = "Dir.children(#{full_path.inspect}).sort.first(#{MAX_ENTRIES + 1})" \
+                   ".map{|n| f=File.join(#{full_path.inspect},n); (File.directory?(f) ? 'd:' : 'f:') + f }.join(\"\\n\")"
+          end
+
+          result = RailsHelper.eval_expr(client, expr)
+          unless result
+            return MCP::Tool::Response.new([{ type: "text",
+              text: "Error: Failed to list directory on remote process: #{full_path}" }])
+          end
+
+          raw_entries = result.split("\n").reject(&:empty?)
+          truncated = raw_entries.length > MAX_ENTRIES
+          raw_entries = raw_entries.first(MAX_ENTRIES) if truncated
+
+          lines = []
+          raw_entries.each do |entry|
+            if entry.start_with?("d:")
+              lines << "[dir]  #{entry[2..]}"
+            else
+              lines << "[file] #{entry[2..]}"
+            end
+          end
+
+          header = "#{full_path} (#{raw_entries.length} entries) [remote]"
+          header += " (truncated to #{MAX_ENTRIES})" if truncated
+          text = "#{header}\n\n#{lines.join("\n")}"
+
+          MCP::Tool::Response.new([{ type: "text", text: text }])
+        rescue DebugMcp::Error => e
+          MCP::Tool::Response.new([{ type: "text", text: "Error listing remote directory: #{e.message}" }])
+        end
+
+        def format_entries(full_path, entries, pattern)
+          truncated = entries.length > MAX_ENTRIES
+          entries = entries.first(MAX_ENTRIES) if truncated
+
+          lines = entries.map do |entry|
+            if File.directory?(entry)
+              "[dir]  #{entry}"
+            else
+              "[file] #{entry}"
+            end
+          end
+
+          header = "#{full_path} (#{entries.length} entries)"
+          header += " matching '#{pattern}'" if pattern
+          header += " (truncated to #{MAX_ENTRIES})" if truncated
+          text = "#{header}\n\n#{lines.join("\n")}"
+
+          MCP::Tool::Response.new([{ type: "text", text: text }])
+        end
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/list_paused_sessions.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module DebugMcp
+  module Tools
+    class ListPausedSessions < MCP::Tool
+      description "[Discovery] List all active debug sessions managed by debug-mcp. " \
+                  "Shows connected sessions, their PIDs, and idle time."
+
+      annotations(
+        title: "List Active Sessions",
+        read_only_hint: true,
+        destructive_hint: false,
+        open_world_hint: false,
+      )
+
+      input_schema(
+        properties: {},
+      )
+
+      class << self
+        def call(server_context:)
+          manager = server_context[:session_manager]
+          sessions = manager.active_sessions(include_client: true)
+
+          if sessions.empty?
+            text = "No active debug sessions. Use 'connect' or 'run_script' to start one."
+          else
+            lines = sessions.map { |s| format_session(s) }
+            text = "Active debug sessions:\n#{lines.join("\n")}"
+            text += "\n\nNote: Sessions expire after inactivity. Any tool call resets the timer."
+          end
+
+          MCP::Tool::Response.new([{ type: "text", text: text }])
+        end
+
+        private
+
+        def format_session(s)
+          status = s[:connected] ? "connected" : "disconnected"
+          status += ", paused" if s[:paused]
+          idle = format_duration(s[:idle_seconds])
+
+          line = "  #{s[:session_id]} (PID: #{s[:pid]}, #{status}, idle: #{idle})"
+
+          # Show remaining time before timeout
+          if s[:timeout_seconds]
+            remaining = s[:timeout_seconds] - s[:idle_seconds]
+            if remaining > 300
+              line += "\n    Timeout: #{format_duration(remaining)} remaining"
+            elsif remaining > 0
+              line += "\n    Timeout: #{format_duration(remaining)} remaining (WARNING: expiring soon)"
+            else
+              line += "\n    Timeout: EXPIRED (will be reaped on next check)"
+            end
+          end
+
+          # Query current stop location and breakpoint count from the client
+          client = s[:client]
+          if client&.connected? && client.paused
+            location = query_stop_location(client)
+            line += "\n    Location: #{location}" if location
+
+            bp_count = query_breakpoint_count(client)
+            line += "\n    Breakpoints: #{bp_count}" if bp_count
+          end
+
+          line
+        end
+
+        # Query the current stop location from the debug session.
+        # Returns "file.rb:10 in ClassName#method" or nil.
+        def query_stop_location(client)
+          output = client.send_command("frame")
+          if (match = output.match(/#\d+\s+(.+?)\s+at\s+(.+:\d+)/))
+            "#{match[2]} in #{match[1].strip}"
+          end
+        rescue DebugMcp::Error
+          nil
+        end
+
+        # Query the number of breakpoints set.
+        # Returns a string like "3 set" or nil.
+        def query_breakpoint_count(client)
+          output = client.send_command("info breakpoints")
+          cleaned = output.strip
+          return nil if cleaned.empty? || cleaned.include?("No breakpoints")
+
+          count = cleaned.lines.count { |l| l.match?(/\A\s*#\d+/) }
+          count > 0 ? "#{count} set" : nil
+        rescue DebugMcp::Error
+          nil
+        end
+
+        def format_duration(seconds)
+          if seconds < 60
+            "#{seconds}s"
+          elsif seconds < 3600
+            "#{seconds / 60}m #{seconds % 60}s"
+          else
+            "#{seconds / 3600}h #{(seconds % 3600) / 60}m"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/next.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module DebugMcp
+  module Tools
+    class Next < MCP::Tool
+      description "[Control] Step over to the next line without entering method calls. " \
+                  "Use 'step' instead to enter called methods. " \
+                  "Inside a block (e.g., each, map, reject), 'next' advances within the current " \
+                  "block iteration. To skip to the NEXT ITERATION, use set_breakpoint with one_shot: true " \
+                  "on the first line of the block body, then continue_execution. " \
+                  "Use 'finish' to exit the current block/method entirely. " \
+                  "If an exception is raised and rescued during the step, it will be reported automatically."
+
+      annotations(
+        title: "Step Over",
+        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("next")
+
+          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

data/lib/debug_mcp/tools/rails_info.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "mcp"
+require "yaml"
+require_relative "../rails_helper"
+
+module DebugMcp
+  module Tools
+    class RailsInfo < MCP::Tool
+      description "[Investigation] Show Rails application overview: app name, Rails/Ruby versions, " \
+                  "environment, and root path. Also shows database configuration and route count " \
+                  "when available (these require escaping trap context first on Puma/threaded servers). " \
+                  "Use this after connecting to a Rails process to quickly understand the application."
+
+      annotations(
+        title: "Rails App Info",
+        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)",
+          },
+        },
+      )
+
+      SENSITIVE_KEYS = %w[password secret secret_key_base secret_key].freeze
+
+      class << self
+        def call(session_id: nil, server_context:)
+          client = server_context[:session_manager].client(session_id)
+          client.auto_repause!
+          RailsHelper.require_rails!(client)
+
+          parts = []
+
+          # App name, Rails version, environment
+          parts << build_app_section(client)
+
+          # Root path
+          parts << build_root_section(client)
+
+          # Database configuration
+          parts << build_db_section(client)
+
+          # Route summary
+          parts << build_routes_section(client)
+
+          text = parts.compact.join("\n\n")
+
+          if text.include?("(unavailable)")
+            text += "\n\n#{RailsHelper::TRAP_CONTEXT_HINT}" if RailsHelper.trap_context?(client)
+          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 build_app_section(client)
+          lines = ["=== Rails Application ==="]
+
+          app_name = eval_expr(client, "Rails.application.class.module_parent_name")
+          lines << "App: #{app_name}" if app_name
+
+          rails_version = eval_expr(client, "Rails::VERSION::STRING")
+          rails_env = eval_expr(client, "Rails.env")
+          if rails_version
+            env_part = rails_env ? " (#{rails_env})" : ""
+            lines << "Rails: #{rails_version}#{env_part}"
+          end
+
+          ruby_version = eval_expr(client, "RUBY_VERSION")
+          lines << "Ruby: #{ruby_version}" if ruby_version
+
+          lines.join("\n")
+        end
+
+        def build_root_section(client)
+          root = eval_expr(client, "Rails.root.to_s")
+          root ? "Root: #{root}" : nil
+        end
+
+        def build_db_section(client)
+          code = build_db_script
+          result = run_info_script(client, code)
+          # Fall through to YAML fallback if result is an error message
+          # (e.g., "Database:\n  Error: can't be called from trap context")
+          return result if result && !result.include?("Error:")
+
+          # Fallback: read database.yml directly (works in trap context)
+          build_db_section_from_yaml(client)
+        rescue DebugMcp::Error
+          build_db_section_from_yaml(client)
+        end
+
+        def build_routes_section(client)
+          code = build_routes_script
+          result = run_info_script(client, code)
+          result || "Routes:\n  (unavailable)"
+        rescue DebugMcp::Error
+          "Routes:\n  (unavailable)"
+        end
+
+        def run_info_script(client, code)
+          RailsHelper.run_base64_script(client, code)
+        end
+
+        def eval_expr(client, expr)
+          RailsHelper.eval_expr(client, expr)
+        end
+
+        # Fallback: read config/database.yml via the debug session's File.read.
+        # File I/O works in trap context (no threads/mutex needed).
+        # ERB tags are replaced with DYNAMIC since they can't be evaluated.
+        def build_db_section_from_yaml(client)
+          root = eval_expr(client, "Rails.root.to_s")
+          return "Database:\n  (unavailable)" unless root
+
+          rails_env = eval_expr(client, "Rails.env") || "development"
+          yaml_path = "#{root}/config/database.yml"
+          # Use RailsHelper.eval_expr which properly handles \n unescaping
+          raw = RailsHelper.eval_expr(client, "File.read(#{yaml_path.inspect})")
+          return "Database:\n  (unavailable)" unless raw
+
+          parse_database_yaml(raw, rails_env)
+        rescue StandardError
+          "Database:\n  (unavailable)"
+        end
+
+        # Parse database.yml content, stripping ERB and extracting the current env config.
+        def parse_database_yaml(raw_yaml, rails_env)
+          # Replace ERB tags with placeholder
+          sanitized = raw_yaml.gsub(/<%.*?%>/, "DYNAMIC")
+          config = YAML.safe_load(sanitized, permitted_classes: [Symbol]) || {}
+          env_config = config[rails_env] || config["default"] || config.values.first
+
+          return "Database:\n  (unavailable)" unless env_config.is_a?(Hash)
+
+          lines = ["Database: (from database.yml)"]
+          env_config.each do |key, value|
+            key_s = key.to_s
+            val = SENSITIVE_KEYS.include?(key_s) ? "[FILTERED]" : value.to_s
+            lines << "  #{key_s}: #{val}"
+          end
+          lines.join("\n")
+        rescue Psych::SyntaxError
+          "Database:\n  (unavailable — database.yml parse error)"
+        end
+
+        # Scripts return values instead of using puts.
+        # In trap context, puts output is not captured by the debug gem,
+        # but expression return values are always captured.
+        def build_db_script
+          sensitive_keys = SENSITIVE_KEYS.map { |k| "\"#{k}\"" }.join(", ")
+          <<~RUBY
+            begin
+              if defined?(ActiveRecord::Base)
+                config = ActiveRecord::Base.connection_db_config
+                hash = config.configuration_hash
+                sensitive = [#{sensitive_keys}]
+                lines = ["Database:"]
+                hash.each do |k, v|
+                  key_s = k.to_s
+                  val = sensitive.include?(key_s) ? "[FILTERED]" : v.to_s
+                  lines << "  " + key_s + ": " + val
+                end
+                lines.join("\\n")
+              end
+            rescue => e
+              "Database:\\n  Error: " + e.message
+            end
+          RUBY
+        end
+
+        def build_routes_script
+          <<~RUBY
+            begin
+              routes = Rails.application.routes.routes
+              count = routes.count { |r| !r.defaults[:controller].to_s.empty? }
+              if count > 0
+                "Routes: " + count.to_s + " defined (use 'rails_routes' for details)"
+              else
+                "Routes: none defined"
+              end
+            rescue => e
+              "Routes: unable to load"
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end