activeadmin_mcp 0.0.4 → 0.2.0

data/lib/activeadmin_mcp/action_definition.rb

@@ -0,0 +1,297 @@
+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
+
+    # MCP tool names are referenced by clients as identifiers, so keep them to
+    # what every client can quote without escaping.
+    TOOL_NAME = /\A[a-z0-9][a-z0-9_-]*\z/
+
+    # 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:, current_user: nil)
+      options = action.mcp_options
+      return nil unless options.is_a?(Hash)
+
+      new(config: config, action: action, kind: kind, options: options, current_user: current_user)
+    end
+
+    def initialize(config:, action:, kind:, options:, current_user: nil)
+      @config = config
+      @action = action
+      @kind = kind
+      @options = options
+      @current_user = current_user
+      @errors = []
+      validate!
+    end
+
+    def action_name
+      (@kind == :batch ? @action.sym : @action.name).to_sym
+    end
+
+    def resource_name
+      @config.resource_class.name
+    end
+
+    # A declaration may choose its own name: an action shared by a concern can
+    # need a different one on each resource, and an action exposed once per
+    # verb needs a distinct name per tool.
+    def tool_name
+      declared = @options[:tool_name]
+      return declared.to_s if declared
+
+      derived_tool_name
+    end
+
+    # Squeezed down to the characters a tool name may carry, because an action
+    # name is not always tame: ActiveAdmin derives a batch action's symbol from
+    # a String title and can leave punctuation in it. A resource may still
+    # choose its own name with tool_name:, which is validated rather than
+    # squeezed, since a name someone typed deliberately should not be silently
+    # rewritten.
+    def derived_tool_name
+      "#{resource_name.underscore.tr('/', '_')}_#{action_name}"
+        .downcase
+        .gsub(/[^a-z0-9_-]+/, "_")
+        .squeeze("_")
+        .delete_suffix("_")
+    end
+
+    def description
+      @options[:description]
+    end
+
+    def permission
+      @options[:permission]
+    end
+
+    # ActiveAdmin's own `:if` proc on a batch action, which decides whether the
+    # admin UI offers it at all. Returned rather than evaluated: like a
+    # `permission:` proc it belongs in controller context, which only the
+    # caller can build.
+    def display_if
+      return nil unless @kind == :batch
+      return nil unless @action.respond_to?(:display_if_block)
+
+      @action.display_if_block
+    end
+
+    # ActiveAdmin always posts a batch action, whatever a declaration says.
+    # Otherwise a declaration may pick among the verbs the action answers to —
+    # `method: [:post, :delete]` is one action with two meanings, and without
+    # this only the first would ever be reachable.
+    def http_verb
+      return :post if @kind == :batch
+
+      declared = @options[:http_verb]&.to_sym
+      return declared if declared
+
+      action_verbs.first || :get
+    end
+
+    def action_verbs
+      Array(@action.http_verb).compact.map(&:to_sym)
+    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
+
+      resolved_form.each_with_object({}) do |(name, widget), acc|
+        acc[name.to_sym] = { type: form_type(widget) }
+      end
+    end
+
+    # A form: entry is usually a widget name, but ActiveAdmin also accepts an
+    # array of options, which it renders as a select. There is no type to read
+    # off that, and its values are not treated as a binding enum: they were
+    # resolved once, at listing time, and a declaration wanting to offer them
+    # should say so with suggestions:, which is advisory by design.
+    def form_type(widget)
+      return :string unless widget.respond_to?(:to_sym)
+
+      FORM_TYPES.fetch(widget.to_sym, :string)
+    end
+
+    # ActiveAdmin lets `form:` be a proc and evaluates it in controller context
+    # at render time, which is the only way a concern shared across resources
+    # can vary its options. Evaluated here the same way, so a proc form still
+    # contributes its param types.
+    #
+    # Deliberately lazy: this runs application code, so it must not happen
+    # while the catalog is merely being built, before the caller has checked
+    # the user is authorized for the action at all. Same posture as
+    # `suggestions:`.
+    def resolved_form
+      return @resolved_form if defined?(@resolved_form)
+
+      @resolved_form = resolve_form || {}
+    end
+
+    def resolve_form
+      return nil unless @action.respond_to?(:inputs)
+
+      form = @action.inputs
+      return form if form.is_a?(Hash)
+      return nil unless form.is_a?(Proc)
+
+      evaluate_form(form)
+    end
+
+    def evaluate_form(form)
+      controller = ControllerDispatcher.new(config: @config, current_user: @current_user)
+                                       .controller_with_mcp_user
+      evaluated = ::MethodOrProcHelper.render_in_context(controller, form)
+      evaluated.is_a?(Hash) ? evaluated : nil
+    rescue StandardError => e
+      # The tool keeps whatever the declaration said; it just inherits nothing.
+      warn("[activeadmin_mcp] evaluating the #{tool_name} form: proc raised #{e.class}: #{e.message}")
+      nil
+    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
+      # Declared params only. Inherited ones come from ActiveAdmin's own form:
+      # hash and are always well formed, and reading them would mean evaluating
+      # a proc form here — the one place it must not happen.
+      declared_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)
+
+      validate_tool_name!
+      validate_http_verb!
+    end
+
+    def validate_tool_name!
+      return if tool_name.match?(TOOL_NAME)
+
+      @errors << "#{tool_name}: tool_name must match #{TOOL_NAME.source}"
+    end
+
+    # Dispatching a verb the action never declared would reach nothing, or
+    # worse, the wrong branch of the action's own body.
+    def validate_http_verb!
+      declared = @options[:http_verb]&.to_sym
+      return if declared.nil? || @kind == :batch
+
+      verbs = action_verbs
+      return if verbs.empty? || verbs.include?(declared)
+
+      @errors << "#{tool_name}: http_verb #{declared} is not one the action answers to (#{verbs.join(', ')})"
+    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,184 @@
+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)
+
+      unavailable = display_refusal(dispatcher)
+      return { error: unavailable } if unavailable
+
+      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
+
+    # ActiveAdmin's `:if` proc decides whether the admin UI offers a batch
+    # action at all, but ActiveAdmin only consults it when rendering — a
+    # dispatched request reaches the action regardless. Consulting it here too
+    # keeps MCP from becoming the way round a gate the admin enforces by not
+    # offering the button.
+    def display_refusal(dispatcher)
+      block = @definition.display_if
+      return nil unless block
+
+      controller = dispatcher.controller_with_mcp_user
+      return nil if ::MethodOrProcHelper.render_in_context(controller, block)
+
+      "#{@definition.tool_name} is not available to you"
+    rescue StandardError => e
+      warn("[activeadmin_mcp] if: proc for #{@definition.tool_name} raised #{e.class}: #{e.message}")
+      "#{@definition.tool_name} is not available to you"
+    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