administrate-mcp 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3f38d54e63d5f8d6b88750c73f284d10d5e0500a0a7f47cae82556be264e8fe
-  data.tar.gz: 1b1d5fda201d08915bdddd2c6eb92fb97f9698ece7f17cbff1a1d563f280eea9
+  metadata.gz: e16575edff64537e779f60e3d447d4bef99e19f46669c64eb882bd14867279a7
+  data.tar.gz: 2490fbf883f4980d3a152a5d245f27448f5729159b8944432a59c1d90dcb51d5
 SHA512:
-  metadata.gz: bdc5883ed9f4d6cadab89dd8be6aca8f890e25cfc39d0a40ef6b2b7e9fd6b11af6de5e817d4d8c6047a0bcd9d3ad1a6bd05b4af095bd64c256ad6d65198bbf7e
-  data.tar.gz: 21bd4c4e668bad2bd5d9050bc6e86abae5800a605be3604d2683687bb3b52bcf4dae42cc2423f5df2fe09713ac14784cc5188a5d76ba28694fe2f41581fa895e
+  metadata.gz: 6b74d3c9e992058ff3d896cd3d4f80075520ee3e977f4a07d0093dc9982aee9b686465c0d236d0f92e199751f863e9fc544afc44b066f1d5548d2bb9a909a19a
+  data.tar.gz: 0142657f7abee895bd4acec60789403c2ddaa999bc55b2ffc3077f6a164f8db579bf8d835daf063e227b4bcfcc9ce9a2c96843cd5ffa91800fa6227d456668c7

data/CHANGELOG.md

@@ -8,6 +8,45 @@ minor release may change behaviour a host depends on; the entry says so when it
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-21
+
+### Added
+
+- Collection-level write actions: `mcp_action name, on: :collection, ...` publishes a tool with no
+  `id` in its input schema. Nothing is loaded; the block receives `admin:` and `params:`, and the
+  authorization predicate, `<name>?` by default as for member actions and overridable with
+  `predicate:` or `pundit:`, is checked against a new instance of the model through
+  `config.authorization`, when the tool list is built and on every call. The `write` scope gate,
+  the `on_tool_call` audit and the error reporting work as for member actions, and the tool keeps
+  the `<resource>_<action>` name. When the block returns an Active Record object, the response
+  includes its primary key as `id`. `on: :member` stays the default.
+- Presigned uploads for Shrine attachments, off until `config.uploads.enabled` is set. The
+  `uploads_prepare` tool takes the target action's `tool` name, an `attribute` and `files`, an
+  object of filename to size in bytes. It is only published to, and only answers, a caller
+  authorized for an action that accepts uploads for that attribute. It records an
+  `administrate_mcp_upload_batches` row and returns `{ filename => { upload_id, method, url,
+  fields } }`, one presigned `POST` per file whose policy bounds the content length. An
+  `mcp_action` declared with `uploads:` (`true`, a list of attributes, or per-attribute
+  `content_types:` and `max_size:`) takes an optional `<attribute>_upload_id` for each attachment
+  attribute; the engine resolves it and the block receives the file as `params[:<attribute>]`.
+  Resolving checks the owning admin (another admin's id is not found), the action and attribute
+  the upload was prepared for, the batch expiry, that the file was uploaded, and its real size
+  and content type, on a copy under a key no URL points to; the copy is reused if the same id is
+  passed again. Defaults: png, jpeg and webp, 10 MB, 10 files per call, 15-minute URLs, 1-hour
+  batches. `Administrate::MCP::CleanExpiredUploadBatches` deletes expired batches. The default
+  storage is the Shrine `:cache` storage, replaceable through `config.uploads.storage`; the gem
+  gains no dependency. Hosts that enable uploads need the new migration
+  (`bin/rails administrate_mcp:install:migrations`).
+
+### Changed
+
+- **Behaviour change for hosts:** an `mcp_action` block that returns an Active Record object that
+  was never saved or has errors is now reported as an error, with the record's validation messages,
+  instead of `status: ok`. A record the block destroyed is still a success. A block that returns
+  `false`, as `record.update(...)` does on a validation error and `record.destroy` does when a
+  callback aborts it, is now an error too, with the loaded record's validation messages for a member
+  action when it has any. A block that returned `false` to mean success must return something else.
+
 ## [0.3.1] - 2026-10-20
 
 ### Security
@@ -138,7 +177,8 @@ minor release may change behaviour a host depends on; the entry says so when it
   took the gem from git before 0.1.0 must reinstall its migrations rather than migrate
   incrementally.
 
-[Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/sorare/administrate-mcp/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/sorare/administrate-mcp/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/sorare/administrate-mcp/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/sorare/administrate-mcp/compare/v0.1.0...v0.2.0

data/README.md

@@ -21,6 +21,7 @@ permissions the admin UI enforces.
 - [Configuration](#configuration)
 - [Routes](#routes)
 - [Dashboard declarations](#dashboard-declarations)
+- [Presigned uploads](#presigned-uploads)
 - [Authentication](#authentication)
 - [OAuth](#oauth)
 - [Improving the server from its own use](#improving-the-server-from-its-own-use)
@@ -45,7 +46,14 @@ about your application; everything host-specific goes through `Administrate::MCP
 - Three generic tools built from every Administrate dashboard: `admin_resource_list_resources`,
   `admin_resource_list`, `admin_resource_show`.
 - Write actions declared per dashboard with `mcp_action`, each published as its own tool, gated by
-  the `write` scope (an API key with write access, or an OAuth token granted it) and the resource's own authorization predicate on the loaded record.
+  the `write` scope (an API key with write access, or an OAuth token granted it) and the resource's
+  own authorization predicate: on the loaded record for a member action, or on the model class for a
+  collection action (`on: :collection`), such as a create, that takes no `id`.
+- Presigned uploads for Shrine attachments, opt-in: `uploads_prepare` hands out presigned `POST`
+  URLs for one action and attribute, and an action declared with `uploads:` takes an
+  `<attribute>_upload_id` for each attachment attribute. The file's owner, target, expiry, real size
+  and real content type are checked on a copy the client cannot overwrite before the action runs.
+  See [Presigned uploads](docs/uploads.md).
 - Three ways to authenticate a caller: API keys stored as a digest, an external identity provider
   through `identity_fallback` (a Cloudflare Access verifier ships with the gem), and an optional
   built-in OAuth 2.1 server with Dynamic Client Registration, PKCE and refresh tokens, on by default
@@ -157,8 +165,8 @@ bin/rails db:migrate
 ```
 
 The tables are `administrate_mcp_api_keys`, `administrate_mcp_feedbacks`,
-`administrate_mcp_oauth_applications`, `administrate_mcp_oauth_access_grants` and
-`administrate_mcp_oauth_access_tokens`. They use uuid primary keys and a uuid column, `admin_id` by
+`administrate_mcp_oauth_applications`, `administrate_mcp_oauth_access_grants`,
+`administrate_mcp_oauth_access_tokens` and `administrate_mcp_upload_batches`. They use uuid primary keys and a uuid column, `admin_id` by
 default, that is indexed but carries no foreign key constraint, so the engine works with any admin
 table. Set `config.admin_foreign_key` before running the migrations if the host's own admin table
 already uses a different column name and renaming it is not an option, for example a live
@@ -166,6 +174,7 @@ credentials table.
 
 `administrate_mcp_feedbacks` is only needed when `config.persist_feedback` is `true`; leave it
 `false`, the default, and the migration ships but the table is never read from or written to.
+Likewise, `administrate_mcp_upload_batches` is only used once `config.uploads.enabled` is `true`.
 
 ## Quick start
 
@@ -219,6 +228,11 @@ helper adds: [docs/routes.md](docs/routes.md).
 and `mcp_action`, the constants and macro that turn one dashboard into an MCP resource with its own
 readable fields and writable actions: [docs/dashboards.md](docs/dashboards.md).
 
+## Presigned uploads
+
+How a client uploads a file to a presigned URL and sets it on an attachment through an action, the
+checks on the uploaded file, and the storage it goes to: [docs/uploads.md](docs/uploads.md).
+
 ## Authentication
 
 How a request is authenticated (API key, then OAuth token, then `identity_fallback`), how to issue

data/app/lib/administrate/mcp/actions.rb

@@ -9,50 +9,68 @@ module Administrate
     # declaration we build a tool whose name, input schema and description let non-developer users
     # discover and call it through the protocol.
     #
+    # An action is a member action by default: it takes an `id` and runs against the loaded record.
+    # Declared with `on: :collection`, it takes no `id`, loads nothing and runs against the model.
+    #
+    # An action declared with `uploads:` (true, a list of attachment attributes, or a hash of
+    # attribute to `content_types:` / `max_size:` overrides) also takes an optional
+    # `<attribute>_upload_id` for each of them. The id is resolved into the attachment value before
+    # the block runs, so the block sees `params[:<attribute>]`.
+    #
     # Enforcement is layered: the generated tool requires an OAuth `write` scope (the rollout gate)
-    # AND runs the resource's authorization predicate against the loaded record (the per-admin
-    # truth, identical to the admin UI). Auditing is inherited from BaseTool.
+    # AND runs the resource's authorization predicate against the loaded record, or against a new
+    # instance of the model for a collection action, as Administrate does for `new` and `create`.
+    # Auditing is inherited from BaseTool.
     module Actions
       Definition =
         Struct.new(
           :model_class,
           :name,
+          :on,
           :predicate,
           :scope,
           :destructive,
           :description,
           :params,
           :required,
+          :uploads,
           :invoke,
           keyword_init: true
         )
 
       RESERVED_PARAMS = %i[admin id].freeze
 
+      TARGETS = %i[member collection].freeze
+
       class << self
         # Normalizes the arguments of a `mcp_action` declaration into a spec (everything but the
         # model, which is inferred from the owning dashboard when definitions are built).
-        def build_spec(name, description:, params: {}, predicate: nil, pundit: nil, scope: :write,
-                       destructive: true, &invoke)
+        def build_spec(name, description:, on: :member, params: {}, predicate: nil, pundit: nil, scope: :write,
+                       destructive: true, uploads: false, &invoke)
           raise ArgumentError, "#{name}: a block is required to invoke the action" unless invoke
+          raise ArgumentError, "#{name}: on: must be :member or :collection" unless TARGETS.include?(on)
 
           reject_reserved_params!(name, params)
           normalized = normalize_params(params)
 
           {
             name: name.to_sym,
+            on:,
             predicate: (predicate || pundit || :"#{name}?").to_sym,
             scope: scope.to_sym,
             destructive:,
             description:,
             params: normalized.transform_values { |spec| spec.except(:required) },
             required: normalized.reject { |_, spec| spec[:required] == false }.keys,
+            uploads: Uploads::Declarations.normalize(uploads, action_name: name),
             invoke:
           }
         end
 
         def normalize_params(params)
-          params.transform_values { |spec| spec.is_a?(String) ? { type: 'string', description: spec } : spec }
+          params.to_h do |name, spec|
+            [name.to_sym, spec.is_a?(String) ? { type: 'string', description: spec } : spec.to_h.symbolize_keys]
+          end
         end
 
         def definitions
@@ -61,11 +79,20 @@ module Administrate
               next [] unless entry.dashboard_class.respond_to?(:mcp_action_specs)
 
               entry.dashboard_class.mcp_action_specs.map do |spec|
-                Definition.new(model_class: entry.model_class, **spec)
+                uploads = Uploads::Declarations.action_attributes(entry.dashboard_class, spec[:name], spec[:uploads])
+                Definition.new(model_class: entry.model_class, **spec, uploads:)
               end
             end
         end
 
+        def tool_name(definition)
+          "#{definition.model_class.name.underscore.tr('/', '_')}_#{definition.name}"
+        end
+
+        def available_to?(admin, definition, scopes:)
+          scopes.map(&:to_sym).include?(definition.scope) && authorized_for_discovery?(admin, definition)
+        end
+
         def all_tools
           @all_tools ||= definitions.map { |defn| ToolFactory.build(defn) }
         end
@@ -73,13 +100,8 @@ module Administrate
         # Tool classes the caller may both see and run: write scope granted AND the authorization
         # predicate satisfied at the role level. The actual call re-checks it against the record.
         def tools_for(server_context)
-          granted = (server_context[:scopes] || []).map(&:to_sym)
-          admin = server_context[:admin]
-
-          all_tools.select do |tool|
-            defn = tool.definition
-            granted.include?(defn.scope) && authorized_for_discovery?(admin, defn)
-          end
+          scopes = server_context[:scopes] || []
+          all_tools.select { |tool| available_to?(server_context[:admin], tool.definition, scopes:) }
         end
 
         def reset!
@@ -106,7 +128,8 @@ module Administrate
         end
 
         def authorized_for_discovery?(admin, definition)
-          Administrate::MCP.config.authorization.authorized?(admin, definition.model_class, definition.predicate)
+          target = definition.on == :collection ? definition.model_class.new : definition.model_class
+          Administrate::MCP.config.authorization.authorized?(admin, target, definition.predicate)
         rescue StandardError
           false
         end
@@ -126,7 +149,7 @@ module Administrate
           def build(defn)
             resource = defn.model_class.name.underscore
             klass = Class.new(BaseTool)
-            klass.tool_name "#{resource.tr('/', '_')}_#{defn.name}"
+            klass.tool_name Actions.tool_name(defn)
             klass.description defn.description
             klass.annotations(read_only_hint: false, destructive_hint: defn.destructive, open_world_hint: true)
             klass.requires_scope defn.scope
@@ -135,42 +158,61 @@ module Administrate
             klass
           end
 
+          private
+
           def schema_for(defn, resource)
-            properties = { id: { type: 'string', description: "ID or slug of the #{resource}" } }
-            defn.params.each { |name, spec| properties[name] = spec }
-            { properties:, required: %w[id] + defn.required.map(&:to_s), additionalProperties: false }
+            properties = defn.params.merge(Uploads::Declarations.param_schemas(defn))
+            required = defn.required.map(&:to_s)
+            if defn.on == :member
+              properties = { id: { type: 'string', description: "ID or slug of the #{resource}" }, **properties }
+              required = %w[id] + required
+            end
+            { properties:, required:, additionalProperties: false }
+          end
+
+          def define_behaviors(klass, defn)
+            klass.define_singleton_method(:definition) { defn }
+            klass.define_singleton_method(:check_roles!) do |admin, id: nil, **|
+              ToolFactory.send(:authorize!, defn, admin, id)
+            end
+            klass.define_singleton_method(:execute) do |admin:, id: nil, **params|
+              outcome = ToolFactory.send(:invoke, defn, admin, id, params)
+              outcome.key?(:error) ? error_response(outcome[:error]) : json_response(outcome[:data])
+            end
           end
 
-          # Replaces the role-based default with instance-level authorization on the loaded record.
           def authorize!(defn, admin, id)
-            record = Actions.find_record!(defn.model_class, id)
-            Actions.authorize!(admin, record, defn.predicate)
+            target = defn.on == :member ? Actions.find_record!(defn.model_class, id) : defn.model_class.new
+            Actions.authorize!(admin, target, defn.predicate)
           end
 
           def invoke(defn, admin, id, params)
-            record = Actions.find_record!(defn.model_class, id)
-            result = defn.invoke.call(record:, admin:, params:)
-            return { error: result.try(:error) || "#{defn.name} failed" } if failed?(result)
+            declared = params.slice(*defn.params.keys, *Uploads::Declarations.param_schemas(defn).keys)
+            arguments = { admin:, params: Uploads::Declarations.resolve_params(defn, admin, declared) }
+            arguments[:record] = Actions.find_record!(defn.model_class, id) if defn.on == :member
+            result = defn.invoke.call(**arguments)
+            return { error: failure_message(defn, result, arguments[:record]) } if failed?(result)
 
-            { data: { status: 'ok', model: defn.model_class.name.underscore, id:, action: defn.name.to_s } }
+            { data: success_data(defn, id, result) }
           end
 
-          private
-
-          def define_behaviors(klass, defn)
-            klass.define_singleton_method(:definition) { defn }
-            klass.define_singleton_method(:check_roles!) do |admin, id: nil, **|
-              ToolFactory.authorize!(defn, admin, id)
-            end
-            klass.define_singleton_method(:execute) do |admin:, id:, **params|
-              outcome = ToolFactory.invoke(defn, admin, id, params)
-              outcome.key?(:error) ? error_response(outcome[:error]) : json_response(outcome[:data])
-            end
+          def success_data(defn, id, result)
+            id = result.id if defn.on == :collection && result.is_a?(ActiveRecord::Base)
+            { status: 'ok', model: defn.model_class.name.underscore, id:, action: defn.name.to_s }.compact
           end
 
           def failed?(result)
+            return true if result == false
+            return result.new_record? || result.errors.any? if result.is_a?(ActiveRecord::Base)
+
             result.respond_to?(:success?) && !result.success?
           end
+
+          def failure_message(defn, result, record)
+            invalid = result.is_a?(ActiveRecord::Base) ? result : (record if result == false)
+            message = invalid ? invalid.errors.full_messages.to_sentence : result.try(:error)
+            message.presence || "#{defn.name} failed"
+          end
         end
       end
     end

data/app/lib/administrate/mcp/base_tool.rb

@@ -55,7 +55,11 @@ module Administrate
           check_roles!(admin, **args)
           audit!(admin, args, server_context)
           reject_reserved_arguments!(args)
-          execute(**args, admin:)
+          execute(**args, admin:, **execute_context(server_context))
+        end
+
+        def execute_context(_server_context)
+          {}
         end
 
         def reject_reserved_arguments!(args)

data/app/lib/administrate/mcp/clean_expired_upload_batches.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Removes upload batches that expired before the given cutoff, one batch at a time. The caller
+    # decides whether to run the next batch: `call` reports whether the batch was full. The
+    # uploaded objects are left to the bucket's own lifecycle rule.
+    class CleanExpiredUploadBatches
+      BATCH_SIZE = 10_000
+
+      Result = Struct.new(:deleted_count, :more?, keyword_init: true)
+
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(till: Time.current)
+        @till = till
+      end
+
+      def call
+        deleted_count = UploadBatch.expired(@till).limit(BATCH_SIZE).delete_all
+        Result.new(deleted_count:, more?: deleted_count == BATCH_SIZE)
+      end
+    end
+  end
+end

data/app/lib/administrate/mcp/field_serializer.rb

@@ -119,6 +119,10 @@ module Administrate
           matches?(field_class, Administrate::MCP.config.has_many_field_classes)
         end
 
+        def serializer_for(field_spec)
+          lookup_serializer(resolve_field_class(field_spec))
+        end
+
         def resolve_field_class(field_spec)
           case field_spec
           when Administrate::Field::Deferred

data/app/lib/administrate/mcp/server_builder.rb

@@ -16,6 +16,8 @@ module Administrate
 
       SIDEKIQ_STATS_TOOL = 'Administrate::MCP::Tools::SidekiqStats'
 
+      UPLOADS_PREPARE_TOOL = 'Administrate::MCP::Tools::UploadsPrepare'
+
       class << self
         def build(server_context:)
           server_context[:authorization_errors] ||= []
@@ -46,12 +48,16 @@ module Administrate
 
         def discover_tools(server_context)
           load_host_tools
-          (built_in_tools + host_tools).uniq + Actions.tools_for(server_context)
+          action_tools = Actions.tools_for(server_context)
+          built_in = built_in_tools
+          built_in -= [Tools::UploadsPrepare] unless Uploads::Declarations.any?(action_tools)
+          (built_in + host_tools).uniq + action_tools
         end
 
         def built_in_tools
           names = BUILT_IN_TOOLS.dup
           names << REPORT_IMPROVEMENT_TOOL if Administrate::MCP.config.feedback_tool
+          names << UPLOADS_PREPARE_TOOL if Administrate::MCP.config.uploads.enabled
           names << SIDEKIQ_RETRIES_TOOL if defined?(::Sidekiq)
           names << SIDEKIQ_STATS_TOOL if defined?(::Sidekiq) && Administrate::MCP.config.sidekiq_stats_provider
           names.filter_map(&:safe_constantize)

data/app/lib/administrate/mcp/tools/uploads_prepare.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    module Tools
+      # Hands out presigned upload URLs for one attachment attribute of one action, so a client can
+      # upload a file and then pass its upload_id to that action. Published only when uploads are
+      # enabled and the caller has an action that accepts uploads.
+      class UploadsPrepare < BaseTool
+        tool_name 'uploads_prepare'
+        requires_scope :write
+        description 'Prepare file uploads for an action that accepts them. Pass the action\'s `tool` name, the ' \
+                    '`attribute` the files are for (the action takes `<attribute>_upload_id`), and `files` as an ' \
+                    'object of filename to size in bytes. Each file gets an `upload_id`, a `method`, a `url` and ' \
+                    'either `fields` or `headers`. For `POST`, send a multipart form to `url` with every entry of ' \
+                    '`fields` followed by the file as `file`, for example ' \
+                    '`curl -F key=... -F policy=... (one -F per field) -F file=@logo.png "<url>"`. For `PUT`, ' \
+                    'send the file as the body with every header in `headers`. Then pass the `upload_id` as ' \
+                    '`<attribute>_upload_id` to that action. URLs expire after 15 minutes by default and upload ' \
+                    'ids after an hour.'
+        annotations(read_only_hint: false, destructive_hint: false, open_world_hint: true)
+
+        input_schema(
+          properties: {
+            tool: { type: 'string', description: 'The action tool the files are for, for example widget_update.' },
+            attribute: { type: 'string', description: 'The attachment attribute, for example picture.' },
+            files: {
+              type: 'object',
+              description: 'Filename to size in bytes, for example {"logo.png": 48213}.',
+              additionalProperties: { type: 'integer' }
+            }
+          },
+          required: %w[tool attribute files],
+          additionalProperties: false
+        )
+
+        def self.execute(admin:, scopes:, tool:, attribute:, files:)
+          json_response(Administrate::MCP::Uploads.prepare(admin:, scopes:, tool:, attribute:, files:))
+        end
+
+        def self.execute_context(server_context)
+          { scopes: server_context[:scopes] || [] }
+        end
+        private_class_method :execute_context
+      end
+    end
+  end
+end

data/app/lib/administrate/mcp/uploads/declarations.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    module Uploads
+      # How an `mcp_action` declares uploads: which attachment attributes take an
+      # `<attribute>_upload_id`, the schema of those params, and turning them into attachment
+      # values before the action's block runs.
+      module Declarations
+        RULE_KEYS = %i[content_types max_size].freeze
+
+        class << self
+          def normalize(uploads, action_name:)
+            return true if uploads == true
+            return {} unless uploads
+            return Array(uploads).to_h { |attribute| [attribute.to_sym, {}] } unless uploads.is_a?(Hash)
+
+            uploads.to_h do |attribute, rules|
+              [attribute.to_sym, validate_rules!("#{action_name}: uploads: #{attribute}", rules)]
+            end
+          end
+
+          def any?(action_tools)
+            config.enabled && action_tools.any? { |tool| tool.definition.uploads.any? }
+          end
+
+          def action_attributes(dashboard_class, action_name, declared)
+            return {} if declared.blank? || !config.enabled
+
+            attachments = attachment_attributes(dashboard_class)
+            if declared == true
+              return attachments.index_with({}) if attachments.any?
+
+              raise ArgumentError, "#{dashboard_class.name} #{action_name}: uploads: true, but the dashboard has " \
+                                   'no attachment attribute'
+            end
+
+            unknown = declared.keys - attachments
+            return declared if unknown.empty?
+
+            raise ArgumentError, "#{dashboard_class.name} #{action_name}: uploads: names #{unknown.join(', ')}, " \
+                                 'which are not attachment attributes'
+          end
+
+          def param_schemas(definition)
+            definition.uploads.keys.to_h do |attribute|
+              [param_name(attribute),
+               { type: 'string', description: "An upload_id from uploads_prepare, to set #{attribute} to that file." }]
+            end
+          end
+
+          def resolve_params(definition, admin, params)
+            tool = Actions.tool_name(definition)
+            definition.uploads.each_key.with_object(params.dup) do |attribute, resolved|
+              upload_id = resolved.delete(param_name(attribute))
+              next if upload_id.blank?
+
+              resolved[attribute] = Uploads.resolve(admin:, upload_id:, tool:, attribute: attribute.to_s,
+                                                    rules: Uploads.rules_for(definition, attribute))
+            end
+          end
+
+          private
+
+          def validate_rules!(context, rules)
+            raise ArgumentError, "#{context} must be a hash of rules" unless rules.is_a?(Hash)
+
+            rules = rules.symbolize_keys
+            unknown = rules.keys - RULE_KEYS
+            raise ArgumentError, "#{context}: unknown rule(s) #{unknown.join(', ')}" if unknown.any?
+            unless rules[:content_types].nil? || content_types?(rules[:content_types])
+              raise ArgumentError, "#{context}: content_types: must be a hash of extension to content type, " \
+                                   "such as { '.png' => 'image/png' }"
+            end
+            return rules if rules[:max_size].nil? || positive_integer?(rules[:max_size])
+
+            raise ArgumentError, "#{context}: max_size: must be a positive number of bytes"
+          end
+
+          def positive_integer?(value)
+            value.is_a?(Integer) && value.positive?
+          end
+
+          def content_types?(content_types)
+            content_types.is_a?(Hash) && content_types.any? &&
+              content_types.all? { |extension, type| extension.to_s.match?(/\A\.\w+\z/) && type.is_a?(String) }
+          end
+
+          def param_name(attribute)
+            :"#{attribute}_upload_id"
+          end
+
+          def attachment_attributes(dashboard_class)
+            dashboard_class.new.attribute_types.filter_map do |attribute, field_spec|
+              attribute if FieldSerializer.serializer_for(field_spec) == :attachment
+            end
+          end
+
+          def config
+            Administrate::MCP.config.uploads
+          end
+        end
+      end
+    end
+  end
+end

data/app/lib/administrate/mcp/uploads/shrine_storage.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    module Uploads
+      # The default upload storage, on a Shrine storage (`:cache` by default). It presigns a POST
+      # whose policy bounds the content length, so the storage itself refuses a file above the
+      # maximum size. Fetching copies the uploaded object to a key no URL points to, so what is
+      # checked and attached cannot be replaced afterwards; on S3 the copy happens server side.
+      # Metadata comes from the uploader's own extraction, so the host's `determine_mime_type` and
+      # `store_dimensions` plugins apply, and runs only once the size is known to be acceptable.
+      class ShrineStorage
+        Upload = Data.define(:mime_type, :size, :value)
+
+        def initialize(uploader: 'Shrine', storage_key: :cache)
+          @uploader = uploader
+          @storage_key = storage_key.to_sym
+        end
+
+        def presignable?
+          storage.respond_to?(:presign)
+        end
+
+        def description
+          "Shrine storage :#{@storage_key} (#{storage.class.name})"
+        end
+
+        def presign(key, content_type:, max_size:, expires_in:)
+          presigned = storage.presign(key, method: :post, content_type:, content_length_range: 1..max_size,
+                                           signature_expiration: expires_in.seconds.from_now)
+          { method: 'POST', url: presigned[:url], fields: presigned[:fields] }
+        end
+
+        def fetch(key, filename:, max_size:)
+          original = uploaded_file(key, filename)
+          return unless original.exists?
+
+          copy = uploader.upload(original, location: "#{SecureRandom.uuid}#{File.extname(key)}")
+          copy.open do
+            next Upload.new(mime_type: nil, size: copy.size, value: copy.data) if copy.size.to_i > max_size
+
+            describe(copy, filename)
+          end
+        end
+
+        def delete(value)
+          uploader_class.uploaded_file(value).delete
+        end
+
+        private
+
+        def describe(file, filename)
+          metadata = file.metadata.merge(uploader.extract_metadata(file).compact, 'filename' => filename)
+          Upload.new(mime_type: metadata['mime_type'], size: metadata['size'],
+                     value: file.data.merge('metadata' => metadata))
+        end
+
+        def uploaded_file(key, filename)
+          uploader_class.uploaded_file('storage' => @storage_key.to_s, 'id' => key,
+                                       'metadata' => { 'filename' => filename })
+        end
+
+        def uploader
+          uploader_class.new(@storage_key)
+        end
+
+        def uploader_class
+          @uploader.is_a?(Class) ? @uploader : @uploader.to_s.constantize
+        end
+
+        def storage
+          uploader_class.storages.fetch(@storage_key)
+        end
+      end
+    end
+  end
+end

data/app/lib/administrate/mcp/uploads.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Presigned uploads. `prepare` checks that the caller may use the target action, records a
+    # batch, and hands out one presigned upload per file. `resolve` turns an upload_id back into an
+    # attachment value for that same action and attribute: it copies the uploaded object to a key
+    # the client cannot write to, checks the copy's real size and content type, and remembers the
+    # copy so a retried action gets the same file.
+    module Uploads
+      class << self
+        def prepare(admin:, scopes:, tool:, attribute:, files:)
+          definition = upload_action!(admin, scopes, tool.to_s, attribute.to_sym)
+          rules = rules_for(definition, attribute.to_sym)
+          storage = presignable_storage!
+          entries = build_entries(files, rules, tool: tool.to_s, attribute: attribute.to_s)
+          UploadBatch.create!(admin:, expires_at: config.batch_ttl.seconds.from_now, files: entries)
+
+          entries.to_h do |entry|
+            presigned = storage.presign(entry[:key], content_type: entry[:content_type], max_size: rules.max_size,
+                                                     expires_in: config.url_ttl.to_i)
+            [entry[:filename], { upload_id: entry[:upload_id], **presigned }]
+          end
+        end
+
+        def resolve(admin:, upload_id:, tool:, attribute:, rules:)
+          batch, entry = find_entry!(admin, upload_id.to_s, tool, attribute)
+          return entry['value'] if entry['value']
+
+          record_value(batch, upload_id.to_s, fetch!(upload_id, entry, rules).value)
+        end
+
+        def rules_for(definition, attribute)
+          config.rules(**definition.uploads.fetch(attribute))
+        end
+
+        private
+
+        def config
+          Administrate::MCP.config.uploads
+        end
+
+        def upload_action!(admin, scopes, tool, attribute)
+          definition = Actions.definitions.find { |candidate| Actions.tool_name(candidate) == tool }
+          return definition if definition&.uploads&.key?(attribute) && Actions.available_to?(admin, definition, scopes:)
+
+          raise InvalidArgumentError, "No action #{tool} that accepts an upload for #{attribute} is available to you"
+        end
+
+        def presignable_storage!
+          storage = config.storage
+          raise ConfigurationError, 'No upload storage is configured; set config.uploads.storage' unless storage
+          return storage if storage.presignable?
+
+          raise ConfigurationError, "#{storage.description} cannot presign uploads. Configure a storage that " \
+                                    'can, such as Shrine::Storage::S3, or set config.uploads.storage'
+        end
+
+        def build_entries(files, rules, **target)
+          raise InvalidArgumentError, 'files must name at least one file' if files.blank?
+          if files.size > config.max_files
+            raise InvalidArgumentError, "files can name at most #{config.max_files} files"
+          end
+
+          errors = files.flat_map { |filename, size| entry_errors(filename.to_s, size, rules) }
+          raise InvalidArgumentError, errors.join('; ') if errors.any?
+
+          files.map { |filename, size| build_entry(filename.to_s, Integer(size), rules, **target) }
+        end
+
+        def entry_errors(filename, size, rules)
+          errors = []
+          unless rules.content_type_for(filename)
+            errors << "#{filename} is not an allowed file type (#{rules.content_types.keys.join(', ')})"
+          end
+          unless Integer(size, exception: false)&.between?(1, rules.max_size)
+            errors << "#{filename} size must be between 1 and #{rules.max_size} bytes"
+          end
+          errors
+        end
+
+        def build_entry(filename, size, rules, tool:, attribute:)
+          upload_id = SecureRandom.uuid
+          extension = File.extname(filename).downcase
+          { upload_id:, key: "#{upload_id}#{extension}", filename:, content_type: rules.content_type_for(filename),
+            size:, tool:, attribute: }
+        end
+
+        def find_entry!(admin, upload_id, tool, attribute)
+          batch = UploadBatch.with_upload(upload_id).find_by(admin:)
+          raise InvalidArgumentError, "Upload #{upload_id} not found" unless batch
+          raise InvalidArgumentError, "Upload #{upload_id} expired at #{batch.expires_at.iso8601}" if batch.expired?
+
+          entry = batch.file(upload_id)
+          unless entry['tool'] == tool && entry['attribute'] == attribute
+            raise InvalidArgumentError, "Upload #{upload_id} was prepared for #{entry['tool']} #{entry['attribute']}"
+          end
+
+          [batch, entry]
+        end
+
+        def fetch!(upload_id, entry, rules)
+          upload = config.storage.fetch(entry['key'], filename: entry['filename'], max_size: rules.max_size)
+          raise InvalidArgumentError, "Upload #{upload_id} has not been uploaded yet" unless upload
+
+          error = content_error(upload_id, upload, rules)
+          return upload unless error
+
+          config.storage.delete(upload.value)
+          raise InvalidArgumentError, error
+        end
+
+        def record_value(batch, upload_id, value)
+          UploadBatch.transaction do
+            locked = UploadBatch.lock.find(batch.id)
+            recorded = locked.file(upload_id)['value']
+            next locked.record_value!(upload_id, value) && value unless recorded
+
+            config.storage.delete(value)
+            recorded
+          end
+        end
+
+        def content_error(upload_id, upload, rules)
+          if upload.size.to_i > rules.max_size
+            "Upload #{upload_id} is #{upload.size} bytes, the maximum is #{rules.max_size}"
+          elsif !rules.allowed_content_type?(upload.mime_type)
+            "Upload #{upload_id} is #{upload.mime_type || 'of an unknown type'}, " \
+              "expected one of #{rules.content_types.values.uniq.join(', ')}"
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/administrate/mcp/upload_batch.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # The files an admin was handed presigned upload URLs for. Each entry of `files` holds the
+    # upload_id given to the client, the storage key, the declared filename, content type and size,
+    # the action tool and attribute it was prepared for, and, once resolved, the checked value.
+    class UploadBatch < ApplicationRecord
+      self.table_name = 'administrate_mcp_upload_batches'
+
+      belongs_to_admin
+
+      scope :with_upload, ->(upload_id) { where('files @> ?', [{ upload_id: }].to_json) }
+      scope :expired, ->(at = Time.current) { where(expires_at: ...at) }
+
+      def expired?
+        expires_at <= Time.current
+      end
+
+      def file(upload_id)
+        files.find { |entry| entry['upload_id'] == upload_id }
+      end
+
+      def record_value!(upload_id, value)
+        update!(files: files.map { |entry| entry['upload_id'] == upload_id ? entry.merge('value' => value) : entry })
+      end
+    end
+  end
+end

data/db/migrate/20260101000004_create_administrate_model_context_protocol_upload_batches.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateAdministrateModelContextProtocolUploadBatches < ActiveRecord::Migration[8.1]
+  def change
+    admin_foreign_key = Administrate::MCP.config.admin_foreign_key
+
+    create_table :administrate_mcp_upload_batches, id: :uuid, if_not_exists: true do |t|
+      t.uuid admin_foreign_key, null: false
+      t.datetime :expires_at, null: false
+      t.jsonb :files, null: false, default: []
+
+      t.timestamps
+    end
+
+    add_index :administrate_mcp_upload_batches, admin_foreign_key, if_not_exists: true
+    add_index :administrate_mcp_upload_batches, :files, using: :gin, opclass: :jsonb_path_ops, if_not_exists: true
+  end
+end

data/docs/configuration.md

@@ -202,6 +202,7 @@ end
 | `skipped_field_classes`     | Password                           | Field class names never serialized                                                                                                                                               |
 | `has_many_field_classes`    | HasMany                            | Field class names treated as expandable collections                                                                                                                              |
 | `field_serializers`         | see above                          | Field class name to serializer                                                                                                                                                   |
+| `uploads`                   | disabled                           | Presigned uploads: `enabled`, `storage`, `allowed_content_types`, `max_size`, `max_files`, `url_ttl`, `batch_ttl`. See [Presigned uploads](uploads.md)                       |
 
 ## Authorization adapters
 

data/docs/dashboards.md

@@ -17,6 +17,14 @@ class OrderDashboard < Administrate::BaseDashboard
              params: { reason: { type: 'string', description: 'Why the order is being refunded.' } } do |record:, admin:, params:|
     Orders::Refund.call!(order: record, admin:, reason: params[:reason])
   end
+
+  mcp_action :import,
+             on: :collection,
+             destructive: false,
+             description: 'Import an order from a marketplace.',
+             params: { reference: 'The marketplace order reference.' } do |admin:, params:|
+    Orders::Import.call!(reference: params[:reference], admin:).order
+  end
 end
 ```
 
@@ -33,10 +41,36 @@ base class, is not applied to every resource. A subclass that wants one declares
   `scoped_resource`.
 - `COLLECTION_FILTERS` are published as filters; a one-argument lambda is a boolean filter, a
   two-argument one takes a value. Foreign key columns are filterable without being declared.
-- `mcp_action` publishes one tool per declaration. It requires the OAuth `write` scope, and the
-  authorization predicate (`refund?` by default, or `predicate:`) on the loaded record. The block
-  receives `record:`, `admin:` and `params:`; a result answering `success? == false` is reported as
-  an error.
+- `mcp_action` publishes one tool per declaration, named `<resource>_<action>` (`order_refund`). It
+  requires the OAuth `write` scope, and the authorization predicate (`refund?` for `:refund` by
+  default, or `predicate:`, also spelled `pundit:`), checked through `config.authorization`. Every
+  call is reported to `config.on_tool_call`.
+  - The input schema lists `params` and closes the object (`additionalProperties: false`), so an
+    argument that is not declared is refused before the action runs, and the block only ever sees
+    declared params.
+  - The block's result decides the answer. A result answering `success? == false` is an error, with
+    the result's `error` as the message when it has one. An Active Record object that was never
+    saved or has errors is an error too, with its validation messages. So is `false`, the result of
+    a failed `update` or of a `destroy` a callback aborted; for a member action the message is the
+    loaded record's validation messages when it has any. Anything else is a success, including a
+    record the block destroyed.
+  - The tool is announced as destructive unless the declaration says `destructive: false`. Clients
+    may ask for confirmation before running a destructive tool, so set it on actions that only add
+    or prepare something.
+  - A member action (`on: :member`, the default) takes an `id` (or slug), loads the record and checks
+    the predicate against it. The block receives `record:`, `admin:` and `params:`. The response
+    echoes the `id` the caller passed.
+  - A collection action (`on: :collection`) takes no `id` and loads nothing, so it suits creating a
+    record or preparing something that is not a record yet. The predicate is checked against a new
+    instance of the model, as Administrate does for `new` and `create`, both when the tool list is
+    built and on every call; a creating action usually declares `predicate: :create?`. The block
+    receives `admin:` and `params:`, and owns any scoping of what it creates, such as a tenant,
+    since no record lookup does it. The response carries the primary key of the record the block
+    returns, so return the created record for the client to act on it; a block that returns
+    something else gets a response without `id`.
+  - `uploads:` (`true`, a list of attachment attributes, or per-attribute `content_types:` and
+    `max_size:`) adds an optional `<attribute>_upload_id` param for each of them, and the block
+    receives the uploaded file as `params[:<attribute>]`. See [Presigned uploads](uploads.md).
 
 ## Search
 

data/docs/development.md

@@ -13,7 +13,10 @@ spec helper catches `ActiveRecord::NoDatabaseError` and calls `ActiveRecord::Tas
 so no separate `createdb` step is needed. Point the specs at another Postgres with
 `ADMINISTRATE_MCP_DB_HOST`, `_PORT`, `_USER`, `_PASSWORD` and `_NAME`.
 
-The dummy application under `spec/dummy` has an `Admin`, a `Widget` (with `MCP_BASE_SCOPE` and
-collection filters) and a `Gadget` (with a `belongs_to` and an `mcp_action`).
+The dummy application under `spec/dummy` has an `Admin`, a `Widget` (with `MCP_BASE_SCOPE`,
+collection filters, a Shrine `picture` attachment shown through a host-style `PictureField`, and a
+collection `mcp_action` that accepts uploads) and a `Gadget` (with a `belongs_to` and a member
+`mcp_action`). Upload specs use the `with presignable storage` shared context, which swaps the Shrine
+cache storage for an S3 storage with a stubbed client.
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md) for how to propose a change.

data/docs/uploads.md

@@ -0,0 +1,157 @@
+# Presigned uploads
+
+[Back to README](../README.md)
+
+A client such as Claude Code can upload a file and set it on an attachment attribute through an
+action, without the file passing through the MCP server:
+
+1. The client calls `uploads_prepare` with the action's `tool` name, the `attribute` and `files`,
+   an object of filename to size in bytes. Each file gets back an `upload_id`, a `method`, a `url`
+   and the `fields` (for a `POST`) or `headers` (for a `PUT`) to send.
+2. The client uploads each file. With the default storage that is a multipart `POST` carrying every
+   field, then the file:
+   `curl -F key=... -F policy=... -F file=@logo.png "<url>"`.
+3. The client calls the action with `<attribute>_upload_id`. The engine resolves it into the
+   attachment value, and the action's block receives it as `params[:<attribute>]`.
+
+```ruby
+class ArticleDashboard < Administrate::BaseDashboard
+  ATTRIBUTE_TYPES = { title: Field::String, cover: Field::Shrine, contract: Field::Shrine }.freeze
+
+  mcp_action :publish, on: :collection, predicate: :create?, destructive: false,
+                       uploads: {
+                         cover: {},
+                         contract: { content_types: { '.pdf' => 'application/pdf' }, max_size: 5 * 1024 * 1024 }
+                       },
+                       description: 'Publish an article.',
+                       params: { title: 'The title.' } do |admin:, params:|
+    Articles::Publish.call(admin:, **params.slice(:title, :cover, :contract)).article
+  end
+end
+```
+
+`uploads:` takes:
+
+- `true`, for every attribute whose field is serialized as `:attachment`:
+  `Administrate::Field::Shrine`, or any field class registered with
+  `register_field(..., as: :attachment)`. It raises when the dashboard has none.
+- a list of attributes, such as `%i[cover]`.
+- a hash of attribute to `content_types:` (extension to content type, like
+  `allowed_content_types`) and `max_size:`, which override the defaults for that attribute.
+
+An attribute that is not an attachment raises when the tools are built. So does a rule other than
+`content_types:` and `max_size:`, a `content_types:` that is not a hash of `.ext` keys, or a
+`max_size:` that is not a positive integer. A call without the param leaves `params[:<attribute>]`
+unset.
+
+Out of the box, uploads work with Shrine: `Administrate::Field::Shrine` is the only field mapped to
+`:attachment` by default, and the default storage is a Shrine storage. An Active Storage dashboard
+gets no upload param until its field is registered as `:attachment` and `config.uploads.storage` is
+set to a storage for it.
+
+## Enabling
+
+```ruby
+Administrate::MCP.configure do |c|
+  c.uploads.enabled = true
+end
+```
+
+Uploads need the `administrate_mcp_upload_batches` table, created by the engine's migrations
+(`bin/rails administrate_mcp:install:migrations`). While `enabled` is `false`, the default,
+`uploads_prepare` is not published, actions publish no upload param, and the table is never used.
+
+| Setting                 | Default                     | Meaning                                                              |
+| ----------------------- | --------------------------- | -------------------------------------------------------------------- |
+| `enabled`               | `false`                     | Publish `uploads_prepare` and the upload params                      |
+| `storage`               | the Shrine `:cache` storage | Where files are uploaded; see below                                  |
+| `allowed_content_types` | png, jpg, jpeg, webp        | Default file extension (with the dot) to content type                |
+| `max_size`              | 10 MB                       | Default largest file in bytes                                        |
+| `max_files`             | 10                          | Most files one `uploads_prepare` call can prepare                    |
+| `url_ttl`               | 15 minutes                  | How long a presigned URL is valid, in seconds                        |
+| `batch_ttl`             | 1 hour                      | How long an `upload_id` can be resolved, in seconds                  |
+
+Do not allow `image/svg+xml`, `text/html` or another type a browser runs. The object is served from
+the bucket with that type, so such a file is stored cross-site scripting for anyone who opens it.
+
+## Checks
+
+`uploads_prepare` requires the OAuth `write` scope and the `default_required_roles`, and is only
+published to a caller who can use an action that accepts uploads. It refuses the call unless the
+named action exists, accepts an upload for the named attribute, and is available to the caller: its
+scope is granted and its predicate passes, the same check that decides whether the action is
+listed. It also refuses a file whose extension
+is not allowed for that attribute, a declared size above its maximum, and more than `max_files`
+files, and records nothing in that case.
+
+Resolving an `upload_id` checks that:
+
+- it was handed out to the calling admin. Another admin's `upload_id` is answered as not found;
+- it was prepared for this action and attribute;
+- its batch has not expired;
+- the file was uploaded;
+- the file's real size is at most the maximum. The default storage's presigned `POST` already makes
+  the storage refuse a larger file; the size is read again before any content is;
+- the file's real content type, read from its content, is allowed, whatever its extension.
+
+The checks run on a copy of the uploaded object, under a key no presigned URL points to, and the
+action receives that copy. Uploading again to the same URL afterwards changes nothing that was
+checked. A copy that fails a check is deleted. The checked copy is remembered: passing the same
+`upload_id` again, for example after the action failed on another param, returns it without a new
+upload. The storage is read outside any database transaction; only recording the checked copy
+locks the batch row, and if two calls race, the first recorded copy wins and the other is deleted.
+
+A failed check is a tool error and the action's block does not run.
+
+## Clean-up
+
+Expired batches stay in the table until removed. Call `Administrate::MCP::CleanExpiredUploadBatches`
+from your scheduler; it deletes up to 10,000 expired batches per call and reports `more?` when there
+may be others:
+
+```ruby
+loop { break unless Administrate::MCP::CleanExpiredUploadBatches.call.more? }
+```
+
+The uploaded objects and their checked copies are not deleted by the engine. Give the bucket a
+lifecycle rule that expires the cache prefix after a period longer than `batch_ttl`. Shrine copies
+the file from the cache to its permanent storage when it promotes it.
+
+## Storage
+
+When Shrine is loaded, the default storage is `Administrate::MCP::Uploads::ShrineStorage`, which
+presigns a `POST` on `Shrine.storages[:cache]` with a policy bounding the content length, and copies
+an uploaded object to a fresh key before checking it. On S3 the copy is server side.
+
+- The storage must be able to presign: `Shrine::Storage::S3` can, `FileSystem` and `Memory`
+  cannot, and `uploads_prepare` answers with an error naming the storage.
+- The content type comes from the uploader's own metadata extraction, so load Shrine's
+  `determine_mime_type` plugin. Without it the type is unknown and every upload is refused.
+  Plugins such as `store_dimensions` add their metadata too.
+- Pass a different uploader or storage with
+  `c.uploads.storage = Administrate::MCP::Uploads::ShrineStorage.new(uploader: 'ImageUploader', storage_key: :cache)`.
+  The uploader is a class or a class name.
+
+The gem does not depend on Shrine or the AWS SDK. A host without Shrine sets `storage` to an object
+answering:
+
+```ruby
+class MyStorage
+  def presignable? = true
+  def description = 'my storage'
+
+  # => { method: 'POST', url: 'https://...', fields: { ... } }
+  #    or { method: 'PUT', url: 'https://...', headers: { 'Content-Type' => content_type } }
+  #    The storage should refuse a file above max_size.
+  def presign(key, content_type:, max_size:, expires_in:); end
+
+  # => nil when nothing was uploaded under key, otherwise an object answering mime_type, size
+  #    and value (what the action receives as params[:<attribute>]). Copy the object to a key the
+  #    client cannot write to and describe the copy, and when it is above max_size, return its size
+  #    without reading the content.
+  def fetch(key, filename:, max_size:); end
+
+  # Deletes the copy behind a value fetch returned, when it failed a check or lost a race.
+  def delete(value); end
+end
+```

data/lib/administrate/mcp/configuration.rb

@@ -5,6 +5,7 @@ require 'administrate/mcp/version'
 require 'administrate/mcp/authorization/base'
 require 'administrate/mcp/authorization/permissive'
 require 'administrate/mcp/authorization/pundit'
+require 'administrate/mcp/uploads_configuration'
 
 module Administrate
   module MCP
@@ -64,7 +65,7 @@ module Administrate
                     :has_many_field_classes,
                     :field_serializers
 
-      attr_reader :api_key_token_prefix
+      attr_reader :api_key_token_prefix, :uploads
 
       def initialize
         assign_identity
@@ -101,6 +102,7 @@ module Administrate
         @persist_feedback = false
         @feedback_tool = true
         @sidekiq_stats_provider = nil
+        @uploads = UploadsConfiguration.new
       end
 
       def assign_fields

data/lib/administrate/mcp/uploads_configuration.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Settings for presigned uploads: the `uploads_prepare` tool and the `<attribute>_upload_id`
+    # params of actions declared with `uploads:`. Off until the host enables it, because it needs
+    # the upload batches table. `allowed_content_types` and `max_size` are defaults an action can
+    # override per attribute.
+    class UploadsConfiguration
+      CONTENT_TYPES = {
+        '.png' => 'image/png',
+        '.jpg' => 'image/jpeg',
+        '.jpeg' => 'image/jpeg',
+        '.webp' => 'image/webp'
+      }.freeze
+
+      Rules =
+        Data.define(:content_types, :max_size) do
+          def content_type_for(filename)
+            content_types[File.extname(filename.to_s).downcase]
+          end
+
+          def allowed_content_type?(content_type)
+            content_types.value?(content_type)
+          end
+        end
+
+      attr_accessor :enabled, :allowed_content_types, :max_size, :max_files, :url_ttl, :batch_ttl
+      attr_writer :storage
+
+      def initialize
+        @enabled = false
+        @storage = nil
+        @allowed_content_types = CONTENT_TYPES.dup
+        @max_size = 10 * 1024 * 1024
+        @max_files = 10
+        @url_ttl = 15 * 60
+        @batch_ttl = 60 * 60
+      end
+
+      def storage
+        @storage || (Uploads::ShrineStorage.new if defined?(::Shrine))
+      end
+
+      def rules(content_types: nil, max_size: nil)
+        Rules.new(content_types: (content_types || allowed_content_types).transform_keys(&:to_s),
+                  max_size: max_size || self.max_size)
+      end
+    end
+  end
+end

data/lib/administrate/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module Administrate
   module MCP
-    VERSION = '0.3.1'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: administrate-mcp
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Sorare
@@ -93,6 +93,7 @@ files:
 - app/lib/administrate/mcp/admin_dashboard_tool.rb
 - app/lib/administrate/mcp/authentication.rb
 - app/lib/administrate/mcp/base_tool.rb
+- app/lib/administrate/mcp/clean_expired_upload_batches.rb
 - app/lib/administrate/mcp/clean_old_feedbacks.rb
 - app/lib/administrate/mcp/dashboard_registry.rb
 - app/lib/administrate/mcp/fast_search.rb
@@ -109,17 +110,23 @@ files:
 - app/lib/administrate/mcp/tools/report_improvement.rb
 - app/lib/administrate/mcp/tools/sidekiq_retries.rb
 - app/lib/administrate/mcp/tools/sidekiq_stats.rb
+- app/lib/administrate/mcp/tools/uploads_prepare.rb
+- app/lib/administrate/mcp/uploads.rb
+- app/lib/administrate/mcp/uploads/declarations.rb
+- app/lib/administrate/mcp/uploads/shrine_storage.rb
 - app/models/administrate/mcp/api_key.rb
 - app/models/administrate/mcp/application_record.rb
 - app/models/administrate/mcp/feedback.rb
 - app/models/administrate/mcp/o_auth_access_grant.rb
 - app/models/administrate/mcp/o_auth_access_token.rb
 - app/models/administrate/mcp/o_auth_application.rb
+- app/models/administrate/mcp/upload_batch.rb
 - app/views/administrate/mcp/o_auth/authorize.html.erb
 - config/routes.rb
 - db/migrate/20260101000001_create_administrate_model_context_protocol_api_keys.rb
 - db/migrate/20260101000002_create_administrate_model_context_protocol_feedbacks.rb
 - db/migrate/20260101000003_create_administrate_model_context_protocol_authorization_tables.rb
+- db/migrate/20260101000004_create_administrate_model_context_protocol_upload_batches.rb
 - docs/admin-integration.md
 - docs/authentication.md
 - docs/configuration.md
@@ -127,6 +134,7 @@ files:
 - docs/development.md
 - docs/oauth.md
 - docs/routes.md
+- docs/uploads.md
 - lib/administrate-mcp.rb
 - lib/administrate/mcp.rb
 - lib/administrate/mcp/authorization/base.rb
@@ -140,6 +148,7 @@ files:
 - lib/administrate/mcp/loopback_uri.rb
 - lib/administrate/mcp/rack_attack.rb
 - lib/administrate/mcp/routes.rb
+- lib/administrate/mcp/uploads_configuration.rb
 - lib/administrate/mcp/version.rb
 homepage: https://github.com/sorare/administrate-mcp
 licenses: