administrate-mcp 0.5.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 7e0b5788d3dd59f527d55db5f4e6e4d748c23f1c6d4f247c2afaa660e4dce89e
4
- data.tar.gz: 932950d82e3472408f440cdb2a736b8107978ca8016c55e625e1221e21e99ddc
3
+ metadata.gz: c350ad45d3f07a28fb76136a472895c5ab803c56771ade63fdfdba70a78bc874
4
+ data.tar.gz: a31ed7ff75cbb2ee5dcacbe581701a46ef3358bb9d77760a3ae91dfe5938cd93
5
5
  SHA512:
6
- metadata.gz: 41f1ca74dbe3ed51314f8ec39ea8f38d99ba1831dd725e4e19ca17e8ef940b31d359f7651526a8fe1b8dfb53bcfb74ed2cba615d45e48a8cba230cb3b463711d
7
- data.tar.gz: e1575180b4778ba2e68addc80c8c90441045436588281fc413d66a6abe43554be3eccc39d6a3965f7a927949f4ae911019890bb0e931bb31cb5a7ee0c6c2f767
6
+ metadata.gz: 27e3a249e626a6ec2413866c87517cf418ef07a6dd25af0d048a122b4cbc92a762e3d18175522b508aa1a620b9159c7791e422ae9f5415d61000487dcb0402dc
7
+ data.tar.gz: 1f5e1a59ce398562594dbf27606402e435da36391ca9a8f8c4d34443fcf33a59ebeccec925c2053290942a9c9de3629d1e9e1f7b65514296c1c75174b3254e51
data/CHANGELOG.md CHANGED
@@ -8,6 +8,26 @@ 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
+
11
31
  ## [0.5.0] - 2026-10-22
12
32
 
13
33
  ### Added
@@ -203,7 +223,8 @@ minor release may change behaviour a host depends on; the entry says so when it
203
223
  took the gem from git before 0.1.0 must reinstall its migrations rather than migrate
204
224
  incrementally.
205
225
 
206
- [Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.5.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
207
228
  [0.5.0]: https://github.com/sorare/administrate-mcp/compare/v0.4.0...v0.5.0
208
229
  [0.4.0]: https://github.com/sorare/administrate-mcp/compare/v0.3.1...v0.4.0
209
230
  [0.3.1]: https://github.com/sorare/administrate-mcp/compare/v0.3.0...v0.3.1
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
@@ -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
@@ -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,8 +121,16 @@ module Administrate
106
121
  ::MCP::Tool::Response.new([{ type: 'text', text: }])
107
122
  end
108
123
 
109
- def json_response(data, structured: false)
110
- ::MCP::Tool::Response.new([{ type: 'text', text: data.to_json }], structured_content: (data if structured))
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
136
  def error_response(message, data: nil)
@@ -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
@@ -16,6 +16,7 @@ module Administrate
16
16
  description 'Search and list admin resources. ' \
17
17
  'Supports text search, filters, sorting, field selection, and HasMany expansion.'
18
18
  annotations read_only_hint: true, destructive_hint: false, open_world_hint: true
19
+ tool_view 'Administrate::MCP::ToolViews::ResourceView'
19
20
 
20
21
  input_schema(
21
22
  properties: {
@@ -103,7 +104,9 @@ module Administrate
103
104
  scope = apply_sort(scope, dashboard, sort, sort_direction)
104
105
  records = scope.page(page).per(per_page)
105
106
 
106
- json_response(build_response(records, dashboard, page, per_page, fields:, expand:))
107
+ response = build_response(records, dashboard, page, per_page, fields:, expand:)
108
+ columns = response[:columns].drop(1).map(&:to_sym)
109
+ json_response(response, meta: ToolViews::FieldHints.meta(entry, dashboard, columns, admin:))
107
110
  end
108
111
 
109
112
  def self.build_response(records, dashboard, page, per_page, fields: nil, expand: nil)
@@ -16,6 +16,7 @@ module Administrate
16
16
  description 'Show admin resource(s) by ID or slug. ' \
17
17
  'Accepts a single ID or an array of up to 10 IDs for batch lookup.'
18
18
  annotations read_only_hint: true, destructive_hint: false, open_world_hint: true
19
+ tool_view 'Administrate::MCP::ToolViews::ResourceView'
19
20
 
20
21
  input_schema(
21
22
  properties: {
@@ -78,19 +79,22 @@ module Administrate
78
79
  attrs, expand_set =
79
80
  resolve_attributes_and_expansions(dashboard, fields, expand, :show_page_attributes, MAX_EXPAND)
80
81
 
81
- return batch_show(entry, dashboard, id, resource, attributes: attrs, expand: expand_set) if id.is_a?(Array)
82
+ if id.is_a?(Array)
83
+ return batch_show(entry, dashboard, id, resource, attributes: attrs, expand: expand_set, admin:)
84
+ end
82
85
 
83
86
  record = find_record(entry, id)
84
87
  return error_response("#{resource.capitalize} not found for: #{id}") unless record
85
88
 
86
89
  json_response(
87
- FieldSerializer.serialize(record, dashboard, attributes: attrs, expand: expand_set, resolve_getters: true)
90
+ FieldSerializer.serialize(record, dashboard, attributes: attrs, expand: expand_set, resolve_getters: true),
91
+ meta: ToolViews::FieldHints.meta(entry, dashboard, attrs, admin:)
88
92
  )
89
93
  end
90
94
 
91
95
  # Getters stay unresolved here: they are per-record work, and a batch multiplies them by up
92
96
  # to MAX_BATCH. Read one id at a time when a getter-backed attribute matters.
93
- def self.batch_show(entry, dashboard, ids, resource, attributes:, expand:)
97
+ def self.batch_show(entry, dashboard, ids, resource, attributes:, expand:, admin:)
94
98
  reject_over_limit!('ids', ids.size, MAX_BATCH)
95
99
  columns = FieldSerializer.resolve_columns(dashboard, attributes)
96
100
 
@@ -105,7 +109,10 @@ module Administrate
105
109
  end
106
110
  end
107
111
 
108
- json_response({ columns: %w[url] + columns.map(&:to_s), rows: })
112
+ json_response(
113
+ { columns: %w[url] + columns.map(&:to_s), rows: },
114
+ meta: ToolViews::FieldHints.meta(entry, dashboard, columns, admin:)
115
+ )
109
116
  end
110
117
 
111
118
  def self.find_record(entry, id)
@@ -9,7 +9,8 @@ module Administrate
9
9
  tool_name 'report_mcp_improvement'
10
10
  requires_roles
11
11
  description 'Report an improvement for the MCP server (misleading description, missing filter, ' \
12
- 'bad serialization, missing resource, etc.).'
12
+ 'bad serialization, missing resource, etc.). Use missing_view when the person needed to ' \
13
+ 'browse, compare or act on a result and plain text was a poor fit for it.'
13
14
 
14
15
  input_schema(
15
16
  properties: {
@@ -11,6 +11,7 @@ module Administrate
11
11
  description 'Get the Sidekiq retry queue size and optionally the first page of retry entries ' \
12
12
  '(up to 25 jobs with class, error, retry count, and timestamps).'
13
13
  annotations read_only_hint: true, destructive_hint: false, open_world_hint: false
14
+ tool_view 'Administrate::MCP::ToolViews::SidekiqView'
14
15
 
15
16
  input_schema(
16
17
  properties: {
@@ -14,6 +14,7 @@ module Administrate
14
14
  'Returns retry breakdown and optionally per-queue breakdowns. ' \
15
15
  'Each breakdown maps job class names to their pending count.'
16
16
  annotations read_only_hint: true, destructive_hint: false, open_world_hint: false
17
+ tool_view 'Administrate::MCP::ToolViews::SidekiqView'
17
18
 
18
19
  input_schema(
19
20
  properties: {
@@ -205,6 +205,8 @@ end
205
205
  | `skipped_field_classes` | Password | Field class names never serialized |
206
206
  | `has_many_field_classes` | HasMany | Field class names treated as expandable collections |
207
207
  | `field_serializers` | see above | Field class name to serializer |
208
+ | `tool_views` | `false` | Whether tools link to their [tool views](tool-views.md) and the server publishes them, for clients that support MCP Apps |
209
+ | `tool_view_csp` | `{}` | Origins a tool view may load from: `resource_domains`, `connect_domains`, `frame_domains`, `base_uri_domains`. See [Tool views](tool-views.md#images-and-other-external-content) |
208
210
  | `uploads` | disabled | Presigned uploads: `enabled`, `storage`, `allowed_content_types`, `max_size`, `max_files`, `url_ttl`, `batch_ttl`. See [Presigned uploads](uploads.md) |
209
211
 
210
212
  ## Authorization adapters
data/docs/dashboards.md CHANGED
@@ -72,6 +72,10 @@ base class, is not applied to every resource. A subclass that wants one declares
72
72
  - `uploads:` (`true`, a list of attachment attributes, or per-attribute `content_types:` and
73
73
  `max_size:`) adds an optional `<attribute>_upload_id` param for each of them, and the block
74
74
  receives the uploaded file as `params[:<attribute>]`. See [Presigned uploads](uploads.md).
75
+ - Once `config.tool_views` is on, an MCP Apps client renders the action's result in the resource
76
+ view: the outcome, the returned data and the saved record. `view:` (an
77
+ `Administrate::MCP::ToolView` subclass or its name) picks another view. See
78
+ [Tool views](tool-views.md).
75
79
 
76
80
  ## Returning data from an action
77
81