activeadmin_mcp 0.0.3 → 0.1.0

data/lib/activeadmin_mcp/action_definition.rb

@@ -0,0 +1,183 @@
+module ActiveadminMcp
+  # One ActiveAdmin action that an application has opted in to MCP, normalised
+  # so the rest of the engine does not care whether it came from a
+  # member_action, a collection_action or a batch_action.
+  #
+  # Batch actions are the special case: ActiveAdmin already knows their input
+  # names and widget types via `form:`, so those become param types and the
+  # `mcp:` declaration only layers descriptions and hints on top.
+  class ActionDefinition
+    KINDS = %i[member collection batch].freeze
+
+    # JSON Schema scalar types an application may declare.
+    TYPES = %i[string integer number boolean array object].freeze
+
+    # ActiveAdmin batch action form widgets -> JSON Schema types.
+    FORM_TYPES = {
+      text: :string,
+      string: :string,
+      select: :string,
+      datepicker: :string,
+      number: :number,
+      checkbox: :boolean,
+    }.freeze
+
+    attr_reader :config, :action, :kind, :errors
+
+    def self.build(config:, action:, kind:)
+      options = action.mcp_options
+      return nil unless options.is_a?(Hash)
+
+      new(config: config, action: action, kind: kind, options: options)
+    end
+
+    def initialize(config:, action:, kind:, options:)
+      @config = config
+      @action = action
+      @kind = kind
+      @options = options
+      @errors = []
+      validate!
+    end
+
+    def action_name
+      (@kind == :batch ? @action.sym : @action.name).to_sym
+    end
+
+    def resource_name
+      @config.resource_class.name
+    end
+
+    def tool_name
+      "#{resource_name.underscore.tr('/', '_')}_#{action_name}"
+    end
+
+    def description
+      @options[:description]
+    end
+
+    def permission
+      @options[:permission]
+    end
+
+    def http_verb
+      return :post if @kind == :batch
+
+      Array(@action.http_verb).first&.to_sym || :get
+    end
+
+    # Declared params, with batch actions inheriting their types from the
+    # ActiveAdmin `form:` hash underneath anything the declaration says.
+    def params
+      @params ||= inherited_params.merge(declared_params) do |_key, inherited, declared|
+        inherited.merge(declared)
+      end
+    end
+
+    def valid?
+      @errors.empty?
+    end
+
+    private
+
+    def declared_params
+      raw = @options[:params]
+      return {} unless raw.is_a?(Hash)
+
+      raw.each_with_object({}) { |(name, spec), acc| acc[name.to_sym] = spec }
+    end
+
+    def inherited_params
+      return {} unless @kind == :batch
+      return {} unless @action.respond_to?(:inputs)
+
+      form = @action.inputs
+      return {} unless form.is_a?(Hash)
+
+      form.each_with_object({}) do |(name, widget), acc|
+        acc[name.to_sym] = { type: FORM_TYPES.fetch(widget.to_sym, :string) }
+      end
+    end
+
+    def validate!
+      @errors << "#{tool_name}: mcp declaration needs a description" if description.to_s.strip.empty?
+      @errors << "#{tool_name}: unknown kind #{@kind}" unless KINDS.include?(@kind)
+
+      reserved = reserved_param_name
+      form_keys = batch_form_keys
+      params.each do |name, spec|
+        unless spec.is_a?(Hash)
+          @errors << "#{tool_name}: param #{name} must be a Hash"
+          next
+        end
+
+        @errors << "#{tool_name}: param #{name} is reserved" if name == reserved
+
+        # ActiveAdmin's own batch_action controller method slices the submitted
+        # inputs down to the keys of the batch action's `inputs` (its `form:`
+        # hash) before calling the block: `inputs.slice(*valid_keys)`. When
+        # there is no `form:` at all, `inputs` is nil, so `valid_keys` is nil,
+        # and `slice(*nil)` is `slice()` — which drops EVERY input, not none.
+        # So a form-less batch action permits nothing, and any declared param
+        # is a declaration error. A Proc form is evaluated by ActiveAdmin in
+        # controller context (MethodOrProcHelper.render_in_context), so we
+        # cannot know its keys here and skip the check rather than guess.
+        case form_keys
+        when :unknown_proc_form
+          nil
+        when :no_form
+          @errors << "#{tool_name}: param #{name} cannot be declared because this batch action " \
+                     "has no form: hash, so ActiveAdmin drops every input before the action runs"
+        when nil
+          nil # not a batch action, or no `inputs` method at all: no rule applies
+        else
+          unless form_keys.include?(name)
+            @errors << "#{tool_name}: param #{name} is not among the batch action's declared " \
+                       "form: keys, so ActiveAdmin would drop it before the action runs"
+          end
+        end
+
+        type = spec[:type]
+        @errors << "#{tool_name}: param #{name} has unknown type #{type}" if type && !TYPES.include?(type.to_sym)
+      end
+
+      @errors << "#{tool_name}: permission must be callable" if permission && !permission.respond_to?(:call)
+    end
+
+    # The permitted param keys for a batch action's `inputs` (its `form:`
+    # hash), distinguishing three outcomes the caller must treat differently:
+    #
+    # * not a batch action, or the action has no `inputs` method at all ->
+    #   nil, the batch form: rule does not apply.
+    # * `inputs` is a Hash -> its keys, the permitted set ActiveAdmin will
+    #   slice submitted params down to.
+    # * `inputs` is nil (no `form:` declared) -> :no_form. ActiveAdmin still
+    #   slices, against a nil key list, which yields an EMPTY permitted set
+    #   (`hash.slice(*nil)` is `hash.slice()` == `{}`), so every declared
+    #   param here is a declaration error.
+    # * `inputs` is a Proc -> :unknown_proc_form. ActiveAdmin evaluates it in
+    #   controller context via `render_in_context`, so we cannot know its
+    #   keys at declaration time. We skip the check rather than guess.
+    def batch_form_keys
+      return nil unless @kind == :batch
+      return nil unless @action.respond_to?(:inputs)
+
+      form = @action.inputs
+      return form.keys.map(&:to_sym) if form.is_a?(Hash)
+      return :unknown_proc_form if form.is_a?(Proc)
+
+      :no_form
+    end
+
+    def reserved_param_name
+      case @kind
+      when :member
+        :id
+      when :batch
+        :ids
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/activeadmin_mcp/action_params.rb

@@ -0,0 +1,78 @@
+module ActiveadminMcp
+  # Validates and coerces a tool call's arguments against its ActionDefinition
+  # before anything reaches the controller.
+  #
+  # Undeclared arguments are dropped rather than passed through: the declaration
+  # is the contract, and forwarding unknown keys into a controller action would
+  # let a client reach parameters the application never opted in to.
+  class ActionParams
+    class CoercionError < StandardError; end
+
+    def initialize(definition)
+      @definition = definition
+    end
+
+    def call(arguments)
+      arguments ||= {}
+      result = { params: {} }
+
+      case @definition.kind
+      when :member
+        id = arguments["id"]
+        return { error: "id is required" } if id.nil? || id.to_s.empty?
+
+        result[:record_id] = id.to_s
+      when :batch
+        ids = Array(arguments["ids"]).reject { |id| id.to_s.empty? }
+        return { error: "ids is required" } if ids.empty?
+
+        result[:record_ids] = ids.map(&:to_s)
+      end
+
+      @definition.params.each do |name, spec|
+        value = arguments[name.to_s]
+
+        if value.nil? || value.to_s.empty?
+          return { error: "#{name} is required" } if spec[:required]
+
+          next
+        end
+
+        begin
+          coerced_value = coerce(value, spec[:type])
+        rescue CoercionError
+          return { error: "#{name} must be a #{spec[:type]}" }
+        end
+
+        if spec[:enum].is_a?(Array) && !spec[:enum].include?(coerced_value)
+          return { error: "#{name} must be one of: #{spec[:enum].join(', ')}" }
+        end
+
+        result[:params][name] = coerced_value
+      end
+
+      result
+    end
+
+    private
+
+    def coerce(value, type)
+      case type&.to_sym
+      when :integer
+        Integer(value)
+      when :number
+        Float(value)
+      when :boolean
+        case value
+        when true, "true", "1", 1 then true
+        when false, "false", "0", 0 then false
+        else raise CoercionError, "invalid boolean value"
+        end
+      else
+        value
+      end
+    rescue ArgumentError, TypeError => e
+      raise CoercionError, e.message
+    end
+  end
+end

data/lib/activeadmin_mcp/action_runner.rb

@@ -0,0 +1,163 @@
+module ActiveadminMcp
+  # Runs one opted-in ActiveAdmin action for an MCP client.
+  #
+  # Two gates gate every call, in this order, both before anything is
+  # dispatched:
+  #
+  #   1. ActiveAdmin's own authorization adapter - the same check `query` and
+  #      `update` make today.
+  #   2. The action's optional `permission:` proc.
+  #   3. For batch actions only, the submitted ids are run back through the
+  #      adapter's scope_collection, since gate 1 could only authorize the
+  #      resource class.
+  #
+  # The proc can only ever narrow access. A record the MCP user cannot touch
+  # stays untouchable whether or not a proc is declared, and the controller's
+  # own before_action chain runs again during dispatch regardless.
+  class ActionRunner
+    def initialize(definition:, current_user:)
+      @definition = definition
+      @current_user = current_user
+    end
+
+    def call(arguments)
+      parsed = ActionParams.new(@definition).call(arguments)
+      return parsed if parsed[:error]
+
+      record = find_record(parsed[:record_id])
+      return { error: "Record not found: #{@definition.resource_name}##{parsed[:record_id]}" } if record_missing?(record, parsed)
+
+      subject = record || @definition.config.resource_class
+      return { error: "Not authorized to run #{@definition.tool_name}" } unless authorized?(subject)
+
+      dispatcher = ControllerDispatcher.new(config: @definition.config, current_user: @current_user)
+
+      refusal = permission_refusal(dispatcher, record, parsed)
+      return { error: refusal } if refusal
+
+      out_of_scope = unauthorized_batch_ids(parsed)
+      return { error: out_of_scope } if out_of_scope
+
+      dispatcher.call(
+        action: dispatch_action,
+        path: path_for(record, parsed),
+        verb: @definition.http_verb,
+        params: dispatch_params(parsed),
+        path_params: path_params(parsed)
+      )
+    end
+
+    private
+
+    def find_record(id)
+      return nil unless id
+
+      @definition.config.resource_class.find_by(id: id)
+    end
+
+    def record_missing?(record, parsed)
+      parsed.key?(:record_id) && record.nil?
+    end
+
+    def authorized?(subject)
+      Authorization.for(@definition.config, @current_user)
+                   .authorized?(@definition.action_name, subject)
+    end
+
+    # Evaluated the way ActiveAdmin evaluates batch action `:if` procs, so
+    # current_admin_user, can? and the usual admin helpers are in scope.
+    # Returns a refusal message, or nil when the proc allows the call.
+    def permission_refusal(dispatcher, record, parsed)
+      permission = @definition.permission
+      return nil unless permission
+
+      controller = dispatcher.controller_with_mcp_user
+      outcome = ::MethodOrProcHelper.render_in_context(controller, permission, *permission_args(permission, record, parsed))
+
+      return outcome if outcome.is_a?(String)
+      return nil if outcome
+
+      "Not permitted to run #{@definition.tool_name}"
+    rescue StandardError => e
+      # Keep the detail server-side: the message can carry SQL, paths and other
+      # internals the MCP client has no business seeing.
+      warn("[activeadmin_mcp] permission proc for #{@definition.tool_name} raised #{e.class}: #{e.message}")
+      "Permission check failed for #{@definition.tool_name}"
+    end
+
+    # Gate 1 can only authorize the resource class for a batch action, because
+    # there is no single record. That leaves the submitted ids unchecked, so a
+    # client could name records the adapter's scope_collection excludes. Run the
+    # ids back through the scope and refuse the whole call if any falls outside
+    # it — narrowing silently would let a client believe it acted on records it
+    # never touched.
+    def unauthorized_batch_ids(parsed)
+      return nil unless @definition.kind == :batch
+
+      ids = Array(parsed[:record_ids])
+      return nil if ids.empty?
+
+      klass = @definition.config.resource_class
+      key = klass.primary_key
+      scoped = Authorization.for(@definition.config, @current_user)
+                            .scope_collection(klass.where(key => ids), @definition.action_name)
+      permitted = scoped.pluck(key).map(&:to_s)
+      refused = ids - permitted
+      return nil if refused.empty?
+
+      "Not authorized to run #{@definition.tool_name} on #{@definition.resource_name} " \
+        "#{refused.join(', ')} (not found, or outside your permitted scope)"
+    rescue StandardError => e
+      warn("[activeadmin_mcp] scoping batch ids for #{@definition.tool_name} raised #{e.class}: #{e.message}")
+      "Not authorized to run #{@definition.tool_name}"
+    end
+
+    # render_in_context instance_execs the proc AND passes args along, so a
+    # zero-arity lambda would raise ArgumentError if we always handed it a
+    # record. Match what the proc actually accepts.
+    def permission_args(permission, record, parsed)
+      return [] if permission.respond_to?(:arity) && permission.arity.zero?
+
+      case @definition.kind
+      when :member then [record]
+      when :batch then [parsed[:record_ids]]
+      else []
+      end
+    end
+
+    # Batch actions enter through ActiveAdmin's own batch_action controller
+    # method, so its slicing of inputs to the declared form: keys applies
+    # exactly as it does in the admin UI.
+    def dispatch_action
+      @definition.kind == :batch ? :batch_action : @definition.action_name
+    end
+
+    def dispatch_params(parsed)
+      return parsed[:params] unless @definition.kind == :batch
+
+      {
+        batch_action: @definition.action_name.to_s,
+        collection_selection: parsed[:record_ids],
+        batch_action_inputs: JSON.generate(parsed[:params]),
+      }
+    end
+
+    def path_params(parsed)
+      parsed[:record_id] ? { id: parsed[:record_id] } : {}
+    end
+
+    def path_for(record, parsed)
+      config = @definition.config
+
+      case @definition.kind
+      when :member then config.route_member_action_path(@definition.action_name, record)
+      # RouteBuilder#batch_action_path calls `.permit!` on the params it is
+      # given, which a plain Hash (its own default argument) does not
+      # respond to. Pass ActionController::Parameters explicitly to avoid
+      # tripping over ActiveAdmin's own default.
+      when :batch then config.route_batch_action_path(ActionController::Parameters.new)
+      else config.route_collection_path
+      end
+    end
+  end
+end

data/lib/activeadmin_mcp/action_schema.rb

@@ -0,0 +1,66 @@
+module ActiveadminMcp
+  # Builds the JSON Schema an MCP client sees for one opted-in action.
+  #
+  # The binding/advisory split matters: a static `enum:` is enforced before we
+  # dispatch, while `suggestions:` is only ever a hint to the model. A
+  # suggestions proc runs application code on every tools/list call, so it is
+  # wrapped — a raising proc costs its suggestions, never the whole listing.
+  class ActionSchema
+    def initialize(definition)
+      @definition = definition
+    end
+
+    def to_h
+      properties = record_properties
+      required = properties.keys.map(&:to_s)
+
+      @definition.params.each do |name, spec|
+        properties[name] = property_for(spec)
+        required << name.to_s if spec[:required]
+      end
+
+      { type: "object", properties: properties, required: required.uniq }
+    end
+
+    private
+
+    def record_properties
+      case @definition.kind
+      when :member
+        { id: { type: "string", description: "Primary key of the record to act on" } }
+      when :batch
+        { ids: { type: "array", items: { type: "string" },
+                 description: "Primary keys of the records to act on" } }
+      else
+        {}
+      end
+    end
+
+    def property_for(spec)
+      property = { type: (spec[:type] || :string).to_s }
+
+      descriptions = []
+      descriptions << spec[:hint] if spec[:hint]
+
+      property[:enum] = spec[:enum] if spec[:enum].is_a?(Array)
+
+      suggestions = resolve_suggestions(spec[:suggestions])
+      if suggestions&.any?
+        property[:examples] = suggestions
+        descriptions << "Suggested values: #{suggestions.join(', ')}"
+      end
+
+      property[:description] = descriptions.join(". ") unless descriptions.empty?
+      property
+    end
+
+    # Advisory only. A proc that blows up must not take the tool listing with it.
+    def resolve_suggestions(suggestions)
+      return nil unless suggestions.respond_to?(:call)
+
+      Array(suggestions.call)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/activeadmin_mcp/active_admin_ext.rb

@@ -0,0 +1,39 @@
+module ActiveadminMcp
+  # Every patch this gem applies to ActiveAdmin lives in this one file, so the
+  # coupling has a single place to check when ActiveAdmin is upgraded.
+  #
+  # ActiveAdmin stores an action's option hash but exposes only the keys it
+  # uses itself (:method, :title, :form, :if, ...). MCP metadata is declared as
+  # an extra `mcp:` key on that same hash, which ActiveAdmin carries through
+  # untouched, so all we need is a reader to get it back out.
+  module ActiveAdminExt
+    module ActionOptions
+      def mcp_options
+        options = instance_variable_get(:@options)
+        options.is_a?(Hash) ? options[:mcp] : nil
+      end
+    end
+
+    # ActiveAdmin::BatchAction only exists once ActiveAdmin's before_load hooks
+    # have run, so this is called from ActiveAdmin.after_load rather than at
+    # require time.
+    def self.apply!
+      unless applicable?
+        # Without these readers every opted-in action silently vanishes from
+        # tools/list, because ActionCatalog can no longer see an mcp: option
+        # anywhere. Say so rather than shipping a feature that is quietly off.
+        warn("[activeadmin_mcp] ActiveAdmin::ControllerAction / ActiveAdmin::BatchAction not found: " \
+             "MCP action options cannot be read, so no opted-in actions will be exposed as tools.")
+        return false
+      end
+
+      ::ActiveAdmin::ControllerAction.include(ActionOptions)
+      ::ActiveAdmin::BatchAction.include(ActionOptions)
+      true
+    end
+
+    def self.applicable?
+      defined?(::ActiveAdmin::ControllerAction) && defined?(::ActiveAdmin::BatchAction) ? true : false
+    end
+  end
+end

data/lib/activeadmin_mcp/authorization.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module ActiveadminMcp
   # Applies a resource's ActiveAdmin authorization adapter to MCP tool calls, so
   # reads, listings and writes obey the same rules as the admin UI.

data/lib/activeadmin_mcp/configuration.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module ActiveadminMcp
   class Configuration
     MOUNT_STRATEGIES = %i[prepend append none].freeze

data/lib/activeadmin_mcp/controller_dispatcher.rb

@@ -0,0 +1,138 @@
+module ActiveadminMcp
+  # Runs a real ActiveAdmin controller action out of band, so an MCP tool call
+  # goes through the same before_action chain, authorization and callbacks as a
+  # click in the admin UI.
+  #
+  # We synthesize the request rather than route one. Routing would mean issuing
+  # a second HTTP request against the app, which would have to authenticate as
+  # the MCP user by forging an admin session — a back door this gem should not
+  # have. Building the request by hand lets us inject the already-authenticated
+  # MCP user directly onto the controller instead.
+  class ControllerDispatcher
+    def initialize(config:, current_user:)
+      @config = config
+      @current_user = current_user
+    end
+
+    # Yields the controller once it has finished processing, so a caller that
+    # needs more than the redirect — the record a write built or loaded, and
+    # its validation errors — can read it off the controller itself. The block
+    # runs whether processing succeeded or raised, because a write that fails
+    # its validations re-renders the form, and that render is exactly the kind
+    # of thing a synthesized request can blow up on. Its return value is
+    # ignored and an exception inside it never reaches the caller.
+    def call(action:, path:, verb: :get, params: {}, path_params: {})
+      controller = controller_with_mcp_user
+      request = build_request(path: path, verb: verb, params: params, action: action, path_params: path_params)
+      response = ActionDispatch::Response.new
+
+      controller.set_request!(request)
+      controller.set_response!(response)
+
+      begin
+        controller.process(action)
+        capture(request, response)
+      rescue StandardError => e
+        # The exception text can carry internals — SQL fragments, table names,
+        # file paths. It belongs in the application's log, not in a tool result
+        # that goes to an MCP client.
+        warn("[activeadmin_mcp] #{@config.resource_class.name}##{action} raised #{e.class}: #{e.message}")
+        { error: "#{@config.resource_class.name}##{action} failed" }
+      ensure
+        inspect_controller(controller, action) { |processed| yield processed } if block_given?
+      end
+    end
+
+    # A controller instance for this resource with the MCP user injected, ready
+    # either to process a request or to serve as the evaluation context for an
+    # action's `permission:` proc. Public because listing-time permission checks
+    # need exactly the same context a dispatched call gets.
+    def controller_with_mcp_user
+      user = @current_user
+      controller = @config.controller.new
+
+      current_user_methods.each do |method_name|
+        controller.define_singleton_method(method_name) { user }
+      end
+
+      # The namespace's authentication_method (typically Devise's
+      # authenticate_admin_user!) would redirect us to a login page. The MCP
+      # request has already authenticated by bearer token, so it is a no-op
+      # here — this does NOT skip authorization, which still runs in full.
+      auth_method = @config.namespace.authentication_method
+      controller.define_singleton_method(auth_method) { true } if auth_method
+
+      # The synthesized request carries no session-bound CSRF token, so
+      # Rails' own forgery protection would refuse every non-GET action
+      # (member actions declared `method: :post`, and every batch action,
+      # which always dispatches as one). The MCP request has already
+      # authenticated by bearer token; this does NOT skip authorization,
+      # which still runs in full.
+      controller.define_singleton_method(:verified_request?) { true }
+
+      controller
+    end
+
+    private
+
+    # An application can point ActiveadminMcp at one current-user method and the
+    # ActiveAdmin namespace at another. Stub both, so an action body calling
+    # either gets the MCP user rather than nil. uniq keeps us from defining the
+    # same singleton method twice when they agree.
+    def current_user_methods
+      namespace_method = @config.namespace.current_user_method if @config.namespace.respond_to?(:current_user_method)
+
+      [
+        ActiveadminMcp.config.current_user_method,
+        namespace_method,
+        :current_active_admin_user,
+      ].select { |name| name.respond_to?(:to_sym) }.map(&:to_sym).uniq
+    end
+
+    def inspect_controller(controller, action)
+      yield controller
+    rescue StandardError => e
+      warn("[activeadmin_mcp] inspecting #{@config.resource_class.name}##{action} raised #{e.class}: #{e.message}")
+    end
+
+    def build_request(path:, verb:, params:, action:, path_params:)
+      env = Rack::MockRequest.env_for(
+        path,
+        method: verb.to_s.upcase,
+        params: params.transform_keys(&:to_s)
+      )
+      # Flash needs somewhere to live; without a session the action raises.
+      env["rack.session"] = {}
+      env["action_dispatch.request.path_parameters"] =
+        { controller: controller_path, action: action.to_s }.merge(path_params)
+
+      ActionDispatch::Request.new(env)
+    end
+
+    def controller_path
+      @config.controller.name.underscore.sub(/_controller\z/, "")
+    end
+
+    def capture(request, response)
+      result = { status: response.status }
+
+      if response.redirect?
+        result[:redirect_to] = response.location
+      else
+        # Deliberately not the body: admin HTML is large and almost entirely
+        # chrome, and would swamp the client's context for no benefit.
+        result[:rendered] = true
+      end
+
+      flash = extract_flash(request)
+      result[:flash] = flash if flash&.any?
+      result
+    end
+
+    def extract_flash(request)
+      request.flash.to_hash
+    rescue StandardError
+      nil
+    end
+  end
+end