debug-mcp 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3deb8c5be59f4db39f02fbf3e4930cf89f3baf3c7389907e313fc1c50fbf9ebf
-  data.tar.gz: a42a9c9c6b89566810cfc939a550c12fa5729c85ad6f60d1608c3b8174a4cc15
+  metadata.gz: 9e02b5e90614a86cdefb3a1829405c60c3c11d4bb03dde266c23769fc264e2ac
+  data.tar.gz: 6a61f417f4720077d4cede1874719da07865c9b7a4b370e3726aecd9a74596ba
 SHA512:
-  metadata.gz: 47de1a4d322016105ec10929a3bffb06c2b627582b910f58ac4d0455022a640c9ee5907cc06f14b463cb40c4a81de26a4717f25a9cb382da346c67191f2e8b90
-  data.tar.gz: 214301d83a465f5df7206eed4c0592fe849f62882548979931a7bc8ea8aae689af12c3499c727d57c29fedec7dc719e6fc9ff0c1efb4aef5b04a335b22c9f7ee
+  metadata.gz: ec411a062c8c2cee35f569c9e73bff9450fdfc99f001c75334b3798019bb8b4d32487a83223f81592af05af1fc9466fe3c4390581f5ff3f80bfd290868bd3b0f
+  data.tar.gz: 7bfe97bf4102f970463dfffd183d02d1d80b3c400170434b3472c68ac57526ce52f66a0a6b9081116e3985ec5a8629b35908d3c409d51222f4403c75ce7aeac8

data/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 0.4.0 — 2026-10-18
+
+### Dependencies
+
+- **Upgrade the `mcp` gem from `~> 0.7` to `~> 1.8`.** The JSON Schema validator
+  dependency changes from `json-schema` to `json_schemer`; debug-mcp does not use
+  either directly.
+- **The HTTP transport now needs the `rack` gem installed separately.** `mcp` 1.x no
+  longer depends on `rack`, but its `StreamableHTTPTransport` still requires it.
+  debug-mcp keeps `rack` optional so STDIO users (the default) don't install it;
+  `--transport http` without `rack` exits with an install hint
+  (`gem install rack`).
+
+### Bug Fixes
+
+- **Fix the HTTP transport under `mcp` 1.x** — The WEBrick bridge now passes a
+  `Rack::Request` (with `CONTENT_LENGTH` set) instead of a minimal hand-written
+  adapter, which lacked `content_length` and made every request return
+  `Internal server error`. `stringio` is now required explicitly instead of relying
+  on another gem to load it.
+
+## 0.3.0 — 2026-06-18
+
+### Features
+
+- **`rails_recent_events` tool** — Read recent Rails internal events (SQL, renders,
+  cache, job enqueues, request lifecycle) from the running process without
+  `trigger_request`. Forward-only (the first call installs the subscriber) and
+  paused-only; every response carries an observability header (`installed_at`,
+  `forward_only`, `events_before_install_are_unavailable`, buffer size + dropped
+  count, `seq` range) so an empty result is never mistaken for "nothing happened".
+  Clock-independent `after_seq` cursor paging.
+
+- **`rails_mail_deliveries` tool** — Structure `ActionMailer::Base.deliveries`
+  (from/to/cc/bcc/subject/body preview/attachment names). `observable` is true only
+  when `delivery_method` is `:test`; otherwise the response states that an empty list
+  is not proof no mail was sent. Bodies are truncated to a preview inside the target
+  process (transport-safe, PII-safe by default); attachment content is never returned.
+
+- **`rails_info` Observability section** — `rails_info` now reports `delivery_method`,
+  ActiveJob `queue_adapter`, cache store, and PID, so an agent can tell up front
+  whether mail/jobs are observable in this process.
+
+### Bug Fixes
+
+- **NotificationsSubscriber lifecycle (machine-verified)** — The injected buffer
+  module now separates definition from activation: `.install` is always called and is
+  idempotent, so a module left with zero subscriptions (e.g. an install attempt that
+  raised in signal trap context, where `ActiveSupport::Notifications.subscribe` takes
+  an internal mutex) recovers on the next injection instead of being permanently
+  poisoned. `install` refuses early in trap context. The injected module is versioned
+  so an older one in a long-running process is replaced. Reads use `Mutex#try_lock`
+  with a lockless fallback so a fetch can't deadlock against a debugger-stopped thread.
+  Per-event monotonic `seq` with clock-independent `fetch_last` / `fetch_after_seq`.
+  SQL bodies and request paths are truncated at save time.
+
+- **Notifications event capture over the debug socket** — Results are now
+  returned as the evaluated expression's value (base64-encoded JSON) instead of
+  via `puts`. End-to-end testing against a live rdbg-attached process showed the
+  debug socket does not forward the debuggee's stdout, so the previous
+  `puts(x.to_json)` path returned nothing — this also fixes `trigger_request`'s
+  `Rails Events` section, which used the same mechanism.
+
+### Documentation
+
+- Corrected docs that claimed Rails tools are registered only when a Rails process is
+  detected — they are always registered and guard themselves via `require_rails!`.
+
 ## 0.2.1 — 2026-06-17
 
 ### Bug Fixes

data/README.ja.md

@@ -147,6 +147,12 @@ debug-mcp
 
 ブラウザベースのクライアントやHTTP対応MCPクライアント向け。
 
+HTTPトランスポートには `rack` gem が必要です。STDIOでは使わないため、debug-mcp と一緒にはインストールされません:
+
+```bash
+gem install rack
+```
+
 ```bash
 debug-mcp --transport http --port 8080
 ```
@@ -204,15 +210,27 @@ debug-mcp --session-timeout 3600  # 1時間
 | `run_script` | rdbg経由でRubyスクリプトを起動して接続 |
 | `trigger_request` | デバッグ中のRailsアプリにHTTPリクエストを送信 |
 
-### Railsツール（自動検出）
+### Railsツール
 
-Railsプロセスを検出すると自動的に登録されます。
+常時登録されますが、Railsプロセスへの接続が必要で、プレーンなRubyスクリプトに対してはエラーを返します。
 
 | ツール | 説明 |
 |------|------|
-| `rails_info` | アプリ名・Rails/Rubyバージョン・環境・ルートパスを表示 |
+| `rails_info` | アプリ名・Rails/Rubyバージョン・環境・ルートパス・DB設定に加え、**Observability** セクション（delivery method・queue adapter・cache store・PID）を表示 |
 | `rails_routes` | ルーティング一覧（verb, path, controller#action）、コントローラ・パスでフィルタ可能 |
 | `rails_model` | モデル構造：カラム・アソシエーション・バリデーション・enum・スコープを表示 |
+| `rails_recent_events` | `trigger_request` を介さず、実行中プロセスの直近Railsイベント（SQL/render/cache/job/request）を表示 |
+| `rails_mail_deliveries` | `ActionMailer::Base.deliveries` のメール（from/to/件名/本文プレビュー/添付名）を表示 |
+
+### リクエストの外側での実行時観測
+
+次の3ツールで、AIはログを読まずに副作用を確認できます。
+
+- **`rails_info`** は観測の前提条件を報告します。たとえば `delivery_method` が `:test` か（メールを観測できるか）、どの `queue_adapter` を使っているか。AIは「何が見えて何が見えないか」を最初に把握できます。
+- **`rails_recent_events`** は `trigger_request` と同じ `ActiveSupport::Notifications` バッファを、リクエストとは独立に読み出します。**forward-only**（最初の呼び出しでsubscriberをinstallし、それ以降のイベントのみ可視）かつ **paused-only**（対象プロセスがdebuggerプロンプトで停止している必要あり）です。応答には毎回ヘッダ（`installed_at`・`forward_only`・`events_before_install_are_unavailable`・buffer件数/drop件数・`seq` 範囲）が付き、空の結果を「何も起きなかった」と誤解しないようにしています。`after_seq` カーソルで前方ページング可能（時計に非依存）。subscriber注入はプロセス内instrumentationの副作用なので、厳密にはread-onlyではありません。
+- **`rails_mail_deliveries`** は `ActionMailer::Base.deliveries` を構造化します。`delivery_method` が `:test` のときだけ中身が入るため、それ以外では「観測不能」と明示し、空＝未送信ではないことを示します。本文はデフォルトでプレビューに切り詰め（PII対策）、添付の中身は返しません。
+
+> 未提供: 専用の `rails_jobs`（queueスナップショット）ツール。ActiveJobのenqueueは既に `enqueue.active_job` として `rails_recent_events` / `trigger_request` に現れます。TestAdapterの `enqueued_jobs`/`performed_jobs` スナップショットは今後の課題です。
 
 ## Rails イベントキャプチャ
 

data/README.md

@@ -148,6 +148,12 @@ debug-mcp
 
 For browser-based clients or other HTTP-compatible MCP clients.
 
+The HTTP transport requires the `rack` gem, which is not installed with debug-mcp (STDIO users don't need it):
+
+```bash
+gem install rack
+```
+
 ```bash
 debug-mcp --transport http --port 8080
 ```
@@ -205,15 +211,27 @@ The session manager also detects and cleans up sessions whose target process has
 | `run_script` | Start a Ruby script under rdbg and connect to it |
 | `trigger_request` | Send an HTTP request to a Rails app under debug |
 
-### Rails Tools (auto-detected)
+### Rails Tools
 
-These tools are automatically registered when a Rails process is detected.
+These tools are always registered, but they require a connected Rails process and return an error when used against a plain Ruby script.
 
 | Tool | Description |
 |------|-------------|
-| `rails_info` | Show app name, Rails/Ruby versions, environment, root path |
+| `rails_info` | Show app name, Rails/Ruby versions, environment, root path, DB config, and an **Observability** section (delivery method, queue adapter, cache store, PID) |
 | `rails_routes` | Show routes (verb, path, controller#action), filterable by controller or path |
 | `rails_model` | Show model structure: columns, associations, validations, enums, scopes |
+| `rails_recent_events` | Show recent Rails internal events (SQL/render/cache/job/request) from the running process, without `trigger_request` |
+| `rails_mail_deliveries` | Show emails in `ActionMailer::Base.deliveries` (from/to/subject/body preview/attachment names) |
+
+### Runtime observability beyond a single request
+
+Three of the Rails tools let an agent confirm side effects without reading logs:
+
+- **`rails_info`** reports the observability *preconditions* — e.g. whether `delivery_method` is `:test` (so mail is observable) and which `queue_adapter` is in use — so the agent knows up front what it can and cannot see.
+- **`rails_recent_events`** reads the same `ActiveSupport::Notifications` buffer used by `trigger_request`, but independent of a request. It is **forward-only** (the first call installs the subscriber; only events fired afterwards are visible) and **paused-only** (the process must be stopped at a debugger prompt). Every response includes a header — `installed_at`, `forward_only`, `events_before_install_are_unavailable`, buffer size/dropped count, and the `seq` range — so an empty result is never mistaken for "nothing happened". Page forward with the `after_seq` cursor (clock-independent). Installing the subscriber is an in-process instrumentation side effect, so this tool is not strictly read-only.
+- **`rails_mail_deliveries`** structures `ActionMailer::Base.deliveries`. It is only populated when `delivery_method` is `:test`; otherwise the response says so, so an empty list does not imply no mail was sent. Bodies are truncated to a preview (PII-safe by default) and attachment content is never returned.
+
+> Not yet included: a dedicated `rails_jobs` queue-snapshot tool. ActiveJob enqueues already appear in `rails_recent_events` / `trigger_request` via `enqueue.active_job`; a TestAdapter `enqueued_jobs`/`performed_jobs` snapshot is planned as a follow-up.
 
 ## Rails event capture
 

data/lib/debug_mcp/notifications_subscriber.rb

@@ -8,6 +8,18 @@ module DebugMcp
   module NotificationsSubscriber
     BUFFER_MAX = 1000
 
+    # Bumped whenever INJECTION_CODE's structure changes so that an older buffer
+    # module already injected into a long-running target process is replaced
+    # instead of silently kept. The injected module exposes `.version` and the
+    # injection guard re-defines the module when the versions differ.
+    VERSION = "2"
+
+    # Save-time caps applied inside the target process, before JSON encoding.
+    # These bound transport size (the debug socket is line-oriented — see
+    # parse_json_array) and limit how much raw SQL / path text we retain.
+    STORE_SQL_MAX = 2000
+    STORE_PATH_MAX = 1000
+
     SUBSCRIBED_EVENTS = %w[
       sql.active_record
       render_template.action_view
@@ -23,38 +35,108 @@ module DebugMcp
       process_action.action_controller
     ].freeze
 
+    # Code injected (via Base64 eval) into the target process. It defines a
+    # process-global ::DebugMcpNotificationsBuffer module that subscribes to
+    # ActiveSupport::Notifications and buffers recent events.
+    #
+    # Lifecycle notes (these fix bugs found by machine verification):
+    # - Module DEFINITION and subscriber ACTIVATION are separated. The
+    #   `.install` call lives OUTSIDE the `unless defined?` guard and is always
+    #   invoked, so a module that was defined but left with zero subscriptions
+    #   (e.g. a previous install attempt raised in trap context) recovers on the
+    #   next injection. `.install` itself is idempotent via `@subscriptions.any?`.
+    # - Reads never block: `safe_read` uses Mutex#try_lock and falls back to a
+    #   lockless read. A blocking `synchronize` would deadlock if a debugger-
+    #   stopped thread is holding the mutex; the process is paused during reads,
+    #   so no writer is actually running and a lockless read is safe.
+    # - A version mismatch re-defines the module (after uninstalling the old one).
     INJECTION_CODE = <<~RUBY
-      unless defined?(::DebugMcpNotificationsBuffer)
-        module ::DebugMcpNotificationsBuffer
-          BUFFER_MAX = #{BUFFER_MAX}
-          SUBSCRIBED_EVENTS = #{SUBSCRIBED_EVENTS.inspect}.freeze
-
-          @buffer = []
-          @subscriptions = []
-          @mutex = Mutex.new
+      unless defined?(::DebugMcpNotificationsBuffer) &&
+             ::DebugMcpNotificationsBuffer.respond_to?(:version) &&
+             ::DebugMcpNotificationsBuffer.version == #{VERSION.inspect}
+        if defined?(::DebugMcpNotificationsBuffer) && ::DebugMcpNotificationsBuffer.respond_to?(:uninstall)
+          ::DebugMcpNotificationsBuffer.uninstall rescue nil
+        end
 
+        module ::DebugMcpNotificationsBuffer
           class << self
             attr_reader :buffer, :subscriptions
 
+            def version; #{VERSION.inspect}; end
+            def buffer_max; #{BUFFER_MAX}; end
+            def subscribed_events; #{SUBSCRIBED_EVENTS.inspect}.freeze; end
+
+            def init!
+              @buffer = []
+              @subscriptions = []
+              @mutex = Mutex.new
+              @seq = 0
+              @dropped = 0
+              @installed_at = nil
+              @buffer_started_at = Time.now.to_f
+            end
+
             def push(event)
               @mutex.synchronize do
+                @seq += 1
+                event[:seq] = @seq
                 @buffer << event
-                @buffer.shift while @buffer.size > BUFFER_MAX
+                while @buffer.size > buffer_max
+                  @buffer.shift
+                  @dropped += 1
+                end
+              end
+            end
+
+            # Read without ever blocking. If try_lock fails the mutex is held by
+            # a debugger-stopped thread; we read locklessly (safe while paused).
+            def safe_read
+              locked = @mutex.try_lock
+              begin
+                yield
+              ensure
+                @mutex.unlock if locked
               end
             end
 
             def fetch_by_request_id(request_id)
-              @mutex.synchronize { @buffer.select { |e| e[:request_id] == request_id } }
+              safe_read { @buffer.select { |e| e[:request_id] == request_id } }
             end
 
             def fetch_since(timestamp)
-              @mutex.synchronize { @buffer.select { |e| e[:timestamp] >= timestamp } }
+              safe_read { @buffer.select { |e| e[:timestamp] >= timestamp } }
+            end
+
+            def fetch_last(n)
+              safe_read { @buffer.last(n) }
+            end
+
+            def fetch_after_seq(cursor)
+              safe_read { @buffer.select { |e| e[:seq] > cursor } }
             end
 
             def clear
               @mutex.synchronize { @buffer.clear }
             end
 
+            def metadata
+              safe_read do
+                {
+                  version: version,
+                  installed: @subscriptions.any?,
+                  installed_at: @installed_at,
+                  buffer_started_at: @buffer_started_at,
+                  buffer_size: @buffer.size,
+                  buffer_max: buffer_max,
+                  dropped_count: @dropped,
+                  oldest_seq: (@buffer.first && @buffer.first[:seq]),
+                  newest_seq: (@buffer.last && @buffer.last[:seq]),
+                  last_seq: @seq,
+                  subscriptions_count: @subscriptions.size,
+                }
+              end
+            end
+
             def install
               return if @subscriptions.any?
 
@@ -74,9 +156,10 @@ module DebugMcp
                 # never raise from subscriber callback
               end
 
-              SUBSCRIBED_EVENTS.each do |event_name|
+              subscribed_events.each do |event_name|
                 @subscriptions << ::ActiveSupport::Notifications.subscribe(event_name, &callback)
               end
+              @installed_at = Time.now.to_f
             end
 
             def uninstall
@@ -107,7 +190,7 @@ module DebugMcp
               case name
               when "sql.active_record"
                 {
-                  sql: payload[:sql].to_s,
+                  sql: truncate_text(payload[:sql].to_s, #{STORE_SQL_MAX}),
                   query_name: payload[:name].to_s,
                   cached: payload[:cached] ? true : false,
                   binds: safe_binds(payload[:type_casted_binds] || payload[:binds]),
@@ -137,7 +220,7 @@ module DebugMcp
                   controller: payload[:controller],
                   action: payload[:action],
                   method: payload[:method],
-                  path: payload[:path],
+                  path: truncate_text(payload[:path].to_s, #{STORE_PATH_MAX}),
                   format: payload[:format].to_s,
                   status: payload[:status],
                   view_runtime: payload[:view_runtime],
@@ -150,6 +233,13 @@ module DebugMcp
               { error: "payload_sanitize_failed: \#{e.class}" }
             end
 
+            def truncate_text(str, limit)
+              return str if str.length <= limit
+              str[0, limit] + "...[truncated \#{str.length - limit} chars]"
+            rescue StandardError
+              "<untruncatable>"
+            end
+
             def safe_binds(binds)
               return [] unless binds.respond_to?(:each)
               binds.map { |b| safe_inspect(b, 100) }
@@ -164,16 +254,25 @@ module DebugMcp
               "<uninspectable>"
             end
           end
+
+          init!
         end
-        ::DebugMcpNotificationsBuffer.install
       end
+      ::DebugMcpNotificationsBuffer.install
     RUBY
 
     class << self
-      # Inject the subscriber into the Rails process. Idempotent.
+      # Inject the subscriber into the Rails process and activate it. Idempotent.
       # Returns true on success, false otherwise.
+      #
+      # Returns false in signal trap context WITHOUT sending the injection: in
+      # trap context ActiveSupport::Notifications.subscribe raises ThreadError
+      # (Fanout#subscribe takes an internal mutex), and merely defining the
+      # module there would leave it with zero subscriptions. We refuse early so
+      # the caller can surface RailsHelper::TRAP_CONTEXT_HINT instead.
       def install(client)
         return false unless RailsHelper.rails?(client)
+        return false if RailsHelper.trap_context?(client)
 
         encoded = Base64.strict_encode64(INJECTION_CODE)
         cmd = "p begin; require 'base64'; eval(::Base64.decode64('#{encoded}').force_encoding('UTF-8')); " \
@@ -197,40 +296,65 @@ module DebugMcp
       def fetch_by_request_id(client, request_id)
         return [] unless request_id
 
-        code = "puts(defined?(::DebugMcpNotificationsBuffer) ? " \
-               "::DebugMcpNotificationsBuffer.fetch_by_request_id(#{request_id.inspect}).to_json : '[]')"
-        result = client.send_command(code)
-        parse_json_array(result)
+        code = RailsHelper.json_command(
+          "defined?(::DebugMcpNotificationsBuffer) ? " \
+          "::DebugMcpNotificationsBuffer.fetch_by_request_id(#{request_id.inspect}).to_json : '[]'",
+        )
+        RailsHelper.decode_json_result(client.send_command(code), [])
       rescue DebugMcp::Error
         []
       end
 
       # Fetch events fired at-or-after the given timestamp.
+      # Prefer fetch_last / fetch_after_seq: those are clock-independent, whereas
+      # this compares against a client-supplied timestamp and is sensitive to
+      # clock skew between the MCP host and the target process.
       def fetch_since(client, timestamp)
-        code = "puts(defined?(::DebugMcpNotificationsBuffer) ? " \
-               "::DebugMcpNotificationsBuffer.fetch_since(#{timestamp.to_f}).to_json : '[]')"
-        result = client.send_command(code)
-        parse_json_array(result)
+        code = RailsHelper.json_command(
+          "defined?(::DebugMcpNotificationsBuffer) ? " \
+          "::DebugMcpNotificationsBuffer.fetch_since(#{timestamp.to_f}).to_json : '[]'",
+        )
+        RailsHelper.decode_json_result(client.send_command(code), [])
       rescue DebugMcp::Error
         []
       end
 
-      private
-
-      def parse_json_array(text)
-        return [] unless text
-        text.each_line do |line|
-          stripped = line.strip
-          next unless stripped.start_with?("[")
-          begin
-            parsed = JSON.parse(stripped, symbolize_names: true)
-            return parsed if parsed.is_a?(Array)
-          rescue JSON::ParserError
-            next
-          end
-        end
+      # Fetch the last n buffered events. Clock-independent.
+      def fetch_last(client, n)
+        code = RailsHelper.json_command(
+          "defined?(::DebugMcpNotificationsBuffer) ? " \
+          "::DebugMcpNotificationsBuffer.fetch_last(#{n.to_i}).to_json : '[]'",
+        )
+        RailsHelper.decode_json_result(client.send_command(code), [])
+      rescue DebugMcp::Error
+        []
+      end
+
+      # Fetch events with seq strictly greater than cursor. Clock-independent
+      # cursor pagination — pass the previous response's newest_seq. An optional
+      # limit caps the result in the TARGET process (oldest-after-cursor first),
+      # so a busy buffer never serializes all 1000 events just to be sliced later.
+      def fetch_after_seq(client, cursor, limit = nil)
+        selector = "::DebugMcpNotificationsBuffer.fetch_after_seq(#{cursor.to_i})"
+        selector += ".first(#{limit.to_i})" if limit
+        code = RailsHelper.json_command(
+          "defined?(::DebugMcpNotificationsBuffer) ? #{selector}.to_json : '[]'",
+        )
+        RailsHelper.decode_json_result(client.send_command(code), [])
+      rescue DebugMcp::Error
         []
       end
+
+      # Fetch subscriber metadata (version, installed_at, buffer_size,
+      # dropped_count, seq cursors, ...). Returns {} if not installed.
+      def metadata(client)
+        code = RailsHelper.json_command(
+          "defined?(::DebugMcpNotificationsBuffer) ? ::DebugMcpNotificationsBuffer.metadata.to_json : '{}'",
+        )
+        RailsHelper.decode_json_result(client.send_command(code), {})
+      rescue DebugMcp::Error
+        {}
+      end
     end
   end
 end

data/lib/debug_mcp/rails_helper.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "base64"
+require "json"
 require_relative "source_tagging"
 
 module DebugMcp
@@ -143,6 +144,32 @@ module DebugMcp
       nil
     end
 
+    # Probe Rails runtime observability settings (trap-safe; uses eval_expr).
+    # Returns a hash of human-readable string values, falling back to
+    # "(unavailable)" when a probe can't be evaluated (e.g. trap context).
+    #
+    # These are plain attribute/class reads (delivery_method, queue adapter
+    # name, cache store class) that do NOT fire ActiveSupport::Notifications
+    # events, so no debug_eval source tagging is needed — consistent with
+    # eval_expr's contract. Shared by rails_info and the mail/recent-events
+    # tools so they report the same observability preconditions.
+    def observability_probe(client)
+      {
+        delivery_method: probe_value(client,
+          "(defined?(ActionMailer::Base) ? ActionMailer::Base.delivery_method : :no_action_mailer)"),
+        queue_adapter: probe_value(client,
+          "(defined?(ActiveJob::Base) ? " \
+          "(ActiveJob::Base.queue_adapter_name rescue ActiveJob::Base.queue_adapter.class.name) : " \
+          ":no_active_job)"),
+        cache_store: probe_value(client,
+          "((defined?(Rails) && Rails.respond_to?(:cache) && Rails.cache) ? Rails.cache.class.name : '(none)')"),
+      }
+    end
+
+    def probe_value(client, expr)
+      eval_expr(client, expr) || "(unavailable)"
+    end
+
     # Get the path to the Rails log file (trap-safe).
     # Returns the absolute path string or nil if not determinable.
     def log_file_path(client)
@@ -155,6 +182,47 @@ module DebugMcp
       nil
     end
 
+    # Wrap a target-side expression that evaluates to a JSON STRING so its value
+    # comes back as a base64 blob on the debug gem's `=> <result>` line.
+    #
+    # Why base64: send_command only returns the evaluated expression's inspected
+    # value; the debuggee's own stdout (anything printed with puts/p) is NOT
+    # forwarded over the debug socket. So we cannot rely on `puts(x.to_json)`
+    # emitting a parseable line — its output goes to the target's stdout and
+    # send_command just sees `=> nil`. Returning the JSON directly would work but
+    # then it is wrapped in Ruby string-inspect escaping (\" , \\ , \n) that is
+    # fragile to undo. Base64's alphabet contains none of those, so it round-trips
+    # through inspect/quoting untouched.
+    def json_command(json_string_expr)
+      "[(#{json_string_expr})].pack(\"m0\")"
+    end
+
+    # Decode the result of a json_command from send_command output. The debug gem
+    # echoes the evaluated value as a quoted string, e.g. `"<base64>"` (sometimes
+    # with a `=> ` prefix, and — for long values — WRAPPED across several lines at
+    # the debugger's width, which read_until_input joins with newlines).
+    #
+    # The value is a base64 blob, whose alphabet contains no `"`, so we take
+    # everything between the first and last double-quote and strip whitespace
+    # (Base64.decode64 also ignores embedded newlines). Returns `default` on any
+    # failure (not installed, parse error, timeout-truncated output, ...).
+    def decode_json_result(output, default)
+      return default unless output
+
+      first = output.index('"')
+      last = output.rindex('"')
+      return default unless first && last && last > first
+
+      b64 = output[(first + 1)...last].gsub(/\s/, "")
+      return default if b64.empty?
+
+      # strict_decode64 (vs decode64) rejects a truncated/corrupt blob instead of
+      # silently returning partial bytes, so we fall back to `default` cleanly.
+      JSON.parse(Base64.strict_decode64(b64), symbolize_names: true)
+    rescue StandardError
+      default
+    end
+
     TRAP_CONTEXT_HINT = "Note: The process may be in signal trap context (common with Puma). " \
                         "Set a breakpoint and use trigger_request to escape trap context first."
   end

data/lib/debug_mcp/server.rb

@@ -23,6 +23,8 @@ require_relative "tools/disconnect"
 require_relative "tools/rails_info"
 require_relative "tools/rails_routes"
 require_relative "tools/rails_model"
+require_relative "tools/rails_recent_events"
+require_relative "tools/rails_mail_deliveries"
 
 module DebugMcp
   class Server
@@ -53,11 +55,17 @@ module DebugMcp
       Tools::TriggerRequest,
     ].freeze
 
-    # Rails tools: dynamically added when a Rails process is detected
+    # Rails tools: always registered (see TOOLS below). They require a connected
+    # Rails process and guard themselves via RailsHelper.require_rails!, returning
+    # an error on plain Ruby targets. register_rails_tools exists for hosts that
+    # want to add them to a pre-built server, but the default server registers
+    # them up front.
     RAILS_TOOLS = [
       Tools::RailsInfo,
       Tools::RailsRoutes,
       Tools::RailsModel,
+      Tools::RailsRecentEvents,
+      Tools::RailsMailDeliveries,
     ].freeze
 
     # All tools (used in tests and for reference)
@@ -116,9 +124,11 @@ module DebugMcp
       trigger_request handles resuming the process automatically.
 
       Rails debugging:
-      When you connect to a Rails process, additional Rails-specific tools become available \
-      automatically (rails_info, rails_routes, rails_model). These tools are NOT shown \
-      when debugging plain Ruby scripts.
+      Rails-specific tools (rails_info, rails_routes, rails_model, rails_recent_events) are \
+      always available, but they require a connected Rails process and will return an error \
+      when used against a plain Ruby script. rails_recent_events shows recent internal events \
+      (SQL, renders, cache, job enqueues) captured from the running process; it is forward-only \
+      (only events after its first call are visible).
 
       Rails debugging workflow:
       1. Start the Rails server with debugging: RUBY_DEBUG_OPEN=true bin/rails server
@@ -134,7 +144,7 @@ module DebugMcp
       7. To debug another request, set new breakpoints and call trigger_request again
       8. When done debugging, use 'disconnect' to detach and resume the server
 
-      Note: rails_info, rails_routes, and rails_model may not work in trap context. \
+      Note: rails_info, rails_routes, rails_model, and rails_recent_events may not work in trap context. \
       Use them after hitting a breakpoint via trigger_request.
 
       Docker / containerized processes:
@@ -253,6 +263,13 @@ module DebugMcp
     end
 
     def start_http(server)
+      begin
+        require "rack"
+      rescue LoadError
+        abort "debug-mcp: the HTTP transport requires the 'rack' gem. " \
+          "Install it with `gem install rack` (or add `gem \"rack\"` to your Gemfile)."
+      end
+      require "stringio"
       require "webrick"
 
       transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
@@ -266,7 +283,7 @@ module DebugMcp
 
       webrick.mount_proc("/mcp") do |req, res|
         env = build_rack_env(req)
-        rack_request = RackRequestAdapter.new(env)
+        rack_request = Rack::Request.new(env)
         status, headers, body = transport.handle_request(rack_request)
 
         res.status = status
@@ -302,27 +319,16 @@ module DebugMcp
       transport&.close
     end
 
-    # Minimal Rack::Request-compatible adapter for WEBrick
-    class RackRequestAdapter
-      attr_reader :env
-
-      def initialize(env)
-        @env = env
-      end
-
-      def body
-        @env["rack.input"]
-      end
-    end
-
     def build_rack_env(req)
+      body = req.body || ""
       env = {
         "REQUEST_METHOD" => req.request_method,
         "PATH_INFO" => req.path,
         "QUERY_STRING" => req.query_string || "",
         "SERVER_NAME" => @http_host,
         "SERVER_PORT" => @http_port.to_s,
-        "rack.input" => StringIO.new(req.body || ""),
+        "CONTENT_LENGTH" => body.bytesize.to_s,
+        "rack.input" => StringIO.new(body),
       }
 
       # Map HTTP headers to Rack convention