administrate-mcp 0.4.0 → 0.6.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 +49 -1
- data/README.md +12 -0
- 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 +24 -7
- data/app/lib/administrate/mcp/base_tool.rb +32 -4
- data/app/lib/administrate/mcp/feedback_categories.rb +2 -1
- data/app/lib/administrate/mcp/server_builder.rb +10 -1
- data/app/lib/administrate/mcp/tool_view.rb +125 -0
- data/app/lib/administrate/mcp/tool_views/field_hints.rb +78 -0
- data/app/lib/administrate/mcp/tool_views/resource_view.rb +17 -0
- data/app/lib/administrate/mcp/tool_views/sidekiq_view.rb +17 -0
- data/app/lib/administrate/mcp/tools/admin_resource_list.rb +4 -1
- data/app/lib/administrate/mcp/tools/admin_resource_show.rb +11 -4
- data/app/lib/administrate/mcp/tools/report_improvement.rb +2 -1
- data/app/lib/administrate/mcp/tools/sidekiq_retries.rb +1 -0
- data/app/lib/administrate/mcp/tools/sidekiq_stats.rb +1 -0
- data/docs/configuration.md +5 -0
- data/docs/dashboards.md +60 -1
- data/docs/tool-views.md +135 -0
- data/lib/administrate/mcp/configuration.rb +6 -0
- data/lib/administrate/mcp/tool_views/resource.css +25 -0
- data/lib/administrate/mcp/tool_views/resource.js +384 -0
- data/lib/administrate/mcp/tool_views/runtime.css +112 -0
- data/lib/administrate/mcp/tool_views/runtime.js +296 -0
- data/lib/administrate/mcp/tool_views/sidekiq.css +6 -0
- data/lib/administrate/mcp/tool_views/sidekiq.js +108 -0
- data/lib/administrate/mcp/version.rb +1 -1
- metadata +14 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: c350ad45d3f07a28fb76136a472895c5ab803c56771ade63fdfdba70a78bc874
|
|
4
|
+
data.tar.gz: a31ed7ff75cbb2ee5dcacbe581701a46ef3358bb9d77760a3ae91dfe5938cd93
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 27e3a249e626a6ec2413866c87517cf418ef07a6dd25af0d048a122b4cbc92a762e3d18175522b508aa1a620b9159c7791e422ae9f5415d61000487dcb0402dc
|
|
7
|
+
data.tar.gz: 1f5e1a59ce398562594dbf27606402e435da36391ca9a8f8c4d34443fcf33a59ebeccec925c2053290942a9c9de3629d1e9e1f7b65514296c1c75174b3254e51
|
data/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,52 @@ minor release may change behaviour a host depends on; the entry says so when it
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
## [0.6.0] - 2026-10-28
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- Tool views, the server side of the MCP Apps extension (SEP-1865), off until a host sets
|
|
16
|
+
`config.tool_views = true`. The server then declares the `io.modelcontextprotocol/ui` extension,
|
|
17
|
+
publishes each linked view as a `ui://<server-name>/<view>` resource, and links tools to them in
|
|
18
|
+
`_meta.ui.resourceUri`. `admin_resource_list` and `admin_resource_show` render in a resource view
|
|
19
|
+
that pages, sorts, searches and follows associations through `tools/call`, and add a
|
|
20
|
+
`_meta["administrate-mcp/view"]` entry to their result describing the returned fields;
|
|
21
|
+
`sidekiq_stats` and `sidekiq_retries` render in a Sidekiq view; an `mcp_action` renders in the
|
|
22
|
+
resource view, which confirms the action and loads the record it saved. A host builds its own view by
|
|
23
|
+
subclassing `Administrate::MCP::ToolView` and links it with `tool_view` on a tool or `view:` on an
|
|
24
|
+
`mcp_action`. `config.tool_view_csp` declares the origins views may load from. A view tells the
|
|
25
|
+
client what is on screen by resource and id only, and field hints name only resources the caller
|
|
26
|
+
can list. With views off, `tools/list`, `resources/list` and every tool result are unchanged. See
|
|
27
|
+
[Tool views](docs/tool-views.md).
|
|
28
|
+
- A `missing_view` category for `report_mcp_improvement`, for a result that would be easier to
|
|
29
|
+
browse or act on as a tool view. It is stored as `6`.
|
|
30
|
+
|
|
31
|
+
## [0.5.0] - 2026-10-22
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
|
|
35
|
+
- An `mcp_action` block can send data back to the client. It returns
|
|
36
|
+
`Administrate::MCP::ActionResult.success(record:, data:)`, or any result object answering
|
|
37
|
+
`mcp_data`, and the answer gains a `data` key next to `status`, `model`, `id` and `action`, which
|
|
38
|
+
are unchanged. The record, optional, goes through the same checks as a record returned directly,
|
|
39
|
+
so an unsaved or invalid one is still an error and a collection action still answers its `id`.
|
|
40
|
+
`ActionResult.failure(message, data:)` is an error whose first content block is the message, as
|
|
41
|
+
before; when there is data, a second block carries `{ "error": message, "data": … }` as JSON and
|
|
42
|
+
the result's `structuredContent` carries the same object. The data must be a Hash of plain JSON
|
|
43
|
+
values nested at most 32 levels deep, with valid UTF-8 strings; the engine encodes a copy
|
|
44
|
+
built from those values, never the host's objects, and its JSON may be at most
|
|
45
|
+
`config.action_data_max_bytes` (new, 32 KB by default, `nil` for no limit). Anything else is
|
|
46
|
+
answered as an error naming the offending path and saying the action ran. A plain Hash returned
|
|
47
|
+
by a block is still not sent back. See
|
|
48
|
+
[Returning data from an action](docs/dashboards.md#returning-data-from-an-action).
|
|
49
|
+
|
|
50
|
+
### Changed
|
|
51
|
+
|
|
52
|
+
- A successful `mcp_action` call now also returns its answer as the result's `structuredContent`,
|
|
53
|
+
the same object as the JSON in its text content, which is unchanged.
|
|
54
|
+
- A tool error may now carry a second content block. Clients that read only the first block still
|
|
55
|
+
get the message on its own; only failures that return data add the second block.
|
|
56
|
+
|
|
11
57
|
## [0.4.0] - 2026-10-21
|
|
12
58
|
|
|
13
59
|
### Added
|
|
@@ -177,7 +223,9 @@ minor release may change behaviour a host depends on; the entry says so when it
|
|
|
177
223
|
took the gem from git before 0.1.0 must reinstall its migrations rather than migrate
|
|
178
224
|
incrementally.
|
|
179
225
|
|
|
180
|
-
[Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.
|
|
226
|
+
[Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.6.0...HEAD
|
|
227
|
+
[0.6.0]: https://github.com/sorare/administrate-mcp/compare/v0.5.0...v0.6.0
|
|
228
|
+
[0.5.0]: https://github.com/sorare/administrate-mcp/compare/v0.4.0...v0.5.0
|
|
181
229
|
[0.4.0]: https://github.com/sorare/administrate-mcp/compare/v0.3.1...v0.4.0
|
|
182
230
|
[0.3.1]: https://github.com/sorare/administrate-mcp/compare/v0.3.0...v0.3.1
|
|
183
231
|
[0.3.0]: https://github.com/sorare/administrate-mcp/compare/v0.2.0...v0.3.0
|
data/README.md
CHANGED
|
@@ -22,6 +22,7 @@ permissions the admin UI enforces.
|
|
|
22
22
|
- [Routes](#routes)
|
|
23
23
|
- [Dashboard declarations](#dashboard-declarations)
|
|
24
24
|
- [Presigned uploads](#presigned-uploads)
|
|
25
|
+
- [Tool views](#tool-views)
|
|
25
26
|
- [Authentication](#authentication)
|
|
26
27
|
- [OAuth](#oauth)
|
|
27
28
|
- [Improving the server from its own use](#improving-the-server-from-its-own-use)
|
|
@@ -54,6 +55,9 @@ about your application; everything host-specific goes through `Administrate::MCP
|
|
|
54
55
|
`<attribute>_upload_id` for each attachment attribute. The file's owner, target, expiry, real size
|
|
55
56
|
and real content type are checked on a copy the client cannot overwrite before the action runs.
|
|
56
57
|
See [Presigned uploads](docs/uploads.md).
|
|
58
|
+
- Tool views, opt-in: MCP Apps clients render list and show results as a browsable table and
|
|
59
|
+
record page, and Sidekiq results as a panel, and a host can attach views of its own to a tool or
|
|
60
|
+
an `mcp_action`. The model's text result is unchanged. See [Tool views](docs/tool-views.md).
|
|
57
61
|
- Three ways to authenticate a caller: API keys stored as a digest, an external identity provider
|
|
58
62
|
through `identity_fallback` (a Cloudflare Access verifier ships with the gem), and an optional
|
|
59
63
|
built-in OAuth 2.1 server with Dynamic Client Registration, PKCE and refresh tokens, on by default
|
|
@@ -233,6 +237,13 @@ readable fields and writable actions: [docs/dashboards.md](docs/dashboards.md).
|
|
|
233
237
|
How a client uploads a file to a presigned URL and sets it on an attachment through an action, the
|
|
234
238
|
checks on the uploaded file, and the storage it goes to: [docs/uploads.md](docs/uploads.md).
|
|
235
239
|
|
|
240
|
+
## Tool views
|
|
241
|
+
|
|
242
|
+
Interactive views an MCP Apps client renders in place of a tool's text result: a table of records
|
|
243
|
+
with paging, sorting, search and association links for `admin_resource_list` and
|
|
244
|
+
`admin_resource_show`, a Sidekiq panel, and a base class for views of your own. Off until
|
|
245
|
+
`config.tool_views` is set: [docs/tool-views.md](docs/tool-views.md).
|
|
246
|
+
|
|
236
247
|
## Authentication
|
|
237
248
|
|
|
238
249
|
How a request is authenticated (API key, then OAuth token, then `identity_fallback`), how to issue
|
|
@@ -264,6 +275,7 @@ Each one names a change you make in a dashboard:
|
|
|
264
275
|
| `missing_field` | a field the caller needed is not on the show page |
|
|
265
276
|
| `missing_resource` | a dashboard is not exposed, or does not exist |
|
|
266
277
|
| `serialization` | a field came back unreadable and needs a serializer registered |
|
|
278
|
+
| `missing_view` | a result the person needed to browse, compare or act on would be better as a [tool view](docs/tool-views.md) |
|
|
267
279
|
| `other` | anything the categories above do not cover |
|
|
268
280
|
|
|
269
281
|
A report arrives with the category, the resource it concerns and the client's own account of what it
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Administrate
|
|
4
|
+
module MCP
|
|
5
|
+
# What an `mcp_action` block may return to send data back to the client. `record` goes through
|
|
6
|
+
# the same checks as a record returned directly, and gives a collection action its `id`; `data`
|
|
7
|
+
# is answered as `mcp_data`, which the engine adds to the response under `data`, or to the error
|
|
8
|
+
# of a failure. Any result object that answers `mcp_data` works the same way.
|
|
9
|
+
class ActionResult
|
|
10
|
+
attr_reader :record, :data, :error
|
|
11
|
+
|
|
12
|
+
alias mcp_data data
|
|
13
|
+
|
|
14
|
+
private_class_method :new
|
|
15
|
+
|
|
16
|
+
def self.success(record: nil, data: nil)
|
|
17
|
+
new(record:, data:, error: nil, success: true)
|
|
18
|
+
end
|
|
19
|
+
|
|
20
|
+
def self.failure(error = nil, data: nil)
|
|
21
|
+
new(record: nil, data:, error:, success: false)
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
def initialize(record:, data:, error:, success:)
|
|
25
|
+
@record = record
|
|
26
|
+
@data = data
|
|
27
|
+
@error = error
|
|
28
|
+
@success = success
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
def success?
|
|
32
|
+
@success
|
|
33
|
+
end
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
end
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Administrate
|
|
4
|
+
module MCP
|
|
5
|
+
module Actions
|
|
6
|
+
# Reads the `mcp_data` of an action's result and turns it into what goes back to the client: a
|
|
7
|
+
# copy built only from plain Hashes with String keys, Arrays, Strings and JSON scalars, no deeper
|
|
8
|
+
# than MAX_DEPTH and no larger than `config.action_data_max_bytes` once encoded. The copy, not
|
|
9
|
+
# the host's objects, is what gets encoded, so no `as_json` of theirs runs. The action has
|
|
10
|
+
# already run when this is checked, so the error says so.
|
|
11
|
+
module ResultData
|
|
12
|
+
MAX_DEPTH = 32
|
|
13
|
+
|
|
14
|
+
SCALARS = [Integer, TrueClass, FalseClass, NilClass].freeze
|
|
15
|
+
|
|
16
|
+
class << self
|
|
17
|
+
def extract!(result, tool_name:)
|
|
18
|
+
return nil unless result.respond_to?(:mcp_data)
|
|
19
|
+
|
|
20
|
+
data = result.mcp_data
|
|
21
|
+
return nil if data.nil?
|
|
22
|
+
|
|
23
|
+
normalize_root!(data, tool_name)
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
private
|
|
27
|
+
|
|
28
|
+
def normalize_root!(data, tool_name)
|
|
29
|
+
raise TypeError, "data (#{data.class}) is not a Hash" unless data.is_a?(Hash)
|
|
30
|
+
|
|
31
|
+
normalize!(data, 'data').tap { |copy| check_size!(copy) }
|
|
32
|
+
rescue TypeError, RangeError => e
|
|
33
|
+
raise Error, "#{tool_name} ran, but its data cannot be returned: #{e.message}"
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
def normalize!(value, path, depth = 0)
|
|
37
|
+
raise RangeError, "#{path} is nested deeper than #{MAX_DEPTH} levels" if depth > MAX_DEPTH
|
|
38
|
+
|
|
39
|
+
case value
|
|
40
|
+
when Hash then normalize_hash!(value, path, depth)
|
|
41
|
+
when Array then value.each_with_index.map { |item, index| normalize!(item, "#{path}[#{index}]", depth + 1) }
|
|
42
|
+
when String, Symbol then normalize_string!(value, path)
|
|
43
|
+
else normalize_scalar!(value, path)
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
def normalize_string!(value, path)
|
|
48
|
+
copy = String.new(value.to_s).encode(Encoding::UTF_8)
|
|
49
|
+
raise TypeError, "#{path} is not valid UTF-8" unless copy.valid_encoding?
|
|
50
|
+
|
|
51
|
+
copy
|
|
52
|
+
rescue EncodingError
|
|
53
|
+
raise TypeError, "#{path} cannot be converted to UTF-8"
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
def normalize_hash!(hash, path, depth)
|
|
57
|
+
hash.each_with_object({}) do |(key, item), copy|
|
|
58
|
+
name = key_name!(key, path)
|
|
59
|
+
raise TypeError, "#{path} has the key #{name} twice" if copy.key?(name)
|
|
60
|
+
|
|
61
|
+
copy[name] = normalize!(item, "#{path}.#{name}", depth + 1)
|
|
62
|
+
end
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
def key_name!(key, path)
|
|
66
|
+
return normalize_string!(key, "a key of #{path}") if key.is_a?(String) || key.is_a?(Symbol)
|
|
67
|
+
|
|
68
|
+
raise TypeError, "#{path} has a key (#{key.class}) that is not a String or Symbol"
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
def normalize_scalar!(value, path)
|
|
72
|
+
if value.instance_of?(Float)
|
|
73
|
+
raise TypeError, "#{path} is not a finite number" unless value.finite?
|
|
74
|
+
|
|
75
|
+
return value
|
|
76
|
+
end
|
|
77
|
+
return value if SCALARS.any? { |type| value.instance_of?(type) }
|
|
78
|
+
|
|
79
|
+
raise TypeError, "#{path} (#{value.class}) is not a JSON value"
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
def check_size!(copy)
|
|
83
|
+
limit = Administrate::MCP.config.action_data_max_bytes
|
|
84
|
+
return if limit.nil?
|
|
85
|
+
|
|
86
|
+
bytes = copy.to_json.bytesize
|
|
87
|
+
return if bytes <= limit
|
|
88
|
+
|
|
89
|
+
raise RangeError,
|
|
90
|
+
"data is #{bytes} bytes of JSON, over the #{limit}-byte limit (config.action_data_max_bytes)"
|
|
91
|
+
end
|
|
92
|
+
end
|
|
93
|
+
end
|
|
94
|
+
end
|
|
95
|
+
end
|
|
96
|
+
end
|
|
@@ -12,6 +12,9 @@ module Administrate
|
|
|
12
12
|
# An action is a member action by default: it takes an `id` and runs against the loaded record.
|
|
13
13
|
# Declared with `on: :collection`, it takes no `id`, loads nothing and runs against the model.
|
|
14
14
|
#
|
|
15
|
+
# Once `config.tool_views` is on, an action's tool renders in the resource view, which confirms the
|
|
16
|
+
# action and shows the record it returned. `view:` (a ToolView subclass or its name) picks another.
|
|
17
|
+
#
|
|
15
18
|
# An action declared with `uploads:` (true, a list of attachment attributes, or a hash of
|
|
16
19
|
# attribute to `content_types:` / `max_size:` overrides) also takes an optional
|
|
17
20
|
# `<attribute>_upload_id` for each of them. The id is resolved into the attachment value before
|
|
@@ -34,6 +37,7 @@ module Administrate
|
|
|
34
37
|
:params,
|
|
35
38
|
:required,
|
|
36
39
|
:uploads,
|
|
40
|
+
:view,
|
|
37
41
|
:invoke,
|
|
38
42
|
keyword_init: true
|
|
39
43
|
)
|
|
@@ -42,11 +46,13 @@ module Administrate
|
|
|
42
46
|
|
|
43
47
|
TARGETS = %i[member collection].freeze
|
|
44
48
|
|
|
49
|
+
DEFAULT_VIEW = 'Administrate::MCP::ToolViews::ResourceView'
|
|
50
|
+
|
|
45
51
|
class << self
|
|
46
52
|
# Normalizes the arguments of a `mcp_action` declaration into a spec (everything but the
|
|
47
53
|
# model, which is inferred from the owning dashboard when definitions are built).
|
|
48
54
|
def build_spec(name, description:, on: :member, params: {}, predicate: nil, pundit: nil, scope: :write,
|
|
49
|
-
destructive: true, uploads: false, &invoke)
|
|
55
|
+
destructive: true, uploads: false, view: nil, &invoke)
|
|
50
56
|
raise ArgumentError, "#{name}: a block is required to invoke the action" unless invoke
|
|
51
57
|
raise ArgumentError, "#{name}: on: must be :member or :collection" unless TARGETS.include?(on)
|
|
52
58
|
|
|
@@ -63,6 +69,7 @@ module Administrate
|
|
|
63
69
|
params: normalized.transform_values { |spec| spec.except(:required) },
|
|
64
70
|
required: normalized.reject { |_, spec| spec[:required] == false }.keys,
|
|
65
71
|
uploads: Uploads::Declarations.normalize(uploads, action_name: name),
|
|
72
|
+
view:,
|
|
66
73
|
invoke:
|
|
67
74
|
}
|
|
68
75
|
end
|
|
@@ -154,6 +161,7 @@ module Administrate
|
|
|
154
161
|
klass.annotations(read_only_hint: false, destructive_hint: defn.destructive, open_world_hint: true)
|
|
155
162
|
klass.requires_scope defn.scope
|
|
156
163
|
klass.input_schema(**schema_for(defn, resource))
|
|
164
|
+
klass.tool_view(defn.view || DEFAULT_VIEW)
|
|
157
165
|
define_behaviors(klass, defn)
|
|
158
166
|
klass
|
|
159
167
|
end
|
|
@@ -177,7 +185,11 @@ module Administrate
|
|
|
177
185
|
end
|
|
178
186
|
klass.define_singleton_method(:execute) do |admin:, id: nil, **params|
|
|
179
187
|
outcome = ToolFactory.send(:invoke, defn, admin, id, params)
|
|
180
|
-
outcome.key?(:error)
|
|
188
|
+
if outcome.key?(:error)
|
|
189
|
+
error_response(outcome[:error], data: outcome[:details])
|
|
190
|
+
else
|
|
191
|
+
json_response(outcome[:data], structured: true)
|
|
192
|
+
end
|
|
181
193
|
end
|
|
182
194
|
end
|
|
183
195
|
|
|
@@ -190,15 +202,20 @@ module Administrate
|
|
|
190
202
|
declared = params.slice(*defn.params.keys, *Uploads::Declarations.param_schemas(defn).keys)
|
|
191
203
|
arguments = { admin:, params: Uploads::Declarations.resolve_params(defn, admin, declared) }
|
|
192
204
|
arguments[:record] = Actions.find_record!(defn.model_class, id) if defn.on == :member
|
|
193
|
-
|
|
194
|
-
|
|
205
|
+
returned = defn.invoke.call(**arguments)
|
|
206
|
+
result = returned.is_a?(ActionResult) ? returned.record : returned
|
|
207
|
+
data = ResultData.extract!(returned, tool_name: Actions.tool_name(defn))
|
|
208
|
+
failures = [returned, result].select { |candidate| failed?(candidate) }
|
|
209
|
+
unless failures.empty?
|
|
210
|
+
return { error: failure_message(defn, failures.first, arguments[:record]), details: data }
|
|
211
|
+
end
|
|
195
212
|
|
|
196
|
-
{ data: success_data(defn, id, result) }
|
|
213
|
+
{ data: success_data(defn, id, result, data) }
|
|
197
214
|
end
|
|
198
215
|
|
|
199
|
-
def success_data(defn, id, result)
|
|
216
|
+
def success_data(defn, id, result, data)
|
|
200
217
|
id = result.id if defn.on == :collection && result.is_a?(ActiveRecord::Base)
|
|
201
|
-
{ status: 'ok', model: defn.model_class.name.underscore, id:, action: defn.name.to_s }.compact
|
|
218
|
+
{ status: 'ok', model: defn.model_class.name.underscore, id:, action: defn.name.to_s, data: }.compact
|
|
202
219
|
end
|
|
203
220
|
|
|
204
221
|
def failed?(result)
|
|
@@ -32,6 +32,21 @@ module Administrate
|
|
|
32
32
|
@required_scopes || []
|
|
33
33
|
end
|
|
34
34
|
|
|
35
|
+
def tool_view(view = nil, visibility: nil)
|
|
36
|
+
if view
|
|
37
|
+
@tool_view = view
|
|
38
|
+
@tool_view_visibility = visibility&.map(&:to_s)
|
|
39
|
+
end
|
|
40
|
+
resolve_tool_view(@tool_view)
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
def meta_value
|
|
44
|
+
view = tool_view
|
|
45
|
+
return super unless view && Administrate::MCP.config.tool_views
|
|
46
|
+
|
|
47
|
+
::MCP::Apps.tool_meta(resource_uri: view.uri, visibility: @tool_view_visibility, meta: super)
|
|
48
|
+
end
|
|
49
|
+
|
|
35
50
|
def call(server_context:, **args)
|
|
36
51
|
instrument(server_context) { call_with_context(server_context, **args) }
|
|
37
52
|
rescue ResourceForbiddenError, InvalidArgumentError => e
|
|
@@ -106,12 +121,25 @@ module Administrate
|
|
|
106
121
|
::MCP::Tool::Response.new([{ type: 'text', text: }])
|
|
107
122
|
end
|
|
108
123
|
|
|
109
|
-
def json_response(data)
|
|
110
|
-
::MCP::Tool::Response.new(
|
|
124
|
+
def json_response(data, structured: false, meta: nil)
|
|
125
|
+
::MCP::Tool::Response.new(
|
|
126
|
+
[{ type: 'text', text: data.to_json }],
|
|
127
|
+
structured_content: (data if structured),
|
|
128
|
+
meta:
|
|
129
|
+
)
|
|
130
|
+
end
|
|
131
|
+
|
|
132
|
+
def resolve_tool_view(view)
|
|
133
|
+
view.is_a?(String) ? view.constantize : view
|
|
111
134
|
end
|
|
112
135
|
|
|
113
|
-
def error_response(message)
|
|
114
|
-
|
|
136
|
+
def error_response(message, data: nil)
|
|
137
|
+
content = [{ type: 'text', text: message }]
|
|
138
|
+
return ::MCP::Tool::Response.new(content, error: true) if data.nil?
|
|
139
|
+
|
|
140
|
+
structured = { error: message, data: }
|
|
141
|
+
content << { type: 'text', text: structured.to_json }
|
|
142
|
+
::MCP::Tool::Response.new(content, error: true, structured_content: structured)
|
|
115
143
|
end
|
|
116
144
|
end
|
|
117
145
|
end
|
|
@@ -22,13 +22,16 @@ module Administrate
|
|
|
22
22
|
def build(server_context:)
|
|
23
23
|
server_context[:authorization_errors] ||= []
|
|
24
24
|
config = Administrate::MCP.config
|
|
25
|
+
tools = discover_tools(server_context)
|
|
25
26
|
server =
|
|
26
27
|
::MCP::Server.new(
|
|
27
28
|
name: config.server_name,
|
|
28
29
|
version: config.server_version,
|
|
29
|
-
tools
|
|
30
|
+
tools:,
|
|
31
|
+
resources: tool_view_resources(tools),
|
|
30
32
|
server_context:
|
|
31
33
|
)
|
|
34
|
+
server.capabilities = server.capabilities.merge(extensions: ::MCP::Apps.capability) if config.tool_views
|
|
32
35
|
server.transport =
|
|
33
36
|
::MCP::Server::Transports::StreamableHTTPTransport.new(
|
|
34
37
|
server,
|
|
@@ -54,6 +57,12 @@ module Administrate
|
|
|
54
57
|
(built_in + host_tools).uniq + action_tools
|
|
55
58
|
end
|
|
56
59
|
|
|
60
|
+
def tool_view_resources(tools)
|
|
61
|
+
return [] unless Administrate::MCP.config.tool_views
|
|
62
|
+
|
|
63
|
+
tools.filter_map(&:tool_view).uniq.map(&:resource)
|
|
64
|
+
end
|
|
65
|
+
|
|
57
66
|
def built_in_tools
|
|
58
67
|
names = BUILT_IN_TOOLS.dup
|
|
59
68
|
names << REPORT_IMPROVEMENT_TOOL if Administrate::MCP.config.feedback_tool
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Administrate
|
|
4
|
+
module MCP
|
|
5
|
+
# An interactive view an MCP Apps host (SEP-1865) renders for a tool's result, served as a
|
|
6
|
+
# `ui://` HTML resource. A subclass names its script and, optionally, its stylesheet; the
|
|
7
|
+
# engine wraps them in a document with the shared runtime (`window.AdministrateMCP`), which
|
|
8
|
+
# speaks the host's postMessage protocol. A tool opts in with `tool_view`, an `mcp_action`
|
|
9
|
+
# with `view:`, and the server publishes nothing until the host sets `config.tool_views`.
|
|
10
|
+
class ToolView
|
|
11
|
+
RUNTIME_DIR = File.expand_path('../../../../lib/administrate/mcp/tool_views', __dir__)
|
|
12
|
+
|
|
13
|
+
CSP_KEYS = {
|
|
14
|
+
connect_domains: :connectDomains,
|
|
15
|
+
resource_domains: :resourceDomains,
|
|
16
|
+
frame_domains: :frameDomains,
|
|
17
|
+
base_uri_domains: :baseUriDomains
|
|
18
|
+
}.freeze
|
|
19
|
+
|
|
20
|
+
class << self
|
|
21
|
+
def view_name(value = nil)
|
|
22
|
+
@view_name = value.to_s if value
|
|
23
|
+
@view_name || name.demodulize.underscore.delete_suffix('_view')
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
def title(value = nil)
|
|
27
|
+
@title = value if value
|
|
28
|
+
@title || view_name.humanize
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
def description(value = nil)
|
|
32
|
+
@description = value if value
|
|
33
|
+
@description
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
def script(path = nil)
|
|
37
|
+
@script = path.to_s if path
|
|
38
|
+
@script
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
def stylesheet(path = nil)
|
|
42
|
+
@stylesheet = path.to_s if path
|
|
43
|
+
@stylesheet
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
def uri
|
|
47
|
+
"#{::MCP::Apps::URI_SCHEME}#{Administrate::MCP.config.server_name.to_s.dasherize}/#{view_name}"
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
def resource
|
|
51
|
+
view = self
|
|
52
|
+
::MCP::Resource.define(
|
|
53
|
+
uri:,
|
|
54
|
+
name: view_name,
|
|
55
|
+
title:,
|
|
56
|
+
description:,
|
|
57
|
+
mime_type: ::MCP::Apps::RESOURCE_MIME_TYPE
|
|
58
|
+
) { |server_context: nil| view.contents(server_context:) }
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
def contents(server_context: nil) # rubocop:disable Lint/UnusedMethodArgument
|
|
62
|
+
::MCP::Resource::TextContents.new(
|
|
63
|
+
uri:,
|
|
64
|
+
mime_type: ::MCP::Apps::RESOURCE_MIME_TYPE,
|
|
65
|
+
text: document,
|
|
66
|
+
meta: { ui: resource_meta }
|
|
67
|
+
)
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
def document
|
|
71
|
+
raise ArgumentError, "#{name}: declare the view's script" if script.blank?
|
|
72
|
+
|
|
73
|
+
<<~HTML
|
|
74
|
+
<!doctype html>
|
|
75
|
+
<html lang="en">
|
|
76
|
+
<head>
|
|
77
|
+
<meta charset="utf-8">
|
|
78
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
79
|
+
<title>#{ERB::Util.html_escape(title)}</title>
|
|
80
|
+
<style>#{style_text(read_runtime('runtime.css'))}#{style_text(read(stylesheet))}</style>
|
|
81
|
+
</head>
|
|
82
|
+
<body>
|
|
83
|
+
<main id="app" aria-live="polite"><p class="am-muted">Loading…</p></main>
|
|
84
|
+
<script>#{script_text(read_runtime('runtime.js'))}</script>
|
|
85
|
+
<script>#{script_text(read(script))}</script>
|
|
86
|
+
</body>
|
|
87
|
+
</html>
|
|
88
|
+
HTML
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
def resource_meta
|
|
92
|
+
csp = Administrate::MCP.config.tool_view_csp.to_h.each_with_object({}) do |(key, domains), result|
|
|
93
|
+
spec_key = CSP_KEYS[key.to_sym]
|
|
94
|
+
raise ArgumentError, "Unknown tool_view_csp key: #{key}" unless spec_key
|
|
95
|
+
|
|
96
|
+
result[spec_key] = Array(domains).map(&:to_s)
|
|
97
|
+
end
|
|
98
|
+
{ prefersBorder: true, csp: (csp unless csp.empty?) }.compact
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
def runtime_path(file)
|
|
102
|
+
File.join(RUNTIME_DIR, file)
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
private
|
|
106
|
+
|
|
107
|
+
def read_runtime(file)
|
|
108
|
+
File.read(runtime_path(file))
|
|
109
|
+
end
|
|
110
|
+
|
|
111
|
+
def read(path)
|
|
112
|
+
path.present? ? File.read(path) : ''
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
def script_text(source)
|
|
116
|
+
source.gsub(%r{</(script)}i, '<\/\1')
|
|
117
|
+
end
|
|
118
|
+
|
|
119
|
+
def style_text(source)
|
|
120
|
+
source.gsub(%r{</(style)}i, '<\/\1')
|
|
121
|
+
end
|
|
122
|
+
end
|
|
123
|
+
end
|
|
124
|
+
end
|
|
125
|
+
end
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Administrate
|
|
4
|
+
module MCP
|
|
5
|
+
module ToolViews
|
|
6
|
+
# What a view needs to render a serialized value and follow it: the field's kind and, for an
|
|
7
|
+
# association to a registered resource, that resource's name and the foreign key a filtered
|
|
8
|
+
# list of it takes. Ships in the tool result's `_meta`, which a host hands to the view and
|
|
9
|
+
# keeps out of the model's context. A resource the caller cannot list is left unnamed, as in the
|
|
10
|
+
# catalog.
|
|
11
|
+
module FieldHints
|
|
12
|
+
META_KEY = 'administrate-mcp/view'
|
|
13
|
+
|
|
14
|
+
ASSOCIATION_KINDS = %i[belongs_to has_many polymorphic].freeze
|
|
15
|
+
|
|
16
|
+
URL_FIELD_CLASSES = ['Administrate::Field::Url'].freeze
|
|
17
|
+
|
|
18
|
+
class << self
|
|
19
|
+
def meta(entry, dashboard, attributes, admin:)
|
|
20
|
+
return nil unless Administrate::MCP.config.tool_views
|
|
21
|
+
|
|
22
|
+
resource = entry.model_class.name.underscore
|
|
23
|
+
{ META_KEY => { resource:, fields: fields(entry, dashboard, attributes, admin:) } }
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
def fields(entry, dashboard, attributes, admin:)
|
|
27
|
+
FieldSerializer.resolve_columns(dashboard, attributes).to_h do |attr_name|
|
|
28
|
+
kind = kind_for(dashboard.attribute_types[attr_name])
|
|
29
|
+
hint = { kind: }
|
|
30
|
+
if ASSOCIATION_KINDS.include?(kind)
|
|
31
|
+
hint.merge!(association_hint(entry.model_class, attr_name, kind, admin))
|
|
32
|
+
end
|
|
33
|
+
[attr_name, hint]
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
def kind_for(field_spec)
|
|
38
|
+
field_class = FieldSerializer.resolve_field_class(field_spec)
|
|
39
|
+
return :has_many if FieldSerializer.expandable_field?(field_class)
|
|
40
|
+
return :url if url_field?(field_class)
|
|
41
|
+
|
|
42
|
+
serializer = FieldSerializer.serializer_for(field_spec)
|
|
43
|
+
serializer.is_a?(Symbol) ? serializer : :value
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
private
|
|
47
|
+
|
|
48
|
+
def url_field?(field_class)
|
|
49
|
+
return false unless field_class.is_a?(Class)
|
|
50
|
+
|
|
51
|
+
field_class.ancestors.any? { |ancestor| URL_FIELD_CLASSES.include?(ancestor.name) }
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
def association_hint(model_class, attr_name, kind, admin)
|
|
55
|
+
reflection = model_class.reflect_on_association(attr_name)
|
|
56
|
+
return {} if reflection.nil? || reflection.polymorphic? || kind == :polymorphic
|
|
57
|
+
|
|
58
|
+
resource = registered_resource(reflection.klass)
|
|
59
|
+
return {} unless resource && AdminDashboardTool.readable?(admin, resource)
|
|
60
|
+
|
|
61
|
+
{ resource:, foreign_key: filter_key(reflection, kind) }.compact
|
|
62
|
+
rescue NameError
|
|
63
|
+
{}
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
def filter_key(reflection, kind)
|
|
67
|
+
reflection.foreign_key.to_s if kind == :has_many && !reflection.through_reflection?
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
def registered_resource(model_class)
|
|
71
|
+
name = model_class.name.underscore
|
|
72
|
+
DashboardRegistry.registry.key?(name) ? name : nil
|
|
73
|
+
end
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
end
|
|
77
|
+
end
|
|
78
|
+
end
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Administrate
|
|
4
|
+
module MCP
|
|
5
|
+
module ToolViews
|
|
6
|
+
# Renders admin_resource_list and admin_resource_show results as a table and a record page,
|
|
7
|
+
# and lets the viewer page, sort, search and follow associations without a model round trip.
|
|
8
|
+
class ResourceView < ToolView
|
|
9
|
+
view_name 'resource'
|
|
10
|
+
title 'Admin records'
|
|
11
|
+
description 'Browse the records an admin_resource_list or admin_resource_show call returned.'
|
|
12
|
+
script runtime_path('resource.js')
|
|
13
|
+
stylesheet runtime_path('resource.css')
|
|
14
|
+
end
|
|
15
|
+
end
|
|
16
|
+
end
|
|
17
|
+
end
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Administrate
|
|
4
|
+
module MCP
|
|
5
|
+
module ToolViews
|
|
6
|
+
# Renders sidekiq_stats and sidekiq_retries results as counts per job class and a retry list,
|
|
7
|
+
# with a refresh button.
|
|
8
|
+
class SidekiqView < ToolView
|
|
9
|
+
view_name 'sidekiq'
|
|
10
|
+
title 'Sidekiq'
|
|
11
|
+
description 'Job counts and retries from a sidekiq_stats or sidekiq_retries call.'
|
|
12
|
+
script runtime_path('sidekiq.js')
|
|
13
|
+
stylesheet runtime_path('sidekiq.css')
|
|
14
|
+
end
|
|
15
|
+
end
|
|
16
|
+
end
|
|
17
|
+
end
|