administrate-mcp 0.1.0

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

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Converts a record + dashboard definition into a plain Hash suitable for JSON.
+    #
+    # Field classes are matched by name against the configured registry, walking the field's
+    # ancestors, so a host can register its own field classes without the engine ever referencing
+    # a constant it does not own.
+    class FieldSerializer
+      MAX_EXPAND_ITEMS = 25
+
+      # Where one attribute's value comes from. Administrate resolves a `getter:` option through the
+      # field instance, never off the record, so an attribute declared only as a lambda has no
+      # matching model method and `public_send` raises. Building the field is the only way to read
+      # those.
+      #
+      # A getter is arbitrary code — several run their own queries — so `resolve_getters` is opt-in
+      # and only single-record callers set it. Resolving them per row would turn one list call into
+      # a query per row.
+      AttributeSource =
+        Struct.new(:record, :attr_name, :field_spec, :resolve_getters) do
+          def value
+            return field_spec.new(attr_name, nil, :show, resource: record).data if getter?
+
+            record.public_send(attr_name)
+          end
+
+          def getter?
+            resolve_getters && field_spec.is_a?(Administrate::Field::Deferred) && field_spec.getter.present?
+          end
+        end
+
+      class << self
+        def serialize(record, dashboard, attributes: nil, expand: nil, resolve_getters: false)
+          attrs = exposed_attributes(dashboard, attributes)
+          attrs.each_with_object({ url: admin_url_for(record) }) do |attr_name, hash|
+            field_spec = dashboard.attribute_types[attr_name]
+            next unless field_spec
+
+            next if skip_field?(resolve_field_class(field_spec))
+
+            hash[attr_name] = serialize_single(
+              AttributeSource.new(record, attr_name, field_spec, resolve_getters),
+              expand
+            )
+          end
+        end
+
+        def admin_url_for(record)
+          return nil unless record.is_a?(ActiveRecord::Base)
+
+          klass = record.class
+          while klass < ActiveRecord::Base && !klass.abstract_class?
+            begin
+              return polymorphic_admin_url(record.becomes(klass))
+            rescue ActionController::UrlGenerationError, NoMethodError
+              klass = klass.superclass
+            end
+          end
+          nil
+        end
+
+        def polymorphic_admin_url(record)
+          config = Administrate::MCP.config
+          Rails.application.routes.url_helpers.polymorphic_url(
+            [config.admin_route_namespace, record],
+            **admin_url_options(config)
+          )
+        end
+
+        # A host may declare `admin_origin` as a proc that reads the request, and there is no request
+        # here. Falling back to the configured options keeps the URL buildable from
+        # default_url_options instead of losing every `url` to a nil.
+        def admin_url_options(config)
+          options = config.admin_url_options
+          return options if options[:host].present?
+
+          origin = URI.parse(config.admin_origin_for.to_s)
+          return options if origin.host.blank?
+
+          { host: origin.host, protocol: origin.scheme, port: origin.port }.compact.merge(options)
+        rescue StandardError
+          options
+        end
+
+        def exposed_attributes(dashboard, attributes = nil)
+          (attributes || dashboard.show_page_attributes) - DashboardRegistry.skipped_attributes(dashboard)
+        end
+
+        def resolve_columns(dashboard, attributes)
+          exposed_attributes(dashboard, attributes).select do |attr_name|
+            field_spec = dashboard.attribute_types[attr_name]
+            next false unless field_spec
+
+            !skip_field?(resolve_field_class(field_spec))
+          end
+        end
+
+        def serialize_row(record, dashboard, columns:, expand: nil, resolve_getters: false)
+          columns.map do |attr_name|
+            source = AttributeSource.new(record, attr_name, dashboard.attribute_types[attr_name], resolve_getters)
+            serialize_single(source, expand)
+          end
+        end
+
+        def serialize_single(source, expand)
+          field_class = resolve_field_class(source.field_spec)
+          if expand&.include?(source.attr_name) && expandable_field?(field_class)
+            serialize_has_many_expanded(source)
+          else
+            serialize_field(source, field_class)
+          end
+        end
+
+        def expandable_field?(field_class)
+          return false unless field_class.is_a?(Class)
+
+          matches?(field_class, Administrate::MCP.config.has_many_field_classes)
+        end
+
+        def resolve_field_class(field_spec)
+          case field_spec
+          when Administrate::Field::Deferred
+            field_spec.deferred_class
+          when Class
+            field_spec
+          end
+        end
+
+        def skip_field?(field_class)
+          return true unless field_class
+
+          matches?(field_class, Administrate::MCP.config.skipped_field_classes)
+        end
+
+        def serialize_field(source, field_class)
+          serializer = lookup_serializer(field_class)
+          return serializer.call(source) if serializer.respond_to?(:call)
+          return send(:"serialize_#{serializer}", source) if serializer
+          return field_class.mcp_value(source.record, source.attr_name) if field_class.respond_to?(:mcp_value)
+
+          serialize_unknown(source)
+        rescue StandardError
+          "[error: could not serialize #{source.attr_name}]"
+        end
+
+        def serialize_has_many(source)
+          relation = has_many_relation(source)
+          return nil unless relation
+
+          { count: relation_count(relation) }
+        rescue StandardError
+          nil
+        end
+
+        def serialize_has_many_expanded(source)
+          relation = has_many_relation(source)
+          return nil unless relation
+
+          { count: relation_count(relation), items: expanded_items(relation) }
+        rescue StandardError
+          nil
+        end
+
+        def has_many_relation(source) # rubocop:disable Naming/PredicatePrefix
+          value = source.value
+          value.is_a?(ActiveRecord::Relation) ? value : nil
+        end
+
+        def expanded_items(relation)
+          related_records = relation.limit(MAX_EXPAND_ITEMS)
+          dashboard_class = "#{relation.klass.name}Dashboard".safe_constantize
+          return related_records.map(&:to_s) unless dashboard_class
+
+          dash = dashboard_class.new
+          related_records.map { |r| serialize(r, dash, attributes: dash.collection_attributes) }
+        end
+
+        def relation_count(relation)
+          return relation.count if relation.select_values.blank?
+
+          relation.klass.from(relation.unscope(:order).arel.as('mcp_count_sub')).count
+        end
+
+        def serialize_belongs_to(source)
+          related = source.value
+          related ? build_related_hash(related) : nil
+        rescue StandardError
+          nil
+        end
+
+        # A polymorphic association is useless to a caller without its type: the id alone names no
+        # table. Both halves ship in the hash.
+        def serialize_polymorphic(source)
+          related = source.value
+          return nil unless related
+
+          build_related_hash(related).merge(type: related.class.name)
+        rescue StandardError
+          nil
+        end
+
+        def serialize_datetime(source)
+          source.value&.iso8601
+        end
+
+        def serialize_enum(source)
+          source.value.to_s
+        end
+
+        def serialize_attachment(source)
+          value = source.value
+          return nil unless value
+
+          value.try(:url) || value.to_s
+        rescue StandardError
+          nil
+        end
+
+        def serialize_scalar(source)
+          source.value
+        end
+
+        def serialize_unknown(source)
+          value = source.value
+          return value if value.nil? || value.is_a?(Numeric) || [true, false].include?(value)
+          return value if value.is_a?(String) || value.is_a?(Hash) || value.is_a?(Array)
+
+          value.to_s
+        end
+
+        def build_related_hash(related)
+          display = display_resource_for(related)
+          result = { id: related.id }
+          result[:display] = display if display != "#{related.class.name.demodulize} ##{related.id}"
+          result[:slug] = related.slug if related.respond_to?(:slug)
+          result
+        end
+
+        def display_resource_for(related)
+          dashboard_class = "#{related.class.name}Dashboard".safe_constantize
+          return related.to_s unless dashboard_class
+
+          dashboard_class.new.display_resource(related)
+        rescue StandardError
+          related.to_s
+        end
+
+        private
+
+        # A field class registered under its own name wins outright. Otherwise a class that speaks
+        # `mcp_value` answers for itself, ahead of anything inherited from an ancestor: that is how
+        # a host subclasses a registered field to publish a richer value.
+        def lookup_serializer(field_class)
+          return nil unless field_class.is_a?(Class)
+
+          registry = Administrate::MCP.config.field_serializers
+          own = field_class.name && registry[field_class.name]
+          return own if own
+          return nil if field_class.respond_to?(:mcp_value)
+
+          inherited_serializer(field_class, registry)
+        end
+
+        def inherited_serializer(field_class, registry)
+          field_class.ancestors.each do |ancestor|
+            name = ancestor.name
+            next unless name
+
+            entry = registry[name]
+            return entry if entry
+          end
+          nil
+        end
+
+        def matches?(field_class, class_names)
+          names = field_class.ancestors.filter_map(&:name)
+          class_names.any? { |candidate| names.include?(candidate.to_s) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # OAuth 2.1 service for MCP authentication: parameter validation and token exchange.
+    # Implements RFC 9126 (PAR), RFC 7636 (PKCE), and RFC 6749 (OAuth 2.0) token exchange.
+    # See https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12
+    class OAuthService
+      BASE64URL_CHALLENGE_PATTERN = /\A[A-Za-z0-9_-]{43,128}\z/
+
+      Result = Struct.new(:success?, :data, :error, :error_description, keyword_init: true)
+
+      def validate_authorize_params(application:, redirect_uri:, code_challenge_method:, code_challenge:)
+        return 'Unknown client_id' unless application
+        return 'Invalid redirect_uri' unless valid_redirect_uri?(application, redirect_uri)
+        unless supported_challenge_method?(code_challenge_method)
+          return 'Unsupported code_challenge_method, must be S256'
+        end
+        return 'Invalid code_challenge format' unless valid_code_challenge?(code_challenge)
+
+        nil
+      end
+
+      def valid_redirect_uri?(application, uri)
+        return false if uri.blank?
+        return true if application.redirect_uris.include?(uri)
+
+        loopback_redirect_uri?(uri)
+      end
+
+      def exchange_authorization_code(code:, code_verifier:, redirect_uri:)
+        grant = find_valid_grant(code)
+        return error_result('invalid_grant') unless grant
+        return error_result('invalid_grant', 'redirect_uri mismatch') if redirect_uri_mismatch?(grant, redirect_uri)
+        unless grant.verify_code_challenge(code_verifier.to_s)
+          return error_result('invalid_grant', 'PKCE verification failed')
+        end
+
+        grant.revoke!
+        success_result(issue_access_token(grant.admin, grant.application, grant.scopes))
+      end
+
+      def exchange_refresh_token(refresh_token:)
+        old_token = OAuthAccessToken.active.find_by_refresh_token(refresh_token)
+        return error_result('invalid_grant') unless old_token && !old_token.expired?
+
+        old_token.revoke!
+        success_result(issue_access_token(old_token.admin, old_token.application, old_token.scopes))
+      end
+
+      private
+
+      # Loopback redirects (RFC 8252) are allowed on any port, but the host must be a real loopback
+      # host — matched on the parsed hostname, so `http://localhost.attacker.com` cannot intercept an
+      # authorization code.
+      def loopback_redirect_uri?(uri)
+        return false unless Administrate::MCP.config.allow_localhost_redirects
+
+        parsed = URI.parse(uri)
+        parsed.scheme == 'http' && LoopbackUri.localhost?(parsed.hostname)
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def valid_code_challenge?(challenge)
+        challenge.blank? || BASE64URL_CHALLENGE_PATTERN.match?(challenge)
+      end
+
+      def supported_challenge_method?(method)
+        method.blank? || method == 'S256'
+      end
+
+      def find_valid_grant(code)
+        grant = OAuthAccessGrant.find_by_token(code)
+        grant if grant && !grant.revoked? && !grant.expired?
+      end
+
+      def redirect_uri_mismatch?(grant, redirect_uri)
+        redirect_uri.present? && grant.redirect_uri != redirect_uri
+      end
+
+      def issue_access_token(admin, application, scopes)
+        OAuthAccessToken.issue(admin:, application:, scopes:, expires_in: OAuthAccessToken::DEFAULT_EXPIRES_IN)
+      end
+
+      def success_result(access_token)
+        Result.new(
+          success?: true,
+          data: {
+            access_token: access_token.plaintext_token,
+            token_type: 'bearer',
+            expires_in: access_token.expires_in,
+            refresh_token: access_token.plaintext_refresh_token
+          }
+        )
+      end
+
+      def error_result(error, description = nil)
+        Result.new(success?: false, error:, error_description: description)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Persists an MCP improvement suggestion and hands it to the host's `on_feedback` hook.
+    class ReportImprovement
+      Result = Struct.new(:success?, :feedback, :errors, keyword_init: true)
+
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(admin:, category:, suggestion:, resource_name: nil)
+        @admin = admin
+        @category = category
+        @suggestion = suggestion
+        @resource_name = resource_name
+      end
+
+      def call
+        errors = validation_errors
+        return Result.new(success?: false, feedback: nil, errors:) if errors.any?
+
+        feedback = create_feedback
+        notify(feedback)
+        Result.new(success?: true, feedback:, errors: [])
+      end
+
+      private
+
+      attr_reader :admin, :category, :suggestion, :resource_name
+
+      def validation_errors
+        errors = []
+        unless Feedback.categories.key?(category.to_s)
+          errors << "category must be one of: #{Feedback.categories.keys.join(', ')}"
+        end
+        errors << "suggestion can't be blank" if suggestion.blank?
+        errors
+      end
+
+      def create_feedback
+        Feedback.create!(admin:, api_key: latest_api_key, category:, resource_name:, suggestion:)
+      end
+
+      def latest_api_key
+        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)
+      rescue StandardError => e
+        Administrate::MCP.config.on_error.call(e)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Builds a configured MCP::Server instance with auto-discovered tools.
+    class ServerBuilder
+      BUILT_IN_TOOLS = %w[
+        Administrate::MCP::Tools::AdminResourceList
+        Administrate::MCP::Tools::AdminResourceShow
+        Administrate::MCP::Tools::AdminResourceListResources
+        Administrate::MCP::Tools::ReportImprovement
+      ].freeze
+
+      SIDEKIQ_RETRIES_TOOL = 'Administrate::MCP::Tools::SidekiqRetries'
+
+      SIDEKIQ_STATS_TOOL = 'Administrate::MCP::Tools::SidekiqStats'
+
+      class << self
+        def build(server_context:)
+          server_context[:authorization_errors] ||= []
+          config = Administrate::MCP.config
+          server =
+            ::MCP::Server.new(
+              name: config.server_name,
+              version: config.server_version,
+              tools: discover_tools(server_context),
+              server_context:
+            )
+          server.transport =
+            ::MCP::Server::Transports::StreamableHTTPTransport.new(
+              server,
+              stateless: true,
+              # The gem's Host/Origin check guards against DNS rebinding on locally-bound servers.
+              # The host's own route constraints already restrict which Host values reach the
+              # controller, and this is not loopback-bound. Passing the incoming request's own host
+              # back as `allowed_hosts:` would just validate the Host header against itself.
+              dns_rebinding_protection: false
+            )
+          server
+        end
+
+        def discover_tools(server_context)
+          load_host_tools
+          (built_in_tools + host_tools).uniq + Actions.tools_for(server_context)
+        end
+
+        def built_in_tools
+          names = BUILT_IN_TOOLS.dup
+          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)
+        end
+
+        def host_tools
+          BaseTool.descendants.select do |klass|
+            klass.name && !klass.name.start_with?('Administrate::MCP::') && klass.instance_variable_get(:@name_value)
+          end
+        end
+
+        private
+
+        def load_host_tools
+          Administrate::MCP.config.tool_paths.each do |path|
+            Dir[File.join(path.to_s, '*.rb')].each { |file| require_dependency file }
+          end
+        end
+      end
+    end
+  end
+end