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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +68 -1
- data/README.md +17 -3
- data/app/lib/administrate/mcp/action_result.rb +36 -0
- data/app/lib/administrate/mcp/actions/result_data.rb +96 -0
- data/app/lib/administrate/mcp/actions.rb +87 -36
- data/app/lib/administrate/mcp/base_tool.rb +14 -5
- data/app/lib/administrate/mcp/clean_expired_upload_batches.rb +27 -0
- data/app/lib/administrate/mcp/field_serializer.rb +4 -0
- data/app/lib/administrate/mcp/server_builder.rb +7 -1
- data/app/lib/administrate/mcp/tools/uploads_prepare.rb +48 -0
- data/app/lib/administrate/mcp/uploads/declarations.rb +106 -0
- data/app/lib/administrate/mcp/uploads/shrine_storage.rb +77 -0
- data/app/lib/administrate/mcp/uploads.rb +135 -0
- data/app/models/administrate/mcp/upload_batch.rb +29 -0
- data/db/migrate/20260101000004_create_administrate_model_context_protocol_upload_batches.rb +18 -0
- data/docs/configuration.md +4 -0
- data/docs/dashboards.md +93 -4
- data/docs/development.md +5 -2
- data/docs/uploads.md +157 -0
- data/lib/administrate/mcp/configuration.rb +5 -1
- data/lib/administrate/mcp/uploads_configuration.rb +51 -0
- data/lib/administrate/mcp/version.rb +1 -1
- metadata +12 -1
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
|
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.
|
|
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:
|