coatepec 0.6.0 → 0.8.0

data/lib/coatepec/introspection/controller.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative "route_entries"
+
+module Coatepec
+  module Introspection
+    # Returns bounded ActionController class metadata for a single controller,
+    # for the rails_controller MCP tool. Pure reflection over an already-loaded,
+    # already-gated class -- no request dispatch, no action execution, and no
+    # evaluation of app-authored callback conditions.
+    # rubocop:disable Metrics/ClassLength -- the route cross-referencing methods serve this class's
+    # one responsibility (reflect on one controller); splitting them out would only satisfy a line count.
+    class Controller
+      NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
+      MAX_ITEMS = 200
+
+      # AbstractController::Callbacks::ActionFilter#match? reads exactly two
+      # things off the controller it is handed: `action_name`, and (Rails 7.1+)
+      # `raise_on_missing_callback_actions`. That second one must be false --
+      # when true, match? raises ActionNotFound for any action named in `only:`
+      # that the controller doesn't define, which is precisely the drift this
+      # tool exists to *report*, so it must never raise here. This Struct is
+      # the entire controller surface match? touches; nothing on it can
+      # execute application code.
+      CallbackProbe = Struct.new(:action_name, :raise_on_missing_callback_actions)
+
+      def initialize(name)
+        @name = name
+      end
+
+      def call
+        validate_name!
+        klass = resolve!
+        validate_action_controller!(klass)
+        build_metadata(klass)
+      end
+
+      private
+
+      def build_metadata(klass)
+        actions = action_names(klass)
+        routes = routes_by_action(klass)
+        {
+          name: klass.name, controller_path: klass.controller_path,
+          actions: actions.map { |action| { name: action, routes: routes.fetch(action, []) } },
+          unroutable_actions: actions.reject { |action| routes.key?(action) },
+          routes_without_action: routes_without_action(klass, routes),
+          callbacks: callbacks_for(klass, actions), concerns: concerns_for(klass)
+        }
+      end
+
+      def validate_name!
+        return if @name.is_a?(String) && NAME_PATTERN.match?(@name)
+
+        raise Coatepec::Error.new(:invalid_controller_name, "#{@name.inspect} is not a valid constant name")
+      end
+
+      def resolve!
+        ::ActiveSupport::Inflector.safe_constantize(@name) ||
+          raise(Coatepec::Error.new(:controller_not_found, "#{@name} could not be resolved"))
+      end
+
+      # Gate on Metal, not Base: an ActionController::API controller is not a
+      # Base descendant, so gating on Base would reject every API-only app.
+      def validate_action_controller!(klass)
+        unless defined?(::ActionController::Metal)
+          raise Coatepec::Error.new(:not_action_controller, "ActionController is not loaded in this app")
+        end
+        return if klass.is_a?(Class) && klass < ::ActionController::Metal
+
+        raise Coatepec::Error.new(:not_action_controller, "#{@name} is not an ActionController controller")
+      end
+
+      # action_methods is a Set of Strings. Sorted for stable output across
+      # runs. A public method contributed by a concern legitimately appears
+      # here -- Rails really would route to it, so surfacing it is the point,
+      # not a leak to filter out.
+      def action_names(klass)
+        klass.action_methods.to_a.map(&:to_s).sort.first(MAX_ITEMS)
+      end
+
+      # Slice the ancestor chain at the first ActionController::* class in it:
+      # ActionController::Base for a normal controller, ActionController::API
+      # for an API-only one. Everything before that point was inserted by the
+      # app, so this needs no denylist of the ~60 framework modules below it.
+      # Anonymous modules have a nil name and are dropped.
+      def concerns_for(klass)
+        base = framework_base(klass)
+        klass.ancestors
+             .take_while { |mod| mod != base }
+             .reject { |mod| mod.is_a?(Class) }
+             .filter_map(&:name)
+             .first(MAX_ITEMS)
+      end
+
+      def framework_base(klass)
+        klass.ancestors.find do |mod|
+          mod.is_a?(Class) && mod.name.to_s.start_with?("ActionController::")
+        end
+      end
+
+      # Matches on controller_path, Rails' own key in route defaults ("admin/reports"), through
+      # RouteEntries so engine controllers resolve too. Routes with no action (mounts, redirects) are skipped.
+      def routes_by_action(klass)
+        grouped_routes(klass).transform_values { |list| list.first(MAX_ITEMS).map { |entry| route_data(entry) } }
+      end
+
+      def grouped_routes(klass)
+        entries = controller_entries(klass.controller_path)
+        entries.group_by { |entry| entry.route.defaults[:action].to_s }.reject { |action, _| action.empty? }
+      end
+
+      def controller_entries(path)
+        RouteEntries.call(self.class.rails_routes)
+                    .select { |entry| entry.route.defaults[:controller].to_s == path }
+      end
+
+      # Differenced against the controller's full action_methods set, not the
+      # (possibly truncated-to-MAX_ITEMS) displayed `actions` list -- a
+      # controller with more than MAX_ITEMS action methods would otherwise
+      # have every route whose action fell past the truncation point reported
+      # here as a false positive, in the field the README calls the tool's
+      # most actionable output. Bounded to MAX_ITEMS like every other
+      # collection in this payload; `routes_by_action` itself caps each route
+      # *list* but not its key count, so this is where that cap belongs.
+      def routes_without_action(klass, routes)
+        defined_actions = klass.action_methods.map(&:to_s)
+        (routes.keys - defined_actions).sort.first(MAX_ITEMS)
+      end
+
+      # path and engine come off the entry, so they are byte-identical to rails_routes' values for the
+      # same route. An engine route's name is engine-local: reach it as `<mount name>.<route_name>_path`.
+      def route_data(entry)
+        { verb: entry.route.verb.to_s, path: entry.path, route_name: entry.route.name&.to_s, engine: entry.engine }
+      end
+
+      # Isolated as a class method purely so unit tests can stub it without
+      # booting Rails -- Rails.application.routes.routes is otherwise only
+      # reachable with a real, booted application. Mirrors
+      # Introspection::Routes.rails_routes.
+      # rubocop:disable Lint/IneffectiveAccessModifier
+      def self.rails_routes
+        Rails.application.routes.routes
+      end
+      # rubocop:enable Lint/IneffectiveAccessModifier
+
+      # Gated on Metal, not Base/API, so a bare ActionController::Metal
+      # subclass -- which passes validate_action_controller!'s class gate but
+      # does not include AbstractController::Callbacks, unlike Base and API --
+      # gets an empty callback list instead of a NoMethodError.
+      def callbacks_for(klass, actions)
+        return [] unless klass.respond_to?(:_process_action_callbacks)
+
+        klass._process_action_callbacks.first(MAX_ITEMS).map do |callback|
+          conditions_for(callback, actions)
+            .merge(kind: callback.kind.to_s, filter: filter_description(callback.filter))
+        end
+      end
+
+      # only:/except: do not survive as readable options. Rails compiles both
+      # into an ActionFilter and distinguishes them purely by *placement*: the
+      # `only:` filter lands in the callback's @if chain, the `except:` one in
+      # its @unless chain. Intent is therefore recovered from which chain the
+      # object sits in, not from the object itself.
+      #
+      # Reaching those chains needs instance_variable_get: Callback exposes
+      # `kind` and `filter` publicly but has no reader for @if/@unless. That
+      # single private read is unavoidable; having taken it, the action set is
+      # then read through ActionFilter's *public* match? rather than a second
+      # private read of its @actions, so this keeps working if Rails changes
+      # how ActionFilter stores them.
+      def conditions_for(callback, actions)
+        ifs = Array(callback.instance_variable_get(:@if))
+        unlesses = Array(callback.instance_variable_get(:@unless))
+        {
+          only: matched_actions(ifs, actions, :all?),
+          except: matched_actions(unlesses, actions, :any?),
+          if: plain_conditions(ifs),
+          unless: plain_conditions(unlesses)
+        }
+      end
+
+      # nil (not []) when there is no ActionFilter at all: "this callback is
+      # unrestricted" and "this callback is restricted to no actions" are
+      # different facts and must not serialize identically.
+      #
+      # A chain routinely carries *more than one* ActionFilter: skip_callback
+      # (ActiveSupport::Callbacks::Callback#merge_conditional_options)
+      # concatenates a skip's normalized only:/except: onto the callback's
+      # existing @if/@unless chain rather than replacing it, so any
+      # `skip_before_action ..., only:`/`except:` leaves two ActionFilters
+      # behind. A callback only runs when *every* @if condition holds and
+      # *none* of its @unless conditions hold (ActiveSupport::Callbacks'
+      # run_callbacks ANDs @if and ANDs the negation of each @unless), so:
+      # only: is every @if ActionFilter's matches intersected (combinator
+      # :all? -- all must hold for the action to run the callback), and
+      # except: is every @unless ActionFilter's matches unioned (combinator
+      # :any? -- any one holding is enough to skip it). Keeping only the
+      # first ActionFilter in the chain (as a naive `find` would) silently
+      # drops every skip layered on top of it, which always biases toward
+      # over-reporting protection -- exactly backwards for a tool whose job is
+      # to answer "is this action protected?".
+      def matched_actions(conditions, actions, combinator)
+        filters = conditions.select { |condition| action_filter?(condition) }
+        return nil if filters.empty?
+
+        actions.select do |action|
+          filters.public_send(combinator) { |filter| filter.match?(CallbackProbe.new(action, false)) }
+        end
+      end
+
+      def action_filter?(condition)
+        defined?(::AbstractController::Callbacks::ActionFilter) &&
+          condition.is_a?(::AbstractController::Callbacks::ActionFilter)
+      end
+
+      # The conditions that are *not* only:/except: -- a real `if:`/`unless:`.
+      # A Symbol is a method reference and safe to name; a Proc must never be
+      # serialized (Proc#to_s leaks the app's absolute source path).
+      def plain_conditions(conditions)
+        conditions.reject { |condition| action_filter?(condition) }
+                  .map { |condition| filter_description(condition) }
+      end
+
+      # A Symbol filter (the method-reference form, e.g.
+      # `before_action :require_login`) is a method reference and safe to
+      # report by name; a Proc must never be serialized, because Proc#to_s
+      # leaks the app's absolute source path, so it is reduced to "(block)"
+      # instead. Introspection::SafeOptions guards the same class of leak
+      # elsewhere, by silently dropping Procs from an options hash rather than
+      # substituting a placeholder -- a different mechanism for the same rule.
+      def filter_description(filter)
+        case filter
+        when Symbol then filter.to_s
+        when Proc then "(block)"
+        else filter.class.name || "(anonymous filter class)"
+        end
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/coatepec/introspection/model.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "model_resolver"
+
 module Coatepec
   module Introspection
     # Returns bounded ActiveRecord schema and class metadata for a single
@@ -7,45 +9,48 @@ module Coatepec
     # reflection, no method dispatch on the resolved class beyond pure
     # introspection APIs.
     class Model
-      NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
+      FIELDS = %w[columns associations validators enums].freeze
       MAX_ITEMS = 200
+      MAX_OPTION_VALUES = 20
       EMPTY_TABLE_METADATA = { table_name: nil, primary_key: nil, columns: [] }.freeze
 
-      def initialize(name)
+      # Counts are always returned; lists are opt-in, so an omitted fields costs a few dozen bytes.
+      def initialize(name, fields: nil)
         @name = name
+        @fields = validate_fields!(fields || [])
       end
 
       def call
-        validate_name!
-        klass = resolve!
-        validate_active_record!(klass)
+        klass = ModelResolver.call(@name)
         build_metadata(klass)
       end
 
       private
 
-      # An abstract class (e.g. ApplicationRecord) has no real table, so
-      # table_name/primary_key/columns all raise if called against it --
-      # report empty/nil table data instead of crashing. Validators aren't
-      # table-dependent, so those are always attempted.
+      # An abstract class (e.g. ApplicationRecord) has no real table, so table_name/primary_key/columns all raise
+      # if called against it -- report empty/nil table data instead. abstract_class? is nil (not false) for a
+      # concrete class on Rails 7.1 and false on 8.1, so normalize it for version-stable JSON. enums, like
+      # validators, are in-memory class metadata needing no connection, so they are always collected.
       def build_metadata(klass)
-        # abstract_class? is a plain attr_accessor-backed predicate that is
-        # never assigned on concrete subclasses -- on Rails 7.1 it returns
-        # nil (not false) in that case, while Rails 8.1 returns false.
-        # Normalize to a genuine Boolean so JSON output is version-stable.
         abstract = klass.abstract_class? || false
         table = abstract ? EMPTY_TABLE_METADATA : table_metadata(klass)
-        {
-          name: klass.name, table_name: table[:table_name], primary_key: table[:primary_key],
-          abstract_class: abstract, columns: table[:columns],
-          associations: abstract ? [] : associations_for(klass),
-          validators: validators_for(klass),
-          # enum declarations are pure in-memory class metadata (populated
-          # when the `enum` macro runs in the class body) -- unlike columns
-          # and associations, they need no DB connection or real table, so
-          # this is attempted unconditionally, the same way validators are.
-          enums: enums_for(klass)
-        }
+        sections = { columns: table[:columns], associations: abstract ? [] : associations_for(klass),
+                     validators: validators_for(klass), enums: enums_for(klass) }
+        { name: klass.name, table_name: table[:table_name], primary_key: table[:primary_key], abstract_class: abstract,
+          counts: sections.transform_values(&:size) }.merge(sections.slice(*(FIELDS & @fields).map(&:to_sym)))
+      end
+
+      # The MCP schema enforces the enum; this guards the worker command against any other caller.
+      def validate_fields!(fields)
+        unless fields.is_a?(Array)
+          raise Coatepec::Error.new(:invalid_model_fields, "fields must be an array, got #{fields.inspect}")
+        end
+
+        unknown = fields - FIELDS
+        return fields if unknown.empty?
+
+        raise Coatepec::Error.new(:invalid_model_fields,
+                                  "fields must be among #{FIELDS.join(", ")}, got #{unknown.inspect}")
       end
 
       # A concrete model can still name a table that isn't there: a checkout
@@ -68,23 +73,6 @@ module Coatepec
         )
       end
 
-      def validate_name!
-        return if @name.is_a?(String) && NAME_PATTERN.match?(@name)
-
-        raise Coatepec::Error.new(:invalid_model_name, "#{@name.inspect} is not a valid constant name")
-      end
-
-      def resolve!
-        ::ActiveSupport::Inflector.safe_constantize(@name) ||
-          raise(Coatepec::Error.new(:model_not_found, "#{@name} could not be resolved"))
-      end
-
-      def validate_active_record!(klass)
-        return if klass.is_a?(Class) && klass < ::ActiveRecord::Base
-
-        raise Coatepec::Error.new(:not_active_record_model, "#{@name} is not an ActiveRecord model")
-      end
-
       def columns_for(klass)
         klass.columns.first(MAX_ITEMS).map do |column|
           { name: column.name, type: column.type.to_s, sql_type: column.sql_type, null: column.null,
@@ -159,12 +147,14 @@ module Coatepec
         nil
       end
 
+      # Rails instantiates one validator per declaration; a concern and the model body often declare the same one.
+      # De-duplicate on the raw validator: SafeOptions drops the Procs and Regexps that tell two apart.
       def validators_for(klass)
-        klass.validators.first(MAX_ITEMS).map do |validator|
+        klass.validators.uniq { |v| [v.class.name, v.attributes, v.options] }.first(MAX_ITEMS).map do |validator|
           {
             name: validator.class.name,
             attributes: validator.attributes.map(&:to_s),
-            options: SafeOptions.call(validator.options)
+            options: BoundedOptions.call(SafeOptions.call(validator.options), MAX_OPTION_VALUES)
           }
         end
       end

data/lib/coatepec/introspection/model_resolver.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Turns a rails_model name into an ActiveRecord class, or raises the structured error that says why not.
+    module ModelResolver
+      NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
+
+      module_function
+
+      def call(name)
+        validate_name!(name)
+        klass = ::ActiveSupport::Inflector.safe_constantize(name) ||
+                raise(Coatepec::Error.new(:model_not_found, "#{name} could not be resolved"))
+        validate_active_record!(name, klass)
+        klass
+      end
+
+      def validate_name!(name)
+        return if name.is_a?(String) && NAME_PATTERN.match?(name)
+
+        raise Coatepec::Error.new(:invalid_model_name, "#{name.inspect} is not a valid constant name")
+      end
+
+      def validate_active_record!(name, klass)
+        return if klass.is_a?(Class) && klass < ::ActiveRecord::Base
+
+        raise Coatepec::Error.new(:not_active_record_model, "#{name} is not an ActiveRecord model")
+      end
+    end
+  end
+end

data/lib/coatepec/introspection/route_entries.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Flattens a route set into application routes followed by one level of mounted-engine
+    # routes with the mount path prefixed, the way `bin/rails routes` shows them.
+    class RouteEntries
+      Entry = Struct.new(:route, :path, :engine)
+
+      def self.call(routes)
+        new(routes).call
+      end
+
+      def initialize(routes)
+        @routes = routes
+      end
+
+      def call
+        visible = @routes.reject { |route| internal?(route) }
+
+        visible.map { |route| Entry.new(route, path_of(route), nil) } +
+          visible.flat_map { |route| engine_entries(route) }
+      end
+
+      private
+
+      # Rails' own /rails/info routes; `bin/rails routes` hides them too. Guarded so unit-spec structs work.
+      def internal?(route)
+        route.respond_to?(:internal) && route.internal
+      end
+
+      # One level only, like RoutesInspector; an engine mounted at two paths appears under both.
+      def engine_entries(route)
+        return [] unless engine_mount?(route)
+
+        engine = route.app.rack_app
+        prefix = mount_prefix(route)
+        name = engine_name(engine)
+        inner_routes(engine).reject { |inner| internal?(inner) }
+                            .map { |inner| Entry.new(inner, prefix + path_of(inner), name) }
+      end
+
+      # `(.:format)` is on nearly every route and says nothing a caller acts on; `bin/rails routes` shows it, we don't.
+      def path_of(route)
+        route.path.spec.to_s.sub(/\(\.:format\)\z/, "")
+      end
+
+      # chomp only affects a mount at "/", whose junction is the one place a "//" could form.
+      def mount_prefix(route)
+        path_of(route).chomp("/")
+      end
+
+      # Only a ::Rails::Engine subclass is expanded or named; nothing else ever gets .name called on it.
+      def engine_mount?(route)
+        route.respond_to?(:app) && route.app.respond_to?(:engine?) && route.app.engine? &&
+          rails_engine?(route.app.rack_app)
+      end
+
+      def rails_engine?(rack_app)
+        defined?(::Rails::Engine) && rack_app.is_a?(Class) && rack_app < ::Rails::Engine
+      end
+
+      # Class.new(Rails::Engine) has a nil name; a fixed label keeps its routes tagged and boot-stable.
+      def engine_name(engine)
+        engine.name || "(anonymous engine)"
+      end
+
+      # engine.routes is a RouteSet whose .routes holds the Journey routes; anything else stays unflattened.
+      def inner_routes(engine)
+        return [] unless engine.respond_to?(:routes)
+
+        route_set = engine.routes
+        route_set.respond_to?(:routes) ? route_set.routes : []
+      end
+    end
+  end
+end

data/lib/coatepec/introspection/routes.rb

@@ -1,33 +1,69 @@
 # frozen_string_literal: true
 
+require_relative "route_entries"
+
 module Coatepec
   module Introspection
-    # Returns a bounded, filterable list of the target Rails app's routes,
-    # for the rails_routes MCP tool. Reads Rails.application.routes.routes
-    # only -- no console, no request dispatch.
+    # Returns a bounded, filterable list of the target app's routes for the rails_routes MCP tool: application
+    # routes by default, mounted-engine routes on request. Reads route tables only -- no console, no dispatch.
     class Routes
       MAX_LIMIT = 200
-      DEFAULT_LIMIT = 50
+      DEFAULT_LIMIT = 100
+      ENGINE_FILTERS = %w[include exclude only].freeze
+      COLUMNS = %w[name verb path controller action engine].freeze
+      COLUMN_KEYS = COLUMNS.map(&:to_sym).freeze
+      # Engine CRUD scaffolding was two thirds of a typical match; the payload states what the default withheld.
+      DEFAULT_ENGINES = "exclude"
 
-      def initialize(query: nil, limit: DEFAULT_LIMIT, offset: 0)
+      def initialize(query: nil, limit: DEFAULT_LIMIT, offset: 0, engines: DEFAULT_ENGINES)
         @query = query
         @limit = [limit || DEFAULT_LIMIT, MAX_LIMIT].min
         @offset = offset || 0
+        @engines = validate_engines!(engines || DEFAULT_ENGINES)
       end
 
       def call
-        matched = filtered_items
+        matched, excluded = partitioned_items
+        page(matched, excluded)
+      end
+
+      private
+
+      # Rows instead of one hash per route: the six key names were a third of every item's bytes.
+      def page(matched, excluded)
         {
-          items: matched[@offset, @limit] || [],
+          columns: COLUMNS,
+          rows: (matched[@offset, @limit] || []).map { |item| item.values_at(*COLUMN_KEYS) },
           matched: matched.size,
           limit: @limit,
-          offset: @offset
+          offset: @offset,
+          next_offset: next_offset_for(matched.size),
+          engines: @engines,
+          engines_excluded: excluded.size
         }
       end
 
-      private
+      # The MCP schema already enforces the enum; this guards the worker command against any other caller.
+      def validate_engines!(value)
+        return value if ENGINE_FILTERS.include?(value)
+
+        raise Coatepec::Error.new(:invalid_engines_filter,
+                                  "engines must be one of #{ENGINE_FILTERS.join(", ")}, got #{value.inspect}")
+      end
+
+      # Spelled out so a caller never has to infer a follow-up page from matched > limit.
+      # candidate > @offset guards limit 0, which would otherwise hand back the same offset forever.
+      def next_offset_for(matched_count)
+        candidate = @offset + @limit
+        candidate > @offset && candidate < matched_count ? candidate : nil
+      end
 
-      def filtered_items
+      # Query first, then the engine filter, so engines_excluded counts routes this exact query would have shown.
+      def partitioned_items
+        query_matches.partition { |item| engine_selected?(item) }
+      end
+
+      def query_matches
         items = all_items
         return items unless @query
 
@@ -35,19 +71,33 @@ module Coatepec
         items.select { |item| item.values.compact.any? { |v| v.to_s.downcase.include?(query_downcased) } }
       end
 
-      def all_items
-        self.class.rails_routes.map do |route|
-          defaults = route.defaults
-          {
-            name: route.name&.to_s,
-            verb: route.verb.to_s,
-            path: route.path.spec.to_s,
-            controller: defaults[:controller]&.to_s,
-            action: defaults[:action]&.to_s
-          }
+      # An engine's mount route has engine: nil -- it is an application route and stays under "exclude".
+      def engine_selected?(item)
+        case @engines
+        when "exclude" then item[:engine].nil?
+        when "only" then !item[:engine].nil?
+        else true
         end
       end
 
+      def all_items
+        RouteEntries.call(self.class.rails_routes).map { |entry| item_for(entry) }
+      end
+
+      # path comes off the entry: for an engine route it already carries the mount prefix.
+      def item_for(entry)
+        route = entry.route
+        defaults = route.defaults
+        {
+          name: route.name&.to_s,
+          verb: route.verb.to_s,
+          path: entry.path,
+          controller: defaults[:controller]&.to_s,
+          action: defaults[:action]&.to_s,
+          engine: entry.engine
+        }
+      end
+
       # Isolated as a class method purely so unit tests can stub it without
       # booting Rails -- Rails.application.routes.routes is otherwise only
       # reachable with a real, booted application.

data/lib/coatepec/mcp/response.rb

@@ -5,20 +5,17 @@ require "mcp"
 
 module Coatepec
   module MCP
-    # Builds the pretty-printed JSON `{ok: true, data:, meta:}` / `{ok: false,
-    # error:}` envelope that every Coatepec tool response wraps in a single
-    # text content block.
+    # Builds the compact JSON `{ok: true, data:, meta:}` / `{ok: false, error:}`
+    # envelope every tool response wraps in one text block.
     module Response
-      # Per-stream caps in Spec::Result bound stdout/stderr, but the fully
-      # assembled envelope (500 examples with long descriptions) can still
-      # exceed what an MCP client will accept, so cap it here -- the single
-      # place every tool response is built.
+      # Per-stream caps in Spec::Result bound stdout/stderr, but a fully assembled
+      # envelope can still exceed what an MCP client accepts, so cap it here.
       MAX_RESPONSE_BYTES = 1024 * 1024
 
       module_function
 
       def ok(data:, meta: {})
-        text = JSON.pretty_generate(ok: true, data: data, meta: meta)
+        text = generate(ok: true, data: data, meta: meta)
         return oversized_response if text.bytesize > MAX_RESPONSE_BYTES
 
         ::MCP::Tool::Response.new([{ type: "text", text: text }])
@@ -29,12 +26,22 @@ module Coatepec
           ok: false,
           error: { code: err.code.to_s, message: err.message, details: err.details }
         }
-        ::MCP::Tool::Response.new([{ type: "text", text: JSON.pretty_generate(payload) }], error: true)
+        ::MCP::Tool::Response.new([{ type: "text", text: generate(payload) }], error: true)
       end
 
       def oversized_response
         error(Coatepec::Error.new(:response_too_large, "Result exceeds the 1 MiB response limit"))
       end
+
+      # Compact by default: nothing downstream reads the indentation. COATEPEC_PRETTY=1 restores it for hand debugging.
+      def generate(payload)
+        ENV["COATEPEC_PRETTY"] == "1" ? JSON.pretty_generate(payload) : JSON.generate(payload)
+      end
+
+      # Per-call timing is the only per-call fact; project_root and environment live on rails_runtime_status.
+      def meta(started_at)
+        { duration_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round }
+      end
     end
   end
 end