activeadmin_mcp 0.0.4 → 0.1.0

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

data/lib/activeadmin_mcp/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module ActiveadminMcp
-  VERSION = "0.0.4"
+  VERSION = "0.1.0"
 end

data/lib/activeadmin_mcp.rb

@@ -1,11 +1,17 @@
-# frozen_string_literal: true
-
 require_relative "activeadmin_mcp/version"
 require_relative "activeadmin_mcp/configuration"
 require_relative "activeadmin_mcp/authorization"
+require_relative "activeadmin_mcp/active_admin_ext"
+require_relative "activeadmin_mcp/action_definition"
+require_relative "activeadmin_mcp/action_schema"
+require_relative "activeadmin_mcp/action_params"
+require_relative "activeadmin_mcp/action_catalog"
+require_relative "activeadmin_mcp/controller_dispatcher"
+require_relative "activeadmin_mcp/action_runner"
 require_relative "activeadmin_mcp/resource_registry"
 require_relative "activeadmin_mcp/form_field_collector"
-require_relative "activeadmin_mcp/record_updater"
+require_relative "activeadmin_mcp/form_description"
+require_relative "activeadmin_mcp/record_writer"
 require_relative "activeadmin_mcp/request_handler"
 require_relative "activeadmin_mcp/engine"
 

data/lib/generators/activeadmin_mcp/install/install_generator.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "rails/generators"
 require "rails/generators/active_record"
 

data/lib/generators/activeadmin_mcp/install/templates/initializer.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 ActiveadminMcp.configure do |config|
   # Uncomment to enable API token authentication.
   # Requires running the auth migration first:
@@ -19,6 +17,11 @@ ActiveadminMcp.configure do |config|
   # Path where the MCP server is mounted.
   # config.mount_path = "/mcp"
 
+  # How the engine adds its route: :prepend (default), :append, or :none.
+  # Set it to :none when you want to mount the engine yourself, for instance
+  # inside a constraints block your admin routes already sit in.
+  # config.mount_strategy = :prepend
+
   # HTTP header used to read the Bearer token from.
   # Useful when a reverse proxy (e.g. AWS Verified Access) strips the
   # standard Authorization header.

data/lib/generators/activeadmin_mcp/install/templates/mcp_api_tokens.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 ActiveAdmin.register_page "MCP API Tokens" do
   menu label: "MCP Tokens", parent: ActiveadminMcp.config.menu_parent, priority: 100
 

data/lib/generators/activeadmin_mcp/install/templates/migration.rb.erb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 class CreateMcpApiTokens < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     return if table_exists?(:mcp_api_tokens)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activeadmin_mcp
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - harunkumars
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: activeadmin
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.5'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -95,11 +95,19 @@ files:
 - app/models/activeadmin_mcp/api_token.rb
 - config/routes.rb
 - lib/activeadmin_mcp.rb
+- lib/activeadmin_mcp/action_catalog.rb
+- lib/activeadmin_mcp/action_definition.rb
+- lib/activeadmin_mcp/action_params.rb
+- lib/activeadmin_mcp/action_runner.rb
+- lib/activeadmin_mcp/action_schema.rb
+- lib/activeadmin_mcp/active_admin_ext.rb
 - lib/activeadmin_mcp/authorization.rb
 - lib/activeadmin_mcp/configuration.rb
+- lib/activeadmin_mcp/controller_dispatcher.rb
 - lib/activeadmin_mcp/engine.rb
+- lib/activeadmin_mcp/form_description.rb
 - lib/activeadmin_mcp/form_field_collector.rb
-- lib/activeadmin_mcp/record_updater.rb
+- lib/activeadmin_mcp/record_writer.rb
 - lib/activeadmin_mcp/request_handler.rb
 - lib/activeadmin_mcp/resource_registry.rb
 - lib/activeadmin_mcp/version.rb
@@ -122,14 +130,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 4.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.20
 specification_version: 4
 summary: MCP server for Rails apps with ActiveAdmin
 test_files: []