active_scaffold_mcp 0.1.0

data/lib/active_scaffold/mcp/list_tool_generator.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    class ListToolGenerator < ToolGenerator
+      OPERATOR_ALIASES = {
+        eq: :equal,
+        equality: :equal,
+        range: :between,
+        not_eq: :not_equal,
+        neq: :not_equal,
+        not_range: :not_between
+      }.freeze
+
+      class << self
+        def generate_tool_for(controller_class:, action_name:, action_config:, mcp_config:, settings:)
+          core_config = mcp_config.core
+          mappings = {}
+
+          list_tool = Class.new(ActiveScaffold::MCP::ListTool).tap do |tool_class|
+            configure_tool_class(tool_class, controller_class:, action_name:, core_config:, mcp_config:, settings:)
+            include_config_list(tool_class, core_config)
+            tool_class.read_only
+
+            views_tool_name = "#{tool_class.tool_name}_views" if saved_views_enabled?(core_config)
+            list_views = add_list_view_property(tool_class, core_config, views_tool_name)
+            add_column_filter_properties(tool_class, core_config, settings, mappings)
+            add_named_filter_properties(tool_class, action_config, settings, mappings)
+            add_search_property(tool_class, core_config, settings, mappings)
+            sortable_columns = add_sorting_properties(tool_class, core_config, action_config)
+            add_pagination_properties(tool_class, action_config)
+            generated_description = description(tool_class.title, mappings, sortable_columns, action_config, list_views)
+            tool_class.description(settings[:description] || generated_description)
+            tool_class.mcp_param_mappings = mappings.freeze
+
+            include_extensions(tool_class, settings)
+          end
+
+          return list_tool unless saved_views_enabled?(core_config)
+
+          [
+            list_tool,
+            build_list_views_tool(
+              controller_class:, action_name:, core_config:, mcp_config:, settings:, list_tool:
+            )
+          ]
+        end
+
+        private
+
+        def include_config_list(tool_class, core_config)
+          return unless core_config.actions.include?(:config_list)
+
+          tool_class.include "ActiveScaffold::Actions::ConfigList".constantize
+        end
+
+        def description(title, mappings, sortable_columns, action_config, list_views)
+          filter_types = []
+          filter_types << "column filters" if mappings.any? { |_name, mapping| mapping[:source].nil? }
+          filter_types << "named list filters" if mappings.any? { |_name, mapping| mapping[:source] == :named_filter }
+          filter_types << "full-text search" if mappings.any? { |_name, mapping| mapping[:source] == :search }
+
+          sentences = ["#{title} as a paginated collection"]
+          sentences << "Supports #{filter_types.to_sentence}" if filter_types.any?
+          search_mapping = mappings.values.find { |mapping| mapping[:source] == :search }
+          sentences << search_mapping[:description] if search_mapping
+          if sortable_columns.any?
+            sentences << "Supports sorting by #{formatted_column_names(sortable_columns)}"
+            sentences << default_sorting_description(action_config)
+          end
+          sentences << list_views[:description] if list_views
+          sentences << "Use limit and page for pagination"
+          "#{sentences.join('. ')}."
+        end
+
+        def add_list_view_property(tool_class, core_config, views_tool_name)
+          return unless core_config.actions.include?(:config_list)
+
+          config_list = core_config.config_list
+          configured_names = config_list.named_views.map { |view| view.name.to_s }
+          saved_views = saved_views_enabled?(core_config)
+          return if configured_names.empty? && !saved_views
+
+          sentences = ["Select a named list view to change the returned columns and default sorting"]
+          sentences << "Configured views: #{formatted_column_names(configured_names)}" if configured_names.any?
+          if saved_views
+            sentences << "Call `#{views_tool_name}` to get all views available to the current user"
+          end
+          description = sentences.join(". ")
+          property_options = {type: "string", description: description}
+          property_options[:enum] = configured_names unless saved_views
+          tool_class.property :list_view, **property_options
+          {description: description}
+        end
+
+        def saved_views_enabled?(core_config)
+          return false unless core_config.actions.include?(:config_list)
+
+          config_list = core_config.config_list
+          config_list.named_views_method.present? && config_list.save_to_user.present?
+        end
+
+        def build_list_views_tool(controller_class:, action_name:, core_config:, mcp_config:, settings:, list_tool:)
+          Class.new(ActiveScaffold::MCP::ListViewsTool).tap do |tool_class|
+            configure_tool_class(tool_class, controller_class:, action_name:, core_config:, mcp_config:, settings:)
+            tool_class.tool_name("#{list_tool.tool_name}_views")
+            tool_class.title("List views for #{tool_resource_label(mcp_config, settings)}")
+            tool_class.description(
+              "List all named views available to the current user for `#{list_tool.tool_name}`. " \
+              "Pass a returned `value` to its `list_view` argument; omit `list_view` to use the default columns."
+            )
+            include_config_list(tool_class, core_config)
+            tool_class.read_only
+            include_extensions(tool_class, settings)
+          end
+        end
+
+        def add_column_filter_properties(tool_class, core_config, settings, mappings)
+          configured_filter_columns(core_config, settings).each do |column_name, operators|
+            column = core_config._columns_hash[column_name.to_s]
+            next unless column
+
+            Array(operators).each do |operator|
+              add_operator_properties(tool_class, column_name, column, normalize_operator(operator), mappings)
+            end
+          end
+        end
+
+        def configured_filter_columns(core_config, settings)
+          result = case settings[:filter_columns]
+                   when Hash
+                     settings[:filter_columns].transform_keys(&:to_sym)
+                   when nil
+                     {}
+                   else
+                     Array(settings[:filter_columns]).to_h { |name| [name.to_sym, :equal] }
+                   end
+
+          settings.fetch(:filter_column_sets, {}).each do |set_name, operators|
+            columns_for_set(core_config, set_name).each { |name| result[name] ||= operators }
+          end
+          add_polymorphic_type_columns(core_config, result)
+          result
+        end
+
+        def add_polymorphic_type_columns(core_config, filter_columns)
+          model = core_config.model
+          return unless model.respond_to?(:reflect_on_all_associations)
+
+          model.reflect_on_all_associations(:belongs_to).select(&:polymorphic?).each do |association|
+            foreign_key = association.foreign_key.to_sym
+            foreign_type = association.foreign_type.to_sym
+            next unless filter_columns.key?(foreign_key)
+            next unless core_config._columns_hash.key?(foreign_type.to_s)
+
+            filter_columns[foreign_type] ||= filter_columns[foreign_key]
+          end
+        end
+
+        def columns_for_set(core_config, set_name)
+          columns = core_config._columns_hash.values
+          selected_columns = case set_name.to_sym
+                             when :foreign_keys
+                               columns.select { |column| column.name.end_with?("_id") }
+                             when :dates
+                               columns.select { |column| column.type.to_sym == :date }
+                             when :timestamps
+                               columns.select { |column| %i[datetime timestamp timestamptz].include?(column.type.to_sym) }
+                             else
+                               raise ArgumentError, "unknown MCP filter column set: #{set_name}"
+                             end
+          selected_columns.map { |column| column.name.to_sym }
+        end
+
+        def normalize_operator(operator)
+          operator = operator.to_sym
+          OPERATOR_ALIASES.fetch(operator, operator)
+        end
+
+        def add_operator_properties(tool_class, column_name, column, operator, mappings)
+          case operator
+          when :equal, :not_equal
+            property_name = operator == :equal ? column_name : :"#{column_name}_not"
+            add_scalar_property(tool_class, property_name, column, "Filter by #{column_name}")
+            mappings[property_name.to_sym] = {target: column_name.to_sym, operator: operator}
+          when :in, :not_in
+            property_name = operator == :in ? :"#{column_name}_in" : :"#{column_name}_not_in"
+            tool_class.collection property_name,
+                                  type: json_type(column),
+                                  description: "Filter #{column_name} by a list of values"
+            mappings[property_name] = {target: column_name.to_sym, operator: operator}
+          when :between, :not_between
+            prefix = operator == :between ? column_name : :"#{column_name}_not"
+            %i[from to].each do |endpoint|
+              property_name = :"#{prefix}_#{endpoint}"
+              add_scalar_property(tool_class, property_name, column, "#{endpoint.to_s.humanize} value for #{column_name}")
+              mappings[property_name] = {
+                target: column_name.to_sym,
+                operator: :"#{'not_' if operator == :not_between}between_#{endpoint}"
+              }
+            end
+          when :null, :not_null
+            property_name = operator == :null ? :"#{column_name}_null" : :"#{column_name}_not_null"
+            tool_class.property property_name,
+                                type: "boolean",
+                                description: "Match records where #{column_name} is #{'not ' if operator == :not_null}null"
+            mappings[property_name] = {target: column_name.to_sym, operator: operator}
+          else
+            raise ArgumentError, "unsupported MCP filter operator for #{column_name}: #{operator}"
+          end
+        end
+
+        def add_scalar_property(tool_class, property_name, column, description)
+          tool_class.property(property_name, **schema_options(column), description: description)
+        end
+
+        def add_named_filter_properties(tool_class, action_config, settings, mappings)
+          selected_filters(action_config, settings[:filters]).each do |filter|
+            property_name = filter.name.to_sym
+            if mappings.key?(property_name)
+              raise ArgumentError, "named list filter #{filter.name} conflicts with an MCP column filter"
+            end
+
+            option_names = filter.map { |option| option.name.to_s }
+            tool_class.property property_name,
+                                type: "string",
+                                description: named_filter_description(filter),
+                                default: filter.default_option&.to_s,
+                                enum: option_names
+            mappings[property_name] = {target: filter.name, operator: :equal, source: :named_filter}
+          end
+        end
+
+        def named_filter_description(filter)
+          sentences = [filter.description || "Apply the #{filter.name} list filter"]
+          sentences << "When omitted, the server uses the default option '#{filter.default_option}'"
+          if filter.security_method_set?
+            sentences << "This filter may be disallowed in the current context"
+          else
+            secured_options = filter.select(&:security_method_set?).map { |option| option.name.to_s }
+            if secured_options.any?
+              sentences << "These options may be disallowed in the current context: #{secured_options.to_sentence}"
+            end
+          end
+          sentences.join(". ")
+        end
+
+        def selected_filters(action_config, configured_filters)
+          return [] if configured_filters.nil? || !action_config.respond_to?(:filters)
+          return action_config.filters.to_a if configured_filters == :all
+
+          Array(configured_filters).filter_map { |name| action_config.filters[name] }
+        end
+
+        def add_search_property(tool_class, core_config, settings, mappings)
+          return unless search_enabled?(core_config, settings)
+
+          description = search_property_description(core_config)
+          tool_class.include ActiveScaffold::Actions::Search
+          tool_class.property :search,
+                              type: "string",
+                              description: description
+          mappings[:search] = {target: :search, operator: :equal, source: :search, description: description}
+        end
+
+        def search_property_description(core_config)
+          columns = core_config.search.columns.visible_columns(skip_authorization: true, flatten: true)
+          labels = columns.map { |column| column.label.presence || column.name.to_s.humanize }
+          return "Search text across the configured ActiveScaffold search columns" if labels.empty?
+
+          displayed_labels = labels.first(12)
+          remaining_count = labels.length - displayed_labels.length
+          description = "Search text across #{displayed_labels.to_sentence}"
+          description += " and #{remaining_count} more" if remaining_count.positive?
+          description
+        end
+
+        def search_enabled?(core_config, settings)
+          settings.fetch(:search, true) && core_config.actions.include?(:search)
+        end
+
+        def add_sorting_properties(tool_class, core_config, action_config)
+          columns = core_config.columns.select(&:sortable?)
+          column_names = columns.map { |column| column.name.to_s }
+          return [] if column_names.empty?
+
+          tool_class.property :sort,
+                              type: "string",
+                              description: "Column to sort by. Allowed columns: #{formatted_column_names(column_names)}. " \
+                                           "#{default_sorting_description(action_config)}.",
+                              enum: column_names
+          tool_class.property :sort_direction,
+                              type: "string",
+                              description: "Sort direction used when sort is provided; defaults to asc",
+                              default: "asc",
+                              enum: %w[asc desc]
+          column_names
+        end
+
+        def formatted_column_names(column_names)
+          column_names.map { |name| "`#{name}`" }.to_sentence
+        end
+
+        def default_sorting_description(action_config)
+          sorting = action_config.sorting if action_config.respond_to?(:sorting)
+          clauses = Array(sorting).map do |column, direction|
+            "`#{column.name}` #{direction.to_s.upcase}"
+          end
+          if clauses.any?
+            "When sort is omitted, the ActiveScaffold default sorting is #{clauses.to_sentence}"
+          else
+            "When sort is omitted, the configured ActiveScaffold default sorting is used"
+          end
+        end
+
+        def add_pagination_properties(tool_class, action_config)
+          configured_limit = action_config.per_page.to_i
+          default_limit = if configured_limit.positive?
+                            [configured_limit, ActiveScaffold::MCP::ListTool::MAX_LIMIT].min
+                          else
+                            ActiveScaffold::MCP::ListTool::DEFAULT_LIMIT
+                          end
+          tool_class.property :limit,
+                              type: "integer",
+                              description: "Maximum records to return",
+                              default: default_limit,
+                              minimum: 1,
+                              maximum: ActiveScaffold::MCP::ListTool::MAX_LIMIT
+          tool_class.property :page,
+                              type: "integer",
+                              description: "Page number",
+                              default: 1,
+                              minimum: 1
+        end
+
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/list_views_tool.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+require "set"
+
+module ActiveScaffold
+  module MCP
+    class ListViewsTool < ListTool
+      abstract!
+
+      def perform
+        render(text: JSON.generate(views: mcp_available_list_views))
+      end
+
+      private
+
+      def mcp_available_list_views
+        configured_views = active_scaffold_config.config_list.named_views.filter_map do |view|
+          next if view.security_method && !send(view.security_method)
+
+          {
+            label: view.name.to_s,
+            value: view.name.to_s,
+            source: "configured"
+          }.tap do |result|
+            result[:description] = view.tooltip.to_s if view.respond_to?(:tooltip) && view.tooltip.present?
+          end
+        end
+        configured_values = configured_views.to_set { |view| view[:value] }
+        saved_views = config_list_named_views.filter_map do |item|
+          label, value = Array(item)
+          value ||= label
+          next if configured_values.include?(value.to_s)
+
+          {
+            label: label.to_s,
+            value: value.to_s,
+            source: "saved"
+          }
+        end
+        configured_views + saved_views
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/presenter.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    class Presenter
+      attr_reader :tool
+
+      def initialize(tool)
+        @tool = tool
+      end
+
+      def presentable_column?(column)
+        return true if column.association || respond_to?(column_method_name(column), true)
+        return false unless model.public_method_defined?(column.name)
+
+        model.instance_method(column.name).parameters.none? { |type, _| type == :req || type == :keyreq }
+      end
+
+      def record(record, columns, counts = nil)
+        columns.each_with_object({}) do |column, result|
+          result[column.name] = column_value(record, column, counts)
+        end
+      end
+
+      protected
+
+      delegate :active_scaffold_config, :current_user, :params, to: :tool
+
+      private
+
+      def column_method_name(column)
+        :"#{column.name}_column"
+      end
+
+      def column_value(record, column, counts)
+        column_method = column_method_name(column)
+        return send(column_method, record, column) if respond_to?(column_method, true)
+        return association_value(record, record.public_send(column.association.name), column, counts) if column.association
+
+        record.public_send(column.name)
+      end
+
+      def association_value(record, value, column, counts)
+        if column.association.collection?
+          collection_association_value(record, value, column, counts)
+        elsif value
+          associated_record_hash(value, polymorphic: column.association.polymorphic?)
+        end
+      end
+
+      def collection_association_value(record, value, column, counts)
+        associated_limit = column.associated_limit
+        associated_number = column.associated_number?
+
+        if associated_limit.nil?
+          return value.map { |associated_record| associated_record_hash(associated_record) }
+        end
+
+        count = association_size(record, value, column, counts) if associated_number
+        return associated_number ? count : nil if associated_limit.zero?
+
+        loaded_limit = associated_number ? associated_limit : associated_limit + 1
+        associated_records = limited_associated_records(value, loaded_limit)
+        more_records = associated_number ? count > associated_limit : associated_records.size > associated_limit
+        associated_records = associated_records.first(associated_limit)
+        records = associated_records.map { |associated_record| associated_record_hash(associated_record) }
+        displayed_count =
+          if associated_number
+            count
+          elsif more_records
+            ">#{associated_limit}"
+          else
+            records.size
+          end
+
+        {
+          (more_records ? :first_records : :records) => records,
+          count: displayed_count
+        }
+      end
+
+      def limited_associated_records(value, limit)
+        if value.respond_to?(:loaded?) && value.loaded?
+          value.first(limit)
+        elsif value.respond_to?(:limit)
+          value.limit(limit).to_a
+        else
+          value.first(limit)
+        end
+      end
+
+      def association_size(_record, value, column, counts)
+        return counts[column.name] if counts&.key?(column.name)
+
+        value.size
+      end
+
+      def associated_record_hash(record, polymorphic: false)
+        result = {id: record.id, label: record.to_label}
+        result[:model] = record.class.model_name.human if polymorphic
+        result
+      end
+
+      def model
+        active_scaffold_config.model
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/profile_user.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    module ProfileUser
+      class InvalidReference < ArgumentError; end
+
+      module_function
+
+      def resolve(reference)
+        class_name, separator, id = reference.to_s.rpartition("#")
+        if separator.empty? || class_name.empty? || id.empty?
+          raise InvalidReference, "MCP_USER must use CLASS#ID, for example: User#201"
+        end
+
+        user_class = class_name.safe_constantize
+        raise InvalidReference, "MCP_USER class does not exist: #{class_name}" unless user_class
+
+        unless user_class.respond_to?(:find)
+          raise InvalidReference, "MCP_USER class must respond to find: #{class_name}"
+        end
+
+        user_class.find(id)
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/settings_validator.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    class SettingsValidator
+      class InvalidSetting < ArgumentError; end
+
+      COLUMN_SETTING = %i[columns].freeze
+      COMMON_SETTINGS = %i[description label modules name presenter presenter_modules].freeze
+      LIST_SETTINGS = %i[columns filter_columns filter_column_sets filters search].freeze
+      SHOW_SETTINGS = %i[columns lookup_columns].freeze
+
+      def validate!(action_name, settings)
+        settings.each do |setting, value|
+          next if valid?(action_name, setting, value)
+
+          raise InvalidSetting, "unsupported MCP setting for #{action_name}: #{setting}"
+        end
+
+        settings
+      end
+
+      def valid?(action_name, setting, value = nil)
+        setting = setting.to_sym
+        return valid_common_setting?(setting, value) if COMMON_SETTINGS.include?(setting)
+
+        validator = :"valid_settings_for_#{action_name}?"
+        return true unless respond_to?(validator, true)
+
+        send(validator, setting, value)
+      end
+
+      private
+
+      def valid_common_setting?(setting, value)
+        case setting
+        when :description, :label, :name
+          (value.is_a?(String) || value.is_a?(Symbol)) && value.to_s.present?
+        when :modules, :presenter_modules
+          Array(value).all? { |extension| extension.is_a?(Module) }
+        when :presenter
+          value.is_a?(Class)
+        end
+      end
+
+      def valid_settings_for_list?(setting, value)
+        return [true, false].include?(value) if setting == :search
+
+        LIST_SETTINGS.include?(setting)
+      end
+
+      def valid_settings_for_show?(setting, _value)
+        SHOW_SETTINGS.include?(setting)
+      end
+
+      def valid_settings_for_create?(setting, _value)
+        COLUMN_SETTING.include?(setting)
+      end
+
+      def valid_settings_for_update?(setting, _value)
+        COLUMN_SETTING.include?(setting)
+      end
+
+      def valid_settings_for_delete?(_setting, _value)
+        false
+      end
+
+      def valid_settings_for_search?(_setting, _value)
+        false
+      end
+
+      def valid_settings_for_nested?(_setting, _value)
+        false
+      end
+
+      def valid_settings_for_subform?(_setting, _value)
+        false
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/show_tool.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ActiveScaffold
+  module MCP
+    class ShowTool < Tool
+      abstract!
+
+      class_attribute :mcp_lookup_column_names, instance_accessor: false, default: [].freeze
+      class_attribute :mcp_primary_key_name, instance_accessor: false
+
+      validate :exactly_one_lookup_argument
+
+      def perform
+        return unless resolve_lookup_id
+
+        do_show
+        render(text: JSON.generate(record: mcp_record_hash(@record, mcp_output_columns)))
+      rescue ActiveRecord::RecordNotFound
+        report_error("No record found for id #{params[:id].inspect}")
+      end
+
+      private
+
+      def tool_authorized?
+        super && show_authorized?
+      end
+
+      def mcp_default_output_columns
+        active_scaffold_config.show.columns.visible_columns(flatten: true)
+      end
+
+      def exactly_one_lookup_argument
+        provided_names = lookup_argument_names.select { |name| mcp_argument_provided?(name) }
+        return if provided_names.one?
+
+        errors.add(:base, "Provide exactly one of #{lookup_argument_names.to_sentence}")
+      end
+
+      def lookup_argument_names
+        [:id, *self.class.mcp_lookup_column_names]
+      end
+
+      def resolve_lookup_id
+        return true if mcp_argument_provided?(:id)
+
+        column_name = self.class.mcp_lookup_column_names.find { |name| mcp_argument_provided?(name) }
+        # Resolve exact identifiers within the base scope, without list filters
+        # (including defaults) hiding an otherwise showable record.
+        ids = beginning_of_chain.where(column_name => public_send(column_name))
+                                .limit(2)
+                                .pluck(self.class.mcp_primary_key_name)
+        if ids.empty?
+          report_error("No record found for #{column_name} #{public_send(column_name).inspect}")
+          return false
+        end
+        if ids.many?
+          report_error("More than one record found for #{column_name} #{public_send(column_name).inspect}; use id instead")
+          return false
+        end
+
+        params[:id] = ids.first
+        true
+      end
+    end
+  end
+end