administrate-mcp 0.1.0

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    module Tools
+      # Lists/searches admin resources using Administrate dashboard definitions and search.
+      class AdminResourceList < AdminDashboardTool
+        MAX_PER_PAGE = 25
+        MAX_EXPAND = 2
+
+        def self.policy_action
+          :index?
+        end
+
+        tool_name 'admin_resource_list'
+        description 'Search and list admin resources. ' \
+                    'Supports text search, filters, sorting, field selection, and HasMany expansion.'
+        annotations read_only_hint: true, destructive_hint: false, open_world_hint: true
+
+        input_schema(
+          properties: {
+            resource: {
+              type: 'string',
+              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.'
+            },
+            query: {
+              type: 'string',
+              description:
+                'Search query (optional). Searches across searchable string fields ' \
+                '(e.g., slug, display_name). Uses exact matching by default — ' \
+                'use * as wildcard for partial matches (e.g., "*stellar*ligue*").'
+            },
+            filters: {
+              type: 'object',
+              description:
+                'Filters to apply (optional). Keys are filter names, values are filter arguments. ' \
+                'Use admin_resource_list_resources to discover available filters per resource.'
+            },
+            sort: {
+              type: 'string',
+              description: 'Field to sort by (e.g., "created_at", "ranking"). Must be a valid dashboard attribute.'
+            },
+            sort_direction: {
+              type: 'string',
+              enum: %w[asc desc],
+              description: 'Sort direction (default: desc)'
+            },
+            fields: {
+              type: 'array',
+              items: {
+                type: 'string'
+              },
+              description: 'Specific fields to return (optional). Returns all collection fields if omitted.'
+            },
+            expand: {
+              type: 'array',
+              items: {
+                type: 'string'
+              },
+              description:
+                'HasMany associations to expand inline instead of counts. Max 2 associations. An expanded ' \
+                'association returns {count, items}: count is the association total, and items is capped at ' \
+                '25 rows. Both ship in the same response, so always compare them — count > items.length ' \
+                'means the list is clipped and items is NOT the full set. items also come back in no ' \
+                'guaranteed order: the sort_by / direction declared on the dashboard attribute is not ' \
+                'applied on this path, so a clipped expand is an arbitrary slice and not the newest rows — ' \
+                'reading recency off it can report a year-old row as the latest one. There is no way to page ' \
+                'past the cap or to sort here: when you need the remaining rows, or the most recent ones, ' \
+                'list the related resource directly with a filter on this record and an explicit sort.'
+            },
+            page: {
+              type: 'number',
+              description: 'Page number (default: 1)'
+            },
+            per_page: {
+              type: 'number',
+              description: "Results per page (default: 10, max: #{MAX_PER_PAGE})"
+            }
+          },
+          required: %w[resource]
+        )
+
+        # rubocop:disable-next Lint/UnusedMethodArgument
+        def self.execute(
+          admin:,
+          resource:,
+          query: nil,
+          filters: nil,
+          sort: nil,
+          sort_direction: 'desc',
+          fields: nil,
+          expand: nil,
+          page: 1,
+          per_page: 10
+        )
+          entry = find_dashboard_entry!(resource)
+          dashboard = entry.dashboard_class.new
+          per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
+          page = [page.to_i, 1].max
+          scope = build_scope(entry, dashboard, query, filters)
+          scope = apply_sort(scope, dashboard, sort, sort_direction)
+          records = scope.page(page).per(per_page)
+
+          json_response(build_response(records, dashboard, page, per_page, fields:, expand:))
+        end
+
+        def self.build_response(records, dashboard, page, per_page, fields: nil, expand: nil)
+          attrs, expand_set =
+            resolve_attributes_and_expansions(dashboard, fields, expand, :collection_attributes, MAX_EXPAND)
+          columns = FieldSerializer.resolve_columns(dashboard, attrs)
+
+          {
+            columns: %w[url] + columns.map(&:to_s),
+            rows:
+              records.map do |r|
+                [FieldSerializer.admin_url_for(r)] +
+                  FieldSerializer.serialize_row(r, dashboard, columns:, expand: expand_set)
+              end,
+            meta: {
+              page:,
+              per_page:,
+              total_count: records.total_count,
+              total_pages: records.total_pages
+            }
+          }
+        end
+
+        def self.build_scope(entry, dashboard, query, filters)
+          scope = entry.scope
+          scope = apply_includes(scope, dashboard)
+          scope = apply_search(scope, dashboard, query) if query.present?
+          scope = apply_filters(scope, entry, filters) if filters.present?
+          scope
+        end
+
+        def self.apply_includes(scope, dashboard)
+          includes = dashboard.collection_includes
+          includes.any? ? scope.preload(*includes) : scope
+        end
+
+        def self.apply_filters(scope, entry, filters)
+          dashboard_filters = dashboard_collection_filters(entry.dashboard_class)
+          valid_columns = association_columns(entry.model_class)
+
+          reject_unknown!('filters', filters.keys, dashboard_filters.keys.map(&:to_s) + valid_columns.to_a)
+
+          filters.each do |name, value|
+            scope = apply_single_filter(scope, name, value, dashboard_filters, valid_columns)
+          end
+          scope
+        end
+
+        def self.apply_single_filter(scope, name, value, dashboard_filters, valid_columns)
+          dashboard_filter = dashboard_filters[name.to_sym]
+          if dashboard_filter
+            dashboard_filter.arity == 1 ? dashboard_filter.call(scope) : dashboard_filter.call(scope, value)
+          elsif valid_columns.include?(name.to_s)
+            scope.where(name.to_s => value)
+          else
+            scope
+          end
+        end
+
+        def self.dashboard_collection_filters(dashboard_class)
+          return {} unless dashboard_class.const_defined?(:COLLECTION_FILTERS, false)
+
+          dashboard_class.const_get(:COLLECTION_FILTERS, false)
+        end
+
+        def self.apply_search(scope, dashboard, query)
+          results = FastSearch.new(scope, dashboard, query).run
+          return results if results.exists?
+
+          Administrate::Search.new(scope, dashboard, query).run
+        end
+
+        def self.apply_sort(scope, dashboard, sort, direction)
+          return scope if sort.blank?
+
+          reject_unknown!('sort fields', sort, FieldSerializer.exposed_attributes(dashboard))
+
+          safe_direction = direction.to_s == 'asc' ? :asc : :desc
+          scope.order(sort.to_sym => safe_direction)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    module Tools
+      # Lists available admin resources. Without a resource param, returns a lightweight catalog
+      # (name + description). With a resource param, returns full detail (fields + filters).
+      class AdminResourceListResources < AdminDashboardTool
+        tool_name 'admin_resource_list_resources'
+        description 'Discover available admin resources. ' \
+                    'Without a resource param: returns all resource names (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
+
+        input_schema(
+          properties: {
+            resource: {
+              type: 'string',
+              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.'
+            }
+          }
+        )
+
+        def self.execute(admin:, resource: nil)
+          return detail_response(admin, resource) if resource.present?
+
+          catalog_response(admin)
+        end
+
+        def self.catalog_response(admin)
+          resources =
+            DashboardRegistry.resource_names.filter_map do |name|
+              entry = DashboardRegistry.find(name)
+              next unless entry
+              next unless authorized?(admin, entry.model_class, :index?)
+
+              result = { name: }
+              result[:description] = entry.description if entry.description.present?
+              result
+            end
+
+          json_response(resources)
+        end
+
+        def self.detail_response(admin, resource_name)
+          entry = find_dashboard_entry!(resource_name)
+          authorize_resource!(admin, entry.model_class, :index?)
+
+          json_response(build_detail(resource_name, entry))
+        end
+
+        def self.build_detail(name, entry)
+          dashboard = entry.dashboard_class.new
+          result = { name:, fields: FieldSerializer.exposed_attributes(dashboard).map(&:to_s) }
+          result[:description] = entry.description if entry.description.present?
+          enrich_detail!(result, entry, dashboard)
+          result
+        end
+
+        def self.enrich_detail!(result, entry, dashboard)
+          filters = collection_filters(entry.dashboard_class, entry.model_class)
+          result[:filters] = filters if filters.present?
+          expandable = expandable_associations(dashboard)
+          result[:expandable] = expandable if expandable.present?
+        end
+
+        def self.expandable_associations(dashboard)
+          dashboard.attribute_types.filter_map do |attr_name, spec|
+            next unless FieldSerializer.expandable_field?(FieldSerializer.resolve_field_class(spec))
+
+            attr_name.to_s
+          end
+        end
+
+        def self.collection_filters(dashboard_class, model_class)
+          dashboard_filters = dashboard_defined_filters(dashboard_class)
+          dashboard_filter_names = dashboard_filters.to_set { |f| f[:name] }
+
+          assoc_filters =
+            association_columns(model_class)
+            .reject { |col| dashboard_filter_names.include?(col) }
+            .sort
+            .map { |col| { name: col, type: 'value' } }
+
+          dashboard_filters + assoc_filters
+        end
+
+        def self.dashboard_defined_filters(dashboard_class)
+          return [] unless dashboard_class.const_defined?(:COLLECTION_FILTERS, false)
+
+          dashboard_class
+            .const_get(:COLLECTION_FILTERS, false)
+            .map do |name, filter|
+              type = filter.arity == 1 ? 'boolean' : 'value'
+              { name: name.to_s, type: }
+            end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    module Tools
+      # Shows a single admin resource by ID or slug using its Administrate dashboard definition.
+      class AdminResourceShow < AdminDashboardTool
+        MAX_BATCH = 10
+        MAX_EXPAND = 2
+
+        def self.policy_action
+          :show?
+        end
+
+        tool_name 'admin_resource_show'
+        description 'Show admin resource(s) by ID or slug. ' \
+                    'Accepts a single ID or an array of up to 10 IDs for batch lookup.'
+        annotations read_only_hint: true, destructive_hint: false, open_world_hint: true
+
+        input_schema(
+          properties: {
+            resource: {
+              type: 'string',
+              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.'
+            },
+            id: {
+              oneOf: [
+                { type: 'string', description: 'Single resource ID or slug — one id, never a list encoded as text' },
+                {
+                  type: 'array',
+                  items: {
+                    type: 'string'
+                  },
+                  maxItems: MAX_BATCH,
+                  description:
+                    "Multiple IDs (max #{MAX_BATCH}), as a real JSON array. A stringified array is read as one " \
+                    'id, matches nothing, and fails with "<Resource> not found for: [...]" echoing the whole ' \
+                    'list — that error means the ids never reached the batch path, not that they are wrong, ' \
+                    'so re-send them as an array rather than falling back to single calls. ' \
+                    'Attributes a dashboard computes per record are not resolved in batch mode and come back ' \
+                    'as "[error: could not serialize <field>]" — pass a single ID when you need one of those.'
+                }
+              ]
+            },
+            fields: {
+              type: 'array',
+              items: {
+                type: 'string'
+              },
+              description: 'Specific fields to return (optional). Returns all fields if omitted.'
+            },
+            expand: {
+              type: 'array',
+              items: {
+                type: 'string'
+              },
+              description:
+                'HasMany associations to expand inline instead of counts. Max 2 associations. An expanded ' \
+                'association returns {count, items}: count is the association total, and items is capped at ' \
+                '25 rows. Both ship in the same response, so always compare them — count > items.length ' \
+                'means the list is clipped and items is NOT the full set. items also come back in no ' \
+                'guaranteed order: the sort_by / direction declared on the dashboard attribute is not ' \
+                'applied on this path, so a clipped expand is an arbitrary slice and not the newest rows — ' \
+                'reading recency off it can report a year-old row as the latest one. There is no way to page ' \
+                'past the cap or to sort here: when you need the remaining rows, or the most recent ones, ' \
+                'list the related resource directly with a filter on this record and an explicit sort.'
+            }
+          },
+          required: %w[resource id]
+        )
+
+        def self.execute(admin:, resource:, id:, fields: nil, expand: nil) # rubocop:disable Lint/UnusedMethodArgument
+          entry = find_dashboard_entry!(resource)
+          dashboard = entry.dashboard_class.new
+          attrs, expand_set =
+            resolve_attributes_and_expansions(dashboard, fields, expand, :show_page_attributes, MAX_EXPAND)
+
+          return batch_show(entry, dashboard, id, resource, attributes: attrs, expand: expand_set) if id.is_a?(Array)
+
+          record = find_record(entry, id)
+          return error_response("#{resource.capitalize} not found for: #{id}") unless record
+
+          json_response(
+            FieldSerializer.serialize(record, dashboard, attributes: attrs, expand: expand_set, resolve_getters: true)
+          )
+        end
+
+        # Getters stay unresolved here: they are per-record work, and a batch multiplies them by up
+        # to MAX_BATCH. Read one id at a time when a getter-backed attribute matters.
+        def self.batch_show(entry, dashboard, ids, resource, attributes:, expand:)
+          reject_over_limit!('ids', ids.size, MAX_BATCH)
+          columns = FieldSerializer.resolve_columns(dashboard, attributes)
+
+          rows =
+            ids.map do |single_id|
+              record = find_record(entry, single_id)
+              if record
+                [FieldSerializer.admin_url_for(record)] +
+                  FieldSerializer.serialize_row(record, dashboard, columns:, expand:)
+              else
+                { id: single_id, error: "#{resource.capitalize} not found" }
+              end
+            end
+
+          json_response({ columns: %w[url] + columns.map(&:to_s), rows: })
+        end
+
+        def self.find_record(entry, id)
+          entry.scope.find_by(id:) || friendly_find(entry, id)
+        rescue ActiveRecord::RecordNotFound
+          nil
+        end
+
+        def self.friendly_find(entry, id)
+          return nil unless entry.model_class.respond_to?(:friendly)
+
+          entry.scope.friendly.find(id)
+        rescue ActiveRecord::RecordNotFound
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    module Tools
+      # Lets MCP users report improvements (misleading descriptions, missing filters, etc.).
+      # Open to every authenticated admin: reporting a bad description is not a privileged action.
+      class ReportImprovement < BaseTool
+        tool_name 'report_mcp_improvement'
+        requires_roles
+        description 'Report an improvement for the MCP server (misleading description, missing filter, ' \
+                    'bad serialization, missing resource, etc.).'
+
+        input_schema(
+          properties: {
+            category: {
+              type: 'string',
+              enum: Feedback.categories.keys,
+              description: 'The type of improvement being reported.'
+            },
+            resource_name: {
+              type: 'string',
+              description: 'The resource this feedback relates to (optional).'
+            },
+            suggestion: {
+              type: 'string',
+              description: 'A detailed description of the improvement.'
+            }
+          },
+          required: %w[category suggestion]
+        )
+
+        def self.execute(admin:, category:, suggestion:, resource_name: nil)
+          result = Administrate::MCP::ReportImprovement.call(admin:, category:, suggestion:, resource_name:)
+
+          return error_response(result.errors.join(', ')) unless result.success?
+
+          json_response({ status: 'created', feedback_id: result.feedback.id })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    module Tools
+      # Exposes Sidekiq retry queue metrics: total size and first page of retries.
+      class SidekiqRetries < BaseTool
+        PAGE_SIZE = 25
+
+        tool_name 'sidekiq_retries'
+        description 'Get the Sidekiq retry queue size and optionally the first page of retry entries ' \
+                    '(up to 25 jobs with class, error, retry count, and timestamps).'
+        annotations read_only_hint: true, destructive_hint: false, open_world_hint: false
+
+        input_schema(
+          properties: {
+            include_entries: {
+              type: 'boolean',
+              description: 'When true, returns the first page of retry entries alongside the total count.'
+            }
+          }
+        )
+
+        def self.execute(admin:, include_entries: false) # rubocop:disable Lint/UnusedMethodArgument
+          retry_set = ::Sidekiq::RetrySet.new
+          data = { total_size: retry_set.size }
+
+          data[:entries] = retry_set.first(PAGE_SIZE)&.map { |entry| serialize_entry(entry) } || [] if include_entries
+
+          json_response(data)
+        end
+
+        def self.serialize_entry(entry)
+          {
+            jid: entry.jid,
+            queue: entry.queue,
+            class: entry['class'],
+            error_class: entry['error_class'],
+            error_message: entry['error_message']&.truncate(200),
+            retry_count: entry['retry_count'],
+            failed_at: entry['failed_at'] && Time.at(entry['failed_at']).utc.iso8601,
+            retried_at: entry['retried_at'] && Time.at(entry['retried_at']).utc.iso8601,
+            next_retry_at: Time.at(entry.score).utc.iso8601
+          }
+        end
+        private_class_method :serialize_entry
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    module Tools
+      # Exposes the host's per-job-class Sidekiq queue stats, through `config.sidekiq_stats_provider`.
+      # The provider answers `counts(queue)`, `total_counts(counts)`, `queues` and `stats_cleared_at`.
+      class SidekiqStats < BaseTool
+        MAX_QUEUES = 20
+        RETRY_QUEUE = 'retries'
+
+        tool_name 'sidekiq_stats'
+        description 'Get per-job-class counts from the custom Sidekiq stats. ' \
+                    'Returns retry breakdown and optionally per-queue breakdowns. ' \
+                    'Each breakdown maps job class names to their pending count.'
+        annotations read_only_hint: true, destructive_hint: false, open_world_hint: false
+
+        input_schema(
+          properties: {
+            include_queues: {
+              type: 'boolean',
+              description: 'When true, also returns per-queue job class breakdowns (capped at 20 queues).'
+            },
+            queue_name: {
+              type: 'string',
+              description: 'Return stats for a specific queue only. Ignored when include_queues is false.'
+            }
+          }
+        )
+
+        def self.provider
+          configured = Administrate::MCP.config.sidekiq_stats_provider
+          case configured
+          when String then configured.constantize
+          when Proc then configured.call
+          else configured
+          end
+        end
+
+        def self.retry_queue
+          provider.const_defined?(:RETRY_QUEUE, false) ? provider.const_get(:RETRY_QUEUE, false) : RETRY_QUEUE
+        end
+
+        def self.execute(admin:, include_queues: false, queue_name: nil) # rubocop:disable Lint/UnusedMethodArgument
+          retries = provider.counts(retry_queue)
+
+          data = {
+            stats_cleared_at: provider.stats_cleared_at.iso8601,
+            retries: sort_desc(retries),
+            total_retries: provider.total_counts(retries)
+          }
+
+          data[:queues] = queue_breakdowns(queue_name) if include_queues
+
+          json_response(data)
+        end
+
+        def self.queue_breakdowns(queue_name)
+          queues = queue_name.present? ? [queue_name] : provider.queues.first(MAX_QUEUES)
+
+          queues.to_h do |q|
+            counts = provider.counts(q)
+            [q, { counts: sort_desc(counts), total: provider.total_counts(counts) }]
+          end
+        end
+        private_class_method :queue_breakdowns
+
+        def self.sort_desc(counts)
+          counts.sort_by { |_, v| -v }.to_h
+        end
+        private_class_method :sort_desc
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Bearer token for authenticating an admin to the MCP server.
+    class ApiKey < ApplicationRecord
+      self.table_name = 'administrate_mcp_api_keys'
+
+      TOKEN_LENGTH = 40
+      WRITE_SCOPE = 'write'
+
+      belongs_to_admin
+
+      has_many :feedbacks, class_name: 'Administrate::MCP::Feedback', dependent: :nullify, inverse_of: :api_key
+
+      validates :token_digest, presence: true, uniqueness: true
+      validates :token_prefix, presence: true
+      validates :name, presence: true
+
+      scope :active, -> { where(revoked_at: nil) }
+
+      class << self
+        def token_prefix_value
+          Administrate::MCP.config.api_key_token_prefix
+        end
+
+        def generate_token
+          "#{token_prefix_value}#{SecureRandom.hex(TOKEN_LENGTH / 2)}"
+        end
+
+        def digest_token(plaintext)
+          Digest::SHA256.hexdigest(plaintext)
+        end
+
+        def authenticate(plaintext)
+          return nil unless plaintext&.start_with?(token_prefix_value)
+
+          key = active.find_by(token_digest: digest_token(plaintext))
+          return nil unless key
+
+          key.touch(:last_used_at) # rubocop:disable Rails/SkipsModelValidations
+          key
+        end
+      end
+
+      def scopes
+        write_access? ? [WRITE_SCOPE] : []
+      end
+
+      def revoke!
+        update!(revoked_at: Time.current)
+      end
+
+      def revoked?
+        revoked_at.present?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Base class for the engine's own tables.
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+
+      class << self
+        # `isolate_namespace` strips the namespace from model_name, so ApiKey would answer
+        # `api_keys` and collide with the host's own resource of that name in route and form
+        # helpers. These records name themselves the way any other namespaced model does.
+        def model_name
+          @model_name ||= ActiveModel::Name.new(self, nil, name)
+        end
+
+        def belongs_to_admin
+          belongs_to :admin, class_name: Administrate::MCP.config.admin_class_name, optional: false
+        end
+      end
+    end
+  end
+end