debug-mcp 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e1fb7afee534aad7a8eefa7dcf23af611f4a4ca0b630ce15abb8be9e4ee1bdb
-  data.tar.gz: ba299cabca9196b1e77ebf871891caf1452ea76c0f1b5010502875d65173a43e
+  metadata.gz: 6257424af8b8ba371cecbb8f76fa8b0b68b1bb7d087528b7d5a99b4f53cccf92
+  data.tar.gz: abaaef014089cfc1dfa20e653a5c86f0614b3de3c685fc0d19602fcc8a411edc
 SHA512:
-  metadata.gz: '0935b47a3b99932f43cc0d43ef4bfdb41a386e1f8ead818643281f86e2c68d0b3457f94e6807d1d16743a356c335c6b08f9e4133abe6142b4fefd92531380360'
-  data.tar.gz: 79a9660c468b25d384ddffcf7d6be41228dadd11b37a5cccc3e096a6cf43e6932b1392a755d796b109d8feea85f424042be57729222dbc363029dd29e40cf5d7
+  metadata.gz: 8a747e5eb9a03f257af96d135128b4ade00c64700ae8c7fe9c7dd7f93c8b025fa41dfc7d345bce78aa2544ab8af0e701329257205294b4e74c1682d23b323a93
+  data.tar.gz: db31877e159f7777f2fa4f242bc07440deb512d99e7eb929de36538ce5f5f879e5efe1b511e5838cdf7d4122f1ebd214176afa2411f3e105621c40038003eaf2

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.2.0 — 2026-05-14
+
+### Features
+
+- **Structured Rails event capture in `trigger_request`** — The response now includes
+  a `Rails Events` section with SQL queries, rendered templates, cache operations,
+  enqueued jobs, and request lifecycle info, sourced from `ActiveSupport::Notifications`.
+  LLM agents can detect N+1 queries, verify cache effectiveness, and track side-effects
+  using structured data instead of parsing log text.
+
+  How it works: debug-mcp injects a subscriber into the Rails process via `evaluate_code`
+  at first use (idempotent, no gem install needed in the Rails app), tags HTTP requests
+  with an auto-generated `X-Request-Id`, and correlates the captured events back to the
+  triggering request. Events live in a per-process ring buffer (1000 events) protected
+  by a Mutex.
+
+- **Source tagging to separate app execution from debugger inspection** — When
+  `evaluate_code` or `inspect_object` is used at a breakpoint, the AR queries they
+  fire run on the request thread. Those events are tagged `source: :debug_eval` so
+  they don't appear to be part of application execution. The default view shows only
+  `:request` events; pass `include_debug_eval: true` to `trigger_request` to see all.
+  Implemented via `Thread.current[:_debug_mcp_event_source]` with save/restore so
+  nested wrapping is safe.
+
+- **New `trigger_request` options** — `event_limits` (per-category count overrides;
+  defaults `sql: 30, render: 20, cache: 20, job: unlimited, logger: 50`; pass `null`
+  to disable a limit) and `include_debug_eval` (boolean) for tuning the event output.
+
+### Bug Fixes (pre-release)
+
+- **`SourceTagging.wrap` nested-safety** — The initial implementation saved the
+  prior Thread-local value in a local variable, which a nested wrap within the
+  same eval overwrote, causing the outer's `ensure` to restore the wrong value.
+  Switched to a Thread-local stack (`:_debug_mcp_event_source_stack`) so each
+  push/pop pair restores the correct prior source regardless of nesting depth.
+  Discovered during real-Rails verification before the 0.2.0 release.
+
+### Internal
+
+- New modules: `DebugMcp::NotificationsSubscriber`, `DebugMcp::EventFormatter`,
+  `DebugMcp::SourceTagging`.
+- `evaluate_code` and `inspect_object` now wrap user expressions with `SourceTagging.wrap`.
+
 ## Renamed: `girb-mcp` → `debug-mcp` (2026-04-28)
 
 This gem was previously released on RubyGems as `girb-mcp`. It has been renamed to

data/README.ja.md

@@ -214,6 +214,55 @@ Railsプロセスを検出すると自動的に登録されます。
 | `rails_routes` | ルーティング一覧（verb, path, controller#action）、コントローラ・パスでフィルタ可能 |
 | `rails_model` | モデル構造：カラム・アソシエーション・バリデーション・enum・スコープを表示 |
 
+## Rails イベントキャプチャ
+
+Rails アプリへ `trigger_request` を実行すると、レスポンスにリクエスト中の挙動を構造化した `Rails Events` セクションが付加されます。
+
+- SQL クエリ (実行時間、bind 値、query name、cached フラグ)
+- レンダリング (template / partial / collection)
+- キャッシュ操作 (read/write/fetch_hit、hit/miss)
+- enqueue された ActiveJob
+- リクエストのライフサイクル (controller#action、status、view/db runtime)
+
+debug-mcp が初回の `trigger_request` 時に `ActiveSupport::Notifications` の subscriber を Rails プロセスに動的注入することで実現しています。Rails アプリ側に gem 追加は不要です。
+
+### 出力例
+
+```
+Agent: trigger_request(method: "GET", url: "http://localhost:3000/users/1")
+
+  HTTP 200 OK
+  {...response body...}
+
+  --- Rails Events ---
+  ## Request
+  GET /users/1 → UsersController#show
+  Status: 200 — total 35.4ms (view 12.5ms, db 4.2ms)
+
+  ## SQL (1 query)
+  1. (0.66ms) User Load SELECT "users".* FROM "users" WHERE "users"."id" = 1 LIMIT 1
+```
+
+### フィルタリング: アプリ実行と debugger 操作の分離
+
+breakpoint 停止中に `evaluate_code` や `inspect_object` を実行すると、それらが発行した AR クエリもリクエストスレッド上で動くためバッファに入ります。debug-mcp はそれらに `source: :debug_eval` タグを付けるので、デフォルト表示からは除外され、アプリ自身の挙動だけが見える状態になります。
+
+- **デフォルト**: `:debug_eval` のイベントを非表示。アプリ自身の動作だけを表示。
+- **`include_debug_eval: true`** を `trigger_request` に渡す: デバッガが触ったクエリも含めて全件表示。
+
+### 出力量の調整
+
+`trigger_request` の `event_limits` オプションでカテゴリ別の上限を上書きできます。
+
+```
+trigger_request(
+  method: "GET", url: "...",
+  event_limits: { sql: 100, render: null }  # null は上限なし
+)
+```
+
+デフォルト: `sql=30`, `render=20`, `cache=20`, `job=無制限`, `logger=50`。
+
 ## ワークフロー例
 
 ### Rubyスクリプトのデバッグ

data/README.md

@@ -215,6 +215,55 @@ These tools are automatically registered when a Rails process is detected.
 | `rails_routes` | Show routes (verb, path, controller#action), filterable by controller or path |
 | `rails_model` | Show model structure: columns, associations, validations, enums, scopes |
 
+## Rails event capture
+
+When `trigger_request` is used against a Rails app, the response includes a structured `Rails Events` section that surfaces what happened inside the request:
+
+- SQL queries (duration, bind values, query name, cached flag)
+- Renders (templates, partials, collections)
+- Cache operations (read/write/fetch_hit, hit/miss)
+- Enqueued ActiveJob jobs
+- Request lifecycle (controller#action, status, view/db runtime)
+
+This is captured via an `ActiveSupport::Notifications` subscriber that debug-mcp injects into the Rails process at first use — no gem installation in your Rails app required.
+
+### Example output
+
+```
+Agent: trigger_request(method: "GET", url: "http://localhost:3000/users/1")
+
+  HTTP 200 OK
+  {...response body...}
+
+  --- Rails Events ---
+  ## Request
+  GET /users/1 → UsersController#show
+  Status: 200 — total 35.4ms (view 12.5ms, db 4.2ms)
+
+  ## SQL (1 query)
+  1. (0.66ms) User Load SELECT "users".* FROM "users" WHERE "users"."id" = 1 LIMIT 1
+```
+
+### Filtering: separating app execution from debugger inspection
+
+When you call `evaluate_code` or `inspect_object` at a breakpoint, any AR queries those make run on the request thread and would otherwise look like application SQL. debug-mcp tags them with `source: :debug_eval` so the default view stays clean.
+
+- **Default**: `:debug_eval` events are hidden — what you see is the app's own work.
+- **`include_debug_eval: true`** on `trigger_request`: include them, useful for seeing what the debugger touched.
+
+### Tuning the output volume
+
+`trigger_request` accepts an `event_limits` object to override per-category caps:
+
+```
+trigger_request(
+  method: "GET", url: "...",
+  event_limits: { sql: 100, render: null }  # null disables the limit
+)
+```
+
+Defaults: `sql=30`, `render=20`, `cache=20`, `job=unlimited`, `logger=50`.
+
 ## Workflows
 
 ### Debug a Ruby script

data/lib/debug_mcp/event_formatter.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module DebugMcp
+  module EventFormatter
+    DEFAULT_LIMITS = {
+      sql: 30,
+      render: 20,
+      cache: 20,
+      job: nil,           # nil = no limit
+      logger: 50,
+    }.freeze
+
+    MAX_SQL_CHARS = 500
+    SQL_HEAD = 300
+    SQL_TAIL = 100
+    MAX_CACHE_KEY_CHARS = 200
+    MAX_JOB_ARG_CHARS = 300
+
+    class << self
+      # Format an array of event hashes (as returned by NotificationsSubscriber.fetch_*)
+      # into a Markdown-flavored structured text block.
+      # Returns nil if events is empty (after filtering).
+      #
+      # By default, events with source: :debug_eval are excluded — these are AR
+      # queries / renders / etc. fired by debug-mcp's own evaluate_code calls
+      # during breakpoint inspection (ADR-0003). Pass include_debug_eval: true
+      # to keep them.
+      def format(events, limits: DEFAULT_LIMITS, include_debug_eval: false)
+        return nil if events.nil? || events.empty?
+
+        filtered = include_debug_eval ? events : events.reject { |e| e[:source].to_s == "debug_eval" }
+        return nil if filtered.empty?
+
+        grouped = group_events(filtered)
+        sections = []
+
+        sections << format_controller(grouped[:controller])
+        sections << format_sql(grouped[:sql], limit: limits[:sql])
+        sections << format_renders(grouped[:render], limit: limits[:render])
+        sections << format_cache(grouped[:cache], limit: limits[:cache])
+        sections << format_jobs(grouped[:job], limit: limits[:job])
+
+        sections.compact.join("\n\n")
+      end
+
+      private
+
+      def group_events(events)
+        groups = { controller: [], sql: [], render: [], cache: [], job: [] }
+        events.each do |e|
+          name = e[:name].to_s
+          case name
+          when "sql.active_record" then groups[:sql] << e
+          when /\Arender_/         then groups[:render] << e
+          when /\Acache_/          then groups[:cache] << e
+          when "enqueue.active_job" then groups[:job] << e
+          when "start_processing.action_controller", "process_action.action_controller"
+            groups[:controller] << e
+          end
+        end
+        groups
+      end
+
+      def format_controller(events)
+        return nil if events.empty?
+        finish = events.find { |e| e[:name] == "process_action.action_controller" }
+        start = events.find { |e| e[:name] == "start_processing.action_controller" }
+        target = finish || start
+        return nil unless target
+
+        data = target[:data] || {}
+        lines = ["## Request"]
+        lines << "#{data[:method]} #{data[:path]} → #{data[:controller]}##{data[:action]}"
+        if finish
+          status = data[:status]
+          dur = finish[:duration_ms]
+          extras = []
+          extras << "view #{data[:view_runtime].round(1)}ms" if data[:view_runtime]
+          extras << "db #{data[:db_runtime].round(1)}ms" if data[:db_runtime]
+          extra_str = extras.any? ? " (#{extras.join(", ")})" : ""
+          lines << "Status: #{status} — total #{dur}ms#{extra_str}"
+        end
+        lines.join("\n")
+      end
+
+      def format_sql(events, limit:)
+        return nil if events.empty?
+        shown, truncated = apply_limit(events, limit)
+        lines = ["## SQL (#{events.size} #{events.size == 1 ? "query" : "queries"})"]
+        shown.each_with_index do |e, i|
+          d = e[:data] || {}
+          dur = e[:duration_ms]
+          cached = d[:cached] ? " [cached]" : ""
+          name = d[:query_name].to_s.empty? ? "" : " #{d[:query_name]}"
+          sql_text = truncate_sql(d[:sql].to_s)
+          lines << "#{i + 1}. (#{dur}ms)#{cached}#{name} #{sql_text}"
+          if d[:binds].is_a?(Array) && d[:binds].any?
+            lines << "   binds: #{d[:binds].join(", ")}"
+          end
+        end
+        lines << "... and #{truncated} more (limit=#{limit})" if truncated > 0
+        lines.join("\n")
+      end
+
+      def format_renders(events, limit:)
+        return nil if events.empty?
+        shown, truncated = apply_limit(events, limit)
+        lines = ["## Renders (#{events.size})"]
+        shown.each_with_index do |e, i|
+          d = e[:data] || {}
+          kind = e[:name].to_s.sub("render_", "").sub(".action_view", "")
+          dur = e[:duration_ms]
+          identifier = d[:identifier].to_s
+          # Shorten absolute paths to just the relative portion when possible
+          identifier = identifier.sub(%r{\A.*?/app/views/}, "app/views/")
+          extras = []
+          extras << "layout=#{d[:layout]}" if d[:layout] && !d[:layout].to_s.empty?
+          extras << "count=#{d[:count]}" if d[:count]
+          extra_str = extras.any? ? " (#{extras.join(", ")})" : ""
+          lines << "#{i + 1}. [#{kind}] #{identifier} — #{dur}ms#{extra_str}"
+        end
+        lines << "... and #{truncated} more (limit=#{limit})" if truncated > 0
+        lines.join("\n")
+      end
+
+      def format_cache(events, limit:)
+        return nil if events.empty?
+        shown, truncated = apply_limit(events, limit)
+        lines = ["## Cache (#{events.size})"]
+        shown.each_with_index do |e, i|
+          d = e[:data] || {}
+          op = e[:name].to_s.sub("cache_", "").sub(".active_support", "")
+          hit_marker = d[:hit] == true ? " hit" : d[:hit] == false ? " miss" : ""
+          key = d[:key].to_s[0, MAX_CACHE_KEY_CHARS]
+          lines << "#{i + 1}. [#{op}#{hit_marker}] #{key} (#{e[:duration_ms]}ms)"
+        end
+        lines << "... and #{truncated} more (limit=#{limit})" if truncated > 0
+        lines.join("\n")
+      end
+
+      def format_jobs(events, limit:)
+        return nil if events.empty?
+        shown, truncated = apply_limit(events, limit)
+        lines = ["## Enqueued Jobs (#{events.size})"]
+        shown.each_with_index do |e, i|
+          d = e[:data] || {}
+          klass = d[:job_class] || "(unknown)"
+          queue = d[:queue_name] ? " [#{d[:queue_name]}]" : ""
+          args = (d[:arguments] || []).join(", ")[0, MAX_JOB_ARG_CHARS]
+          arg_str = args.empty? ? "" : " args=#{args}"
+          lines << "#{i + 1}. #{klass}#{queue}#{arg_str}"
+        end
+        lines << "... and #{truncated} more (limit=#{limit})" if truncated > 0
+        lines.join("\n")
+      end
+
+      # Apply an item count limit. Returns [shown_array, truncated_count].
+      # Pass limit=nil for no limit.
+      def apply_limit(events, limit)
+        return [events, 0] if limit.nil? || events.size <= limit
+        [events.first(limit), events.size - limit]
+      end
+
+      def truncate_sql(sql)
+        return sql if sql.length <= MAX_SQL_CHARS
+        head = sql[0, SQL_HEAD]
+        tail = sql[-SQL_TAIL, SQL_TAIL]
+        "#{head} ... [truncated #{sql.length - SQL_HEAD - SQL_TAIL} chars] ... #{tail}"
+      end
+    end
+  end
+end

data/lib/debug_mcp/notifications_subscriber.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require_relative "rails_helper"
+
+module DebugMcp
+  module NotificationsSubscriber
+    BUFFER_MAX = 1000
+
+    SUBSCRIBED_EVENTS = %w[
+      sql.active_record
+      render_template.action_view
+      render_partial.action_view
+      render_collection.action_view
+      cache_read.active_support
+      cache_write.active_support
+      cache_fetch_hit.active_support
+      cache_generate.active_support
+      cache_delete.active_support
+      enqueue.active_job
+      start_processing.action_controller
+      process_action.action_controller
+    ].freeze
+
+    INJECTION_CODE = <<~RUBY
+      unless defined?(::DebugMcpNotificationsBuffer)
+        module ::DebugMcpNotificationsBuffer
+          BUFFER_MAX = #{BUFFER_MAX}
+          SUBSCRIBED_EVENTS = #{SUBSCRIBED_EVENTS.inspect}.freeze
+
+          @buffer = []
+          @subscriptions = []
+          @mutex = Mutex.new
+
+          class << self
+            attr_reader :buffer, :subscriptions
+
+            def push(event)
+              @mutex.synchronize do
+                @buffer << event
+                @buffer.shift while @buffer.size > BUFFER_MAX
+              end
+            end
+
+            def fetch_by_request_id(request_id)
+              @mutex.synchronize { @buffer.select { |e| e[:request_id] == request_id } }
+            end
+
+            def fetch_since(timestamp)
+              @mutex.synchronize { @buffer.select { |e| e[:timestamp] >= timestamp } }
+            end
+
+            def clear
+              @mutex.synchronize { @buffer.clear }
+            end
+
+            def install
+              return if @subscriptions.any?
+
+              callback = lambda do |name, started, finished, _id, payload|
+                req_id = extract_request_id(name, payload)
+                src = Thread.current[:_debug_mcp_event_source] || :request
+                push({
+                  name: name,
+                  timestamp: started.to_f,
+                  duration_ms: ((finished.to_f - started.to_f) * 1000).round(2),
+                  request_id: req_id,
+                  source: src,
+                  data: sanitize_payload(name, payload),
+                })
+                Thread.current[:_debug_mcp_request_id] = nil if name == "process_action.action_controller"
+              rescue StandardError
+                # never raise from subscriber callback
+              end
+
+              SUBSCRIBED_EVENTS.each do |event_name|
+                @subscriptions << ::ActiveSupport::Notifications.subscribe(event_name, &callback)
+              end
+            end
+
+            def uninstall
+              @subscriptions.each { |s| ::ActiveSupport::Notifications.unsubscribe(s) }
+              @subscriptions.clear
+            end
+
+            def extract_request_id(name, payload)
+              return nil unless payload.is_a?(Hash)
+              req_id = payload[:request_id]
+              if name == "start_processing.action_controller" && payload[:headers]
+                h = payload[:headers]
+                req_id ||= safe_header_lookup(h, "action_dispatch.request_id")
+                req_id ||= safe_header_lookup(h, "HTTP_X_REQUEST_ID")
+                Thread.current[:_debug_mcp_request_id] = req_id if req_id
+              end
+              req_id || Thread.current[:_debug_mcp_request_id]
+            end
+
+            def safe_header_lookup(headers, key)
+              headers[key]
+            rescue StandardError
+              nil
+            end
+
+            def sanitize_payload(name, payload)
+              return {} unless payload.is_a?(Hash)
+              case name
+              when "sql.active_record"
+                {
+                  sql: payload[:sql].to_s,
+                  query_name: payload[:name].to_s,
+                  cached: payload[:cached] ? true : false,
+                  binds: safe_binds(payload[:type_casted_binds] || payload[:binds]),
+                }
+              when /\\Arender_/
+                {
+                  identifier: payload[:identifier].to_s,
+                  layout: payload[:layout]&.to_s,
+                  count: payload[:count],
+                }
+              when /\\Acache_/
+                {
+                  key: payload[:key].to_s[0, 200],
+                  hit: payload[:hit],
+                  store: payload[:store]&.to_s,
+                }
+              when "enqueue.active_job"
+                job = payload[:job]
+                {
+                  job_class: (job.class.name rescue nil),
+                  job_id: (job.respond_to?(:job_id) ? job.job_id : nil),
+                  queue_name: (job.respond_to?(:queue_name) ? job.queue_name : nil),
+                  arguments: (job.respond_to?(:arguments) ? job.arguments : []).map { |a| safe_inspect(a, 100) },
+                }
+              when "start_processing.action_controller", "process_action.action_controller"
+                {
+                  controller: payload[:controller],
+                  action: payload[:action],
+                  method: payload[:method],
+                  path: payload[:path],
+                  format: payload[:format].to_s,
+                  status: payload[:status],
+                  view_runtime: payload[:view_runtime],
+                  db_runtime: payload[:db_runtime],
+                }
+              else
+                {}
+              end
+            rescue StandardError => e
+              { error: "payload_sanitize_failed: \#{e.class}" }
+            end
+
+            def safe_binds(binds)
+              return [] unless binds.respond_to?(:each)
+              binds.map { |b| safe_inspect(b, 100) }
+            rescue StandardError
+              []
+            end
+
+            def safe_inspect(obj, limit)
+              s = obj.inspect
+              s.length > limit ? s[0, limit] + "..." : s
+            rescue StandardError
+              "<uninspectable>"
+            end
+          end
+        end
+        ::DebugMcpNotificationsBuffer.install
+      end
+    RUBY
+
+    class << self
+      # Inject the subscriber into the Rails process. Idempotent.
+      # Returns true on success, false otherwise.
+      def install(client)
+        return false unless RailsHelper.rails?(client)
+
+        encoded = Base64.strict_encode64(INJECTION_CODE)
+        cmd = "p begin; require 'base64'; eval(::Base64.decode64('#{encoded}').force_encoding('UTF-8')); " \
+              ":debug_mcp_subscriber_ok; rescue => __e; \"\#{__e.class}: \#{__e.message}\"; end"
+        result = client.send_command(cmd)
+        result.include?("debug_mcp_subscriber_ok")
+      rescue DebugMcp::Error
+        false
+      end
+
+      # Remove the subscriber. Best-effort; returns nil on error.
+      def uninstall(client)
+        client.send_command(
+          "::DebugMcpNotificationsBuffer.uninstall if defined?(::DebugMcpNotificationsBuffer)",
+        )
+      rescue DebugMcp::Error
+        nil
+      end
+
+      # Fetch events for a request_id. Returns array of event hashes (symbolized keys).
+      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)
+      rescue DebugMcp::Error
+        []
+      end
+
+      # Fetch events fired at-or-after the given timestamp.
+      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)
+      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
+        []
+      end
+    end
+  end
+end

data/lib/debug_mcp/rails_helper.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "base64"
+require_relative "source_tagging"
 
 module DebugMcp
   module RailsHelper
@@ -63,6 +64,11 @@ module DebugMcp
     # result by the debug gem, which works even in signal trap context.
     # Returns nil if the result is nil or evaluation fails.
     def eval_expr(client, expr)
+      # Note: internal probes use simple expressions (Rails.root, Rails.env,
+      # Dir.pwd, etc.) that don't fire ActiveSupport::Notifications events,
+      # so SourceTagging.wrap isn't applied here. Tools that take arbitrary
+      # user expressions (evaluate_code, inspect_object) handle tagging
+      # themselves at the call site.
       result = client.send_command("p #{expr}")
       cleaned = result.strip.sub(/\A=> /, "")
       return nil if cleaned == "nil" || cleaned.empty?

data/lib/debug_mcp/source_tagging.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module DebugMcp
+  module SourceTagging
+    SOURCE_KEY = ":_debug_mcp_event_source"
+    STACK_KEY = ":_debug_mcp_event_source_stack"
+    DEBUG_EVAL_SOURCE = ":debug_eval"
+
+    class << self
+      # Wrap a Ruby expression so ActiveSupport::Notifications events fired
+      # during its evaluation are tagged with source: :debug_eval.
+      #
+      # Uses a Thread-local stack rather than a local variable so nested
+      # wraps within a single eval are safe — each push/pop pair restores
+      # the correct previous value even when wraps share the same call frame.
+      #
+      # The wrapped expression evaluates to the same value as the original.
+      def wrap(code)
+        "begin; " \
+        "(::Thread.current[#{STACK_KEY}] ||= []) << ::Thread.current[#{SOURCE_KEY}]; " \
+        "::Thread.current[#{SOURCE_KEY}]=#{DEBUG_EVAL_SOURCE}; " \
+        "(#{code}); " \
+        "ensure ::Thread.current[#{SOURCE_KEY}]=::Thread.current[#{STACK_KEY}].pop; end"
+      end
+    end
+  end
+end

data/lib/debug_mcp/tools/evaluate_code.rb

@@ -228,13 +228,19 @@ module DebugMcp
         # gem protocol is line-based) or non-ASCII characters (to avoid
         # encoding conflicts on the socket).
         def build_eval_command(code)
+          # Tag any ActiveSupport::Notifications events fired during this eval
+          # so trigger_request can filter them out (ADR-0003).
+          # SourceTagging.wrap uses save/restore so nested wraps don't clobber
+          # any outer source value.
           if code.include?("\n") || !code.ascii_only?
             encoded = Base64.strict_encode64(code.encode(Encoding::UTF_8))
+            inner = "eval(::Base64.decode64('#{encoded}').force_encoding('UTF-8'), binding)"
             "$__debug_mcp_err=nil; pp(begin; require 'base64'; " \
-            "eval(::Base64.decode64('#{encoded}').force_encoding('UTF-8'), binding); " \
+            "#{DebugMcp::SourceTagging.wrap(inner)}; " \
             'rescue => __e; $__debug_mcp_err="#{__e.class}: #{__e.message}"; nil; end)'
           else
-            "$__debug_mcp_err=nil; pp(begin; (#{code}); " \
+            "$__debug_mcp_err=nil; pp(begin; " \
+            "#{DebugMcp::SourceTagging.wrap(code)}; " \
             'rescue => __e; $__debug_mcp_err="#{__e.class}: #{__e.message}"; nil; end)'
           end
         end

data/lib/debug_mcp/tools/inspect_object.rb

@@ -2,6 +2,7 @@
 
 require "mcp"
 require_relative "../pending_http_helper"
+require_relative "../source_tagging"
 
 module DebugMcp
   module Tools
@@ -38,16 +39,19 @@ module DebugMcp
 
           parts = []
 
+          # User-supplied expressions can hit ActiveRecord and fire Notifications
+          # events. Tag them as :debug_eval so trigger_request can filter them
+          # out (ADR-0003).
+
           # RT 1: Get the pretty-printed value (primary - if this fails, expression is invalid)
-          value_output = client.send_command("pp #{expression}")
+          value_output = client.send_command("pp(#{DebugMcp::SourceTagging.wrap(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]",
-            )
+            meta_expr = "[(#{expression}).class.to_s, (#{expression}).instance_variables, " \
+                        "(#{expression}).is_a?(Module) ? (#{expression}).class_variables : nil]"
+            meta_output = client.send_command("p(#{DebugMcp::SourceTagging.wrap(meta_expr)})")
             class_name, ivars, cvars = parse_meta(meta_output)
             parts << "Class: #{class_name}" if class_name
             parts << "Instance variables: #{ivars}" if ivars
@@ -55,10 +59,9 @@ module DebugMcp
             # 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]}]",
-                )
+                cvar_expr = "Hash[(#{expression}).class_variables.map{|v|" \
+                            "[v,begin;(#{expression}).class_variable_get(v);rescue;'(error)';end]}]"
+                cvar_values = client.send_command("pp(#{DebugMcp::SourceTagging.wrap(cvar_expr)})")
                 parts << "Class variables:\n#{cvar_values}"
               rescue DebugMcp::TimeoutError
                 parts << "Class variables: #{cvars}"

data/lib/debug_mcp/tools/trigger_request.rb

@@ -2,9 +2,12 @@
 
 require "mcp"
 require "net/http"
+require "securerandom"
 require "uri"
 require "json"
 require_relative "../rails_helper"
+require_relative "../notifications_subscriber"
+require_relative "../event_formatter"
 
 module DebugMcp
   module Tools
@@ -63,6 +66,21 @@ module DebugMcp
             type: "string",
             description: "Debug session ID to monitor for breakpoint hits (uses default if omitted)",
           },
+          event_limits: {
+            type: "object",
+            description: "Override the per-category event count limits in the structured 'Rails Events' " \
+                         "section. Partial overrides supported. Keys: sql, render, cache, job, logger. " \
+                         "Pass null for a key to disable its limit. " \
+                         "Defaults: sql=30, render=20, cache=20, job=unlimited, logger=50. " \
+                         "Example: {\"sql\": 100, \"render\": null}",
+          },
+          include_debug_eval: {
+            type: "boolean",
+            description: "Include events triggered by debug-mcp's own evaluate_code / inspect_object calls " \
+                         "(tagged source: :debug_eval). Defaults to false — debugger-driven SQL is hidden " \
+                         "to keep the request view focused on application execution. " \
+                         "Set true when you want to see what the debugger touched.",
+          },
         },
         required: ["method", "url"],
       )
@@ -71,9 +89,11 @@ module DebugMcp
         MAX_LOG_BYTES = 4000
 
         def call(method:, url:, headers: {}, body: nil, cookies: nil, skip_csrf: nil,
-                 timeout: nil, session_id: nil, server_context:)
+                 timeout: nil, session_id: nil, event_limits: nil, include_debug_eval: false,
+                 server_context:)
           manager = server_context[:session_manager]
           timeout_sec = timeout || DEFAULT_TIMEOUT
+          formatter_limits = resolve_event_limits(event_limits)
 
           # Auto-detect Content-Type if body is present and no Content-Type header set
           headers = (headers || {}).dup
@@ -92,10 +112,18 @@ module DebugMcp
             end
           end
 
+          # Inject a request ID so we can correlate Notifications events with this request.
+          # Rails (ActionDispatch::RequestId middleware) honors X-Request-Id if present.
+          request_id = SecureRandom.uuid
+          unless headers.any? { |k, _| k.to_s.downcase == "x-request-id" }
+            headers["X-Request-Id"] = request_id
+          end
+
           # CSRF handling: disable forgery protection for non-GET requests on Rails
           csrf_disabled = false
           client = nil
           log_capture = nil
+          subscriber_ready = false
           begin
             client = manager.client(session_id)
             # Recover paused state if a previous timeout left @paused=false
@@ -112,6 +140,8 @@ module DebugMcp
               if method != "GET" && should_disable_csrf?(skip_csrf, client)
                 csrf_disabled = temporarily_disable_csrf(client)
               end
+              # Inject the Notifications subscriber lazily (idempotent).
+              subscriber_ready = NotificationsSubscriber.install(client)
               # Snapshot log file position before request for Rails log capture
               log_capture = start_log_capture(client)
             end
@@ -126,7 +156,10 @@ module DebugMcp
               handle_without_session(method, url, headers, body, timeout_sec)
             end
 
-            append_captured_logs(response, log_capture)
+            response = append_captured_logs(response, log_capture)
+            append_notifications_events(response, client, request_id, subscriber_ready,
+                                        limits: formatter_limits,
+                                        include_debug_eval: include_debug_eval)
           ensure
             # Only restore CSRF when the process is paused (at a breakpoint).
             # If the process is running (interrupted/timeout), sending commands
@@ -433,6 +466,51 @@ module DebugMcp
           nil
         end
 
+        # Query the Notifications subscriber buffer for events tied to this request
+        # and append a structured section to the response. Best-effort: returns the
+        # response unchanged if the subscriber is unavailable or the client is not
+        # paused (we cannot send_command on a running process).
+        def append_notifications_events(response, client, request_id, subscriber_ready,
+                                        limits: EventFormatter::DEFAULT_LIMITS, include_debug_eval: false)
+          return response unless subscriber_ready
+          return response unless client&.connected? && client.paused
+
+          events = NotificationsSubscriber.fetch_by_request_id(client, request_id)
+          return response if events.nil? || events.empty?
+
+          formatted = EventFormatter.format(events, limits: limits, include_debug_eval: include_debug_eval)
+          return response if formatted.nil? || formatted.empty?
+
+          existing = response.content.first
+          return response unless existing.is_a?(Hash) && existing[:type] == "text"
+
+          updated_text = existing[:text] + "\n\n--- Rails Events ---\n" + formatted
+          MCP::Tool::Response.new([{ type: "text", text: updated_text }])
+        rescue StandardError
+          response
+        end
+
+        # Merge user-supplied event_limits hash into the DEFAULT_LIMITS.
+        # Accepts both symbol and string keys. Returns a fully-populated hash
+        # suitable for EventFormatter.format.
+        def resolve_event_limits(overrides)
+          return EventFormatter::DEFAULT_LIMITS if overrides.nil? || overrides.empty?
+
+          result = EventFormatter::DEFAULT_LIMITS.dup
+          overrides.each do |k, v|
+            key = k.to_sym
+            next unless result.key?(key)
+            # Accept nil (no limit), integers, and other numerics; coerce strings if possible.
+            result[key] = case v
+                          when nil then nil
+                          when Integer then v
+                          when String then (Integer(v, exception: false) || result[key])
+                          else result[key]
+                          end
+          end
+          result.freeze
+        end
+
         # Read new log entries since the snapshot and append to the response.
         def append_captured_logs(response, log_capture)
           return response unless log_capture

data/lib/debug_mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DebugMcp
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/debug_mcp.rb

@@ -6,6 +6,9 @@ require_relative "debug_mcp/session_manager"
 require_relative "debug_mcp/exit_message_builder"
 require_relative "debug_mcp/stop_event_annotator"
 require_relative "debug_mcp/tcp_session_discovery"
+require_relative "debug_mcp/source_tagging"
+require_relative "debug_mcp/event_formatter"
+require_relative "debug_mcp/notifications_subscriber"
 require_relative "debug_mcp/server"
 
 module DebugMcp

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: debug-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - rira100000000
@@ -194,11 +194,14 @@ files:
 - lib/debug_mcp/client_cleanup.rb
 - lib/debug_mcp/code_safety_analyzer.rb
 - lib/debug_mcp/debug_client.rb
+- lib/debug_mcp/event_formatter.rb
 - lib/debug_mcp/exit_message_builder.rb
+- lib/debug_mcp/notifications_subscriber.rb
 - lib/debug_mcp/pending_http_helper.rb
 - lib/debug_mcp/rails_helper.rb
 - lib/debug_mcp/server.rb
 - lib/debug_mcp/session_manager.rb
+- lib/debug_mcp/source_tagging.rb
 - lib/debug_mcp/stop_event_annotator.rb
 - lib/debug_mcp/tcp_session_discovery.rb
 - lib/debug_mcp/tools/connect.rb