admin_suite 0.5.0 → 0.6.1

data/lib/admin_suite/configuration.rb

@@ -5,7 +5,6 @@ module AdminSuite
   class Configuration
     attr_accessor :authenticate,
       :current_actor,
-      :authorize,
       :auth_strategy,
       :auth_options,
       :allow_unauthenticated,
@@ -31,7 +30,61 @@ module AdminSuite
       :on_action_executed,
       :resolve_action_handler
 
-    attr_reader :portals
+    McpConfig = Struct.new(:enabled, :max_page_size, keyword_init: true)
+
+    attr_reader :portals, :authorize, :mcp
+
+    # The authorize hook's keywords are validated at assignment rather than
+    # at call time: a hook with the pre-0.6.0 `controller:` keyword would
+    # otherwise raise deep inside a request (or, worse, bind `context:` to
+    # nothing and silently mis-evaluate). Failing in the initializer puts
+    # the error where the mistake is.
+    REQUIRED_AUTHORIZE_KEYWORDS = %i[actor action resource record context].freeze
+
+    def authorize=(hook)
+      if hook
+        parameters =
+          if hook.respond_to?(:parameters)
+            hook.parameters
+          elsif hook.respond_to?(:call)
+            # A plain object implementing #call is a legitimate hook, and its
+            # signature is still introspectable -- one level down, on the
+            # method itself. Falling back here keeps the keyword guard working
+            # for callables instead of skipping validation for them.
+            hook.method(:call).parameters
+          else
+            raise ArgumentError,
+              "config.authorize must be callable (a lambda, proc, method, or an object responding to #call), got #{hook.class}."
+          end
+
+        keywords = parameters.filter_map { |type, name| name if %i[key keyreq].include?(type) }
+
+        # A `**` splat absorbs every keyword, so such a hook cannot be missing one --
+        # `->(**) {}` reports `[[:keyrest, :**]]` and no :key/:keyreq at all. Test
+        # doubles and coarse "deny everything" hooks are written this way; rejecting
+        # them would be a false positive.
+        accepts_rest = parameters.any? { |type, _| type == :keyrest }
+
+        missing = accepts_rest ? [] : REQUIRED_AUTHORIZE_KEYWORDS - keywords
+        # The `extra` check still runs against explicitly named keywords even when a
+        # splat is present: `->(controller:, **)` is exactly the mistake this guard
+        # exists to catch, and the splat would otherwise hide it -- `controller:`
+        # binds to nil while `**` quietly swallows the real arguments, so the hook
+        # mis-evaluates instead of failing.
+        extra = keywords - REQUIRED_AUTHORIZE_KEYWORDS
+
+        unless missing.empty? && extra.empty?
+          raise ArgumentError, <<~MESSAGE
+            config.authorize must accept exactly (actor:, action:, resource:, record:, context:).
+            Missing: #{missing.inspect}. Unexpected: #{extra.inspect}.
+            As of admin_suite 0.6.0 the `controller:` keyword is replaced by `context:`,
+            which carries `surface` (:web or :mcp), `controller` (web only) and `request`.
+          MESSAGE
+        end
+      end
+
+      @authorize = hook
+    end
 
     # Records that the host explicitly assigned portals (even to `{}`), so
     # the engine's built-in defaults are never re-applied over explicit
@@ -77,6 +130,7 @@ module AdminSuite
       @root_dashboard_loaded = false
       @on_action_executed = nil
       @resolve_action_handler = nil
+      @mcp = McpConfig.new(enabled: true, max_page_size: AdminSuite::Query::MAX_PAGE_SIZE)
     end
 
     # Sets the built-in default portals without marking portals as

data/lib/admin_suite/mcp/authorization.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Mcp
+    module Authorization
+      DENIED_MESSAGE = "Not authorized, or no such resource."
+
+      class << self
+        def readable_resources(actor:, request: nil)
+          return [] if AdminSuite.config.authorize.nil? || Auth.normalize_actor(actor).nil?
+
+          resource_configs.select do |config|
+            mcp_enabled?(config) && permitted?(config: config, actor: actor, action: :read, request: request)
+          end
+        end
+
+        def authorize_resource!(name:, actor:, action:, request: nil)
+          return nil if AdminSuite.config.authorize.nil? || Auth.normalize_actor(actor).nil?
+
+          config = resource_configs.find { |resource| resource.resource_name == name.to_s }
+          return nil unless config && mcp_enabled?(config)
+
+          config if permitted?(config: config, actor: actor, action: action, request: request)
+        end
+
+        def authorize_record?(config:, actor:, record:, request: nil)
+          return false if AdminSuite.config.authorize.nil? || Auth.normalize_actor(actor).nil?
+
+          permitted?(config: config, actor: actor, record: record, action: :read, request: request)
+        end
+
+        def denied_response
+          ::MCP::Tool::Response.new([{ type: "text", text: DENIED_MESSAGE }], error: true)
+        end
+
+        def error_response(message)
+          ::MCP::Tool::Response.new([{ type: "text", text: message }], error: true)
+        end
+
+        private
+
+        def resource_configs
+          AdminSuite::DefinitionLoader.load!(:resources)
+          Admin::Base::Resource.registered_resources
+        end
+
+        def mcp_enabled?(config)
+          !config.respond_to?(:mcp_enabled?) || config.mcp_enabled?
+        end
+
+        def permitted?(config:, actor:, action:, record: nil, request: nil)
+          AdminSuite.config.authorize.call(
+            actor: actor,
+            action: action,
+            resource: config,
+            record: record,
+            context: AdminSuite::AuthorizationContext.new(surface: :mcp, request: request)
+          )
+        rescue StandardError => error
+          Rails.logger&.warn(
+            "AdminSuite: MCP authorize hook raised #{error.class}: #{error.message}; denying."
+          )
+          false
+        end
+      end
+    end
+  end
+end

data/lib/admin_suite/mcp/serializer.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Mcp
+    # Serializes only fields declared by the resource DSL. This is the MCP
+    # surface's data-exposure boundary.
+    module Serializer
+      def self.index_row(record, config)
+        config.index_config.columns_list.each_with_object({}) do |column, row|
+          row[column.name] = primitive(resolve_column(record, column))
+        end
+      end
+
+      def self.show_payload(record, config)
+        sections = config.show_config&.sidebar_sections.to_a +
+          config.show_config&.main_sections.to_a
+
+        sections.each_with_object({}) do |section, payload|
+          Array(section.fields).each do |field|
+            payload[field] = primitive(value_for(record, field))
+          end
+        end
+      end
+
+      def self.associations_payload(record, config, max_rows:)
+        sections = config.show_config&.sidebar_sections.to_a + config.show_config&.main_sections.to_a
+        sections.each_with_object({}) do |section, payload|
+          next if section.association.blank? || section.columns.blank?
+
+          payload[section.name] = association_panel(record, section, max_rows)
+        end
+      end
+
+      def self.dump(payload)
+        JSON.pretty_generate(primitive(payload))
+      end
+
+      def self.resolve_column(record, column)
+        if column.respond_to?(:type) && column.type == :toggle
+          field = column.respond_to?(:toggle_field) ? (column.toggle_field || column.name) : column.name
+          value_for(record, field)
+        elsif column.respond_to?(:type) && column.type == :label
+          proc_or_attribute(record, column)
+        elsif column.respond_to?(:content) && column.content.is_a?(Proc)
+          column.content.call(record)
+        else
+          value_for(record, column.name)
+        end
+      rescue StandardError
+        nil
+      end
+      private_class_method :resolve_column
+
+      def self.proc_or_attribute(record, column)
+        if column.respond_to?(:content) && column.content.is_a?(Proc)
+          column.content.call(record)
+        else
+          value_for(record, column.name)
+        end
+      end
+      private_class_method :proc_or_attribute
+
+      def self.association_panel(record, section, max_rows)
+        limit = Integer(section.limit || section.per_page || max_rows).clamp(1..max_rows)
+        rows = record.public_send(section.association)
+        rows = rows.respond_to?(:limit) ? rows.limit(limit) : Array(rows).first(limit)
+        {
+          applied_limit: limit,
+          rows: Array(rows).map do |row|
+            section.columns.to_h { |column| [ column, primitive(value_for(row, column)) ] }
+          end
+        }
+      rescue StandardError
+        { applied_limit: 0, rows: [] }
+      end
+      private_class_method :association_panel
+
+      def self.value_for(record, name)
+        return nil unless record.respond_to?(name)
+
+        record.public_send(name)
+      rescue StandardError
+        nil
+      end
+      private_class_method :value_for
+
+      def self.primitive(value)
+        case value
+        when nil, true, false, String, Integer, Float
+          value
+        when Symbol
+          value.to_s
+        when Date, Time, DateTime
+          value.iso8601
+        when Array
+          value.map { |item| primitive(item) }
+        when Hash
+          value.each_with_object({}) { |(key, item), acc| acc[key] = primitive(item) }
+        else
+          coerce_object(value)
+        end
+      rescue StandardError
+        nil
+      end
+      private_class_method :primitive
+
+      def self.coerce_object(value)
+        if defined?(ActiveSupport::TimeWithZone) && value.is_a?(ActiveSupport::TimeWithZone)
+          value.iso8601
+        elsif defined?(BigDecimal) && value.is_a?(BigDecimal)
+          value.to_s("F")
+        elsif defined?(ActiveRecord::Base) && value.is_a?(ActiveRecord::Base)
+          display_name(value)
+        elsif value.respond_to?(:iso8601)
+          value.iso8601
+        else
+          display_name(value)
+        end
+      end
+      private_class_method :coerce_object
+
+      def self.display_name(item)
+        %i[name title display_title].each do |method_name|
+          next unless item.respond_to?(method_name)
+
+          text = item.public_send(method_name)
+          return text.to_s if text.present?
+        end
+        return "##{item.id}" if item.respond_to?(:id) && !item.id.nil?
+
+        item.class.name
+      rescue StandardError
+        nil
+      end
+      private_class_method :display_name
+    end
+  end
+end

data/lib/admin_suite/mcp/tools/aggregate.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Mcp
+    module Tools
+      class Aggregate < ::MCP::Tool
+        tool_name "aggregate"
+        description "Counts and index stats for a resource under a filter set. Returns no records."
+        input_schema(
+          properties: {
+            resource: { type: "string" },
+            q: { type: "string" },
+            filters: { type: "object" }
+          },
+          required: ["resource"]
+        )
+
+        def self.call(resource:, server_context:, q: nil, filters: {})
+          AdminSuite::Mcp.instrument(tool: "aggregate", resource: resource, actor: server_context[:actor], request: server_context[:request], filters: filters, q: q) do
+            allowed = false
+            config = Authorization.authorize_resource!(name: resource, actor: server_context[:actor], action: :read, request: server_context[:request])
+            next [Authorization.denied_response, nil, false] if config.nil?
+
+            allowed = true
+            params = (filters || {}).merge(search: q).compact
+            scope = AdminSuite::Query.new(
+              resource_config: config,
+              params: params,
+              max_page_size: AdminSuite.config.mcp.max_page_size
+            ).scope
+            payload = { resource: resource, count: scope.count, stats: stats_for(config, scope) }
+            response = ::MCP::Tool::Response.new([{ type: "text", text: Serializer.dump(payload) }])
+            [response, payload[:count], true]
+          rescue StandardError => e
+            Rails.logger&.warn("AdminSuite MCP aggregate failed: #{e.class}: #{e.message}")
+            [Authorization.error_response("aggregate failed"), nil, allowed]
+          end
+        end
+
+        def self.stats_for(config, scope)
+          Array(config.index_config&.stats_list).each_with_object({}) do |stat, stats|
+            stats[stat.name] = calculate(stat, scope)
+          end
+        end
+
+        def self.calculate(stat, scope)
+          stat.calculator.arity.zero? ? stat.calculator.call : stat.calculator.call(scope)
+        rescue StandardError
+          nil
+        end
+        private_class_method :calculate
+      end
+    end
+  end
+end

data/lib/admin_suite/mcp/tools/describe_resources.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Mcp
+    module Tools
+      class DescribeResources < ::MCP::Tool
+        tool_name "describe_resources"
+        description "List the admin resources this actor may read, with their " \
+                    "portals, declared fields, filters, sort keys, page size and actions."
+        input_schema(properties: {}, required: [])
+
+        def self.call(server_context:)
+          AdminSuite::Mcp.instrument(tool: "describe_resources", actor: server_context[:actor], request: server_context[:request]) do
+            allowed = false
+            if AdminSuite.config.authorize.nil? || Auth.normalize_actor(server_context[:actor]).nil?
+              [Authorization.denied_response, nil, false]
+            else
+              allowed = true
+              payload = Authorization
+                .readable_resources(actor: server_context[:actor], request: server_context[:request])
+                .map { |config| describe(config) }
+              response = ::MCP::Tool::Response.new([{ type: "text", text: Serializer.dump(payload) }])
+              [response, payload.size, true]
+            end
+          rescue StandardError => e
+            Rails.logger&.warn("AdminSuite MCP describe_resources failed: #{e.class}: #{e.message}")
+            [Authorization.error_response("describe_resources failed"), nil, allowed]
+          end
+        end
+
+        def self.describe(config)
+          index = config.index_config
+          {
+            name: config.resource_name,
+            model: config.model_class.to_s,
+            portal: config.portal_name,
+            section: config.section_name,
+            fields: Array(index&.columns_list).map do |column|
+              { name: column.name, label: column.header, type: column.type }
+            end,
+            filters: Array(index&.filters_list).map(&:name),
+            sortable: Array(index&.sortable_fields),
+            searchable: Array(index&.searchable_fields),
+            default_page_size: index&.per_page,
+            actions: declared_actions(config)
+          }
+        end
+
+        def self.declared_actions(config)
+          actions = config.actions_config
+          return [] unless actions
+
+          [
+            *Array(actions.member_actions).map { |action| { name: action.name, kind: "member" } },
+            *Array(actions.collection_actions).map { |action| { name: action.name, kind: "collection" } },
+            *Array(actions.bulk_actions).map { |action| { name: action.name, kind: "bulk" } }
+          ]
+        end
+        private_class_method :declared_actions
+      end
+    end
+  end
+end

data/lib/admin_suite/mcp/tools/get_record.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Mcp
+    module Tools
+      class GetRecord < ::MCP::Tool
+        tool_name "get_record"
+        description "One record by id, using the resource's show-page field set."
+        input_schema(
+          properties: { resource: { type: "string" }, id: { type: "string" } },
+          required: %w[resource id]
+        )
+
+        def self.call(resource:, id:, server_context:)
+          AdminSuite::Mcp.instrument(tool: "get_record", resource: resource, actor: server_context[:actor], request: server_context[:request]) do
+            allowed = false
+            config = Authorization.authorize_resource!(name: resource, actor: server_context[:actor], action: :read, request: server_context[:request])
+            next [Authorization.denied_response, nil, false] if config.nil?
+
+            allowed = true
+            record = config.model_class.find_by(id: id)
+            next [Authorization.denied_response, nil, false] if record.nil?
+            unless Authorization.authorize_record?(config: config, actor: server_context[:actor], record: record, request: server_context[:request])
+              next [Authorization.denied_response, nil, false]
+            end
+
+            payload = {
+              resource: resource, id: id, fields: Serializer.show_payload(record, config),
+              associations: Serializer.associations_payload(record, config, max_rows: AdminSuite.config.mcp.max_page_size)
+            }
+            response = ::MCP::Tool::Response.new([{ type: "text", text: Serializer.dump(payload) }])
+            [response, 1, true]
+          rescue StandardError => e
+            Rails.logger&.warn("AdminSuite MCP get_record failed: #{e.class}: #{e.message}")
+            [Authorization.error_response("get_record failed"), nil, allowed]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/admin_suite/mcp/tools/list_records.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Mcp
+    module Tools
+      class ListRecords < ::MCP::Tool
+        tool_name "list_records"
+        description "List records using the filters, search, and sort keys the resource declares."
+        input_schema(
+          properties: {
+            resource: { type: "string" },
+            q: { type: "string" },
+            filters: { type: "object" },
+            sort: { type: "string" },
+            direction: { type: "string", enum: %w[asc desc] },
+            page: { type: "integer" },
+            per_page: { type: "integer" }
+          },
+          required: ["resource"]
+        )
+
+        def self.call(resource:, server_context:, q: nil, filters: {}, sort: nil, direction: nil, page: 1, per_page: nil)
+          AdminSuite::Mcp.instrument(tool: "list_records", resource: resource, actor: server_context[:actor], request: server_context[:request], filters: filters, q: q) do
+            allowed = false
+            config = Authorization.authorize_resource!(name: resource, actor: server_context[:actor], action: :read, request: server_context[:request])
+            next [Authorization.denied_response, nil, false] unless config
+
+            allowed = true
+            query = build_query(config, filters, q:, sort:, direction:, per_page:)
+            payload = response_payload(resource, config, query, page)
+            response = ::MCP::Tool::Response.new([{ type: "text", text: Serializer.dump(payload) }])
+            [response, payload[:rows].size, true]
+          rescue StandardError => e
+            Rails.logger&.warn("AdminSuite MCP list_records failed: #{e.class}: #{e.message}")
+            [Authorization.error_response("list_records failed"), nil, allowed]
+          end
+        end
+
+        def self.build_query(config, filters, **params)
+          AdminSuite::Query.new(
+            resource_config: config,
+            params: (filters || {}).merge(params.except(:q), search: params[:q]).compact,
+            max_page_size: AdminSuite.config.mcp.max_page_size
+          )
+        end
+
+        def self.response_payload(resource, config, query, page)
+          applied_page = page.to_i.clamp(1..)
+          {
+            resource: resource,
+            page: applied_page,
+            applied_per_page: query.per_page,
+            rows: paginated(query, applied_page).map { |record| Serializer.index_row(record, config) }
+          }
+        end
+
+        def self.paginated(query, page)
+          offset = (page - 1) * query.per_page
+          scope = query.scope
+          return scope.offset(offset).limit(query.per_page) if scope.respond_to?(:offset)
+
+          Array(scope).drop(offset).first(query.per_page)
+        end
+      end
+    end
+  end
+end

data/lib/admin_suite/mcp.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Mcp
+    TOOLS = [
+      AdminSuite::Mcp::Tools::DescribeResources,
+      AdminSuite::Mcp::Tools::ListRecords,
+      AdminSuite::Mcp::Tools::GetRecord,
+      AdminSuite::Mcp::Tools::Aggregate
+    ].freeze
+
+    # A fresh server is built for each request, so its advertised tool list is
+    # derived from the current fail-closed authorization posture rather than
+    # cached across actors or requests.
+    def self.server_for(actor:, request: nil)
+      tools = AdminSuite.config.authorize.nil? || Auth.normalize_actor(actor).nil? ? [] : TOOLS
+
+      ::MCP::Server.new(
+        name: "admin_suite",
+        version: AdminSuite::VERSION,
+        tools: tools,
+        server_context: { actor: actor, request: request }
+      )
+    end
+
+    def self.instrument(tool:, resource: nil, actor: nil, action: :read, request: nil, filters: nil, q: nil)
+      payload = {
+        tool: tool,
+        resource: resource,
+        actor_type: actor&.class&.name,
+        actor_id: actor.respond_to?(:id) ? actor.id.to_s : nil,
+        request_id: request&.request_id,
+        action: action,
+        filters: filters,
+        q: q,
+        allowed: false,
+        error: true,
+        result_count: nil
+      }
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      ActiveSupport::Notifications.instrument("admin_suite.mcp.tool_call", payload) do
+        response, count, allowed = yield
+        payload[:allowed] = allowed
+        payload[:result_count] = count
+        payload[:error] = response.error?
+        response
+      ensure
+        payload[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(2)
+      end
+    end
+  end
+end

data/lib/admin_suite/query.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  # The one place an index-style query is built.
+  #
+  # Both the web index action and the MCP `list_records` tool go through
+  # this object, so the two surfaces cannot disagree about what a filter,
+  # a sort, or a page size means.
+  class Query
+    MAX_PAGE_SIZE = 100
+
+    def initialize(resource_config:, params: {}, max_page_size: MAX_PAGE_SIZE)
+      @resource_config = resource_config
+      @params = params || {}
+      @max_page_size = max_page_size
+    end
+
+    def scope
+      @scope ||= apply_includes(filtered)
+    end
+
+    def per_page
+      @per_page ||= clamp(@params[:per_page] || @params["per_page"])
+    end
+
+    private
+
+    def index_config = @resource_config&.index_config
+    def model_class = @resource_config.model_class
+
+    def filtered
+      return model_class.all unless index_config
+
+      Admin::Base::FilterBuilder.new(@resource_config, @params).apply(model_class.all)
+    end
+
+    # Applies the index's `includes:` DSL option when the relation supports
+    # it. Invalid associations degrade to an unoptimized working query.
+    def apply_includes(relation)
+      list = index_config&.includes_list
+      return relation if list.blank?
+      return relation unless relation.respond_to?(:includes)
+
+      relation.includes(*list)
+    rescue StandardError => e
+      Rails.logger&.warn(
+        "AdminSuite: #{model_class}'s index `includes(#{list.inspect})` raised " \
+        "#{e.class}: #{e.message}; rendering the index without eager loading."
+      )
+      relation
+    end
+
+    def clamp(requested)
+      cap = page_cap
+      fallback = (index_config&.per_page || 25).clamp(1..cap)
+      value = Integer(requested)
+      return fallback if value <= 0
+
+      value.clamp(..cap)
+    rescue ArgumentError, TypeError
+      fallback
+    end
+
+    def page_cap
+      cap = Integer(@max_page_size)
+      cap.positive? ? cap : MAX_PAGE_SIZE
+    rescue ArgumentError, TypeError
+      MAX_PAGE_SIZE
+    end
+  end
+end

data/lib/admin_suite/ui/show_value_formatter.rb

@@ -53,9 +53,9 @@ module AdminSuite
           end
         end
 
-        if defined?(ActiveStorage::Attached::One) && value.is_a?(ActiveStorage::Attached::One)
+        if defined?(::ActiveStorage::Attached::One) && value.is_a?(::ActiveStorage::Attached::One)
           return render_attachment_preview(value)
-        elsif defined?(ActiveStorage::Attached::Many) && value.is_a?(ActiveStorage::Attached::Many)
+        elsif defined?(::ActiveStorage::Attached::Many) && value.is_a?(::ActiveStorage::Attached::Many)
           return render_attachments_preview(value)
         end
 

data/lib/admin_suite/version.rb

@@ -2,7 +2,7 @@
 
 module AdminSuite
   module Version
-    VERSION = "0.5.0"
+    VERSION = "0.6.1"
   end
 
   # Backward-compatible constant.