administrate-mcp 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68fb06b806eb2dea5dbb0e0a01a865b4a9984b515a358bfd86fab8d0b949b65c
-  data.tar.gz: ac0a3ef739bf776dff2325bc3ae641e22b694047ffd03d078c944810b2071768
+  metadata.gz: c22f6f3b6febbe8e86b8cb721e30f63e4e9232edbd668a3a311e44ff180b9117
+  data.tar.gz: cd60a0dad70e15f8235e1ed6c3c2385b5d8cc56efe2a66e1b84a18b3b5fe4087
 SHA512:
-  metadata.gz: 1d6204806b8c490362a1e4a56939a3ae588897f069f7c1e21c4ff653eaed486d06cd238e3243d3c3a29edcc2399a7aef25deed80022e598f8b52fc36a7fc7895
-  data.tar.gz: 2064c7b7ad08e21f32eba4db06ebda81d594e1abf0c731ddf369a901282ce419c923eea77715faa1c25ae44601809e4f3195d55fc539c91e90ae5b2d4107eca1
+  metadata.gz: 65ea611de7b893d7b4aaec605cc91a3bd742187ca3ff2ef340229009daa130a7bc7abb79e1f4bda2d4995670ff0dadfce95252f659366ada2713458a4d70a60c
+  data.tar.gz: 23a0677acecdb975efeb760a6f797f9319e0ae95b607be57db1dd5a5be5c1db21141aaa3cfcfbf90625472059b65a3263ae8b10ec0ab00d002414e19d5c67215

data/CHANGELOG.md

@@ -8,6 +8,35 @@ minor release may change behaviour a host depends on; the entry says so when it
 
 ## [Unreleased]
 
+## [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 +117,7 @@ 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.0...HEAD
+[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/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,6 +5,7 @@ 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
 
       class << self
@@ -26,11 +27,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

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.0'
   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.0
 platform: ruby
 authors:
 - Sorare