activeadmin_mcp 0.0.3 → 0.1.0

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

data/lib/activeadmin_mcp/form_field_collector.rb

@@ -1,29 +1,34 @@
-# 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
 
@@ -32,7 +37,14 @@ module ActiveadminMcp
       self
     end
 
-    def has_many(*_args, **_opts)
+    # 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)
+      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
 
@@ -44,5 +56,46 @@ module ActiveadminMcp
     def respond_to_missing?(_name, _include_private = false)
       true
     end
+
+    private
+
+    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

data/lib/activeadmin_mcp/record_writer.rb

@@ -0,0 +1,161 @@
+module ActiveadminMcp
+  # Creates and updates ActiveAdmin-managed records by dispatching the
+  # resource's own create and update actions, so a write from an MCP client
+  # goes through the same permitted params, callbacks, before_action chain and
+  # authorization as the same write made by clicking Save in the admin UI.
+  #
+  # Three gates run before anything is dispatched: the resource must expose the
+  # action, the authorization adapter must allow it, and the resource must
+  # declare what may be written. The controller then applies all three again,
+  # against the record it builds or loads.
+  class RecordWriter
+    CREATE = :create
+    UPDATE = :update
+
+    def initialize(resource:, current_user:)
+      @resource = resource
+      @current_user = current_user
+      @config = resource[:config]
+    end
+
+    def create(attributes:)
+      return error("Resource is not creatable: #{resource_name}") unless exposes?(CREATE)
+
+      permitted = resolve_permitted(attributes)
+      refusal = permit_refusal(permitted)
+      return refusal if refusal
+      return error("Not authorized to create #{resource_name}") unless authorized?(CREATE, @config.resource_class)
+
+      write(
+        action: CREATE,
+        verb: :post,
+        path: @config.route_collection_path,
+        attributes: attributes,
+        written: permitted.keys,
+        written_key: :created,
+        description: "Create #{resource_name}"
+      )
+    end
+
+    def update(id:, attributes:)
+      return error("Resource is not editable: #{resource_name}") unless exposes?(UPDATE)
+
+      record = @resource[:model].find_by(id: id)
+      return error("Record not found: #{resource_name}##{id}") unless record
+
+      permitted = resolve_permitted(attributes)
+      refusal = permit_refusal(permitted)
+      return refusal if refusal
+      return error("Not authorized to update #{resource_name}##{id}") unless authorized?(UPDATE, record)
+
+      write(
+        action: UPDATE,
+        verb: :patch,
+        path: @config.route_instance_path(record),
+        attributes: attributes,
+        written: permitted.keys,
+        written_key: :updated,
+        path_params: { id: record.to_param },
+        description: "Update #{resource_name}##{id}"
+      )
+    end
+
+    private
+
+    def write(action:, verb:, path:, attributes:, written:, written_key:, description:, path_params: {})
+      record = nil
+
+      outcome = ControllerDispatcher.new(config: @config, current_user: @current_user).call(
+        action: action,
+        verb: verb,
+        path: path,
+        params: { @config.param_key => attributes },
+        path_params: path_params
+      ) { |controller| record = controller.send(:get_resource_ivar) }
+
+      return rejection(record, description, outcome) unless saved?(record)
+
+      {
+        resource: resource_name,
+        id: record.id,
+        written_key => written,
+        record: without_sensitive_attributes(record),
+      }
+    end
+
+    def saved?(record)
+      !record.nil? && record.persisted? && record.errors.empty?
+    end
+
+    # The controller declined to save. Validation messages are the usual
+    # reason, and they are read off the record rather than the response
+    # because a rejected write re-renders the admin form — a render the
+    # synthesized request may well not survive, leaving the dispatch itself
+    # reported as a failure even though the record knows exactly what was
+    # wrong with it.
+    #
+    # With no record and no validation messages, anything the controller put
+    # in the flash is the best account left of what the admin UI would have
+    # told the user.
+    def rejection(record, description, outcome)
+      messages = record ? record.errors.full_messages : []
+      return error("Validation failed", details: messages) if messages.any?
+      return outcome if outcome[:error]
+
+      error("#{description} failed", details: Array(outcome[:flash]&.values).presence)
+    end
+
+    def exposes?(action)
+      @config.defined_actions.include?(action)
+    end
+
+    def authorized?(action, subject)
+      Authorization.for(@config, @current_user).authorized?(action, subject)
+    end
+
+    # Turns what the controller says it would permit into a refusal, or nil to
+    # go ahead. The answer is not used to filter the write — dispatch means
+    # ActiveAdmin applies permit_params itself — but to refuse early, and with
+    # a reason, in the two cases where dispatching would otherwise fail
+    # obscurely: a resource that never declared permit_params, and a call whose
+    # every attribute would be dropped.
+    #
+    # A resource with no permit_params cannot be written through ActiveAdmin's
+    # own forms either — Rails raises ForbiddenAttributesError on the
+    # unpermitted params — so refusing it says what the admin UI would.
+    def permit_refusal(permitted)
+      if permitted.nil?
+        return error("Resource declares no permit_params, so nothing may be written: #{resource_name}")
+      end
+
+      error("No permitted attributes to write") if permitted.empty?
+    end
+
+    # Asks the resource's own controller what it would permit, or nil when it
+    # has nothing to say because permit_params was never declared.
+    def resolve_permitted(attributes)
+      param_key = @config.param_key.to_sym
+      controller = @config.controller.new
+      controller.params = ActionController::Parameters.new(param_key => attributes)
+      permitted = controller.send(:permitted_params)
+      scoped = permitted && permitted[param_key]
+      scoped&.to_h&.symbolize_keys
+    rescue StandardError
+      nil
+    end
+
+    def without_sensitive_attributes(record)
+      record.as_json.except(*ResourceRegistry.sensitive_attributes)
+    end
+
+    def resource_name
+      @resource[:name]
+    end
+
+    def error(message, details: nil)
+      result = { error: message }
+      result[:details] = details if details
+      result
+    end
+  end
+end

data/lib/activeadmin_mcp/request_handler.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module ActiveadminMcp
   class RequestHandler
     PROTOCOL_VERSION = "2025-06-18"
@@ -40,45 +38,131 @@ module ActiveadminMcp
     end
 
     def tools_list
-      {
-        tools: [
-          {
-            name: "list_resources",
-            description: "List the ActiveAdmin resources the authenticated user is authorized " \
-                         "to read, with their attributes",
-            inputSchema: { type: "object", properties: {} },
+      { tools: built_in_tools + action_tools }
+    end
+
+    # Both gates run before the schema is built, never after: ActionSchema calls
+    # the application's `suggestions:` procs, which read the database. Filtering
+    # an already-assembled list would mean those procs had already run — and
+    # their values already been read — for a user authorized for none of it.
+    def action_tools
+      ActionCatalog.all.filter_map do |definition|
+        next unless authorized_to_run?(definition)
+        next unless authorized_to_list?(definition)
+
+        {
+          name: definition.tool_name,
+          description: definition.description,
+          inputSchema: ActionSchema.new(definition).to_h,
+        }
+      end
+    end
+
+    # The same authorization adapter check ActionRunner makes before dispatch,
+    # and the one list_resources makes for reads. There is no record at listing
+    # time, so the subject is the resource class.
+    def authorized_to_run?(definition)
+      Authorization.for(definition.config, @current_user)
+                   .authorized?(definition.action_name, definition.config.resource_class)
+    rescue StandardError => e
+      warn("[activeadmin_mcp] hiding #{definition.tool_name}: authorization check raised #{e.class}: #{e.message}")
+      false
+    end
+
+    # Collection and batch actions whose permission proc takes no record can be
+    # resolved now, so the tool is simply hidden. A member action's proc needs a
+    # record, so its tool stays listed and refusal happens at call time.
+    #
+    # The proc is evaluated in controller context, exactly as ActionRunner
+    # evaluates it at call time, so `current_admin_user`, `can?` and the rest of
+    # the admin helpers are in scope. Evaluating it bare would make every such
+    # proc raise NameError and hide its tool from everybody.
+    def authorized_to_list?(definition)
+      permission = definition.permission
+      return true unless permission
+      return true unless permission.respond_to?(:arity) && permission.arity.zero?
+
+      controller = ControllerDispatcher.new(config: definition.config, current_user: @current_user)
+                                       .controller_with_mcp_user
+      !!::MethodOrProcHelper.render_in_context(controller, permission)
+    rescue StandardError => e
+      # One broken proc hides its own tool and nothing else, but it says so.
+      warn("[activeadmin_mcp] hiding #{definition.tool_name}: permission proc raised #{e.class}: #{e.message}")
+      false
+    end
+
+    def built_in_tools
+      [
+        {
+          name: "list_resources",
+          description: "List the ActiveAdmin resources the authenticated user is authorized " \
+                       "to read, with their attributes",
+          inputSchema: { type: "object", properties: {} },
+        },
+        {
+          name: "query",
+          description: "Query an ActiveAdmin resource using Ransack syntax. Respects ActiveAdmin " \
+                       "authorization: the resource must be readable by the authenticated user, " \
+                       "and results are scoped to the records they may access.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              resource: { type: "string", description: "Resource name (e.g., 'User', 'Post')" },
+              q: { type: "object", description: "Ransack query (e.g., {name_cont: 'john'})" },
+              limit: { type: "integer", description: "Max records (default: 25)" },
+            },
+            required: ["resource"],
           },
-          {
-            name: "query",
-            description: "Query an ActiveAdmin resource using Ransack syntax. Respects ActiveAdmin " \
-                         "authorization: the resource must be readable by the authenticated user, " \
-                         "and results are scoped to the records they may access.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                resource: { type: "string", description: "Resource name (e.g., 'User', 'Post')" },
-                q: { type: "object", description: "Ransack query (e.g., {name_cont: 'john'})" },
-                limit: { type: "integer", description: "Max records (default: 25)" },
+        },
+        {
+          name: "describe_form",
+          description: "Describe the fields of a resource's ActiveAdmin form — their input " \
+                       "types, labels, hints, allowed values, column types and which are " \
+                       "required — so a create or update call need not guess them.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              resource: { type: "string", description: "Resource name (e.g., 'User', 'Post')" },
+              action: {
+                type: "string",
+                enum: %w[new edit],
+                description: "Which form to describe: 'new' for creating, 'edit' for updating " \
+                             "(default: 'new')",
               },
-              required: ["resource"],
             },
+            required: ["resource"],
           },
-          {
-            name: "update",
-            description: "Update an existing record. Only fields the resource's ActiveAdmin " \
-                         "form permits are written, and the update respects ActiveAdmin authorization.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                resource: { type: "string", description: "Resource name (e.g., 'User', 'Post')" },
-                id: { type: ["integer", "string"], description: "Primary key of the record to update" },
-                attributes: { type: "object", description: "Attributes to update (e.g., {name: 'New name'})" },
-              },
-              required: %w[resource id attributes],
+        },
+        {
+          name: "create",
+          description: "Create a new record. The write runs through the resource's real " \
+                       "ActiveAdmin create action, so only fields its permit_params accepts " \
+                       "are written and its callbacks and authorization all apply.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              resource: { type: "string", description: "Resource name (e.g., 'User', 'Post')" },
+              attributes: { type: "object", description: "Attributes for the new record (e.g., {name: 'Ada'})" },
             },
+            required: %w[resource attributes],
           },
-        ],
-      }
+        },
+        {
+          name: "update",
+          description: "Update an existing record. The write runs through the resource's real " \
+                       "ActiveAdmin update action, so only fields its permit_params accepts " \
+                       "are written and its callbacks and authorization all apply.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              resource: { type: "string", description: "Resource name (e.g., 'User', 'Post')" },
+              id: { type: ["integer", "string"], description: "Primary key of the record to update" },
+              attributes: { type: "object", description: "Attributes to update (e.g., {name: 'New name'})" },
+            },
+            required: %w[resource id attributes],
+          },
+        },
+      ]
     end
 
     def call_tool(params)
@@ -88,13 +172,22 @@ module ActiveadminMcp
       result = case name
                when "list_resources" then tool_list_resources
                when "query" then tool_query(args)
+               when "describe_form" then tool_describe_form(args)
+               when "create" then tool_create(args)
                when "update" then tool_update(args)
-               else { error: "Unknown tool: #{name}" }
+               else tool_action(name, args)
                end
 
       { content: [{ type: "text", text: JSON.pretty_generate(result) }] }
     end
 
+    def tool_action(name, args)
+      definition = ActionCatalog.find(name)
+      return { error: "Unknown tool: #{name}" } unless definition
+
+      ActionRunner.new(definition: definition, current_user: @current_user).call(args)
+    end
+
     def tool_list_resources
       entries = ResourceRegistry.resources.select { |entry| authorized_to_read?(entry) }
       { resources: entries.map { |entry| ResourceRegistry.resource_info(entry) } }
@@ -113,6 +206,24 @@ module ActiveadminMcp
       { resource: resource[:name], count: records.size, records: filter_sensitive(records.as_json) }
     end
 
+    def tool_describe_form(args)
+      resource = ResourceRegistry.find(args["resource"])
+      return { error: "Resource not found: #{args['resource']}" } unless resource
+
+      FormDescription.new(resource: resource, current_user: @current_user)
+                     .call(action: args["action"] || "new")
+    end
+
+    def tool_create(args)
+      resource = ResourceRegistry.find(args["resource"])
+      return { error: "Resource not found: #{args['resource']}" } unless resource
+
+      attributes = args["attributes"] || {}
+      return { error: "attributes are required" } if attributes.empty?
+
+      RecordWriter.new(resource: resource, current_user: @current_user).create(attributes: attributes)
+    end
+
     def tool_update(args)
       resource = ResourceRegistry.find(args["resource"])
       return { error: "Resource not found: #{args['resource']}" } unless resource
@@ -121,8 +232,8 @@ module ActiveadminMcp
       attributes = args["attributes"] || {}
       return { error: "attributes are required" } if attributes.empty?
 
-      RecordUpdater.new(resource: resource, current_user: @current_user)
-                   .call(id: args["id"], attributes: attributes)
+      RecordWriter.new(resource: resource, current_user: @current_user)
+                  .update(id: args["id"], attributes: attributes)
     end
 
     def authorized_to_read?(resource)

data/lib/activeadmin_mcp/resource_registry.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module ActiveadminMcp
   module ResourceRegistry
     class << self