administrate-mcp 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e16575edff64537e779f60e3d447d4bef99e19f46669c64eb882bd14867279a7
-  data.tar.gz: 2490fbf883f4980d3a152a5d245f27448f5729159b8944432a59c1d90dcb51d5
+  metadata.gz: 7e0b5788d3dd59f527d55db5f4e6e4d748c23f1c6d4f247c2afaa660e4dce89e
+  data.tar.gz: 932950d82e3472408f440cdb2a736b8107978ca8016c55e625e1221e21e99ddc
 SHA512:
-  metadata.gz: 6b74d3c9e992058ff3d896cd3d4f80075520ee3e977f4a07d0093dc9982aee9b686465c0d236d0f92e199751f863e9fc544afc44b066f1d5548d2bb9a909a19a
-  data.tar.gz: 0142657f7abee895bd4acec60789403c2ddaa999bc55b2ffc3077f6a164f8db579bf8d835daf063e227b4bcfcc9ce9a2c96843cd5ffa91800fa6227d456668c7
+  metadata.gz: 41f1ca74dbe3ed51314f8ec39ea8f38d99ba1831dd725e4e19ca17e8ef940b31d359f7651526a8fe1b8dfb53bcfb74ed2cba615d45e48a8cba230cb3b463711d
+  data.tar.gz: e1575180b4778ba2e68addc80c8c90441045436588281fc413d66a6abe43554be3eccc39d6a3965f7a927949f4ae911019890bb0e931bb31cb5a7ee0c6c2f767

data/CHANGELOG.md

@@ -8,6 +8,32 @@ minor release may change behaviour a host depends on; the entry says so when it
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-22
+
+### Added
+
+- An `mcp_action` block can send data back to the client. It returns
+  `Administrate::MCP::ActionResult.success(record:, data:)`, or any result object answering
+  `mcp_data`, and the answer gains a `data` key next to `status`, `model`, `id` and `action`, which
+  are unchanged. The record, optional, goes through the same checks as a record returned directly,
+  so an unsaved or invalid one is still an error and a collection action still answers its `id`.
+  `ActionResult.failure(message, data:)` is an error whose first content block is the message, as
+  before; when there is data, a second block carries `{ "error": message, "data": … }` as JSON and
+  the result's `structuredContent` carries the same object. The data must be a Hash of plain JSON
+  values nested at most 32 levels deep, with valid UTF-8 strings; the engine encodes a copy
+  built from those values, never the host's objects, and its JSON may be at most
+  `config.action_data_max_bytes` (new, 32 KB by default, `nil` for no limit). Anything else is
+  answered as an error naming the offending path and saying the action ran. A plain Hash returned
+  by a block is still not sent back. See
+  [Returning data from an action](docs/dashboards.md#returning-data-from-an-action).
+
+### Changed
+
+- A successful `mcp_action` call now also returns its answer as the result's `structuredContent`,
+  the same object as the JSON in its text content, which is unchanged.
+- A tool error may now carry a second content block. Clients that read only the first block still
+  get the message on its own; only failures that return data add the second block.
+
 ## [0.4.0] - 2026-10-21
 
 ### Added
@@ -177,7 +203,8 @@ minor release may change behaviour a host depends on; the entry says so when it
   took the gem from git before 0.1.0 must reinstall its migrations rather than migrate
   incrementally.
 
-[Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/sorare/administrate-mcp/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/sorare/administrate-mcp/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/sorare/administrate-mcp/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/sorare/administrate-mcp/compare/v0.2.0...v0.3.0

data/app/lib/administrate/mcp/action_result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # What an `mcp_action` block may return to send data back to the client. `record` goes through
+    # the same checks as a record returned directly, and gives a collection action its `id`; `data`
+    # is answered as `mcp_data`, which the engine adds to the response under `data`, or to the error
+    # of a failure. Any result object that answers `mcp_data` works the same way.
+    class ActionResult
+      attr_reader :record, :data, :error
+
+      alias mcp_data data
+
+      private_class_method :new
+
+      def self.success(record: nil, data: nil)
+        new(record:, data:, error: nil, success: true)
+      end
+
+      def self.failure(error = nil, data: nil)
+        new(record: nil, data:, error:, success: false)
+      end
+
+      def initialize(record:, data:, error:, success:)
+        @record = record
+        @data = data
+        @error = error
+        @success = success
+      end
+
+      def success?
+        @success
+      end
+    end
+  end
+end

data/app/lib/administrate/mcp/actions/result_data.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    module Actions
+      # Reads the `mcp_data` of an action's result and turns it into what goes back to the client: a
+      # copy built only from plain Hashes with String keys, Arrays, Strings and JSON scalars, no deeper
+      # than MAX_DEPTH and no larger than `config.action_data_max_bytes` once encoded. The copy, not
+      # the host's objects, is what gets encoded, so no `as_json` of theirs runs. The action has
+      # already run when this is checked, so the error says so.
+      module ResultData
+        MAX_DEPTH = 32
+
+        SCALARS = [Integer, TrueClass, FalseClass, NilClass].freeze
+
+        class << self
+          def extract!(result, tool_name:)
+            return nil unless result.respond_to?(:mcp_data)
+
+            data = result.mcp_data
+            return nil if data.nil?
+
+            normalize_root!(data, tool_name)
+          end
+
+          private
+
+          def normalize_root!(data, tool_name)
+            raise TypeError, "data (#{data.class}) is not a Hash" unless data.is_a?(Hash)
+
+            normalize!(data, 'data').tap { |copy| check_size!(copy) }
+          rescue TypeError, RangeError => e
+            raise Error, "#{tool_name} ran, but its data cannot be returned: #{e.message}"
+          end
+
+          def normalize!(value, path, depth = 0)
+            raise RangeError, "#{path} is nested deeper than #{MAX_DEPTH} levels" if depth > MAX_DEPTH
+
+            case value
+            when Hash then normalize_hash!(value, path, depth)
+            when Array then value.each_with_index.map { |item, index| normalize!(item, "#{path}[#{index}]", depth + 1) }
+            when String, Symbol then normalize_string!(value, path)
+            else normalize_scalar!(value, path)
+            end
+          end
+
+          def normalize_string!(value, path)
+            copy = String.new(value.to_s).encode(Encoding::UTF_8)
+            raise TypeError, "#{path} is not valid UTF-8" unless copy.valid_encoding?
+
+            copy
+          rescue EncodingError
+            raise TypeError, "#{path} cannot be converted to UTF-8"
+          end
+
+          def normalize_hash!(hash, path, depth)
+            hash.each_with_object({}) do |(key, item), copy|
+              name = key_name!(key, path)
+              raise TypeError, "#{path} has the key #{name} twice" if copy.key?(name)
+
+              copy[name] = normalize!(item, "#{path}.#{name}", depth + 1)
+            end
+          end
+
+          def key_name!(key, path)
+            return normalize_string!(key, "a key of #{path}") if key.is_a?(String) || key.is_a?(Symbol)
+
+            raise TypeError, "#{path} has a key (#{key.class}) that is not a String or Symbol"
+          end
+
+          def normalize_scalar!(value, path)
+            if value.instance_of?(Float)
+              raise TypeError, "#{path} is not a finite number" unless value.finite?
+
+              return value
+            end
+            return value if SCALARS.any? { |type| value.instance_of?(type) }
+
+            raise TypeError, "#{path} (#{value.class}) is not a JSON value"
+          end
+
+          def check_size!(copy)
+            limit = Administrate::MCP.config.action_data_max_bytes
+            return if limit.nil?
+
+            bytes = copy.to_json.bytesize
+            return if bytes <= limit
+
+            raise RangeError,
+                  "data is #{bytes} bytes of JSON, over the #{limit}-byte limit (config.action_data_max_bytes)"
+          end
+        end
+      end
+    end
+  end
+end

data/app/lib/administrate/mcp/actions.rb

@@ -177,7 +177,11 @@ module Administrate
             end
             klass.define_singleton_method(:execute) do |admin:, id: nil, **params|
               outcome = ToolFactory.send(:invoke, defn, admin, id, params)
-              outcome.key?(:error) ? error_response(outcome[:error]) : json_response(outcome[:data])
+              if outcome.key?(:error)
+                error_response(outcome[:error], data: outcome[:details])
+              else
+                json_response(outcome[:data], structured: true)
+              end
             end
           end
 
@@ -190,15 +194,20 @@ module Administrate
             declared = params.slice(*defn.params.keys, *Uploads::Declarations.param_schemas(defn).keys)
             arguments = { admin:, params: Uploads::Declarations.resolve_params(defn, admin, declared) }
             arguments[:record] = Actions.find_record!(defn.model_class, id) if defn.on == :member
-            result = defn.invoke.call(**arguments)
-            return { error: failure_message(defn, result, arguments[:record]) } if failed?(result)
+            returned = defn.invoke.call(**arguments)
+            result = returned.is_a?(ActionResult) ? returned.record : returned
+            data = ResultData.extract!(returned, tool_name: Actions.tool_name(defn))
+            failures = [returned, result].select { |candidate| failed?(candidate) }
+            unless failures.empty?
+              return { error: failure_message(defn, failures.first, arguments[:record]), details: data }
+            end
 
-            { data: success_data(defn, id, result) }
+            { data: success_data(defn, id, result, data) }
           end
 
-          def success_data(defn, id, result)
+          def success_data(defn, id, result, data)
             id = result.id if defn.on == :collection && result.is_a?(ActiveRecord::Base)
-            { status: 'ok', model: defn.model_class.name.underscore, id:, action: defn.name.to_s }.compact
+            { status: 'ok', model: defn.model_class.name.underscore, id:, action: defn.name.to_s, data: }.compact
           end
 
           def failed?(result)

data/app/lib/administrate/mcp/base_tool.rb

@@ -106,12 +106,17 @@ module Administrate
           ::MCP::Tool::Response.new([{ type: 'text', text: }])
         end
 
-        def json_response(data)
-          ::MCP::Tool::Response.new([{ type: 'text', text: data.to_json }])
+        def json_response(data, structured: false)
+          ::MCP::Tool::Response.new([{ type: 'text', text: data.to_json }], structured_content: (data if structured))
         end
 
-        def error_response(message)
-          ::MCP::Tool::Response.new([{ type: 'text', text: message }], error: true)
+        def error_response(message, data: nil)
+          content = [{ type: 'text', text: message }]
+          return ::MCP::Tool::Response.new(content, error: true) if data.nil?
+
+          structured = { error: message, data: }
+          content << { type: 'text', text: structured.to_json }
+          ::MCP::Tool::Response.new(content, error: true, structured_content: structured)
         end
       end
     end

data/docs/configuration.md

@@ -111,6 +111,7 @@ class Configuration
                 :persist_feedback,
                 :feedback_tool,
                 :sidekiq_stats_provider,
+                :action_data_max_bytes,
                 :admin_route_namespace,
                 :admin_url_options,
                 :skipped_field_classes,
@@ -148,6 +149,7 @@ class Configuration
     @persist_feedback = false
     @feedback_tool = true
     @sidekiq_stats_provider = nil
+    @action_data_max_bytes = 32_768
   end
 
   def assign_fields
@@ -197,6 +199,7 @@ end
 | `persist_feedback`          | `false`                            | Whether `report_mcp_improvement` creates an `Administrate::MCP::Feedback` row before calling `on_feedback`. False needs no `administrate_mcp_feedbacks` table at all             |
 | `feedback_tool`             | `true`                             | Whether `report_mcp_improvement` is published                                                                                                                                    |
 | `sidekiq_stats_provider`    | `nil`                              | Object answering `counts`, `total_counts`, `queues`, `stats_cleared_at`; a class name String or a Proc is resolved lazily so autoloaded providers can be named in an initializer |
+| `action_data_max_bytes`     | `32_768`                           | Largest `data` an `mcp_action` may return, in bytes of JSON; larger data is an error. `nil` removes the limit. See [Returning data from an action](dashboards.md#returning-data-from-an-action) |
 | `admin_route_namespace`     | `:admin`                           | Namespace record URLs are built from                                                                                                                                             |
 | `admin_url_options`         | `{}`                               | Options passed to `polymorphic_url`; when no `:host` is given, host, protocol and port are taken from `admin_origin`                                                             |
 | `skipped_field_classes`     | Password                           | Field class names never serialized                                                                                                                                               |

data/docs/dashboards.md

@@ -53,7 +53,8 @@ base class, is not applied to every resource. A subclass that wants one declares
     saved or has errors is an error too, with its validation messages. So is `false`, the result of
     a failed `update` or of a `destroy` a callback aborted; for a member action the message is the
     loaded record's validation messages when it has any. Anything else is a success, including a
-    record the block destroyed.
+    record the block destroyed. To send data back with the answer, return an
+    `Administrate::MCP::ActionResult`; see [Returning data from an action](#returning-data-from-an-action).
   - The tool is announced as destructive unless the declaration says `destructive: false`. Clients
     may ask for confirmation before running a destructive tool, so set it on actions that only add
     or prepare something.
@@ -72,6 +73,60 @@ base class, is not applied to every resource. A subclass that wants one declares
     `max_size:`) adds an optional `<attribute>_upload_id` param for each of them, and the block
     receives the uploaded file as `params[:<attribute>]`. See [Presigned uploads](uploads.md).
 
+## Returning data from an action
+
+An action answers `{ status, model, id, action }` by default, as JSON text and, identically, as the
+result's `structuredContent`. When the client needs more than that, such as what an import created
+and what it skipped, the block returns an `Administrate::MCP::ActionResult` and the answer gains a
+`data` key:
+
+```ruby
+mcp_action :import_batch,
+           on: :collection,
+           description: 'Import orders from a marketplace export.',
+           params: { references: { type: 'array', items: { type: 'string' } } } do |admin:, params:|
+  report = Orders::ImportBatch.call!(references: params[:references], admin:)
+  next Administrate::MCP::ActionResult.failure('No order matched', data: { unknown: report.unknown }) if report.empty?
+
+  Administrate::MCP::ActionResult.success(record: report.batch,
+                                          data: { created: report.created.size, unknown: report.unknown })
+end
+```
+
+```json
+{ "status": "ok", "model": "order", "id": 42, "action": "import_batch", "data": { "created": 3, "unknown": ["X-9"] } }
+```
+
+- `ActionResult.success(record:, data:)`: `record` is optional and is checked as if the block had
+  returned it, so an unsaved or invalid record is still an error, and a collection action still
+  answers its `id`.
+- `ActionResult.failure(message, data:)` is an error with `message`, or `<action> failed` without
+  one. The error's first content block stays the message alone. When there is data, a second block
+  carries `{ "error": message, "data": … }` as JSON, and the result's `structuredContent` carries the
+  same object, so clients that only read the content still see the data.
+- These two are the only constructors. Any result object that answers `mcp_data` with a Hash works
+  the same way, so a host's own service result can carry its data without being wrapped; `success?`
+  and `error` are read from it as for any other result.
+- A plain Hash returned by the block is not sent back, as before: data reaches the client only when
+  the block asks for it, never because a service happened to return a Hash.
+- `data` must be a Hash of JSON values: Hashes with String or Symbol keys, Arrays, Strings, Symbols,
+  Integers, finite Floats, `true`, `false` and `nil`, nested at most 32 levels deep. Strings and
+  keys must be valid UTF-8 or convertible to it, so check bytes read from a file. Convert
+  anything else, such as a time (`at.iso8601`) or a record (`record.id`), yourself. The engine
+  encodes a plain copy it builds from those values, so an object's own `as_json` never runs, and a
+  key given both as a String and as a Symbol is refused rather than sent twice. The copy's JSON may
+  be at most `config.action_data_max_bytes` (32 KB by default; `nil` removes the limit), so that an
+  action cannot fill the client's context. Return counts and the few items the client must act on,
+  not every row.
+- Data that breaks a rule is answered as an error naming the offending path, for example
+  `data.report.rows[1] (Object) is not a JSON value`. The block has already run by then, so the
+  message says the action ran: fix the action rather than retrying the call.
+- `data` reaches the client as it is, without the protections fields get from
+  `skipped_field_classes` and the field serializers. Don't return secrets, tokens or credentials. A
+  download URL is a bearer credential that ends up in transcripts and client logs, so make it
+  short-lived. Strings that came from end users (names, notes, references) are untrusted text in the
+  model's context, as they are in any field.
+
 ## Search
 
 The `admin_resource_list` tool's `query` argument matches exactly by default, so searching for an id

data/lib/administrate/mcp/configuration.rb

@@ -59,6 +59,7 @@ module Administrate
                     :persist_feedback,
                     :feedback_tool,
                     :sidekiq_stats_provider,
+                    :action_data_max_bytes,
                     :admin_route_namespace,
                     :admin_url_options,
                     :skipped_field_classes,
@@ -102,6 +103,7 @@ module Administrate
         @persist_feedback = false
         @feedback_tool = true
         @sidekiq_stats_provider = nil
+        @action_data_max_bytes = 32_768
         @uploads = UploadsConfiguration.new
       end
 

data/lib/administrate/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module Administrate
   module MCP
-    VERSION = '0.4.0'
+    VERSION = '0.5.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: administrate-mcp
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Sorare
@@ -89,7 +89,9 @@ files:
 - app/controllers/concerns/administrate/mcp/resource_controller.rb
 - app/dashboards/administrate/mcp/api_key_dashboard.rb
 - app/dashboards/administrate/mcp/feedback_dashboard.rb
+- app/lib/administrate/mcp/action_result.rb
 - app/lib/administrate/mcp/actions.rb
+- app/lib/administrate/mcp/actions/result_data.rb
 - app/lib/administrate/mcp/admin_dashboard_tool.rb
 - app/lib/administrate/mcp/authentication.rb
 - app/lib/administrate/mcp/base_tool.rb