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.
Files changed (30) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +49 -1
  3. data/README.md +12 -0
  4. data/app/lib/administrate/mcp/action_result.rb +36 -0
  5. data/app/lib/administrate/mcp/actions/result_data.rb +96 -0
  6. data/app/lib/administrate/mcp/actions.rb +24 -7
  7. data/app/lib/administrate/mcp/base_tool.rb +32 -4
  8. data/app/lib/administrate/mcp/feedback_categories.rb +2 -1
  9. data/app/lib/administrate/mcp/server_builder.rb +10 -1
  10. data/app/lib/administrate/mcp/tool_view.rb +125 -0
  11. data/app/lib/administrate/mcp/tool_views/field_hints.rb +78 -0
  12. data/app/lib/administrate/mcp/tool_views/resource_view.rb +17 -0
  13. data/app/lib/administrate/mcp/tool_views/sidekiq_view.rb +17 -0
  14. data/app/lib/administrate/mcp/tools/admin_resource_list.rb +4 -1
  15. data/app/lib/administrate/mcp/tools/admin_resource_show.rb +11 -4
  16. data/app/lib/administrate/mcp/tools/report_improvement.rb +2 -1
  17. data/app/lib/administrate/mcp/tools/sidekiq_retries.rb +1 -0
  18. data/app/lib/administrate/mcp/tools/sidekiq_stats.rb +1 -0
  19. data/docs/configuration.md +5 -0
  20. data/docs/dashboards.md +60 -1
  21. data/docs/tool-views.md +135 -0
  22. data/lib/administrate/mcp/configuration.rb +6 -0
  23. data/lib/administrate/mcp/tool_views/resource.css +25 -0
  24. data/lib/administrate/mcp/tool_views/resource.js +384 -0
  25. data/lib/administrate/mcp/tool_views/runtime.css +112 -0
  26. data/lib/administrate/mcp/tool_views/runtime.js +296 -0
  27. data/lib/administrate/mcp/tool_views/sidekiq.css +6 -0
  28. data/lib/administrate/mcp/tool_views/sidekiq.js +108 -0
  29. data/lib/administrate/mcp/version.rb +1 -1
  30. metadata +14 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e16575edff64537e779f60e3d447d4bef99e19f46669c64eb882bd14867279a7
4
- data.tar.gz: 2490fbf883f4980d3a152a5d245f27448f5729159b8944432a59c1d90dcb51d5
3
+ metadata.gz: c350ad45d3f07a28fb76136a472895c5ab803c56771ade63fdfdba70a78bc874
4
+ data.tar.gz: a31ed7ff75cbb2ee5dcacbe581701a46ef3358bb9d77760a3ae91dfe5938cd93
5
5
  SHA512:
6
- metadata.gz: 6b74d3c9e992058ff3d896cd3d4f80075520ee3e977f4a07d0093dc9982aee9b686465c0d236d0f92e199751f863e9fc544afc44b066f1d5548d2bb9a909a19a
7
- data.tar.gz: 0142657f7abee895bd4acec60789403c2ddaa999bc55b2ffc3077f6a164f8db579bf8d835daf063e227b4bcfcc9ce9a2c96843cd5ffa91800fa6227d456668c7
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.4.0...HEAD
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) ? error_response(outcome[:error]) : json_response(outcome[:data])
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
- result = defn.invoke.call(**arguments)
194
- return { error: failure_message(defn, result, arguments[:record]) } if failed?(result)
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([{ type: 'text', text: data.to_json }])
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
- ::MCP::Tool::Response.new([{ type: 'text', text: message }], error: true)
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
@@ -12,7 +12,8 @@ module Administrate
12
12
  'missing_field' => 2,
13
13
  'missing_resource' => 3,
14
14
  'serialization' => 4,
15
- 'other' => 5
15
+ 'other' => 5,
16
+ 'missing_view' => 6
16
17
  }.freeze
17
18
  end
18
19
  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: discover_tools(server_context),
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