administrate-mcp 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68fb06b806eb2dea5dbb0e0a01a865b4a9984b515a358bfd86fab8d0b949b65c
-  data.tar.gz: ac0a3ef739bf776dff2325bc3ae641e22b694047ffd03d078c944810b2071768
+  metadata.gz: f3f38d54e63d5f8d6b88750c73f284d10d5e0500a0a7f47cae82556be264e8fe
+  data.tar.gz: 1b1d5fda201d08915bdddd2c6eb92fb97f9698ece7f17cbff1a1d563f280eea9
 SHA512:
-  metadata.gz: 1d6204806b8c490362a1e4a56939a3ae588897f069f7c1e21c4ff653eaed486d06cd238e3243d3c3a29edcc2399a7aef25deed80022e598f8b52fc36a7fc7895
-  data.tar.gz: 2064c7b7ad08e21f32eba4db06ebda81d594e1abf0c731ddf369a901282ce419c923eea77715faa1c25ae44601809e4f3195d55fc539c91e90ae5b2d4107eca1
+  metadata.gz: bdc5883ed9f4d6cadab89dd8be6aca8f890e25cfc39d0a40ef6b2b7e9fd6b11af6de5e817d4d8c6047a0bcd9d3ad1a6bd05b4af095bd64c256ad6d65198bbf7e
+  data.tar.gz: 21bd4c4e668bad2bd5d9050bc6e86abae5800a605be3604d2683687bb3b52bcf4dae42cc2423f5df2fe09713ac14784cc5188a5d76ba28694fe2f41581fa895e

data/CHANGELOG.md

@@ -8,6 +8,56 @@ minor release may change behaviour a host depends on; the entry says so when it
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-10-20
+
+### Security
+
+- A `tools/call` argument named `admin` no longer replaces the authenticated admin passed to a
+  tool's `execute` and to `mcp_action` blocks
+  ([GHSA-vv7c-hhjc-fhq8](https://github.com/sorare/administrate-mcp/security/advisories/GHSA-vv7c-hhjc-fhq8)).
+  The call is now refused with a tool error. For built-in and host-defined tools, the refusal comes
+  after the scope and role checks, and the `on_tool_call` hook still reports the call under the
+  authenticated admin, with the refused argument in `arguments`. The tools generated from
+  `mcp_action` refuse it while validating arguments, before the hook runs.
+
+### Changed
+
+- **Behaviour change for hosts:** a tool that declares an input property named `admin` now raises
+  `ArgumentError` when its class is loaded, and an `mcp_action` param named `admin` or `id` raises
+  `ArgumentError` when the dashboard is loaded. Rename the property or param.
+- **Behaviour change for clients:** the tools generated from `mcp_action` declarations now reject
+  arguments they do not declare, with an `Invalid arguments` tool error, instead of passing them to
+  the block in `params`.
+
+## [0.3.0] - 2026-10-02
+
+### Changed
+
+- **Behaviour change for clients:** two failures of `admin_resource_list_resources`,
+  `admin_resource_list` and `admin_resource_show` now return HTTP 200 with a tool error
+  (`result.isError: true`) instead of HTTP 403 with `X-Auth-Error: forbidden` and JSON-RPC code
+  -32003. Clients such as Claude showed that 403 as an authentication failure and dropped the message:
+  - An unknown resource name. The message says the name is not registered and lists up to five
+    close registered names, taken only from the resources the caller can read.
+  - A registered resource the caller may not read. The message is "Resource `<name>` exists but you
+    are not authorized to list it" (or "show it"), followed by the authorization adapter's own
+    message when the host wrote one. The old 403 body already told the two cases apart
+    (`Unknown resource: …` against `Not authorized to show? <Model>`); the difference is that
+    clients now display it.
+
+  A tool-level refusal, a missing OAuth scope or a required role, is still a 403 for now
+  ([#11](https://github.com/sorare/administrate-mcp/issues/11)). The per-resource denial is raised
+  as `Administrate::MCP::ResourceForbiddenError`, a subclass of `UnauthorizedError`, so host code
+  that rescues `UnauthorizedError` still catches it.
+
+### Fixed
+
+- A `subscriptions/listen` request no longer raises `NoMethodError` in the host's Rack stack. The
+  `mcp` gem answers it with a streaming SSE body meant to stay open, which the engine's controller
+  cannot serve; the transport is now built with `serve_subscriptions_listen: false`, so the method
+  is answered with HTTP 404 and JSON-RPC error `-32601` like any unimplemented method, and
+  `server/discover` stops advertising the `listChanged` and `subscribe` capability flags.
+
 ## [0.2.0] - 2026-09-22
 
 ### Added
@@ -88,6 +138,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.2.0...HEAD
+[Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.3.1...HEAD
+[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
 [0.2.0]: https://github.com/sorare/administrate-mcp/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/sorare/administrate-mcp/releases/tag/v0.1.0

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

@@ -27,6 +27,8 @@ module Administrate
           keyword_init: true
         )
 
+      RESERVED_PARAMS = %i[admin id].freeze
+
       class << self
         # Normalizes the arguments of a `mcp_action` declaration into a spec (everything but the
         # model, which is inferred from the owning dashboard when definitions are built).
@@ -34,6 +36,7 @@ module Administrate
                        destructive: true, &invoke)
           raise ArgumentError, "#{name}: a block is required to invoke the action" unless invoke
 
+          reject_reserved_params!(name, params)
           normalized = normalize_params(params)
 
           {
@@ -97,6 +100,11 @@ module Administrate
 
         private
 
+        def reject_reserved_params!(name, params)
+          reserved = RESERVED_PARAMS & params.keys.map(&:to_sym)
+          raise ArgumentError, "#{name}: reserved param name(s): #{reserved.join(', ')}" if reserved.any?
+        end
+
         def authorized_for_discovery?(admin, definition)
           Administrate::MCP.config.authorization.authorized?(admin, definition.model_class, definition.predicate)
         rescue StandardError
@@ -130,7 +138,7 @@ module Administrate
           def schema_for(defn, resource)
             properties = { id: { type: 'string', description: "ID or slug of the #{resource}" } }
             defn.params.each { |name, spec| properties[name] = spec }
-            { properties:, required: %w[id] + defn.required.map(&:to_s) }
+            { properties:, required: %w[id] + defn.required.map(&:to_s), additionalProperties: false }
           end
 
           # Replaces the role-based default with instance-level authorization on the loaded record.

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

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require 'did_you_mean'
+
 module Administrate
   module MCP
     # Base class for MCP tools that operate on Administrate dashboard resources.
     class AdminDashboardTool < BaseTool
       LISTED_VALID_VALUES = 40
+      MAX_SUGGESTIONS = 5
+      ACTION_VERBS = { index?: 'list', show?: 'show' }.freeze
 
       class << self
         def policy_action
@@ -14,7 +18,7 @@ module Administrate
         def check_roles!(admin, resource: nil, **)
           return unless resource && policy_action
 
-          entry = find_dashboard_entry!(resource)
+          entry = find_dashboard_entry!(admin, resource)
           authorize_resource!(admin, entry.model_class, policy_action)
         end
 
@@ -22,15 +26,57 @@ module Administrate
           Administrate::MCP.config.authorization.authorized?(admin, model_class, action)
         end
 
+        # The adapter is the host's and raises a plain UnauthorizedError. Re-raised here so a denial on
+        # one resource reaches the caller as a tool error instead of a 403 on the whole response. A
+        # message the host wrote is kept, since it may say why; the adapters' generic one adds nothing.
         def authorize_resource!(admin, model_class, action)
           Administrate::MCP.config.authorization.authorize!(admin, model_class, action)
+        rescue UnauthorizedError => e
+          verb = ACTION_VERBS.fetch(action.to_sym) { action.to_s.delete_suffix('?') }
+          message = "Resource `#{model_class.name.underscore}` exists but you are not authorized to #{verb} it."
+          reason = e.message unless e.message == Authorization::Base.denial_message(action, model_class.name)
+          raise ResourceForbiddenError, [message, reason].compact.join(' ')
         end
 
-        def find_dashboard_entry!(resource_name)
+        def find_dashboard_entry!(admin, resource_name)
           entry = DashboardRegistry.find(resource_name)
           return entry if entry
 
-          raise UnauthorizedError, "Unknown resource: #{resource_name}"
+          raise InvalidArgumentError, unknown_resource_message(admin, resource_name)
+        end
+
+        def unknown_resource_message(admin, resource_name)
+          message = "Unknown resource: #{resource_name}. This name is not registered."
+          suggestions = resource_suggestions(admin, resource_name)
+          return "#{message} Call admin_resource_list_resources for the catalog." if suggestions.empty?
+
+          "#{message} Closest registered names: #{suggestions.join(', ')}"
+        end
+
+        # Only names the caller can read are suggested, as in the catalog, so a typo does not reveal
+        # hidden resources.
+        def resource_suggestions(admin, resource_name)
+          suggestion_candidates(resource_name).lazy.select { |name| readable?(admin, name) }.first(MAX_SUGGESTIONS)
+        end
+
+        # Matches on the last path segment too, so a bare "order" finds "shop/order".
+        def suggestion_candidates(resource_name)
+          key = resource_name.to_s.underscore.singularize
+          names = DashboardRegistry.resource_names
+          by_segment = names.group_by { |name| name.split('/').last }
+          segment = key.split('/').last.to_s
+          close_segments = DidYouMean::SpellChecker.new(dictionary: by_segment.keys).correct(segment)
+
+          (
+            by_segment.fetch(segment, []) +
+              DidYouMean::SpellChecker.new(dictionary: names).correct(key) +
+              close_segments.flat_map { |name| by_segment[name] }
+          ).uniq
+        end
+
+        def readable?(admin, resource_name)
+          entry = DashboardRegistry.find(resource_name)
+          entry && authorized?(admin, entry.model_class, :index?)
         end
 
         def reject_unknown!(kind, given, allowed)

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

@@ -5,9 +5,17 @@ module Administrate
     # Base class for all MCP tools — provides role gating, auditing, and response helpers.
     class BaseTool < ::MCP::Tool
       UnauthorizedError = Administrate::MCP::UnauthorizedError
+      ResourceForbiddenError = Administrate::MCP::ResourceForbiddenError
       InvalidArgumentError = Administrate::MCP::InvalidArgumentError
 
+      RESERVED_ARGUMENTS = %i[admin].freeze
+
       class << self
+        def input_schema(value = NOT_SET)
+          reject_reserved_properties!(value) if value.is_a?(Hash)
+          super
+        end
+
         def requires_roles(*roles)
           @required_roles = roles.flatten
         end
@@ -26,11 +34,11 @@ module Administrate
 
         def call(server_context:, **args)
           instrument(server_context) { call_with_context(server_context, **args) }
+        rescue ResourceForbiddenError, InvalidArgumentError => e
+          error_response(e.message)
         rescue UnauthorizedError => e
           (server_context[:authorization_errors] ||= []).push(e.message)
           error_response(e.message)
-        rescue InvalidArgumentError => e
-          error_response(e.message)
         rescue StandardError => e
           error_response("Internal error: #{e.message}")
         end
@@ -46,7 +54,21 @@ module Administrate
           check_scopes!(server_context)
           check_roles!(admin, **args)
           audit!(admin, args, server_context)
-          execute(admin:, **args)
+          reject_reserved_arguments!(args)
+          execute(**args, admin:)
+        end
+
+        def reject_reserved_arguments!(args)
+          reserved = args.keys & RESERVED_ARGUMENTS
+          return if reserved.empty?
+
+          raise InvalidArgumentError, "Reserved argument(s) cannot be passed: #{reserved.join(', ')}"
+        end
+
+        def reject_reserved_properties!(schema)
+          properties = (schema[:properties] || schema['properties'] || {}).keys.map(&:to_sym)
+          reserved = properties & RESERVED_ARGUMENTS
+          raise ArgumentError, "#{name}: reserved input property name(s): #{reserved.join(', ')}" if reserved.any?
         end
 
         def check_scopes!(server_context)

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

@@ -35,7 +35,11 @@ module Administrate
               # The host's own route constraints already restrict which Host values reach the
               # controller, and this is not loopback-bound. Passing the incoming request's own host
               # back as `allowed_hosts:` would just validate the Host header against itself.
-              dns_rebinding_protection: false
+              dns_rebinding_protection: false,
+              # `subscriptions/listen` answers with a streaming SSE body that is held open. The
+              # controller buffers the response and builds a stateless transport per request, so it
+              # cannot serve that stream; refusing answers the method as unimplemented (-32601).
+              serve_subscriptions_listen: false
             )
           server
         end

data/app/lib/administrate/mcp/tools/admin_resource_list.rb

@@ -24,10 +24,7 @@ module Administrate
               description:
                 'Resource type name (e.g., "card", "user", "player"). ' \
                 'Use admin_resource_list_resources with no arguments to see available ones. ' \
-                'Many resources are namespaced (e.g. "shop/order") and bare names are not aliased. ' \
-                'An unrecognised name currently surfaces as an authorization error, not a "not found" ' \
-                'error, so treat an auth failure here as a likely wrong resource name and re-check the ' \
-                'catalog rather than assuming the server is unavailable.'
+                'Many resources are namespaced (e.g. "shop/order") and bare names are not aliased.'
             },
             query: {
               type: 'string',
@@ -86,7 +83,6 @@ module Administrate
           required: %w[resource]
         )
 
-        # rubocop:disable-next Lint/UnusedMethodArgument
         def self.execute(
           admin:,
           resource:,
@@ -99,7 +95,7 @@ module Administrate
           page: 1,
           per_page: 10
         )
-          entry = find_dashboard_entry!(resource)
+          entry = find_dashboard_entry!(admin, resource)
           dashboard = entry.dashboard_class.new
           per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
           page = [page.to_i, 1].max

data/app/lib/administrate/mcp/tools/admin_resource_list_resources.rb

@@ -8,7 +8,7 @@ module Administrate
       class AdminResourceListResources < AdminDashboardTool
         tool_name 'admin_resource_list_resources'
         description 'Discover available admin resources. ' \
-                    'Without a resource param: returns all resource names (lightweight catalog). ' \
+                    'Without a resource param: returns the resource names you can read (lightweight catalog). ' \
                     'With a resource param: returns fields and filters for that resource.'
         annotations read_only_hint: true, destructive_hint: false, open_world_hint: true
 
@@ -19,10 +19,7 @@ module Administrate
               description:
                 'Resource name to inspect (optional). When provided, returns fields and filters for that ' \
                 'resource. Must be an exact name from the no-argument catalog — many resources are ' \
-                'namespaced (e.g. "shop/order") and bare names are not aliased. An unrecognised name ' \
-                'currently surfaces as an authorization error, not a "not found" error, so treat an auth ' \
-                'failure here as a likely wrong resource name and re-check the catalog rather than ' \
-                'assuming the server is unavailable.'
+                'namespaced (e.g. "shop/order") and bare names are not aliased.'
             }
           }
         )
@@ -49,7 +46,7 @@ module Administrate
         end
 
         def self.detail_response(admin, resource_name)
-          entry = find_dashboard_entry!(resource_name)
+          entry = find_dashboard_entry!(admin, resource_name)
           authorize_resource!(admin, entry.model_class, :index?)
 
           json_response(build_detail(resource_name, entry))

data/app/lib/administrate/mcp/tools/admin_resource_show.rb

@@ -24,10 +24,7 @@ module Administrate
               description:
                 'Resource type name (e.g., "card", "user", "player"). ' \
                 'Use admin_resource_list_resources with no arguments to see available ones. ' \
-                'Many resources are namespaced (e.g. "shop/order") and bare names are not aliased. ' \
-                'An unrecognised name currently surfaces as an authorization error, not a "not found" ' \
-                'error, so treat an auth failure here as a likely wrong resource name and re-check the ' \
-                'catalog rather than assuming the server is unavailable.'
+                'Many resources are namespaced (e.g. "shop/order") and bare names are not aliased.'
             },
             id: {
               oneOf: [
@@ -75,8 +72,8 @@ module Administrate
           required: %w[resource id]
         )
 
-        def self.execute(admin:, resource:, id:, fields: nil, expand: nil) # rubocop:disable Lint/UnusedMethodArgument
-          entry = find_dashboard_entry!(resource)
+        def self.execute(admin:, resource:, id:, fields: nil, expand: nil)
+          entry = find_dashboard_entry!(admin, resource)
           dashboard = entry.dashboard_class.new
           attrs, expand_set =
             resolve_attributes_and_expansions(dashboard, fields, expand, :show_page_attributes, MAX_EXPAND)

data/lib/administrate/mcp/authorization/base.rb

@@ -8,10 +8,16 @@ module Administrate
       # Shared role gating. Roles are a host concept: an admin class that does not answer
       # `can_access?` cannot be gated on them, and saying so beats letting the call through.
       class Base
+        # The message the built-in adapters raise. A caller that reformats a denial compares against
+        # it to tell the generic message from one the host wrote.
+        def self.denial_message(action, model_name)
+          "Not authorized to #{action} #{model_name}"
+        end
+
         def authorize!(admin, record_or_class, action)
           return if authorized?(admin, record_or_class, action)
 
-          raise UnauthorizedError, "Not authorized to #{action} #{model_name(record_or_class)}"
+          raise UnauthorizedError, Base.denial_message(action, model_name(record_or_class))
         end
 
         def authorized?(_admin, _record_or_class, _action)

data/lib/administrate/mcp/authorization/pundit.rb

@@ -11,7 +11,7 @@ module Administrate
           policy = policy_for(admin, record_or_class)
           return if policy.public_send(action)
 
-          raise UnauthorizedError, "Not authorized to #{action} #{model_name(record_or_class)}"
+          raise UnauthorizedError, Base.denial_message(action, model_name(record_or_class))
         end
 
         def authorized?(admin, record_or_class, action)

data/lib/administrate/mcp/errors.rb

@@ -9,6 +9,12 @@ module Administrate
     class UnauthorizedError < Error
     end
 
+    # Raised when the caller's role may not read one resource. It is still an authorization failure,
+    # but it is returned as a tool error rather than a 403: the credentials work for the tool, only
+    # this resource is out of reach, and the caller needs the message to tell the two apart.
+    class ResourceForbiddenError < UnauthorizedError
+    end
+
     # Raised when the host asked for something the configuration cannot deliver.
     class ConfigurationError < Error
     end

data/lib/administrate/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module Administrate
   module MCP
-    VERSION = '0.2.0'
+    VERSION = '0.3.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: administrate-mcp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Sorare