administrate-mcp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4da1e224450ced4f0f0e209279bf8f07e3e863b8cc54d53deb20071e09c162f5
-  data.tar.gz: 7299ecaabb67efa26432087c689d6291d7b839692a97855997f0a5aa94ea8e5c
+  metadata.gz: 68fb06b806eb2dea5dbb0e0a01a865b4a9984b515a358bfd86fab8d0b949b65c
+  data.tar.gz: ac0a3ef739bf776dff2325bc3ae641e22b694047ffd03d078c944810b2071768
 SHA512:
-  metadata.gz: 52016172bf5d81384da02d845c2a7e491ad88859b414ce20b1732804deeff46f930a4df8e4d73b254721c31c39fe8bf2907cda7e56c32dd7b1728641993025ae
-  data.tar.gz: 78e0e4ac8f02ce53a3c4603d5bcb8d95ace6976192fed36519a0df092fa2a0b7bec2ac1fc071e3fcc2862e60f81195377943bd2c7693060c488d5ea4b4548a5a
+  metadata.gz: 1d6204806b8c490362a1e4a56939a3ae588897f069f7c1e21c4ff653eaed486d06cd238e3243d3c3a29edcc2399a7aef25deed80022e598f8b52fc36a7fc7895
+  data.tar.gz: 2064c7b7ad08e21f32eba4db06ebda81d594e1abf0c731ddf369a901282ce419c923eea77715faa1c25ae44601809e4f3195d55fc539c91e90ae5b2d4107eca1

data/CHANGELOG.md

@@ -8,6 +8,37 @@ minor release may change behaviour a host depends on; the entry says so when it
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-22
+
+### Added
+
+- The admin console for the engine's own tables: the `Administrate::MCP::ApiKeyDashboard` and
+  `Administrate::MCP::FeedbackDashboard` base dashboards, and the `Administrate::MCP::ApiKeysAdmin`
+  and `Administrate::MCP::FeedbacksAdmin` controller concerns. A host subclasses each dashboard
+  under the name its own inflections give `administrate_mcp_api_key_dashboard.rb`, which differs
+  between an application that registers MCP as an acronym and one that does not. The concern goes in
+  a controller of the host's own, which keeps its base controller, authentication and policies; the
+  engine supplies the resource wiring, key generation, the one-time plaintext in the flash, and
+  revocation. Write-enabled keys are refused until the host overrides `mcp_write_access_allowed?`.
+- `config.admin_foreign_key`, defaulting to `:admin_id`, so a host whose admin table already has a
+  differently named foreign key can keep that column name instead of renaming it. The association
+  stays called `admin` everywhere in the engine's API; only the column it reads and writes changes.
+- `config.persist_feedback`, defaulting to `false`, so a host can use `report_mcp_improvement` and
+  `on_feedback` as a plain signal without carrying the `administrate_mcp_feedbacks` table, its model
+  or its migration. Set it to `true` for the previous behaviour: the report is persisted before
+  `on_feedback` runs, and the dashboard and `CleanOldFeedbacks` housekeeping become meaningful.
+- `config.feedback_tool`, defaulting to `true`, to stop publishing `report_mcp_improvement`
+  altogether.
+
+### Changed
+
+- `on_feedback` is now called with a `FeedbackReport`, a plain value object, instead of a persisted
+  `Feedback` record. A host reading attributes off the argument (`category`, `suggestion`,
+  `resource_name`, `admin`, `api_key`) sees no difference; a host that relied on it being an
+  `ActiveRecord` instance, for example calling `.save`, `.update` or `.reload` on it, or expecting
+  `.persisted?` to be true, must update its `on_feedback` hook. When `config.persist_feedback` is
+  `true` the persisted record is still reachable, as `report.record`.
+
 ## [0.1.0] - 2026-09-22
 
 ### Added
@@ -57,5 +88,6 @@ 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.1.0...HEAD
+[Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.2.0...HEAD
+[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/README.md

@@ -23,6 +23,7 @@ permissions the admin UI enforces.
 - [Dashboard declarations](#dashboard-declarations)
 - [Authentication](#authentication)
 - [OAuth](#oauth)
+- [Improving the server from its own use](#improving-the-server-from-its-own-use)
 - [Rate limiting](#rate-limiting)
 - [Admin integration](#admin-integration)
 - [Development](#development)
@@ -53,8 +54,14 @@ about your application; everything host-specific goes through `Administrate::MCP
   as the admin UI, so a resource an admin cannot see in the browser is not exposed over MCP either.
 - Search, filters and field selection built from the dashboard's own declarations, plus foreign key
   filters that need no declaration at all.
-- A feedback tool, `report_mcp_improvement`, so users can report what the server got wrong, and a
-  housekeeping method to clean up old feedback records.
+- A feedback tool, `report_mcp_improvement`, so the client can tell you which of your descriptions,
+  filters and fields let it down, and you can fix them. See
+  [Improving the server from its own use](#improving-the-server-from-its-own-use). The signal is
+  always available through `config.on_feedback`; storing it, the dashboard and the clean-up service
+  are a batteries-included option a host turns on with `config.persist_feedback`.
+- The admin console for its own tables, as two dashboards and two controller concerns you include
+  in controllers of your own: issuing an API key, revoking one, and reading the feedback, without
+  giving up your base controller, your authentication or your policies.
 - Optional Sidekiq introspection tools, `sidekiq_stats` and `sidekiq_retries`, wired to a stats
   provider object you supply.
 - No reference to a constant it does not own: field serializers are keyed on class names, dashboards
@@ -151,13 +158,20 @@ bin/rails db:migrate
 
 The tables are `administrate_mcp_api_keys`, `administrate_mcp_feedbacks`,
 `administrate_mcp_oauth_applications`, `administrate_mcp_oauth_access_grants` and
-`administrate_mcp_oauth_access_tokens`. They use uuid primary keys and a uuid `admin_id` column
-that is indexed but carries no foreign key constraint, so the engine works with any admin table.
+`administrate_mcp_oauth_access_tokens`. They use uuid primary keys and a uuid column, `admin_id` by
+default, that is indexed but carries no foreign key constraint, so the engine works with any admin
+table. Set `config.admin_foreign_key` before running the migrations if the host's own admin table
+already uses a different column name and renaming it is not an option, for example a live
+credentials table.
+
+`administrate_mcp_feedbacks` is only needed when `config.persist_feedback` is `true`; leave it
+`false`, the default, and the migration ships but the table is never read from or written to.
 
 ## Quick start
 
 The smallest configuration that works. Save it as `config/initializers/administrate_mcp.rb`; it
-must run before the engine's models load, because the `admin` association reads `admin_class_name`:
+must run before the engine's models load, because the `admin` association reads `admin_class_name`
+and `admin_foreign_key`:
 
 ```ruby
 Administrate::MCP.configure do |c|
@@ -218,6 +232,35 @@ with the gem for hosts that run edge-managed OAuth in front of the application:
 The built-in OAuth 2.1 server, what turning it off with `c.oauth = false` changes, and when a host
 should: [docs/oauth.md](docs/oauth.md).
 
+## Improving the server from its own use
+
+Every tool here is built from your dashboards: the resource names, the field lists, the filters and
+the `MCP_DESCRIPTION` you wrote. The client calling those tools is the one that gets misled when any
+of it is wrong, and it is the only party that knows which call it was trying to make. The engine has
+no way to detect this on its own: a vague description is not an error, it is a successful call that
+returned the wrong thing or a query the caller gave up on.
+
+`report_mcp_improvement` is how the client tells you. Its categories are deliberately not free text.
+Each one names a change you make in a dashboard:
+
+| Category | What it points at |
+| --- | --- |
+| `description` | `MCP_DESCRIPTION` is missing, vague or actively misleading |
+| `missing_filter` | the query needed a filter the dashboard does not declare |
+| `missing_field` | a field the caller needed is not on the show page |
+| `missing_resource` | a dashboard is not exposed, or does not exist |
+| `serialization` | a field came back unreadable and needs a serializer registered |
+| `other` | anything the categories above do not cover |
+
+A report arrives with the category, the resource it concerns and the client's own account of what it
+wanted, which is most of a change request already. Wire `config.on_feedback` to somewhere your team
+will actually read, work through what arrives, and the next caller gets a server that describes
+itself better. Turning on `config.persist_feedback` keeps the reports in a table so you can triage a
+batch at a time rather than react to each one.
+
+This is the loop the tool exists for. It is worth running deliberately rather than waiting for
+complaints: point a client at the server, give it real tasks, and collect what it could not do.
+
 ## Rate limiting
 
 The rack-attack throttles recommended for the OAuth endpoints, and the helper that registers them
@@ -225,8 +268,9 @@ for you: [docs/oauth.md#rate-limiting](docs/oauth.md#rate-limiting).
 
 ## Admin integration
 
-Exposing the engine's own tables (API keys, feedback) in your host admin, customising the consent
-screen, and cleaning up old feedback: [docs/admin-integration.md](docs/admin-integration.md).
+Including the API key and feedback consoles the engine ships, what a host overrides in them,
+listing the engine's own tables over the protocol, customising the consent screen, and cleaning up
+old feedback: [docs/admin-integration.md](docs/admin-integration.md).
 
 ## Development
 

data/app/controllers/concerns/administrate/mcp/api_keys_admin.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Administrate console for the API keys admins authenticate to the MCP server with. The host
+    # keeps its own base controller, authentication and policies; this supplies the resource wiring
+    # and the two actions a write-once credential needs, because the plaintext key exists only in
+    # the response that creates it.
+    #
+    # A host that lets some admins mint write-enabled keys overrides `mcp_write_access_allowed?`.
+    module ApiKeysAdmin
+      extend ActiveSupport::Concern
+      include ResourceController
+
+      TOKEN_PREFIX_LENGTH = 13
+      WRITE_ACCESS_REFUSAL = 'Only administrators allowed to grant write access can create write-enabled API keys.'
+
+      included do
+        administrate_mcp_resource Administrate::MCP::ApiKey
+      end
+
+      def create
+        token = Administrate::MCP::ApiKey.generate_token
+        api_key = build_mcp_api_key(token)
+        authorize_mcp_resource(api_key)
+
+        if api_key.write_access? && !mcp_write_access_allowed?
+          return render_mcp_form_error(api_key, WRITE_ACCESS_REFUSAL)
+        end
+
+        if api_key.save
+          redirect_to_mcp_index("MCP API key created. Copy it now, it is not shown again: #{token}")
+        else
+          render_mcp_form_error(api_key, api_key.errors.full_messages.join(', '))
+        end
+      end
+
+      def destroy
+        api_key = requested_resource
+        authorize_mcp_resource(api_key)
+        api_key.revoke!
+
+        redirect_to_mcp_index("API key '#{api_key.name}' has been revoked.")
+      end
+
+      private
+
+      def build_mcp_api_key(token)
+        Administrate::MCP::ApiKey.new(
+          admin: mcp_api_key_owner,
+          token_digest: Administrate::MCP::ApiKey.digest_token(token),
+          token_prefix: token[0, TOKEN_PREFIX_LENGTH],
+          name: mcp_api_key_name,
+          write_access: mcp_write_access_requested?
+        )
+      end
+
+      def mcp_api_key_owner
+        Administrate::MCP.config.current_admin.call(self)
+      end
+
+      def mcp_api_key_name
+        params.dig(resource_name, :name).presence || 'Unnamed key'
+      end
+
+      def mcp_write_access_requested?
+        ActiveModel::Type::Boolean.new.cast(params.dig(resource_name, :write_access)) || false
+      end
+
+      # A write-enabled key carries every write tool, so granting one is a decision the host makes.
+      def mcp_write_access_allowed?
+        false
+      end
+
+      def authorize_mcp_resource(api_key)
+        authorize(api_key) if respond_to?(:authorize, true)
+      end
+
+      def redirect_to_mcp_index(notice)
+        redirect_to({ action: :index }, notice:, status: :see_other)
+      end
+
+      def render_mcp_form_error(api_key, message)
+        flash.now[:error] = message
+        render :new, locals: { page: Administrate::Page::Form.new(dashboard, api_key) }, status: :unprocessable_content
+      end
+
+      def scoped_resource
+        super.order(created_at: :desc)
+      end
+    end
+  end
+end

data/app/controllers/concerns/administrate/mcp/feedbacks_admin.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Administrate console for the improvement reports `report_mcp_improvement` stores. Reading them
+    # is the whole point, so no action is overridden beyond the resource wiring and the ordering:
+    # the newest report is the one a maintainer has not acted on yet.
+    #
+    # Only meaningful with `config.persist_feedback` on; without it nothing writes to the table.
+    module FeedbacksAdmin
+      extend ActiveSupport::Concern
+      include ResourceController
+
+      included do
+        administrate_mcp_resource Administrate::MCP::Feedback
+      end
+
+      private
+
+      def scoped_resource
+        super.order(created_at: :desc)
+      end
+    end
+  end
+end

data/app/controllers/concerns/administrate/mcp/resource_controller.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Points an Administrate controller at a model the engine owns, rather than at the one
+    # Administrate would infer from the controller's own name.
+    #
+    # The dashboard is left alone on purpose. Administrate finds it by camelizing the controller's
+    # name, and a host that registers MCP as an inflection acronym spells that constant differently
+    # from one that does not. Naming it here would be right in one host and an autoloading error in
+    # the other, so each host declares its own dashboard, usually a subclass of the engine's.
+    module ResourceController
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :mcp_resource_class, :mcp_dashboard_class
+      end
+
+      class_methods do
+        # `dashboard` is only needed for a dashboard Administrate cannot find from the controller's
+        # own name.
+        def administrate_mcp_resource(resource_class, dashboard: nil)
+          self.mcp_resource_class = resource_class
+          self.mcp_dashboard_class = dashboard
+        end
+      end
+
+      def resource_class
+        mcp_resource_class
+      end
+
+      private
+
+      def resource_resolver
+        @resource_resolver ||=
+          Administrate::MCP::ResourceResolver.new(
+            controller_path,
+            resource_class: mcp_resource_class,
+            dashboard_class: mcp_dashboard_class
+          )
+      end
+    end
+  end
+end

data/app/dashboards/administrate/mcp/api_key_dashboard.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'administrate/base_dashboard'
+
+module Administrate
+  module MCP
+    # Default Administrate dashboard for the engine's API keys. A host that wants other columns
+    # subclasses it and redefines the constants it cares about.
+    #
+    # Nothing here is registered as an MCP resource: the registry only reads the host's own
+    # dashboard directory, so a host that wants the keys listed over the protocol declares a
+    # subclass there with an `MCP_DESCRIPTION`.
+    class ApiKeyDashboard < Administrate::BaseDashboard
+      ATTRIBUTE_TYPES = {
+        id: Field::String.with_options(searchable: false),
+        admin: Field::BelongsTo.with_options(class_name: Administrate::MCP.config.admin_class_name),
+        name: Field::String,
+        token_prefix: Field::String,
+        write_access: Field::Boolean,
+        last_used_at: Field::DateTime,
+        revoked_at: Field::DateTime,
+        created_at: Field::DateTime,
+        updated_at: Field::DateTime
+      }.freeze
+
+      COLLECTION_ATTRIBUTES = %i[name admin token_prefix write_access last_used_at revoked_at].freeze
+
+      SHOW_PAGE_ATTRIBUTES = %i[
+        id
+        admin
+        name
+        token_prefix
+        write_access
+        last_used_at
+        revoked_at
+        created_at
+        updated_at
+      ].freeze
+
+      FORM_ATTRIBUTES = %i[name write_access].freeze
+
+      COLLECTION_FILTERS = {}.freeze
+
+      def self.model
+        Administrate::MCP::ApiKey
+      end
+
+      def display_resource(api_key)
+        "#{api_key.name} (#{api_key.token_prefix}...)"
+      end
+    end
+  end
+end

data/app/dashboards/administrate/mcp/feedback_dashboard.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'administrate/base_dashboard'
+
+module Administrate
+  module MCP
+    # Default Administrate dashboard for the improvement reports the feedback tool stores. A host
+    # that wants other columns subclasses it and redefines the constants it cares about.
+    class FeedbackDashboard < Administrate::BaseDashboard
+      ATTRIBUTE_TYPES = {
+        id: Field::String.with_options(searchable: false),
+        admin: Field::BelongsTo.with_options(class_name: Administrate::MCP.config.admin_class_name),
+        api_key: Field::BelongsTo.with_options(class_name: 'Administrate::MCP::ApiKey'),
+        category: Field::Select.with_options(collection: -> { Administrate::MCP::Feedback.categories.keys }),
+        resource_name: Field::String,
+        suggestion: Field::Text,
+        status: Field::Select.with_options(collection: -> { Administrate::MCP::Feedback.statuses.keys }),
+        created_at: Field::DateTime,
+        updated_at: Field::DateTime
+      }.freeze
+
+      COLLECTION_ATTRIBUTES = %i[category resource_name status admin created_at].freeze
+
+      SHOW_PAGE_ATTRIBUTES = %i[id admin api_key category resource_name suggestion status created_at updated_at].freeze
+
+      # Triaging a report is the one edit worth making from the console.
+      FORM_ATTRIBUTES = %i[status].freeze
+
+      COLLECTION_FILTERS = {
+        status: ->(resources, status) { resources.where(status:) },
+        category: ->(resources, category) { resources.where(category:) }
+      }.freeze
+
+      def self.model
+        Administrate::MCP::Feedback
+      end
+
+      def display_resource(feedback)
+        "#{feedback.category} on #{feedback.resource_name.presence || 'the server'}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # The category list behind `Feedback#category` and the `report_mcp_improvement` schema, kept
+    # independent of the model so validation and the tool's input schema work whether or not the
+    # `administrate_mcp_feedbacks` table exists.
+    module FeedbackCategories
+      CATEGORIES = {
+        'description' => 0,
+        'missing_filter' => 1,
+        'missing_field' => 2,
+        'missing_resource' => 3,
+        'serialization' => 4,
+        'other' => 5
+      }.freeze
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Plain report of an MCP improvement suggestion, handed to `config.on_feedback` whether or not
+    # `config.persist_feedback` is on. `record` and `api_key` are only set when it is, so a host that
+    # wants the persisted row can reach it; the report itself never needs the `Feedback` table to
+    # exist.
+    FeedbackReport = Struct.new(:admin, :category, :suggestion, :resource_name, :api_key, :record, keyword_init: true)
+  end
+end

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

@@ -2,9 +2,12 @@
 
 module Administrate
   module MCP
-    # Persists an MCP improvement suggestion and hands it to the host's `on_feedback` hook.
+    # Validates an MCP improvement suggestion and hands a plain report to the host's `on_feedback`
+    # hook. Persisting the report to the `Feedback` table is opt-in through `config.persist_feedback`;
+    # when that is off, nothing here touches `Feedback` or `ApiKey`, so a host that never turns it on
+    # need not carry the table at all.
     class ReportImprovement
-      Result = Struct.new(:success?, :feedback, :errors, keyword_init: true)
+      Result = Struct.new(:success?, :report, :errors, keyword_init: true)
 
       def self.call(...)
         new(...).call
@@ -19,11 +22,11 @@ module Administrate
 
       def call
         errors = validation_errors
-        return Result.new(success?: false, feedback: nil, errors:) if errors.any?
+        return Result.new(success?: false, report: nil, errors:) if errors.any?
 
-        feedback = create_feedback
-        notify(feedback)
-        Result.new(success?: true, feedback:, errors: [])
+        report = build_report
+        notify(report)
+        Result.new(success?: true, report:, errors: [])
       end
 
       private
@@ -32,13 +35,22 @@ module Administrate
 
       def validation_errors
         errors = []
-        unless Feedback.categories.key?(category.to_s)
-          errors << "category must be one of: #{Feedback.categories.keys.join(', ')}"
+        unless FeedbackCategories::CATEGORIES.key?(category.to_s)
+          errors << "category must be one of: #{FeedbackCategories::CATEGORIES.keys.join(', ')}"
         end
         errors << "suggestion can't be blank" if suggestion.blank?
         errors
       end
 
+      def build_report
+        record = create_feedback if persist_feedback?
+        FeedbackReport.new(admin:, category:, suggestion:, resource_name:, record:, api_key: record&.api_key)
+      end
+
+      def persist_feedback?
+        Administrate::MCP.config.persist_feedback
+      end
+
       def create_feedback
         Feedback.create!(admin:, api_key: latest_api_key, category:, resource_name:, suggestion:)
       end
@@ -47,9 +59,8 @@ module Administrate
         ApiKey.active.where(admin:).order(last_used_at: :desc).first
       end
 
-      # The feedback is already persisted; a broken notifier must not take the report down with it.
-      def notify(feedback)
-        Administrate::MCP.config.on_feedback.call(feedback)
+      def notify(report)
+        Administrate::MCP.config.on_feedback.call(report)
       rescue StandardError => e
         Administrate::MCP.config.on_error.call(e)
       end

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'
@@ -46,6 +47,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/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/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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: administrate-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sorare
@@ -84,6 +84,11 @@ files:
 - README.md
 - app/controllers/administrate/mcp/json_rpc_controller.rb
 - app/controllers/administrate/mcp/o_auth_controller.rb
+- app/controllers/concerns/administrate/mcp/api_keys_admin.rb
+- app/controllers/concerns/administrate/mcp/feedbacks_admin.rb
+- 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/actions.rb
 - app/lib/administrate/mcp/admin_dashboard_tool.rb
 - app/lib/administrate/mcp/authentication.rb
@@ -91,9 +96,12 @@ files:
 - app/lib/administrate/mcp/clean_old_feedbacks.rb
 - app/lib/administrate/mcp/dashboard_registry.rb
 - app/lib/administrate/mcp/fast_search.rb
+- app/lib/administrate/mcp/feedback_categories.rb
+- app/lib/administrate/mcp/feedback_report.rb
 - app/lib/administrate/mcp/field_serializer.rb
 - app/lib/administrate/mcp/o_auth_service.rb
 - app/lib/administrate/mcp/report_improvement.rb
+- app/lib/administrate/mcp/resource_resolver.rb
 - app/lib/administrate/mcp/server_builder.rb
 - app/lib/administrate/mcp/tools/admin_resource_list.rb
 - app/lib/administrate/mcp/tools/admin_resource_list_resources.rb