activeadmin_mcp 0.0.4 → 0.1.0

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

data/lib/activeadmin_mcp/engine.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module ActiveadminMcp
   class Engine < ::Rails::Engine
     isolate_namespace ActiveadminMcp
@@ -16,5 +14,11 @@ module ActiveadminMcp
         end
       end
     end
+
+    initializer "activeadmin_mcp.active_admin_ext" do
+      ActiveSupport.on_load(:after_initialize) do
+        ActiveAdmin.after_load { ActiveadminMcp::ActiveAdminExt.apply! } if defined?(::ActiveAdmin)
+      end
+    end
   end
 end

data/lib/activeadmin_mcp/form_description.rb

@@ -0,0 +1,149 @@
+module ActiveadminMcp
+  # Describes the form behind a resource's create or update action richly
+  # enough that an MCP client stops guessing field types and allowed values
+  # from column names.
+  #
+  # The description is read from the resource's own `form do ... end` block
+  # when it declares one. When it does not, ActiveAdmin renders a bare
+  # `f.inputs` that Formtastic only expands at render time — there is nothing
+  # to introspect — so the description is derived from the resource's
+  # `permit_params` instead, which is what `create` and `update` enforce
+  # anyway. The payload says which of the two it is.
+  #
+  # Either way each field is annotated from the model: the column type it is
+  # stored in, and whether the model validates its presence.
+  class FormDescription
+    WRITE_ACTIONS = { "new" => :create, "edit" => :update }.freeze
+    REFUSALS = { create: "is not creatable", update: "is not editable" }.freeze
+
+    def initialize(resource:, current_user:)
+      @resource = resource
+      @current_user = current_user
+      @config = resource[:config]
+    end
+
+    def call(action: "new")
+      write_action = WRITE_ACTIONS[action.to_s]
+      return error(%(Unknown form action: #{action} (expected "new" or "edit"))) unless write_action
+
+      refusal = write_refusal(write_action)
+      return refusal if refusal
+
+      declared = declared_inputs
+      return describe(action, "form", declared) if declared
+
+      permitted = permitted_inputs
+      return permit_params_refusal unless permitted
+
+      describe(action, "permit_params", permitted)
+    end
+
+    private
+
+    def describe(action, source, inputs)
+      fields, groups = inputs.partition { |input| !input.key?(:nested) }
+
+      {
+        resource: @resource[:name],
+        action: action.to_s,
+        source: source,
+        attributes: fields.map { |field| attribute(field) },
+        nested: groups.map { |group| nested_group(group) },
+      }
+    end
+
+    # An association's own fields are reported as the form declared them and
+    # are not annotated from a model: they belong to the associated record, not
+    # to the one being written.
+    def nested_group(group)
+      { name: group[:name].to_s, attributes: group[:nested].map { |field| stringify(field) } }
+    end
+
+    def attribute(field)
+      described = stringify(field)
+      described[:type] = column_type(field[:name]) if column_type(field[:name])
+      described[:required] = true if !described.key?(:required) && presence_validated?(field[:name])
+      described
+    end
+
+    def stringify(field)
+      field.each_with_object({}) do |(key, value), described|
+        described[key] = value.is_a?(Symbol) ? value.to_s : value
+      end
+    end
+
+    def column_type(name)
+      @resource[:model].columns_hash[name.to_s]&.type&.to_s
+    end
+
+    def presence_validated?(name)
+      @resource[:model].validators_on(name).any? do |validator|
+        validator.is_a?(ActiveModel::Validations::PresenceValidator)
+      end
+    rescue StandardError
+      false
+    end
+
+    def declared_inputs
+      block = form_block
+      return nil unless block
+
+      FormFieldCollector.new.collect(&block)
+    rescue StandardError => e
+      # A form block that will not run outside a request describes nothing, but
+      # the resource's permitted params still can.
+      warn("[activeadmin_mcp] reading the #{@resource[:name]} form raised #{e.class}: #{e.message}")
+      nil
+    end
+
+    def form_block
+      return nil unless @config.respond_to?(:page_presenters)
+
+      @config.page_presenters[:form]&.block
+    end
+
+    # ActiveAdmin stores no list of the params it permits, only a method that
+    # filters against them, so the permitted names are recovered by offering it
+    # every column the model has and seeing which survive. A resource that
+    # never declared permit_params has no such method to answer, and is
+    # reported as unwritable rather than described.
+    def permitted_inputs
+      names = permitted_names
+      return nil unless names
+
+      names.map { |name| { name: name } }
+    end
+
+    def permitted_names
+      param_key = @config.param_key.to_sym
+      controller = @config.controller.new
+      controller.params = ActionController::Parameters.new(
+        param_key => @resource[:model].column_names.index_with { nil }
+      )
+      permitted = controller.send(:permitted_params)
+      scoped = permitted && permitted[param_key]
+      scoped&.keys&.map(&:to_sym)
+    rescue StandardError
+      nil
+    end
+
+    def write_refusal(write_action)
+      unless @config.defined_actions.include?(write_action)
+        return error("Resource #{REFUSALS[write_action]}: #{@resource[:name]}")
+      end
+
+      return if Authorization.for(@config, @current_user)
+                             .authorized?(write_action, @config.resource_class)
+
+      error("Not authorized to #{write_action} #{@resource[:name]}")
+    end
+
+    def permit_params_refusal
+      error("Resource declares no permit_params, so nothing may be written: #{@resource[:name]}")
+    end
+
+    def error(message)
+      { error: message }
+    end
+  end
+end