administrate-mcp 0.1.0 → 0.3.0

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Administrate derives the model from the controller path, which cannot name a class living
+    # inside the engine's namespace. This resolver takes the model from the controller instead, and
+    # leaves the dashboard to Administrate: a dashboard's constant name follows the host's own
+    # inflections, which only the host can spell.
+    class ResourceResolver < Administrate::ResourceResolver
+      attr_reader :resource_class
+
+      def initialize(controller_path, resource_class:, dashboard_class: nil)
+        super(controller_path)
+        @resource_class = resource_class
+        @dashboard_class = dashboard_class
+      end
+
+      def dashboard_class
+        @dashboard_class || super
+      end
+
+      # The form builder names its parameters after the record, so the controller has to read them
+      # under the same key whatever path the host mounted it at.
+      def resource_name
+        resource_class.model_name.param_key.to_sym
+      end
+    end
+  end
+end

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

@@ -8,9 +8,10 @@ module Administrate
         Administrate::MCP::Tools::AdminResourceList
         Administrate::MCP::Tools::AdminResourceShow
         Administrate::MCP::Tools::AdminResourceListResources
-        Administrate::MCP::Tools::ReportImprovement
       ].freeze
 
+      REPORT_IMPROVEMENT_TOOL = 'Administrate::MCP::Tools::ReportImprovement'
+
       SIDEKIQ_RETRIES_TOOL = 'Administrate::MCP::Tools::SidekiqRetries'
 
       SIDEKIQ_STATS_TOOL = 'Administrate::MCP::Tools::SidekiqStats'
@@ -34,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
@@ -46,6 +51,7 @@ module Administrate
 
         def built_in_tools
           names = BUILT_IN_TOOLS.dup
+          names << REPORT_IMPROVEMENT_TOOL if Administrate::MCP.config.feedback_tool
           names << SIDEKIQ_RETRIES_TOOL if defined?(::Sidekiq)
           names << SIDEKIQ_STATS_TOOL if defined?(::Sidekiq) && Administrate::MCP.config.sidekiq_stats_provider
           names.filter_map(&:safe_constantize)

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/app/lib/administrate/mcp/tools/report_improvement.rb

@@ -15,7 +15,7 @@ module Administrate
           properties: {
             category: {
               type: 'string',
-              enum: Feedback.categories.keys,
+              enum: FeedbackCategories::CATEGORIES.keys,
               description: 'The type of improvement being reported.'
             },
             resource_name: {
@@ -35,7 +35,10 @@ module Administrate
 
           return error_response(result.errors.join(', ')) unless result.success?
 
-          json_response({ status: 'created', feedback_id: result.feedback.id })
+          payload = { status: 'created' }
+          payload[:feedback_id] = result.report.record.id if result.report.record
+
+          json_response(payload)
         end
       end
     end

data/app/models/administrate/mcp/application_record.rb

@@ -15,7 +15,10 @@ module Administrate
         end
 
         def belongs_to_admin
-          belongs_to :admin, class_name: Administrate::MCP.config.admin_class_name, optional: false
+          belongs_to :admin, class_name: Administrate::MCP.config.admin_class_name,
+                             foreign_key: Administrate::MCP.config.admin_foreign_key,
+                             inverse_of: false,
+                             optional: false
         end
       end
     end

data/app/models/administrate/mcp/feedback.rb

@@ -9,8 +9,7 @@ module Administrate
       belongs_to_admin
       belongs_to :api_key, class_name: 'Administrate::MCP::ApiKey', optional: true, inverse_of: :feedbacks
 
-      enum :category,
-           { description: 0, missing_filter: 1, missing_field: 2, missing_resource: 3, serialization: 4, other: 5 }
+      enum :category, FeedbackCategories::CATEGORIES
       enum :status, { pending: 0, accepted: 1, rejected: 2, shipped: 3 }, prefix: true
 
       validates :suggestion, presence: true

data/db/migrate/20260101000001_create_administrate_model_context_protocol_api_keys.rb

@@ -2,8 +2,10 @@
 
 class CreateAdministrateModelContextProtocolApiKeys < ActiveRecord::Migration[8.1]
   def change
+    admin_foreign_key = Administrate::MCP.config.admin_foreign_key
+
     create_table :administrate_mcp_api_keys, id: :uuid, if_not_exists: true do |t|
-      t.uuid :admin_id, null: false
+      t.uuid admin_foreign_key, null: false
       t.string :token_digest, null: false
       t.string :token_prefix, null: false
       t.string :name, null: false
@@ -14,7 +16,7 @@ class CreateAdministrateModelContextProtocolApiKeys < ActiveRecord::Migration[8.
       t.timestamps
     end
 
-    add_index :administrate_mcp_api_keys, :admin_id, if_not_exists: true
+    add_index :administrate_mcp_api_keys, admin_foreign_key, if_not_exists: true
     add_index :administrate_mcp_api_keys, :token_digest, unique: true, if_not_exists: true
   end
 end

data/db/migrate/20260101000002_create_administrate_model_context_protocol_feedbacks.rb

@@ -2,8 +2,10 @@
 
 class CreateAdministrateModelContextProtocolFeedbacks < ActiveRecord::Migration[8.1]
   def change
+    admin_foreign_key = Administrate::MCP.config.admin_foreign_key
+
     create_table :administrate_mcp_feedbacks, id: :uuid, if_not_exists: true do |t|
-      t.uuid :admin_id
+      t.uuid admin_foreign_key
       t.uuid :api_key_id
       t.integer :category, null: false
       t.string :resource_name
@@ -13,7 +15,7 @@ class CreateAdministrateModelContextProtocolFeedbacks < ActiveRecord::Migration[
       t.timestamps
     end
 
-    add_index :administrate_mcp_feedbacks, :admin_id, if_not_exists: true
+    add_index :administrate_mcp_feedbacks, admin_foreign_key, if_not_exists: true
     add_index :administrate_mcp_feedbacks, :api_key_id, if_not_exists: true
   end
 end

data/db/migrate/20260101000003_create_administrate_model_context_protocol_authorization_tables.rb

@@ -2,6 +2,8 @@
 
 class CreateAdministrateModelContextProtocolAuthorizationTables < ActiveRecord::Migration[8.1]
   def change
+    admin_foreign_key = Administrate::MCP.config.admin_foreign_key
+
     create_table :administrate_mcp_oauth_applications, id: :uuid, if_not_exists: true do |t|
       t.string :client_id, null: false
       t.text :client_secret_digest
@@ -15,7 +17,7 @@ class CreateAdministrateModelContextProtocolAuthorizationTables < ActiveRecord::
     add_index :administrate_mcp_oauth_applications, :client_id, unique: true, if_not_exists: true
 
     create_table :administrate_mcp_oauth_access_grants, id: :uuid, if_not_exists: true do |t|
-      t.uuid :admin_id, null: false
+      t.uuid admin_foreign_key, null: false
       t.uuid :application_id, null: false
       t.string :token_digest, null: false
       t.integer :expires_in, null: false
@@ -28,12 +30,12 @@ class CreateAdministrateModelContextProtocolAuthorizationTables < ActiveRecord::
       t.datetime :created_at, null: false
     end
 
-    add_index :administrate_mcp_oauth_access_grants, :admin_id, if_not_exists: true
+    add_index :administrate_mcp_oauth_access_grants, admin_foreign_key, if_not_exists: true
     add_index :administrate_mcp_oauth_access_grants, :application_id, if_not_exists: true
     add_index :administrate_mcp_oauth_access_grants, :token_digest, unique: true, if_not_exists: true
 
     create_table :administrate_mcp_oauth_access_tokens, id: :uuid, if_not_exists: true do |t|
-      t.uuid :admin_id, null: false
+      t.uuid admin_foreign_key, null: false
       t.uuid :application_id, null: false
       t.string :token_digest, null: false
       t.string :refresh_token_digest, null: false
@@ -44,7 +46,7 @@ class CreateAdministrateModelContextProtocolAuthorizationTables < ActiveRecord::
       t.datetime :created_at, null: false
     end
 
-    add_index :administrate_mcp_oauth_access_tokens, :admin_id, if_not_exists: true
+    add_index :administrate_mcp_oauth_access_tokens, admin_foreign_key, if_not_exists: true
     add_index :administrate_mcp_oauth_access_tokens, :application_id, if_not_exists: true
     add_index :administrate_mcp_oauth_access_tokens, :token_digest, unique: true, if_not_exists: true
     add_index :administrate_mcp_oauth_access_tokens, :refresh_token_digest, unique: true, if_not_exists: true

data/docs/admin-integration.md

@@ -2,22 +2,116 @@
 
 [Back to README](../README.md)
 
-## Exposing the engine's own tables in your admin
+## The API key and feedback consoles
 
-The engine's records keep their namespace in `model_name`, so `Administrate::MCP::ApiKey` routes as
-`administrate_mcp_api_keys` and never shadows a resource of your own called `api_keys`. Administrate
-needs three things to manage a namespaced model:
+The engine ships the console for its own tables: two Administrate dashboards and two controller
+concerns. Include them in controllers of your own, so that authentication, the base controller and
+the policies stay yours:
 
 ```ruby
 # config/routes.rb, inside your admin namespace
 namespace :admin do
-  resources :administrate_mcp_api_keys
-  resources :administrate_mcp_feedbacks, only: %i[index show destroy]
+  resources :administrate_mcp_api_keys, only: %i[index show new create destroy]
+  # Only when config.persist_feedback is true; the table exists only then.
+  resources :administrate_mcp_feedbacks, only: %i[index show edit update]
 end
 
+# app/dashboards/administrate_mcp_api_key_dashboard.rb
+class AdministrateMcpApiKeyDashboard < Administrate::MCP::ApiKeyDashboard
+end
+
+# app/dashboards/administrate_mcp_feedback_dashboard.rb
+class AdministrateMcpFeedbackDashboard < Administrate::MCP::FeedbackDashboard
+end
+
+# app/controllers/admin/administrate_mcp_api_keys_controller.rb
+module Admin
+  class AdministrateMcpApiKeysController < Admin::ApplicationController
+    include Administrate::MCP::ApiKeysAdmin
+  end
+end
+
+# app/controllers/admin/administrate_mcp_feedbacks_controller.rb
+module Admin
+  class AdministrateMcpFeedbacksController < Admin::ApplicationController
+    include Administrate::MCP::FeedbacksAdmin
+  end
+end
+```
+
+`ApiKeysAdmin` generates the key, stores its digest, and puts the plaintext in the flash of the
+redirect that created it, because that response is the only place it can ever be read. `destroy`
+revokes rather than deletes, so the row still says what the token was. Both concerns point
+Administrate at the engine's model, which the controller's own name cannot spell.
+
+The two empty subclasses are the part the engine cannot write for you. Administrate finds a
+dashboard by camelizing the controller's name, and an application that registers MCP as an
+inflection acronym expects `AdministrateMCPApiKeyDashboard` where one that does not expects
+`AdministrateMcpApiKeyDashboard`. Name the file `administrate_mcp_api_key_dashboard.rb` and the
+class whatever your own inflections produce for it; the columns come from the engine's class.
+
+The key owner comes from `config.current_admin`, so no host code decides it twice. If your base
+controller offers Pundit's `authorize`, both actions call it.
+
+### What a host overrides
+
+| Method | Default | Override to |
+| --- | --- | --- |
+| `mcp_write_access_allowed?` | `false` | let some admins mint write-enabled keys |
+| `mcp_api_key_owner` | `config.current_admin` | attribute the key to someone else |
+| `scoped_resource` | every key, newest first | show an admin only their own keys |
+
+```ruby
+module Admin
+  class AdministrateMcpApiKeysController < Admin::ApplicationController
+    include Administrate::MCP::ApiKeysAdmin
+
+    private
+
+    def mcp_write_access_allowed?
+      policy(Administrate::MCP::ApiKey).grant_write_access?
+    end
+
+    def scoped_resource
+      current_administrator.full_access? ? super : super.where(admin: current_administrator)
+    end
+  end
+end
+```
+
+### Different columns
+
+Redefine the constants you want to change in your subclass:
+
+```ruby
+class AdministrateMcpApiKeyDashboard < Administrate::MCP::ApiKeyDashboard
+  COLLECTION_ATTRIBUTES = %i[name last_used_at].freeze
+end
+```
+
+For a console mounted at a path Administrate cannot derive the dashboard from, name it explicitly:
+
+```ruby
+module Admin
+  class AdministrateMcpApiKeysController < Admin::ApplicationController
+    include Administrate::MCP::ApiKeysAdmin
+    administrate_mcp_resource Administrate::MCP::ApiKey, dashboard: ApiKeyConsoleDashboard
+  end
+end
+```
+
+## Listing the engine's tables over the protocol
+
+The consoles above are not MCP resources. The registry only reads your own dashboard directory, so
+the engine's dashboards are invisible to it whatever they are called. To expose a key list over the
+protocol, declare a dashboard in `app/dashboards` with an `MCP_DESCRIPTION` and a `self.model`:
+
+```ruby
 # app/dashboards/administrate_mcp/api_key_dashboard.rb
 module AdministrateMcp
   class ApiKeyDashboard < Administrate::BaseDashboard
+    MCP_DESCRIPTION = 'API keys admins authenticate to the MCP server with.'
+
     ATTRIBUTE_TYPES = { id: Field::String, name: Field::String, admin: Field::BelongsTo }.freeze
     COLLECTION_ATTRIBUTES = %i[id name].freeze
     SHOW_PAGE_ATTRIBUTES = %i[id name admin].freeze
@@ -28,18 +122,11 @@ module AdministrateMcp
     end
   end
 end
-
-# app/controllers/admin/administrate_mcp_api_keys_controller.rb
-module Admin
-  class AdministrateMcpApiKeysController < Admin::ApplicationController
-    def resource_class = Administrate::MCP::ApiKey
-    def dashboard_class = AdministrateMcp::ApiKeyDashboard
-  end
-end
 ```
 
-The MCP registry finds the dashboard through `self.model`, registers it as
-`administrate/mcp/api_key`, and builds record URLs from the namespaced route key.
+The registry finds it through `self.model`, registers it as `administrate/mcp/api_key`, and builds
+record URLs from the namespaced route key, so it never shadows a resource of your own called
+`api_keys`.
 
 ## Customising the consent screen
 
@@ -48,6 +135,11 @@ has `@application`, `@redirect_uri`, `@redirect_host` and `@scopes`.
 
 ## Feedback housekeeping
 
+The `administrate_mcp_feedbacks` table, its dashboard and this housekeeping service are only needed
+when `config.persist_feedback` is `true`. With it off, `report_mcp_improvement` still works and
+`on_feedback` still fires, just without a row behind it, and the table can be left out entirely; see
+[docs/configuration.md](configuration.md) for the setting.
+
 `Administrate::MCP::CleanOldFeedbacks.call(till: 2.months.ago)` deletes one batch of 10,000 and
 reports `more?`; schedule it however your app schedules work.
 

data/docs/configuration.md

@@ -3,7 +3,8 @@
 [Back to README](../README.md)
 
 Configure the engine in an initializer, `config/initializers/administrate_mcp.rb`. It must run
-before the engine's models load, because the `admin` association reads `admin_class_name`.
+before the engine's models load, because the `admin` association reads `admin_class_name` and
+`admin_foreign_key`.
 
 ```ruby
 Administrate::MCP.configure do |c|
@@ -11,6 +12,7 @@ Administrate::MCP.configure do |c|
   c.server_version = '1.0.0'
 
   c.admin_class_name = 'Administrator'
+  c.admin_foreign_key = :administrator_id
   c.current_admin = ->(controller) { controller.send(:warden)&.authenticate(scope: :administrator) }
   c.admin_active = ->(admin) { admin.admin? && admin.anonymized_at.nil? }
   c.sign_in = lambda do |controller|
@@ -36,10 +38,28 @@ Administrate::MCP.configure do |c|
     Admin::AuditOperation.call!(administrator_id: admin.id, request_method: 'POST',
                                 request_url: "mcp://tools/#{tool_name}", params: arguments)
   end
-  c.on_feedback = ->(feedback) { SlackNotifier.notify(notification_type: :mcp_feedback, blocks: blocks_for(feedback)) }
+  c.persist_feedback = true
+  c.on_feedback = ->(report) { SlackNotifier.notify(notification_type: :mcp_feedback, blocks: blocks_for(report)) }
 end
 ```
 
+Set `admin_foreign_key` when the host's own admin table already has a foreign key column under a
+different name, for example a live credentials table called `administrator_id`, and renaming that
+column is not something you want to do. The association is still called `admin` everywhere the
+engine's API uses it; only the column it reads and writes changes.
+
+`report_mcp_improvement` gives users of the MCP server a way to flag what the server got wrong; the
+gem's job stops at reporting that signal to `on_feedback`. Storing what it reports, showing it in a
+dashboard and cleaning up old rows is an opinion about how a host wants to handle the signal, not
+something every host needs, so it is batteries-included rather than mandatory: set
+`persist_feedback` to `true` to have the gem create an `Administrate::MCP::Feedback` row before
+calling `on_feedback`, expose it in your admin as described in
+[docs/admin-integration.md](admin-integration.md), and clean old rows up with
+`Administrate::MCP::CleanOldFeedbacks`. Leave it `false`, the default, and `on_feedback` still fires
+with the same report, just without a persisted record behind it, and the `administrate_mcp_feedbacks`
+table is never touched. Set `feedback_tool` to `false` to stop publishing `report_mcp_improvement`
+at all.
+
 ## The full configuration object
 
 ```ruby
@@ -77,6 +97,7 @@ class Configuration
                 :oauth,
                 :sign_in,
                 :admin_class_name,
+                :admin_foreign_key,
                 :authorization,
                 :default_required_roles,
                 :tool_paths,
@@ -87,6 +108,8 @@ class Configuration
                 :on_error,
                 :allow_localhost_redirects,
                 :default_client_name,
+                :persist_feedback,
+                :feedback_tool,
                 :sidekiq_stats_provider,
                 :admin_route_namespace,
                 :admin_url_options,
@@ -107,6 +130,7 @@ class Configuration
     @oauth = true
     @sign_in = nil
     @admin_class_name = 'Administrator'
+    @admin_foreign_key = :admin_id
     @authorization = default_authorization
     @default_required_roles = []
     @tool_paths = []
@@ -116,11 +140,13 @@ class Configuration
   def assign_hooks
     @instrument = ->(tool_name:, admin:, &block) { block.call }
     @on_tool_call = ->(tool_name:, admin:, arguments:, scopes:) {}
-    @on_feedback = ->(feedback) {}
+    @on_feedback = ->(report) {}
     @on_error = ->(exception) {}
     @allow_localhost_redirects = true
     @api_key_token_prefix = 'amcp_'
     @default_client_name = 'MCP Client'
+    @persist_feedback = false
+    @feedback_tool = true
     @sidekiq_stats_provider = nil
   end
 
@@ -155,18 +181,21 @@ end
 | `identity_fallback`         | returns `nil`                      | Proc taking the request, returning an `Authentication::Identity` or nil, consulted when no credential the engine issued matched                                                  |
 | `oauth`                     | `true`                             | Whether the engine serves its own OAuth 2.1 server. False draws no OAuth routes and never looks an access token up                                                               |
 | `sign_in`                   | `nil` (renders 401)                | Proc taking the OAuth controller, sending an anonymous visitor to sign in                                                                                                        |
-| `admin_class_name`          | `'Administrator'`                  | Class the `admin_id` column points at                                                                                                                                            |
+| `admin_class_name`          | `'Administrator'`                  | Class the admin foreign key column points at                                                                                                                                     |
+| `admin_foreign_key`         | `:admin_id`                        | Column on the engine's own tables that stores the owning admin's id. The association is still called `admin`; only the column name changes                                       |
 | `authorization`             | Pundit if defined, else Permissive | Adapter: `authorize!`, `authorized?`, `authorize_roles!`                                                                                                                         |
 | `default_required_roles`    | `[]`                               | Roles a tool requires unless it declares its own                                                                                                                                 |
 | `tool_paths`                | `[]`                               | Directories scanned for extra `BaseTool` subclasses                                                                                                                              |
 | `dashboard_paths`           | `app/dashboards`                   | Where dashboards are found                                                                                                                                                       |
 | `instrument`                | yields                             | Around hook `(tool_name:, admin:, &block)`                                                                                                                                       |
 | `on_tool_call`              | no-op                              | Audit hook `(tool_name:, admin:, arguments:, scopes:)`, after the permission checks                                                                                              |
-| `on_feedback`               | no-op                              | Called with each new `Feedback` record                                                                                                                                           |
+| `on_feedback`               | no-op                              | Called with each `FeedbackReport`, whether or not it was persisted                                                                                                               |
 | `on_error`                  | no-op                              | Called with an exception the engine swallowed, so you can report it                                                                                                              |
 | `allow_localhost_redirects` | `true`                             | Whether loopback OAuth redirect URIs are accepted. Inert when `oauth` is false                                                                                                   |
 | `api_key_token_prefix`      | `'amcp_'`                          | Prefix that marks a bearer token as an API key. Cannot be blank                                                                                                                  |
 | `default_client_name`       | `'MCP Client'`                     | Name given to a dynamically registered client that sends no `client_name`. Inert when `oauth` is false                                                                           |
+| `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 |
 | `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`                                                             |

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/configuration.rb

@@ -44,6 +44,7 @@ module Administrate
                     :oauth,
                     :sign_in,
                     :admin_class_name,
+                    :admin_foreign_key,
                     :authorization,
                     :default_required_roles,
                     :tool_paths,
@@ -54,6 +55,8 @@ module Administrate
                     :on_error,
                     :allow_localhost_redirects,
                     :default_client_name,
+                    :persist_feedback,
+                    :feedback_tool,
                     :sidekiq_stats_provider,
                     :admin_route_namespace,
                     :admin_url_options,
@@ -80,6 +83,7 @@ module Administrate
         @oauth = true
         @sign_in = nil
         @admin_class_name = 'Administrator'
+        @admin_foreign_key = :admin_id
         @authorization = default_authorization
         @default_required_roles = []
         @tool_paths = []
@@ -89,11 +93,13 @@ module Administrate
       def assign_hooks
         @instrument = ->(tool_name:, admin:, &block) { block.call } # rubocop:disable Lint/UnusedBlockArgument
         @on_tool_call = ->(tool_name:, admin:, arguments:, scopes:) {}
-        @on_feedback = ->(feedback) {}
+        @on_feedback = ->(report) {}
         @on_error = ->(exception) {}
         @allow_localhost_redirects = true
         @api_key_token_prefix = 'amcp_'
         @default_client_name = 'MCP Client'
+        @persist_feedback = false
+        @feedback_tool = true
         @sidekiq_stats_provider = nil
       end
 

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.1.0'
+    VERSION = '0.3.0'
   end
 end