administrate-mcp 0.3.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/docs/uploads.md ADDED
@@ -0,0 +1,157 @@
1
+ # Presigned uploads
2
+
3
+ [Back to README](../README.md)
4
+
5
+ A client such as Claude Code can upload a file and set it on an attachment attribute through an
6
+ action, without the file passing through the MCP server:
7
+
8
+ 1. The client calls `uploads_prepare` with the action's `tool` name, the `attribute` and `files`,
9
+ an object of filename to size in bytes. Each file gets back an `upload_id`, a `method`, a `url`
10
+ and the `fields` (for a `POST`) or `headers` (for a `PUT`) to send.
11
+ 2. The client uploads each file. With the default storage that is a multipart `POST` carrying every
12
+ field, then the file:
13
+ `curl -F key=... -F policy=... -F file=@logo.png "<url>"`.
14
+ 3. The client calls the action with `<attribute>_upload_id`. The engine resolves it into the
15
+ attachment value, and the action's block receives it as `params[:<attribute>]`.
16
+
17
+ ```ruby
18
+ class ArticleDashboard < Administrate::BaseDashboard
19
+ ATTRIBUTE_TYPES = { title: Field::String, cover: Field::Shrine, contract: Field::Shrine }.freeze
20
+
21
+ mcp_action :publish, on: :collection, predicate: :create?, destructive: false,
22
+ uploads: {
23
+ cover: {},
24
+ contract: { content_types: { '.pdf' => 'application/pdf' }, max_size: 5 * 1024 * 1024 }
25
+ },
26
+ description: 'Publish an article.',
27
+ params: { title: 'The title.' } do |admin:, params:|
28
+ Articles::Publish.call(admin:, **params.slice(:title, :cover, :contract)).article
29
+ end
30
+ end
31
+ ```
32
+
33
+ `uploads:` takes:
34
+
35
+ - `true`, for every attribute whose field is serialized as `:attachment`:
36
+ `Administrate::Field::Shrine`, or any field class registered with
37
+ `register_field(..., as: :attachment)`. It raises when the dashboard has none.
38
+ - a list of attributes, such as `%i[cover]`.
39
+ - a hash of attribute to `content_types:` (extension to content type, like
40
+ `allowed_content_types`) and `max_size:`, which override the defaults for that attribute.
41
+
42
+ An attribute that is not an attachment raises when the tools are built. So does a rule other than
43
+ `content_types:` and `max_size:`, a `content_types:` that is not a hash of `.ext` keys, or a
44
+ `max_size:` that is not a positive integer. A call without the param leaves `params[:<attribute>]`
45
+ unset.
46
+
47
+ Out of the box, uploads work with Shrine: `Administrate::Field::Shrine` is the only field mapped to
48
+ `:attachment` by default, and the default storage is a Shrine storage. An Active Storage dashboard
49
+ gets no upload param until its field is registered as `:attachment` and `config.uploads.storage` is
50
+ set to a storage for it.
51
+
52
+ ## Enabling
53
+
54
+ ```ruby
55
+ Administrate::MCP.configure do |c|
56
+ c.uploads.enabled = true
57
+ end
58
+ ```
59
+
60
+ Uploads need the `administrate_mcp_upload_batches` table, created by the engine's migrations
61
+ (`bin/rails administrate_mcp:install:migrations`). While `enabled` is `false`, the default,
62
+ `uploads_prepare` is not published, actions publish no upload param, and the table is never used.
63
+
64
+ | Setting | Default | Meaning |
65
+ | ----------------------- | --------------------------- | -------------------------------------------------------------------- |
66
+ | `enabled` | `false` | Publish `uploads_prepare` and the upload params |
67
+ | `storage` | the Shrine `:cache` storage | Where files are uploaded; see below |
68
+ | `allowed_content_types` | png, jpg, jpeg, webp | Default file extension (with the dot) to content type |
69
+ | `max_size` | 10 MB | Default largest file in bytes |
70
+ | `max_files` | 10 | Most files one `uploads_prepare` call can prepare |
71
+ | `url_ttl` | 15 minutes | How long a presigned URL is valid, in seconds |
72
+ | `batch_ttl` | 1 hour | How long an `upload_id` can be resolved, in seconds |
73
+
74
+ Do not allow `image/svg+xml`, `text/html` or another type a browser runs. The object is served from
75
+ the bucket with that type, so such a file is stored cross-site scripting for anyone who opens it.
76
+
77
+ ## Checks
78
+
79
+ `uploads_prepare` requires the OAuth `write` scope and the `default_required_roles`, and is only
80
+ published to a caller who can use an action that accepts uploads. It refuses the call unless the
81
+ named action exists, accepts an upload for the named attribute, and is available to the caller: its
82
+ scope is granted and its predicate passes, the same check that decides whether the action is
83
+ listed. It also refuses a file whose extension
84
+ is not allowed for that attribute, a declared size above its maximum, and more than `max_files`
85
+ files, and records nothing in that case.
86
+
87
+ Resolving an `upload_id` checks that:
88
+
89
+ - it was handed out to the calling admin. Another admin's `upload_id` is answered as not found;
90
+ - it was prepared for this action and attribute;
91
+ - its batch has not expired;
92
+ - the file was uploaded;
93
+ - the file's real size is at most the maximum. The default storage's presigned `POST` already makes
94
+ the storage refuse a larger file; the size is read again before any content is;
95
+ - the file's real content type, read from its content, is allowed, whatever its extension.
96
+
97
+ The checks run on a copy of the uploaded object, under a key no presigned URL points to, and the
98
+ action receives that copy. Uploading again to the same URL afterwards changes nothing that was
99
+ checked. A copy that fails a check is deleted. The checked copy is remembered: passing the same
100
+ `upload_id` again, for example after the action failed on another param, returns it without a new
101
+ upload. The storage is read outside any database transaction; only recording the checked copy
102
+ locks the batch row, and if two calls race, the first recorded copy wins and the other is deleted.
103
+
104
+ A failed check is a tool error and the action's block does not run.
105
+
106
+ ## Clean-up
107
+
108
+ Expired batches stay in the table until removed. Call `Administrate::MCP::CleanExpiredUploadBatches`
109
+ from your scheduler; it deletes up to 10,000 expired batches per call and reports `more?` when there
110
+ may be others:
111
+
112
+ ```ruby
113
+ loop { break unless Administrate::MCP::CleanExpiredUploadBatches.call.more? }
114
+ ```
115
+
116
+ The uploaded objects and their checked copies are not deleted by the engine. Give the bucket a
117
+ lifecycle rule that expires the cache prefix after a period longer than `batch_ttl`. Shrine copies
118
+ the file from the cache to its permanent storage when it promotes it.
119
+
120
+ ## Storage
121
+
122
+ When Shrine is loaded, the default storage is `Administrate::MCP::Uploads::ShrineStorage`, which
123
+ presigns a `POST` on `Shrine.storages[:cache]` with a policy bounding the content length, and copies
124
+ an uploaded object to a fresh key before checking it. On S3 the copy is server side.
125
+
126
+ - The storage must be able to presign: `Shrine::Storage::S3` can, `FileSystem` and `Memory`
127
+ cannot, and `uploads_prepare` answers with an error naming the storage.
128
+ - The content type comes from the uploader's own metadata extraction, so load Shrine's
129
+ `determine_mime_type` plugin. Without it the type is unknown and every upload is refused.
130
+ Plugins such as `store_dimensions` add their metadata too.
131
+ - Pass a different uploader or storage with
132
+ `c.uploads.storage = Administrate::MCP::Uploads::ShrineStorage.new(uploader: 'ImageUploader', storage_key: :cache)`.
133
+ The uploader is a class or a class name.
134
+
135
+ The gem does not depend on Shrine or the AWS SDK. A host without Shrine sets `storage` to an object
136
+ answering:
137
+
138
+ ```ruby
139
+ class MyStorage
140
+ def presignable? = true
141
+ def description = 'my storage'
142
+
143
+ # => { method: 'POST', url: 'https://...', fields: { ... } }
144
+ # or { method: 'PUT', url: 'https://...', headers: { 'Content-Type' => content_type } }
145
+ # The storage should refuse a file above max_size.
146
+ def presign(key, content_type:, max_size:, expires_in:); end
147
+
148
+ # => nil when nothing was uploaded under key, otherwise an object answering mime_type, size
149
+ # and value (what the action receives as params[:<attribute>]). Copy the object to a key the
150
+ # client cannot write to and describe the copy, and when it is above max_size, return its size
151
+ # without reading the content.
152
+ def fetch(key, filename:, max_size:); end
153
+
154
+ # Deletes the copy behind a value fetch returned, when it failed a check or lost a race.
155
+ def delete(value); end
156
+ end
157
+ ```
@@ -5,6 +5,7 @@ require 'administrate/mcp/version'
5
5
  require 'administrate/mcp/authorization/base'
6
6
  require 'administrate/mcp/authorization/permissive'
7
7
  require 'administrate/mcp/authorization/pundit'
8
+ require 'administrate/mcp/uploads_configuration'
8
9
 
9
10
  module Administrate
10
11
  module MCP
@@ -58,13 +59,14 @@ module Administrate
58
59
  :persist_feedback,
59
60
  :feedback_tool,
60
61
  :sidekiq_stats_provider,
62
+ :action_data_max_bytes,
61
63
  :admin_route_namespace,
62
64
  :admin_url_options,
63
65
  :skipped_field_classes,
64
66
  :has_many_field_classes,
65
67
  :field_serializers
66
68
 
67
- attr_reader :api_key_token_prefix
69
+ attr_reader :api_key_token_prefix, :uploads
68
70
 
69
71
  def initialize
70
72
  assign_identity
@@ -101,6 +103,8 @@ module Administrate
101
103
  @persist_feedback = false
102
104
  @feedback_tool = true
103
105
  @sidekiq_stats_provider = nil
106
+ @action_data_max_bytes = 32_768
107
+ @uploads = UploadsConfiguration.new
104
108
  end
105
109
 
106
110
  def assign_fields
@@ -0,0 +1,51 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Administrate
4
+ module MCP
5
+ # Settings for presigned uploads: the `uploads_prepare` tool and the `<attribute>_upload_id`
6
+ # params of actions declared with `uploads:`. Off until the host enables it, because it needs
7
+ # the upload batches table. `allowed_content_types` and `max_size` are defaults an action can
8
+ # override per attribute.
9
+ class UploadsConfiguration
10
+ CONTENT_TYPES = {
11
+ '.png' => 'image/png',
12
+ '.jpg' => 'image/jpeg',
13
+ '.jpeg' => 'image/jpeg',
14
+ '.webp' => 'image/webp'
15
+ }.freeze
16
+
17
+ Rules =
18
+ Data.define(:content_types, :max_size) do
19
+ def content_type_for(filename)
20
+ content_types[File.extname(filename.to_s).downcase]
21
+ end
22
+
23
+ def allowed_content_type?(content_type)
24
+ content_types.value?(content_type)
25
+ end
26
+ end
27
+
28
+ attr_accessor :enabled, :allowed_content_types, :max_size, :max_files, :url_ttl, :batch_ttl
29
+ attr_writer :storage
30
+
31
+ def initialize
32
+ @enabled = false
33
+ @storage = nil
34
+ @allowed_content_types = CONTENT_TYPES.dup
35
+ @max_size = 10 * 1024 * 1024
36
+ @max_files = 10
37
+ @url_ttl = 15 * 60
38
+ @batch_ttl = 60 * 60
39
+ end
40
+
41
+ def storage
42
+ @storage || (Uploads::ShrineStorage.new if defined?(::Shrine))
43
+ end
44
+
45
+ def rules(content_types: nil, max_size: nil)
46
+ Rules.new(content_types: (content_types || allowed_content_types).transform_keys(&:to_s),
47
+ max_size: max_size || self.max_size)
48
+ end
49
+ end
50
+ end
51
+ end
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Administrate
4
4
  module MCP
5
- VERSION = '0.3.1'
5
+ VERSION = '0.5.0'
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: administrate-mcp
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.3.1
4
+ version: 0.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Sorare
@@ -89,10 +89,13 @@ files:
89
89
  - app/controllers/concerns/administrate/mcp/resource_controller.rb
90
90
  - app/dashboards/administrate/mcp/api_key_dashboard.rb
91
91
  - app/dashboards/administrate/mcp/feedback_dashboard.rb
92
+ - app/lib/administrate/mcp/action_result.rb
92
93
  - app/lib/administrate/mcp/actions.rb
94
+ - app/lib/administrate/mcp/actions/result_data.rb
93
95
  - app/lib/administrate/mcp/admin_dashboard_tool.rb
94
96
  - app/lib/administrate/mcp/authentication.rb
95
97
  - app/lib/administrate/mcp/base_tool.rb
98
+ - app/lib/administrate/mcp/clean_expired_upload_batches.rb
96
99
  - app/lib/administrate/mcp/clean_old_feedbacks.rb
97
100
  - app/lib/administrate/mcp/dashboard_registry.rb
98
101
  - app/lib/administrate/mcp/fast_search.rb
@@ -109,17 +112,23 @@ files:
109
112
  - app/lib/administrate/mcp/tools/report_improvement.rb
110
113
  - app/lib/administrate/mcp/tools/sidekiq_retries.rb
111
114
  - app/lib/administrate/mcp/tools/sidekiq_stats.rb
115
+ - app/lib/administrate/mcp/tools/uploads_prepare.rb
116
+ - app/lib/administrate/mcp/uploads.rb
117
+ - app/lib/administrate/mcp/uploads/declarations.rb
118
+ - app/lib/administrate/mcp/uploads/shrine_storage.rb
112
119
  - app/models/administrate/mcp/api_key.rb
113
120
  - app/models/administrate/mcp/application_record.rb
114
121
  - app/models/administrate/mcp/feedback.rb
115
122
  - app/models/administrate/mcp/o_auth_access_grant.rb
116
123
  - app/models/administrate/mcp/o_auth_access_token.rb
117
124
  - app/models/administrate/mcp/o_auth_application.rb
125
+ - app/models/administrate/mcp/upload_batch.rb
118
126
  - app/views/administrate/mcp/o_auth/authorize.html.erb
119
127
  - config/routes.rb
120
128
  - db/migrate/20260101000001_create_administrate_model_context_protocol_api_keys.rb
121
129
  - db/migrate/20260101000002_create_administrate_model_context_protocol_feedbacks.rb
122
130
  - db/migrate/20260101000003_create_administrate_model_context_protocol_authorization_tables.rb
131
+ - db/migrate/20260101000004_create_administrate_model_context_protocol_upload_batches.rb
123
132
  - docs/admin-integration.md
124
133
  - docs/authentication.md
125
134
  - docs/configuration.md
@@ -127,6 +136,7 @@ files:
127
136
  - docs/development.md
128
137
  - docs/oauth.md
129
138
  - docs/routes.md
139
+ - docs/uploads.md
130
140
  - lib/administrate-mcp.rb
131
141
  - lib/administrate/mcp.rb
132
142
  - lib/administrate/mcp/authorization/base.rb
@@ -140,6 +150,7 @@ files:
140
150
  - lib/administrate/mcp/loopback_uri.rb
141
151
  - lib/administrate/mcp/rack_attack.rb
142
152
  - lib/administrate/mcp/routes.rb
153
+ - lib/administrate/mcp/uploads_configuration.rb
143
154
  - lib/administrate/mcp/version.rb
144
155
  homepage: https://github.com/sorare/administrate-mcp
145
156
  licenses: