activeadmin_mcp 0.0.4 → 0.2.0

data/lib/activeadmin_mcp/active_admin_ext.rb

@@ -0,0 +1,83 @@
+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
+
+    # Records MCP annotations declared against a resource for actions it does
+    # not declare inline — typically because a shared concern declares them,
+    # and one description could not suit every resource that includes it.
+    #
+    # They live on the resource config rather than on the action, so a
+    # declaration may appear above or below the `include` that brings the
+    # action in, and so they are discarded with the config when ActiveAdmin
+    # reloads in development.
+    module ResourceAnnotations
+      def mcp_annotations
+        @mcp_annotations ||= []
+      end
+    end
+
+    module McpActionDsl
+      # Annotates an already-declared action so it is exposed as an MCP tool.
+      # Never declares the action itself: naming one that does not exist is
+      # reported when the catalog is built, not here, because the action may
+      # legitimately be declared after this call.
+      def mcp_action(name, kind: nil, **options)
+        config.mcp_annotations << {
+          action_name: name.to_sym,
+          kind: kind&.to_sym,
+          options: options,
+        }
+      end
+    end
+
+    # Installed separately from, and earlier than, apply!. A registration block
+    # calls mcp_action while ActiveAdmin loads its resources, which is before
+    # ActiveAdmin.after_load fires — so waiting for that hook would mean the
+    # method did not exist at the only moment anybody calls it.
+    #
+    # ActiveAdmin::Resource and ActiveAdmin::ResourceDSL both exist as soon as
+    # ActiveAdmin is required, so there is nothing to wait for. Idempotent:
+    # including a module twice is a no-op.
+    def self.apply_dsl!
+      return false unless defined?(::ActiveAdmin::Resource) && defined?(::ActiveAdmin::ResourceDSL)
+
+      ::ActiveAdmin::Resource.include(ResourceAnnotations)
+      ::ActiveAdmin::ResourceDSL.include(McpActionDsl)
+      true
+    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,17 @@ module ActiveadminMcp
         end
       end
     end
+
+    initializer "activeadmin_mcp.active_admin_ext" do
+      ActiveSupport.on_load(:after_initialize) do
+        next unless defined?(::ActiveAdmin)
+
+        # The DSL has to exist before ActiveAdmin loads the registrations that
+        # call it; the option readers only have to exist before the catalog is
+        # read, and ActiveAdmin::BatchAction does not exist until load time.
+        ActiveadminMcp::ActiveAdminExt.apply_dsl!
+        ActiveAdmin.after_load { ActiveadminMcp::ActiveAdminExt.apply! }
+      end
+    end
   end
 end

data/lib/activeadmin_mcp/form_description.rb

@@ -0,0 +1,157 @@
+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
+
+      # An empty result is not the same as no form block, but it means the same
+      # thing here: ActiveAdmin's own default form is a bare `f.inputs` that
+      # Formtastic expands only at render time, so a block written that way has
+      # nothing in it to read and the permitted params are all there is.
+      declared = declared_inputs
+      return describe(action, "form", declared) if declared&.any?
+
+      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
+
+    # The controller carries the MCP user: ActiveAdmin instance_execs a
+    # block-form permit_params on it, so a block reading current_admin_user
+    # raises on a bare instance and the resource looks unwritable.
+    def permitted_names
+      param_key = @config.param_key.to_sym
+      controller = ControllerDispatcher.new(config: @config, current_user: @current_user)
+                                       .controller_with_mcp_user
+      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

data/lib/activeadmin_mcp/form_field_collector.rb

@@ -1,39 +1,54 @@
-# frozen_string_literal: true
-
 module ActiveadminMcp
-  # Records the field names declared by an ActiveAdmin `form do ... end` block.
+  # Reads an ActiveAdmin `form do ... end` block and reports what each input
+  # tells a client about how to fill the field in.
   #
   # ActiveAdmin form blocks are arbitrary Formtastic DSL — `input`, `inputs`,
-  # `actions`, helper calls, conditionals — so the block is run against this
-  # stand-in form builder. Every `input :field` records `:field`; every other
-  # message (including unknown helpers) is swallowed and returns self, so the
-  # block executes without a real view context. Nested `has_many` associations
-  # are intentionally not descended into: the updater only writes flat
-  # attributes, and descending would record association fields as top-level.
+  # `actions`, application helpers, conditionals — so the block is run against
+  # this stand-in form builder rather than parsed. Every `input :field` is
+  # recorded; every other message (including helpers that would need a view
+  # context we do not have) is swallowed and returns self, so the block runs to
+  # completion outside a request.
+  #
+  # Only the options that describe the field to whoever is filling it in are
+  # kept. Presentation options (`input_html:`, `wrapper_html:` and the rest)
+  # say nothing an MCP client can act on and are dropped.
   class FormFieldCollector
-    attr_reader :fields
+    DESCRIBED_TEXT_OPTIONS = %i[label hint].freeze
 
     def initialize
-      @fields = []
+      @inputs = []
     end
 
     def collect(&block)
       instance_exec(self, &block)
-      @fields.uniq
+      @inputs
     end
 
-    def input(name, *_args, **_opts, &_block)
-      @fields << name.to_sym if name.respond_to?(:to_sym)
+    def input(name, *_args, **options, &_block)
+      return self unless name.respond_to?(:to_sym)
+      return self if declared?(name.to_sym)
+
+      @inputs << describe(name.to_sym, options)
       self
     end
 
-    def inputs(*_args, **_opts, &block)
+    # `inputs for: :author` scopes its fields to an association, the same way
+    # has_many does; only an unscoped `inputs` groups fields of the record
+    # itself. Descending into a scoped one would advertise the associated
+    # record's fields as attributes of the record being written.
+    def inputs(*_args, **options, &block)
+      association = options[:for]
+      return nest(association, &block) if association
+
       instance_exec(self, &block) if block
       self
     end
 
-    def has_many(*_args, **_opts)
-      self
+    # Recorded as a group of its own rather than descended into, so a client
+    # can tell an association's fields from the record's own. Flattening them
+    # would advertise `body` as an attribute of the parent record.
+    def has_many(name, *_args, **_opts, &block)
+      nest(name, &block)
     end
 
     def method_missing(_name, *_args, **_opts, &block)
@@ -44,5 +59,57 @@ module ActiveadminMcp
     def respond_to_missing?(_name, _include_private = false)
       true
     end
+
+    private
+
+    # `for:` may name the association or give it as [name, object]; only the
+    # name says anything to a client.
+    def nest(association, &block)
+      name = association.is_a?(Array) ? association.first : association
+      return self unless name.respond_to?(:to_sym)
+      return self if declared?(name.to_sym)
+
+      @inputs << { name: name.to_sym, nested: block ? self.class.new.collect(&block) : [] }
+      self
+    end
+
+    def declared?(name)
+      @inputs.any? { |input| input[:name] == name }
+    end
+
+    def describe(name, options)
+      described = { name: name }
+
+      described[:as] = options[:as].to_sym if scalar_name?(options[:as])
+      described[:required] = options[:required] if [true, false].include?(options[:required])
+
+      DESCRIBED_TEXT_OPTIONS.each do |key|
+        described[key] = options[key].to_s if scalar_name?(options[key])
+      end
+
+      values = allowed_values(options[:collection])
+      described[:collection] = values if values
+
+      described
+    end
+
+    # A helper the collector swallowed comes back as the collector itself, so
+    # anything that is not plain text is not something to report as a label.
+    def scalar_name?(value)
+      value.is_a?(String) || value.is_a?(Symbol)
+    end
+
+    # Only a literal array is resolved. A relation would mean firing a query
+    # from what is meant to be a description, and can be arbitrarily large; a
+    # proc usually needs the view context this collector does not have. Either
+    # is omitted rather than evaluated.
+    def allowed_values(collection)
+      return nil unless collection.is_a?(Array)
+
+      values = collection.map { |entry| entry.is_a?(Array) ? entry.last : entry }
+      return nil unless values.all? { |value| scalar_name?(value) || value.is_a?(Numeric) }
+
+      values
+    end
   end
 end