administrate-mcp 0.1.0

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Generates self-describing MCP tools from the custom write actions declared on dashboards.
+    #
+    # A dashboard declares an action with `mcp_action`, alongside its MCP_DESCRIPTION — so one file
+    # defines a resource's full MCP contract (readable fields + writable actions). From each
+    # declaration we build a tool whose name, input schema and description let non-developer users
+    # discover and call it through the protocol.
+    #
+    # Enforcement is layered: the generated tool requires an OAuth `write` scope (the rollout gate)
+    # AND runs the resource's authorization predicate against the loaded record (the per-admin
+    # truth, identical to the admin UI). Auditing is inherited from BaseTool.
+    module Actions
+      Definition =
+        Struct.new(
+          :model_class,
+          :name,
+          :predicate,
+          :scope,
+          :destructive,
+          :description,
+          :params,
+          :required,
+          :invoke,
+          keyword_init: true
+        )
+
+      class << self
+        # Normalizes the arguments of a `mcp_action` declaration into a spec (everything but the
+        # model, which is inferred from the owning dashboard when definitions are built).
+        def build_spec(name, description:, params: {}, predicate: nil, pundit: nil, scope: :write,
+                       destructive: true, &invoke)
+          raise ArgumentError, "#{name}: a block is required to invoke the action" unless invoke
+
+          normalized = normalize_params(params)
+
+          {
+            name: name.to_sym,
+            predicate: (predicate || pundit || :"#{name}?").to_sym,
+            scope: scope.to_sym,
+            destructive:,
+            description:,
+            params: normalized.transform_values { |spec| spec.except(:required) },
+            required: normalized.reject { |_, spec| spec[:required] == false }.keys,
+            invoke:
+          }
+        end
+
+        def normalize_params(params)
+          params.transform_values { |spec| spec.is_a?(String) ? { type: 'string', description: spec } : spec }
+        end
+
+        def definitions
+          @definitions ||=
+            DashboardRegistry.registry.values.flat_map do |entry|
+              next [] unless entry.dashboard_class.respond_to?(:mcp_action_specs)
+
+              entry.dashboard_class.mcp_action_specs.map do |spec|
+                Definition.new(model_class: entry.model_class, **spec)
+              end
+            end
+        end
+
+        def all_tools
+          @all_tools ||= definitions.map { |defn| ToolFactory.build(defn) }
+        end
+
+        # Tool classes the caller may both see and run: write scope granted AND the authorization
+        # predicate satisfied at the role level. The actual call re-checks it against the record.
+        def tools_for(server_context)
+          granted = (server_context[:scopes] || []).map(&:to_sym)
+          admin = server_context[:admin]
+
+          all_tools.select do |tool|
+            defn = tool.definition
+            granted.include?(defn.scope) && authorized_for_discovery?(admin, defn)
+          end
+        end
+
+        def reset!
+          @definitions = nil
+          @all_tools = nil
+        end
+
+        def find_record!(model_class, id)
+          record = model_class.find_by(id:) || friendly_find(model_class, id)
+          raise UnauthorizedError, "#{model_class.name} not found: #{id}" unless record
+
+          record
+        end
+
+        def authorize!(admin, record, predicate)
+          Administrate::MCP.config.authorization.authorize!(admin, record, predicate)
+        end
+
+        private
+
+        def authorized_for_discovery?(admin, definition)
+          Administrate::MCP.config.authorization.authorized?(admin, definition.model_class, definition.predicate)
+        rescue StandardError
+          false
+        end
+
+        def friendly_find(model_class, id)
+          return nil unless model_class.respond_to?(:friendly)
+
+          model_class.friendly.find(id)
+        rescue ActiveRecord::RecordNotFound
+          nil
+        end
+      end
+
+      # Turns one Definition into an anonymous BaseTool subclass.
+      module ToolFactory
+        class << self
+          def build(defn)
+            resource = defn.model_class.name.underscore
+            klass = Class.new(BaseTool)
+            klass.tool_name "#{resource.tr('/', '_')}_#{defn.name}"
+            klass.description defn.description
+            klass.annotations(read_only_hint: false, destructive_hint: defn.destructive, open_world_hint: true)
+            klass.requires_scope defn.scope
+            klass.input_schema(**schema_for(defn, resource))
+            define_behaviors(klass, defn)
+            klass
+          end
+
+          def schema_for(defn, resource)
+            properties = { id: { type: 'string', description: "ID or slug of the #{resource}" } }
+            defn.params.each { |name, spec| properties[name] = spec }
+            { properties:, required: %w[id] + defn.required.map(&:to_s) }
+          end
+
+          # Replaces the role-based default with instance-level authorization on the loaded record.
+          def authorize!(defn, admin, id)
+            record = Actions.find_record!(defn.model_class, id)
+            Actions.authorize!(admin, record, defn.predicate)
+          end
+
+          def invoke(defn, admin, id, params)
+            record = Actions.find_record!(defn.model_class, id)
+            result = defn.invoke.call(record:, admin:, params:)
+            return { error: result.try(:error) || "#{defn.name} failed" } if failed?(result)
+
+            { data: { status: 'ok', model: defn.model_class.name.underscore, id:, action: defn.name.to_s } }
+          end
+
+          private
+
+          def define_behaviors(klass, defn)
+            klass.define_singleton_method(:definition) { defn }
+            klass.define_singleton_method(:check_roles!) do |admin, id: nil, **|
+              ToolFactory.authorize!(defn, admin, id)
+            end
+            klass.define_singleton_method(:execute) do |admin:, id:, **params|
+              outcome = ToolFactory.invoke(defn, admin, id, params)
+              outcome.key?(:error) ? error_response(outcome[:error]) : json_response(outcome[:data])
+            end
+          end
+
+          def failed?(result)
+            result.respond_to?(:success?) && !result.success?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Base class for MCP tools that operate on Administrate dashboard resources.
+    class AdminDashboardTool < BaseTool
+      LISTED_VALID_VALUES = 40
+
+      class << self
+        def policy_action
+          nil
+        end
+
+        def check_roles!(admin, resource: nil, **)
+          return unless resource && policy_action
+
+          entry = find_dashboard_entry!(resource)
+          authorize_resource!(admin, entry.model_class, policy_action)
+        end
+
+        def authorized?(admin, model_class, action)
+          Administrate::MCP.config.authorization.authorized?(admin, model_class, action)
+        end
+
+        def authorize_resource!(admin, model_class, action)
+          Administrate::MCP.config.authorization.authorize!(admin, model_class, action)
+        end
+
+        def find_dashboard_entry!(resource_name)
+          entry = DashboardRegistry.find(resource_name)
+          return entry if entry
+
+          raise UnauthorizedError, "Unknown resource: #{resource_name}"
+        end
+
+        def reject_unknown!(kind, given, allowed)
+          allowed = allowed.to_a.map(&:to_s).sort
+          unknown = Array.wrap(given).map(&:to_s) - allowed
+          return if unknown.empty?
+
+          raise InvalidArgumentError,
+                "Unknown #{kind}: #{unknown.sort.join(', ')}. " \
+                "Valid #{kind} for this resource: #{listed(allowed)}"
+        end
+
+        def reject_over_limit!(kind, size, max)
+          return if size <= max
+
+          raise InvalidArgumentError, "Too many #{kind}: #{size} requested, at most #{max} are allowed per call."
+        end
+
+        def listed(allowed)
+          return 'none' if allowed.empty?
+          return allowed.join(', ') if allowed.size <= LISTED_VALID_VALUES
+
+          "#{allowed.first(LISTED_VALID_VALUES).join(', ')} " \
+            "(+#{allowed.size - LISTED_VALID_VALUES} more, see admin_resource_list_resources)"
+        end
+
+        def resolve_attributes(dashboard, fields, default_method)
+          return dashboard.public_send(default_method) if fields.blank?
+
+          reject_unknown!('fields', fields, FieldSerializer.exposed_attributes(dashboard))
+
+          fields.map(&:to_sym)
+        end
+
+        # An expansion only applies to an attribute the response carries, so an expanded association
+        # is added to the returned attributes rather than quietly doing nothing.
+        def resolve_attributes_and_expansions(dashboard, fields, expand, default_method, max_expand)
+          attrs = resolve_attributes(dashboard, fields, default_method)
+          expand_set = validated_expand_set(dashboard, expand, attrs, max_expand)
+          return attrs, nil unless expand_set
+
+          [attrs | expand_set.to_a, expand_set]
+        end
+
+        # Expandable names stay bounded by show_page_attributes so an expansion cannot surface an
+        # attribute the dashboard withholds from its show page.
+        def validated_expand_set(dashboard, expand, attributes, max_expand)
+          return nil if expand.blank?
+
+          exposed = FieldSerializer.exposed_attributes(dashboard) | attributes.to_a
+          expandable = expandable_attributes(dashboard) & exposed
+          reject_unknown!('expandable associations', expand, expandable)
+          reject_over_limit!('expansions', expand.size, max_expand)
+
+          expand.to_set(&:to_sym)
+        end
+
+        def expandable_attributes(dashboard)
+          dashboard
+            .attribute_types
+            .select { |_, spec| FieldSerializer.expandable_field?(FieldSerializer.resolve_field_class(spec)) }
+            .keys
+        end
+
+        def association_columns(model_class)
+          column_names = model_class.column_names.to_set
+          model_class
+            .reflect_on_all_associations(:belongs_to)
+            .each_with_object(Set.new) do |reflection, columns|
+              fk = reflection.foreign_key.to_s
+              columns << fk if column_names.include?(fk)
+              next unless reflection.options[:polymorphic]
+
+              ft = reflection.foreign_type.to_s
+              columns << ft if column_names.include?(ft)
+            end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Extracts and verifies the credentials on an MCP request. Session cookies are never consulted:
+    # hosts commonly share a session across sibling subdomains, and the protocol endpoint must not
+    # inherit that trust.
+    #
+    # A bearer token this server issued takes precedence: API keys and the engine's own OAuth tokens
+    # are resolved, and a failure on either raises rather than falling through. Anything else — an
+    # absent header, or a token no row matches — is offered to `config.identity_fallback`, which is
+    # how a host authenticates callers whose token was already resolved in front of the application.
+    module Authentication
+      OAUTH_ERROR_CODE = -32_001
+      API_KEY_ERROR_CODE = -32_001
+      MISSING_TOKEN_ERROR_CODE = -32_001
+      INACTIVE_ADMIN_ERROR_CODE = -32_001
+      EXTERNAL_IDENTITY_ERROR_CODE = -32_001
+
+      # Authenticated caller: the admin plus the scopes their credential carries. API keys are
+      # read-only unless granted write access; OAuth tokens carry the scopes they were granted.
+      Identity = Struct.new(:admin, :scopes, keyword_init: true)
+
+      # Base authentication error for MCP requests.
+      class Error < StandardError
+        def auth_error_type
+          'unknown'
+        end
+
+        def jsonrpc_error_code
+          MISSING_TOKEN_ERROR_CODE
+        end
+      end
+
+      # Raised when an OAuth access token is invalid, expired, or revoked.
+      class OAuthTokenError < Error
+        def auth_error_type
+          'oauth'
+        end
+
+        def jsonrpc_error_code
+          OAUTH_ERROR_CODE
+        end
+      end
+
+      # Raised when an API key is invalid or revoked.
+      class InvalidApiKeyError < Error
+        def auth_error_type
+          'api_key'
+        end
+
+        def jsonrpc_error_code
+          API_KEY_ERROR_CODE
+        end
+      end
+
+      # Raised when the credential is still valid but its owner no longer is. A credential outlives
+      # the admin who holds it, so the host is asked on every call.
+      class InactiveAdminError < Error
+        def auth_error_type
+          'inactive_admin'
+        end
+
+        def jsonrpc_error_code
+          INACTIVE_ADMIN_ERROR_CODE
+        end
+      end
+
+      # Raised by an identity fallback that recognised the caller but found no admin account for
+      # them. The host picks the `auth_error_type` the client sees.
+      class ExternalIdentityError < Error
+        def initialize(message = nil, auth_error_type: 'external')
+          super(message)
+          @auth_error_type = auth_error_type
+        end
+
+        attr_reader :auth_error_type
+
+        def jsonrpc_error_code
+          EXTERNAL_IDENTITY_ERROR_CODE
+        end
+      end
+
+      class << self
+        def authenticate!(request)
+          token = extract_bearer_token(request)
+
+          if token.present?
+            return active!(authenticate_api_key!(token)) if token.start_with?(ApiKey.token_prefix_value)
+
+            oauth_token = find_oauth_token(token)
+            return active!(authenticate_oauth_token!(oauth_token)) if oauth_token
+          end
+
+          fallback = Administrate::MCP.config.identity_fallback.call(request)
+          raise missing_credential_error(token) unless fallback
+
+          active!(fallback)
+        end
+
+        private
+
+        # With the OAuth server off the table may not even exist, so it is never queried and an
+        # OAuth token is just another bearer the engine does not recognise.
+        def find_oauth_token(token)
+          return nil unless Administrate::MCP.config.oauth
+
+          OAuthAccessToken.find_by_token(token)
+        end
+
+        def authenticate_api_key!(token)
+          api_key = ApiKey.authenticate(token)
+          raise InvalidApiKeyError, 'Invalid or revoked API key' if api_key.nil?
+
+          Identity.new(admin: api_key.admin, scopes: api_key.scopes)
+        end
+
+        def missing_credential_error(token)
+          return Error.new('Missing Authorization header') if token.blank?
+
+          OAuthTokenError.new('Invalid token')
+        end
+
+        def active!(identity)
+          return identity if Administrate::MCP.config.admin_active.call(identity.admin)
+
+          raise InactiveAdminError, 'Admin is no longer active'
+        end
+
+        def authenticate_oauth_token!(oauth_token)
+          raise OAuthTokenError, 'Token has been revoked' if oauth_token.revoked?
+          raise OAuthTokenError, 'Token has expired' if oauth_token.expired?
+
+          Identity.new(admin: oauth_token.admin, scopes: oauth_token.scopes.to_s.split)
+        end
+
+        def extract_bearer_token(request)
+          header = request.headers['Authorization']
+          return nil if header.blank?
+
+          header[/\ABearer (.+)\z/, 1]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Base class for all MCP tools — provides role gating, auditing, and response helpers.
+    class BaseTool < ::MCP::Tool
+      UnauthorizedError = Administrate::MCP::UnauthorizedError
+      InvalidArgumentError = Administrate::MCP::InvalidArgumentError
+
+      class << self
+        def requires_roles(*roles)
+          @required_roles = roles.flatten
+        end
+
+        def required_roles
+          @required_roles || Administrate::MCP.config.default_required_roles
+        end
+
+        def requires_scope(*scopes)
+          @required_scopes = scopes.map(&:to_sym)
+        end
+
+        def required_scopes
+          @required_scopes || []
+        end
+
+        def call(server_context:, **args)
+          instrument(server_context) { call_with_context(server_context, **args) }
+        rescue UnauthorizedError => e
+          (server_context[:authorization_errors] ||= []).push(e.message)
+          error_response(e.message)
+        rescue InvalidArgumentError => e
+          error_response(e.message)
+        rescue StandardError => e
+          error_response("Internal error: #{e.message}")
+        end
+
+        private
+
+        def instrument(server_context, &)
+          Administrate::MCP.config.instrument.call(tool_name: name_value, admin: server_context[:admin], &)
+        end
+
+        def call_with_context(server_context, **args)
+          admin = server_context[:admin]
+          check_scopes!(server_context)
+          check_roles!(admin, **args)
+          audit!(admin, args, server_context)
+          execute(admin:, **args)
+        end
+
+        def check_scopes!(server_context)
+          return if required_scopes.empty?
+
+          granted = (server_context[:scopes] || []).map(&:to_sym)
+          missing = required_scopes - granted
+          return if missing.empty?
+
+          raise UnauthorizedError, "Missing required scope(s): #{missing.join(', ')}"
+        end
+
+        def check_roles!(admin, **)
+          Administrate::MCP.config.authorization.authorize_roles!(admin, required_roles)
+        end
+
+        def audit!(admin, args, server_context)
+          Administrate::MCP.config.on_tool_call.call(
+            tool_name: name_value,
+            admin:,
+            arguments: args,
+            scopes: server_context[:scopes] || []
+          )
+        end
+
+        def execute(admin:, **args)
+          raise NotImplementedError, "#{name} must implement .execute"
+        end
+
+        def text_response(text)
+          ::MCP::Tool::Response.new([{ type: 'text', text: }])
+        end
+
+        def json_response(data)
+          ::MCP::Tool::Response.new([{ type: 'text', text: data.to_json }])
+        end
+
+        def error_response(message)
+          ::MCP::Tool::Response.new([{ type: 'text', text: message }], error: true)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Removes MCP feedbacks older than the given cutoff, one batch at a time. The caller decides
+    # whether to run the next batch: `call` reports whether the batch was full.
+    class CleanOldFeedbacks
+      BATCH_SIZE = 10_000
+
+      Result = Struct.new(:deleted_count, :more?, keyword_init: true)
+
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(till: 2.months.ago)
+        @till = till
+      end
+
+      def call
+        deleted_count = Feedback.where(created_at: ...@till).limit(BATCH_SIZE).delete_all
+        Result.new(deleted_count:, more?: deleted_count == BATCH_SIZE)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Maps resource names (e.g. "card", "card_factory/card_sample") to their dashboard and model
+    # classes. Dashboards can declare MCP_DESCRIPTION to provide a human-readable description for
+    # LLM tool discovery, MCP_BASE_SCOPE (a proc returning a relation) to override the model's
+    # default scope, MCP_SKIPPED_ATTRIBUTES to keep attributes out of MCP reads, and
+    # MCP_EXPOSED = false to leave the resource out of the registry altogether.
+    # default scope for MCP reads — mirroring an admin controller's custom scoped_resource.
+    class DashboardRegistry
+      Entry =
+        Struct.new(:dashboard_class, :model_class, :description, :base_scope, keyword_init: true) do
+          def scope
+            base_scope ? base_scope.call : model_class.all
+          end
+        end
+
+      class << self
+        def find(resource_name)
+          key = resource_name.to_s.underscore.singularize
+          registry[key]
+        end
+
+        def resource_names
+          registry.keys.sort
+        end
+
+        def reset!
+          @registry = nil
+        end
+
+        def registry
+          @registry ||= build_registry
+        end
+
+        def build_registry
+          dashboard_files.each_with_object({}) do |file, result|
+            entry = build_entry(file)
+            next unless entry
+
+            result[entry.model_class.name.underscore] = entry
+          rescue NameError
+            next
+          end
+        end
+
+        def build_entry(file)
+          require_dependency file
+          class_name = dashboard_class_name(file)
+          dashboard_class = class_name.safe_constantize
+          return unless dashboard_class
+          return unless dashboard_class < Administrate::BaseDashboard
+          return if dashboard_constant(dashboard_class, :MCP_EXPOSED) == false
+
+          model_class = infer_model_class(dashboard_class, class_name)
+          return unless model_class
+
+          Entry.new(
+            dashboard_class:,
+            model_class:,
+            description: dashboard_constant(dashboard_class, :MCP_DESCRIPTION),
+            base_scope: dashboard_constant(dashboard_class, :MCP_BASE_SCOPE)
+          )
+        end
+
+        def dashboard_files
+          dashboard_roots.flat_map { |root| Dir[File.join(root, '**', '*_dashboard.rb')] }
+        end
+
+        def dashboard_class_name(file)
+          root = dashboard_roots.find { |candidate| file.start_with?("#{candidate}/") }
+          file.delete_prefix("#{root}/").delete_suffix('.rb').camelize
+        end
+
+        def infer_model_class(dashboard_class, class_name)
+          dashboard_class.model
+        rescue StandardError
+          class_name.delete_suffix('Dashboard').safe_constantize
+        end
+
+        def skipped_attributes(dashboard)
+          dashboard_class = dashboard.is_a?(Class) ? dashboard : dashboard.class
+          Array(dashboard_constant(dashboard_class, :MCP_SKIPPED_ATTRIBUTES)).map(&:to_sym)
+        end
+
+        private
+
+        def dashboard_roots
+          Administrate::MCP.config.dashboard_directories
+        end
+
+        # `inherit: false`: a constant of the same name defined at the top level of the host would
+        # otherwise be found on every dashboard, and a stray MCP_EXPOSED = false would empty the
+        # registry. A dashboard that wants one has to declare it itself.
+        def dashboard_constant(dashboard_class, name)
+          dashboard_class.const_defined?(name, false) ? dashboard_class.const_get(name, false) : nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Administrate's Search with exact matching by default: `*` is the only wildcard, so an id or a
+    # slug does not accidentally match every row that contains it.
+    class FastSearch < Administrate::Search
+      PRIMARY_COLUMN_NAMES = %i[id slug].freeze
+
+      def query_template
+        return '' if term.blank?
+
+        search_attributes.map { |attr| attribute_template(attr) }.join(' OR ')
+      end
+
+      def operator
+        exact_term.include?('%') ? 'LIKE' : '='
+      end
+
+      def query_values
+        [exact_term] * search_attributes.sum { |attr| searchable_fields(attr).count }
+      end
+
+      def exact_term
+        term.downcase.tr('*', '%').presence || '%'
+      end
+
+      private
+
+      def attribute_template(attr)
+        table_name = query_table_name(attr)
+        searchable_fields(attr).map { |field| field_template(table_name, field) }.join(' OR ')
+      end
+
+      def field_template(table_name, field)
+        column_name = column_to_query(field)
+        return "LOWER(CAST(#{table_name}.#{column_name} AS TEXT)) #{operator} ?" unless primary?(field)
+
+        "CAST(#{table_name}.#{column_name} AS TEXT) #{operator} ?"
+      end
+
+      def primary?(field)
+        PRIMARY_COLUMN_NAMES.include?(field)
+      end
+    end
+  end
+end