rails_pulse 0.4.2 → 0.5.0.pre.2

data/lib/rails_pulse/mcp/tools/endpoint.rb

@@ -0,0 +1,167 @@
+require "json"
+
+module RailsPulse
+  module Mcp
+    module Tools
+      class Endpoint < ::MCP::Tool
+        extend Helpers
+
+        tool_name "rails_pulse_endpoint"
+        description "Detailed performance profile for a single endpoint, computed from its most recent requests " \
+                    "in the period: latency distribution, error rate and status codes. " \
+                    "Use this to deep-dive into a specific route's performance."
+
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          open_world_hint: false
+        )
+
+        input_schema(
+          properties: {
+            endpoint: {
+              type: "string",
+              description: "Controller action (e.g. 'CheckoutController#create') or path (e.g. '/checkout'); " \
+                           "case-insensitive substring match. If unknown, use rails_pulse_routes first."
+            },
+            **Helpers.window_properties("last_7_days"),
+            limit: {
+              type: "integer",
+              description: "Most recent requests of this endpoint to analyze (1-500). More data = more accurate percentiles.",
+              default: 200
+            }
+          },
+          required: [ "endpoint" ]
+        )
+
+        def self.call(endpoint:, period: "last_7_days", limit: 200, server_context:, **options)
+          respond(server_context) do |client|
+            window = resolve_window(period: period, since: options[:since], until_time: options[:until])
+            limit = limit.to_i.clamp(1, 500)
+
+            # The API matches the endpoint against the request's controller
+            # action and its route's path, so the page holds only this
+            # endpoint's requests rather than the newest across the app.
+            result = client.get("/requests", window_params(window).merge(route: endpoint, limit: limit, offset: 0))
+            matching = result["data"] || []
+
+            if matching.empty?
+              {
+                endpoint: endpoint,
+                window: window,
+                error: "No requests found matching '#{endpoint}'. Use rails_pulse_routes to see available endpoints."
+              }
+            else
+              build_profile(endpoint, window, matching, result.dig("meta", "total"))
+            end
+          end
+        end
+
+        private_class_method def self.build_profile(endpoint, window, requests, total)
+          durations = requests.map { |r| r["duration"].to_f }.sort
+          errors = requests.select { |r| r["is_error"] }
+          statuses = requests.map { |r| r["status"] }.tally.sort_by { |_, c| -c }
+          sorted_by_time = requests.sort_by { |r| r["occurred_at"].to_s }
+
+          # A substring can match several routes ('/users' also matches
+          # '/admin/users'). The figures then cover all of them, so the profile
+          # is labelled as such and offers no single route_id to drill into.
+          routes = requests.group_by { |r| r["route_id"] }
+          single = routes.size == 1
+
+          profile = {
+            endpoint: single ? (requests.first["controller_action"] || endpoint) : "#{routes.size} routes matching '#{endpoint}'",
+            # The handle for the next hop: rails_pulse_queries takes it to show
+            # the SQL that ran inside this endpoint.
+            route_id: single ? requests.first["route_id"] : nil,
+            window: window,
+            request_count: total || requests.size,
+            sampled_requests: requests.size,
+            latency: {
+              avg_ms: (durations.sum / durations.size).round(1),
+              min_ms: durations.first.round(1),
+              max_ms: durations.last.round(1),
+              p50_ms: percentile(durations, 50).round(1),
+              p95_ms: percentile(durations, 95).round(1),
+              p99_ms: percentile(durations, 99).round(1)
+            },
+            errors: {
+              count: errors.size,
+              rate: ((errors.size.to_f / requests.size) * 100).round(1)
+            },
+            status_distribution: statuses.map { |code, count| { status: code, count: count } },
+            time_range: {
+              first_request: sorted_by_time.first&.dig("occurred_at"),
+              last_request: sorted_by_time.last&.dig("occurred_at")
+            }
+          }
+
+          unless single
+            profile[:matched_routes] = routes.map do |route_id, reqs|
+              { route_id: route_id, controller_action: reqs.first["controller_action"], sampled_requests: reqs.size }
+            end.sort_by { |r| -r[:sampled_requests] }
+          end
+
+          # Percentiles are computed over the sampled page, which is the most
+          # recent requests rather than the whole window. Said beside the
+          # numbers so they are not read as the window's own statistics: a
+          # window whose older half was slow reports a much lower p95 here.
+          if profile[:sampled_requests] < profile[:request_count]
+            profile[:latency][:computed_over] =
+              "the #{profile[:sampled_requests]} most recent requests, not all #{profile[:request_count]} in the window"
+          end
+
+          # Add recent errors detail if any
+          if errors.any?
+            profile[:recent_errors] = errors.sort_by { |r| r["occurred_at"].to_s }.reverse.first(5).map do |r|
+              {
+                status: r["status"],
+                duration_ms: r["duration"].to_f.round(1),
+                occurred_at: r["occurred_at"]
+              }
+            end
+          end
+
+          profile[:summary] = build_summary(profile)
+          profile[:next_steps] = build_next_steps(profile)
+          profile
+        end
+
+        private_class_method def self.build_summary(profile)
+          parts = []
+          parts << "#{profile[:request_count]} requests (#{profile[:sampled_requests]} most recent analyzed)"
+          parts << "avg #{profile[:latency][:avg_ms]}ms (p95: #{profile[:latency][:p95_ms]}ms)"
+          parts << "#{profile[:errors][:rate]}% error rate" if profile[:errors][:count] > 0
+          parts.join(", ") + "."
+        end
+
+        private_class_method def self.build_next_steps(profile)
+          steps = []
+          if profile[:matched_routes]
+            steps << "'#{profile[:endpoint]}' covers several routes, so these figures mix them. Call rails_pulse_endpoint " \
+                     "again with one controller_action from matched_routes, or pass a route_id from it to rails_pulse_queries."
+          end
+          if profile[:latency][:computed_over]
+            steps << "Percentiles cover only the sampled requests. Narrow the window with since/until until " \
+                     "sampled_requests equals request_count for statistics over the whole window."
+          end
+          if profile[:latency][:p95_ms] > 1000
+            steps << "P95 latency is over 1s — investigate slow database queries or N+1s in the controller."
+          end
+          if profile[:latency][:p95_ms] > profile[:latency][:avg_ms] * 3
+            steps << "High p95/avg ratio suggests occasional very slow requests — look for intermittent issues."
+          end
+          if profile[:errors][:rate] > 5
+            steps << "Error rate is above 5% — check recent_errors and investigate the failure pattern."
+          end
+          steps << "Use rails_pulse_errors to see error details for this endpoint." if profile[:errors][:count] > 0
+          if profile[:route_id]
+            steps << "Call rails_pulse_queries with route: #{profile[:route_id]} for the SQL that ran inside this endpoint and the file and line each query came from."
+          end
+          steps << "Inspect the controller source code and associated SQL queries for optimization opportunities."
+          steps
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/mcp/tools/errors.rb

@@ -0,0 +1,104 @@
+require "json"
+
+module RailsPulse
+  module Mcp
+    module Tools
+      class Errors < ::MCP::Tool
+        extend Helpers
+
+        tool_name "rails_pulse_errors"
+        description "Show recent errors: HTTP 4xx/5xx responses grouped by endpoint. " \
+                    "Use this to identify which endpoints are failing and how often."
+
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          open_world_hint: false
+        )
+
+        input_schema(
+          properties: {
+            **Helpers.window_properties("last_24_hours"),
+            limit: {
+              type: "integer",
+              description: "Maximum number of error requests to fetch (1-500)",
+              default: 100
+            },
+            status: {
+              type: "string",
+              description: "Error class filter: '4xx', '5xx' (default), or exact code like '500'",
+              default: "5xx"
+            },
+            path_prefix: {
+              type: "string",
+              description: "Only requests whose path starts with this, e.g. '/wp-admin/'. A trailing '*' is ignored, " \
+                           "so a Rails Pulse Cloud path_prefix such as '/wp-admin/*' can be passed as it is. " \
+                           "Requests no route matched are listed by path; pair with status '404'."
+            }
+          }
+        )
+
+        def self.call(period: "last_24_hours", limit: 100, status: "5xx", path_prefix: nil, server_context:, **options)
+          respond(server_context) do |client|
+            window = resolve_window(period: period, since: options[:since], until_time: options[:until])
+            limit = limit.to_i.clamp(1, 500)
+
+            params = { limit: limit, offset: 0 }
+            params.merge!(window_params(window))
+            params[:status] = status
+            params[:path_prefix] = path_prefix if path_prefix
+
+            result = client.get("/requests", params)
+            requests = result["data"] || []
+            total = result.dig("meta", "total") || requests.size
+
+            # A request no route matched has no controller action, so it is
+            # grouped under its path rather than with every other one.
+            by_endpoint = requests.group_by { |r| r["controller_action"] || r["path"] || "unknown" }
+
+            error_groups = by_endpoint.map do |action, reqs|
+              sorted = reqs.sort_by { |r| r["occurred_at"].to_s }.reverse
+              statuses = reqs.map { |r| r["status"] }.tally.sort_by { |_, c| -c }
+
+              {
+                endpoint: action,
+                count: reqs.size,
+                status_codes: statuses.map { |code, count| { status: code, count: count } },
+                first_seen: sorted.last&.dig("occurred_at"),
+                last_seen: sorted.first&.dig("occurred_at"),
+                avg_duration_ms: (reqs.sum { |r| r["duration"].to_f } / reqs.size).round(1)
+              }
+            end
+
+            error_groups.sort_by! { |g| -g[:count] }
+
+            {
+              window: window,
+              status_filter: status,
+              total_errors: total,
+              errors_returned: requests.size,
+              by_endpoint: error_groups,
+              summary: build_summary(error_groups, total, requests.size, status)
+            }
+          end
+        end
+
+        # by_endpoint groups only the requests fetched, so when that is fewer
+        # than the total the endpoint count is said to cover the sample.
+        private_class_method def self.build_summary(groups, total, sampled, status)
+          return "No #{status} errors found for this period." if groups.empty?
+
+          worst = groups.first
+          parts = if sampled < total
+            [ "#{total} total #{status} errors; the latest #{sampled} span #{groups.size} endpoint(s)" ]
+          else
+            [ "#{total} total #{status} errors across #{groups.size} endpoint(s)" ]
+          end
+          parts << "Most errors: #{worst[:endpoint]} (#{worst[:count]} occurrences)"
+
+          parts.join(". ") + "."
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/mcp/tools/exception_detail.rb

@@ -0,0 +1,118 @@
+module RailsPulse
+  module Mcp
+    module Tools
+      # Named ExceptionDetail rather than Exception so nothing in this namespace
+      # shadows ::Exception.
+      class ExceptionDetail < ::MCP::Tool
+        extend Helpers
+
+        tool_name "rails_pulse_exception"
+        description "Everything recorded about one exception group: its status and counts plus its most recent " \
+                    "occurrences, each with the full backtrace, request method, URL, filtered params, environment " \
+                    "and deploy SHA. Use this after rails_pulse_exceptions (or when given an id) to find the cause " \
+                    "in the code; app_frames lists the backtrace frames inside the application."
+
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          open_world_hint: false
+        )
+
+        input_schema(
+          properties: {
+            id: {
+              type: "integer",
+              description: "The exception group id, from rails_pulse_exceptions or the dashboard URL"
+            },
+            occurrences: {
+              type: "integer",
+              description: "How many of the most recent occurrences to include (1-20)",
+              default: 3
+            }
+          },
+          required: [ "id" ]
+        )
+
+        def self.call(id:, occurrences: 3, server_context:, **_options)
+          respond(server_context) do |client|
+            count = occurrences.to_i.clamp(1, 20)
+            result = client.get("/exceptions/#{id.to_i}", { occurrences: count })
+            group = result["data"] || {}
+            recent = (group["occurrences"] || []).map { |o| format_occurrence(o) }
+            latest = recent.first
+
+            {
+              id: group["id"],
+              exception_class: group["exception_class"],
+              location: group["location"],
+              message: group["message"],
+              status: group["status"],
+              occurrence_count: group["occurrence_count"],
+              first_seen_at: group["first_seen_at"],
+              last_seen_at: group["last_seen_at"],
+              resolved_at: group["resolved_at"],
+              app_frames: latest ? latest[:app_frames] : [],
+              occurrences: recent,
+              summary: build_summary(group, latest),
+              next_steps: build_next_steps(group, latest)
+            }
+          end
+        end
+
+        private_class_method def self.format_occurrence(occurrence)
+          frames = Array(occurrence["backtrace"]).map { |f| format_frame(f) }
+          {
+            id: occurrence["id"],
+            occurred_at: occurrence["occurred_at"],
+            message: truncate(occurrence["message"], 500),
+            request: occurrence["request_url"] ? "#{occurrence["request_method"]} #{occurrence["request_url"]}".strip : nil,
+            request_params: occurrence["request_params"],
+            environment: occurrence["environment"],
+            deploy_sha: occurrence["deploy_sha"],
+            app_frames: frames.select { |f| app_frame?(f) },
+            backtrace: frames
+          }
+        end
+
+        private_class_method def self.format_frame(frame)
+          return { location: frame.to_s } unless frame.is_a?(Hash)
+
+          location = [ frame["file"], frame["line"] ].compact.join(":")
+          { location: location, method: frame["method"] }
+        end
+
+        private_class_method def self.app_frame?(frame)
+          frame[:location].to_s.start_with?("app/", "lib/", "config/")
+        end
+
+        private_class_method def self.build_summary(group, latest)
+          return "No exception group found." if group.empty?
+
+          parts = [ "#{group["exception_class"]} at #{group["location"] || "unknown location"}: " \
+                    "#{group["status"]}, #{group["occurrence_count"]} occurrence(s), last #{group["last_seen_at"]}" ]
+          if latest
+            parts << (latest[:request] ? "Latest was #{latest[:request]}" : "Latest came from a background job")
+            top = latest[:app_frames].first
+            parts << "First app frame: #{top[:location]}#{top[:method] ? " in #{top[:method]}" : ""}" if top
+          end
+          parts.join(". ") + "."
+        end
+
+        private_class_method def self.build_next_steps(group, latest)
+          return [ "Check the id with rails_pulse_exceptions; nothing matched." ] if group.empty?
+
+          steps = []
+          top = latest && latest[:app_frames].first
+          if top
+            steps << "Open #{top[:location]} and read the code around it with the latest message in mind: #{truncate(group["message"], 160)}"
+          else
+            steps << "No application frame in the backtrace; the raise happened in a gem. Read the outermost frames to find the call site."
+          end
+          steps << "Compare the occurrences' request params and URLs to see what input triggers it." if latest && latest[:request]
+          steps << "Call rails_pulse_deployments with period: \"#{group["first_seen_at"]}\" to see whether a release introduced it." if group["first_seen_at"]
+          steps
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/mcp/tools/exceptions.rb

@@ -0,0 +1,128 @@
+module RailsPulse
+  module Mcp
+    module Tools
+      class Exceptions < ::MCP::Tool
+        extend Helpers
+
+        tool_name "rails_pulse_exceptions"
+        description "Exception groups captured from web requests and background jobs: one entry per exception " \
+                    "class and app-code location, with its status (open, resolved, ignored), occurrence count, " \
+                    "latest message, and when it first and last fired. Use this to see what is actually raising " \
+                    "right now; rails_pulse_errors only knows which endpoints answered 5xx."
+
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          open_world_hint: false
+        )
+
+        input_schema(
+          properties: {
+            **Helpers.window_properties("last_7_days"),
+            period: {
+              type: "string",
+              description: "Only groups last seen in this window: 'last_hour', 'last_24_hours', 'last_7_days', " \
+                           "or 'all' for no time filter. Ignored when 'since' or 'until' is given.",
+              default: "last_7_days"
+            },
+            status: {
+              type: "string",
+              description: "Lifecycle filter: 'open' (default), 'resolved', 'ignored', or 'all'",
+              default: "open"
+            },
+            search: {
+              type: "string",
+              description: "Substring match on the exception class or location, e.g. 'RecordNotFound' or 'app/models'"
+            },
+            fingerprint: {
+              type: "string",
+              description: "Exact fingerprint of one group, as returned by this tool or by Rails Pulse Cloud. " \
+                           "Finds the group whatever its status or when it was last seen, so status and period are ignored."
+            },
+            limit: {
+              type: "integer",
+              description: "Maximum number of groups (1-100)",
+              default: 25
+            }
+          }
+        )
+
+        # `period: "all"` drops the time filter; groups are otherwise limited to
+        # those last seen inside the window. A fingerprint names one group, so
+        # it drops both filters: the defaults would hide a resolved group or
+        # one last seen a month ago, and the caller asked for that group.
+        def self.call(period: "last_7_days", status: "open", search: nil, fingerprint: nil, limit: 25, server_context:, **options)
+          respond(server_context) do |client|
+            limit = limit.to_i.clamp(1, 100)
+            if fingerprint.to_s != ""
+              period = "all"
+              status = "all"
+              options = options.except(:since, :until)
+            end
+            all_time = period.to_s == "all" && options[:since].nil? && options[:until].nil?
+            window = all_time ? nil : resolve_window(period: period, since: options[:since], until_time: options[:until])
+
+            params = { limit: limit, offset: 0 }
+            params.merge!(window_params(window)) if window
+            params[:status] = status unless status.to_s == "all"
+            params[:search] = search if search.to_s != ""
+            params[:fingerprint] = fingerprint if fingerprint.to_s != ""
+
+            result = client.get("/exceptions", params)
+            groups = (result["data"] || []).map { |g| format_group(g) }
+            total  = result.dig("meta", "total") || groups.size
+
+            {
+              window: window || { period: "all" },
+              status_filter: status,
+              total_groups: total,
+              groups_returned: groups.size,
+              groups: groups,
+              summary: build_summary(groups, total, status),
+              next_steps: build_next_steps(groups)
+            }
+          end
+        end
+
+        private_class_method def self.format_group(group)
+          {
+            id: group["id"],
+            fingerprint: group["fingerprint"],
+            exception_class: group["exception_class"],
+            location: group["location"],
+            message: truncate(group["message"], 300),
+            status: group["status"],
+            occurrence_count: group["occurrence_count"],
+            first_seen_at: group["first_seen_at"],
+            last_seen_at: group["last_seen_at"],
+            resolved_at: group["resolved_at"]
+          }
+        end
+
+        private_class_method def self.build_summary(groups, total, status)
+          label = status.to_s == "all" ? "" : "#{status} "
+          return "No #{label}exception groups found for this period." if groups.empty?
+
+          occurrences = groups.sum { |g| g[:occurrence_count].to_i }
+          loudest = groups.max_by { |g| g[:occurrence_count].to_i }
+          parts = [ "#{total} #{label}exception group(s), #{occurrences} occurrences across the #{groups.size} returned" ]
+          parts << "Most frequent: #{loudest[:exception_class]} at #{loudest[:location] || 'unknown location'} " \
+                   "(#{loudest[:occurrence_count]} occurrences)"
+          parts.join(". ") + "."
+        end
+
+        private_class_method def self.build_next_steps(groups)
+          return [ "Nothing is raising in this window. Widen period or set status: \"all\" to see resolved and ignored groups." ] if groups.empty?
+
+          steps = []
+          latest = groups.max_by { |g| g[:last_seen_at].to_s }
+          steps << "Start with #{latest[:exception_class]} at #{latest[:location] || 'unknown location'}: it fired most recently " \
+                   "(#{latest[:last_seen_at]}). Read the location and message, then open the file at that frame."
+          steps << "Call rails_pulse_deployments for the same period to see whether the first_seen_at of a group lines up with a release."
+          steps << "Call rails_pulse_errors to see which endpoints answered 5xx as a result, and rails_pulse_jobs for failing job classes."
+          steps
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/mcp/tools/helpers.rb

@@ -0,0 +1,162 @@
+require "json"
+require "time"
+
+module RailsPulse
+  module Mcp
+    module Tools
+      module Helpers
+        PERIODS = {
+          "last_hour" => 3600,
+          "last_24_hours" => 86_400,
+          "last_7_days" => 604_800
+        }.freeze
+
+        # Raised for a time argument a tool cannot turn into a window. Carries
+        # the correction in its message, so the agent can fix the call rather
+        # than retry it unchanged.
+        class WindowError < ArgumentError; end
+
+        # A trailing Z or ±HH:MM offset.
+        ZONED = /(?:Z|[+-]\d{2}:?\d{2})\z/i
+
+        # ISO 8601: a date, optionally a time, optionally a zone. Anything else
+        # is refused rather than handed to Time.parse, which reads
+        # "last_30_days" as the 30th of this month and "24h" as midnight.
+        ISO8601 = /\A\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?(?:Z|[+-]\d{2}:?\d{2})?\z/i
+
+        # The default window when a tool is given neither a period nor bounds.
+        DEFAULT_PERIOD = "last_24_hours".freeze
+
+        # The time arguments every windowed tool accepts. Spliced into each
+        # tool's input_schema so the three stay described identically.
+        def self.window_properties(default_period)
+          {
+            period: {
+              type: "string",
+              description: "Relative window: 'last_hour', 'last_24_hours' or 'last_7_days'. For any other " \
+                           "window pass 'since' and 'until'. Ignored when either is given.",
+              default: default_period
+            },
+            since: {
+              type: "string",
+              description: "Start of the window, ISO 8601 (e.g. '2026-09-24T12:00:00Z'). Read as UTC when no " \
+                           "zone is given. Use with 'until' to pin an exact window that can be compared with another."
+            },
+            until: {
+              type: "string",
+              description: "End of the window, ISO 8601. Read as UTC when no zone is given. Omit to measure up to now."
+            }
+          }
+        end
+
+        # Turns a tool's time arguments into explicit UTC bounds.
+        #
+        # `period` names a relative window and is enough for "how are things
+        # right now". `since`/`until` pin an exact one, which is what makes a
+        # question repeatable: the 24 hours before a deploy stay the same 24
+        # hours however long afterwards they are asked about. Explicit bounds
+        # win when both are given.
+        #
+        # @return [Hash] `:since` and `:until` as ISO 8601 UTC strings (`:until`
+        #   is nil when the window runs to now), plus `:period` describing which
+        #   form was used.
+        def resolve_window(period: nil, since: nil, until_time: nil)
+          from = resolve_start(period, since)
+          to = until_time ? parse_time(until_time, "until") : nil
+
+          if to && from >= to
+            raise WindowError, "'since' (#{from.iso8601}) must be earlier than 'until' (#{to.iso8601})."
+          end
+          if from > Time.now.utc
+            raise WindowError, "'since' (#{from.iso8601}) is in the future, so nothing can have been recorded yet."
+          end
+
+          {
+            since: from.iso8601,
+            until: to&.iso8601,
+            period: since || until_time ? "custom" : (period || DEFAULT_PERIOD)
+          }
+        end
+
+        # A timestamp with no zone is read as UTC, so a window means the same
+        # thing on the agent's machine as on the server.
+        def parse_time(value, name)
+          string = value.to_s.strip
+          raise ArgumentError unless string.match?(ISO8601)
+
+          parsed = Time.parse(string)
+          return parsed.utc if string.match?(ZONED)
+
+          Time.utc(parsed.year, parsed.month, parsed.day, parsed.hour, parsed.min, parsed.sec)
+        rescue ArgumentError, TypeError
+          raise WindowError,
+            "Invalid #{name}: #{value.inspect}. Use an ISO 8601 timestamp such as 2026-09-24T12:00:00Z."
+        end
+
+        # The API's time arguments for a resolved window. `until` is omitted
+        # when the window runs to now, which the API reads as no upper bound.
+        def window_params(window)
+          params = { since: window[:since] }
+          params[:until] = window[:until] if window[:until]
+          params
+        end
+
+        def resolve_start(period, since)
+          return parse_time(since, "since") if since
+
+          seconds = PERIODS[period || DEFAULT_PERIOD]
+          return (Time.now.utc - seconds) if seconds
+
+          # An ISO 8601 period was the documented way to pin a start before
+          # `since` existed, so it is still read as one.
+          return parse_time(period, "period") if period.to_s.strip.match?(ISO8601)
+
+          raise WindowError,
+            "Unknown period #{period.inspect}. Use #{PERIODS.keys.join(', ')}, or pass 'since' and 'until' " \
+            "as ISO 8601 timestamps for any other window."
+        end
+
+        # Every row of a paginated endpoint, for a tool that ranks the rows
+        # itself. Bounded so an unexpectedly large table cannot keep the tool
+        # paging forever.
+        #
+        # @return [Array(Array<Hash>, Hash)] the rows and the first page's response
+        def fetch_all(client, path, params, page_size: 500, max_pages: 20)
+          rows = []
+          first = nil
+          max_pages.times do |page|
+            result = client.get(path, params.merge(limit: page_size, offset: page * page_size))
+            first ||= result
+            batch = result["data"] || []
+            rows.concat(batch)
+            total = result.dig("meta", "total")
+            break if batch.size < page_size || (total && rows.size >= total)
+          end
+          [ rows, first ]
+        end
+
+        def percentile(sorted, pct)
+          return 0 if sorted.empty?
+          k = ((pct / 100.0) * (sorted.size - 1)).ceil
+          sorted[k]
+        end
+
+        def truncate(str, length)
+          str = str.to_s
+          str.length > length ? "#{str[0, length]}..." : str
+        end
+
+        def respond(server_context)
+          payload = yield server_context[:client]
+          ::MCP::Tool::Response.new([ { type: "text", text: JSON.pretty_generate(payload) } ])
+        rescue WindowError => e
+          # The call is malformed rather than the server unreachable, so the
+          # message says how to correct it.
+          ::MCP::Tool::Response.new([ { type: "text", text: e.message } ], error: true)
+        rescue CLI::Client::ApiError => e
+          ::MCP::Tool::Response.new([ { type: "text", text: "Error querying Rails Pulse: #{e.message}" } ], error: true)
+        end
+      end
+    end
+  end
+end