active_scaffold_mcp 0.1.0

data/lib/active_scaffold/config/mcp.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module Config
+    class MCP < Base
+      def initialize(core_config)
+        super
+        @actions = self.class.duplicate_actions(self.class.actions)
+        self.filter_column_sets = self.class.filter_column_sets
+      end
+
+      # Global defaults. These are available through config.mcp in an
+      # ActiveScaffold.defaults block.
+      cattr_accessor :actions, instance_accessor: false, default: {}.freeze
+      cattr_accessor :filter_column_sets, instance_accessor: false, default: {}.freeze
+      cattr_accessor :base_tool, instance_accessor: false,
+                    default: -> { "ApplicationMCPTool".safe_constantize || ActionMCP::Tool }
+      cattr_accessor :settings_validator, instance_accessor: false,
+                    default: ActiveScaffold::MCP::SettingsValidator
+      cattr_accessor :tool_generator, instance_accessor: false,
+                    default: ActiveScaffold::MCP::GeneratorFactory.new
+
+      class << self
+        alias unvalidated_actions= actions=
+        alias filter_columns_sets filter_column_sets
+        alias filter_columns_sets= filter_column_sets=
+
+        def actions=(value)
+          self.unvalidated_actions = normalize_actions(value)
+        end
+        private :unvalidated_actions=
+
+        def resolve_tool(name)
+          configured_tool = public_send(:"#{name}_tool")
+          configured_tool = configured_tool.call if configured_tool.respond_to?(:call)
+          configured_tool.is_a?(String) ? configured_tool.constantize : configured_tool
+        end
+
+        def resolved_settings_validator
+          configured_validator = settings_validator
+          if !defined?(@resolved_settings_validator_source) || @resolved_settings_validator_source != configured_validator
+            @resolved_settings_validator_source = configured_validator
+            @resolved_settings_validator = configured_validator.is_a?(Class) ? configured_validator.new : configured_validator
+          end
+
+          @resolved_settings_validator
+        end
+
+        def validate_mcp_setting!(action_name, setting, value)
+          resolved_settings_validator.validate!(action_name, setting.to_sym => value)
+        end
+
+        def mcp_setting_for(action_name, setting)
+          action_settings = actions.fetch(:all, {}).merge(actions.fetch(action_name.to_sym, {}))
+          action_settings[setting.to_sym]
+        end
+
+        def set_mcp_setting(action_name, setting, value)
+          action_name = action_name.to_sym
+          setting = setting.to_sym
+          updated_actions = actions.transform_keys(&:to_sym)
+          action_settings = updated_actions.fetch(action_name, {}).merge(setting => value)
+          updated_actions[action_name] = normalize_settings(action_settings)
+          self.unvalidated_actions = updated_actions
+          value
+        end
+
+        def expose(action_name, settings = nil)
+          action_name = action_name.to_sym
+          updated_actions = actions.transform_keys(&:to_sym)
+          unless settings.nil? && updated_actions.key?(action_name)
+            updated_actions[action_name] = normalize_action_settings(action_name, settings)
+          end
+          self.unvalidated_actions = updated_actions
+
+          action_config = ActiveScaffold::MCP::ActionConfig.new(self, action_name)
+          yield action_config if block_given?
+          action_config
+        end
+
+        # These methods are also used by per-controller MCP config instances,
+        # keeping global defaults and local configuration normalized identically.
+        def normalize_actions(value)
+          return {all: {}} if all?(value)
+
+          case value
+          when nil
+            {}
+          when Hash
+            value.each_with_object({}) do |(action_name, settings), result|
+              result[action_name.to_sym] = normalize_action_settings(action_name, settings)
+            end
+          else
+            Array(value).each_with_object({}) do |action_name, result|
+              result[action_name.to_sym] = {}
+            end
+          end
+        end
+
+        def normalize_action_settings(action_name, value)
+          settings = case value
+                     when nil, true
+                       {}
+                     when Array
+                       {columns: normalize_names(value)}
+                     when Hash
+                       value.to_h.transform_keys(&:to_sym)
+                     else
+                       raise ArgumentError, "settings for #{action_name} must be an array or hash"
+                     end
+
+          resolved_settings_validator.validate!(action_name, settings)
+          normalize_settings(settings)
+        end
+
+        def normalize_settings(settings)
+          settings.each_with_object({}) do |(name, value), result|
+            result[name] = case name
+                           when :description, :label, :name
+                             value.to_s
+                           when :columns, :lookup_columns
+                             normalize_names(value)
+                           when :filter_columns
+                             value.is_a?(Hash) ? normalize_operator_map(value) : normalize_names(value)
+                           when :filter_column_sets
+                             normalize_filter_column_sets(value)
+                           when :filters
+                             all?(value) ? :all : normalize_names(value)
+                           when :modules, :presenter_modules
+                             Array(value).compact
+                           when :presenter
+                             value
+                           else
+                             duplicate_setting(value)
+                           end
+          end
+        end
+
+        def duplicate_actions(configured_actions)
+          configured_actions.each_with_object({}) do |(action_name, settings), result|
+            result[action_name] = duplicate_settings(settings)
+          end
+        end
+
+        def duplicate_settings(settings)
+          settings.each_with_object({}) do |(name, value), result|
+            result[name] = case name.to_sym
+                           when :modules, :presenter_modules
+                             Array(value).dup
+                           when :presenter
+                             value
+                           else
+                             duplicate_setting(value)
+                           end
+          end
+        end
+
+        def normalize_operator_map(value)
+          return {} if value.nil?
+
+          value.to_h.each_with_object({}) do |(name, operators), result|
+            result[name.to_sym] = operators.is_a?(Array) ? normalize_names(operators) : operators.to_sym
+          end
+        end
+
+        def normalize_filter_column_sets(value)
+          return {} if value.nil?
+
+          unless value.is_a?(Hash)
+            raise ArgumentError,
+                  "filter_column_sets must be a hash mapping set names to operators, " \
+                  "for example: {foreign_keys: :in, timestamps: :range}"
+          end
+
+          normalize_operator_map(value)
+        end
+
+        def method_missing(name, *args)
+          if args.empty? && mcp_action?(name)
+            ActiveScaffold::MCP::ActionConfig.new(self, name)
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(name, include_all = false)
+          mcp_action?(name) || super
+        end
+
+        def mcp_action?(name)
+          ActiveScaffold::Config::Core.config_class?(name) || actions.key?(name.to_sym)
+        end
+
+        def all?(value)
+          value == :all || value == "all"
+        end
+
+        def normalize_names(value)
+          Array(value).flatten.compact.map(&:to_sym).uniq
+        end
+
+        def duplicate_setting(value)
+          value.respond_to?(:deep_dup) ? value.deep_dup : value
+        end
+
+        private :mcp_action?, :all?, :normalize_names, :duplicate_setting
+      end
+
+      attr_reader :actions, :filter_column_sets
+      attr_writer :label, :name
+      alias exposed_actions actions
+      alias filter_columns_sets filter_column_sets
+
+      def label(core: @core)
+        @label ? as_(@label, count: 2) : core.label(count: 2)
+      end
+
+      def name
+        (@name || core.model.model_name.route_key).to_s
+      end
+
+      def actions=(value)
+        @actions = self.class.normalize_actions(value)
+      end
+      alias exposed_actions= actions=
+
+      def filter_column_sets=(value)
+        @filter_column_sets = self.class.normalize_filter_column_sets(value)
+      end
+      alias filter_columns_sets= filter_column_sets=
+
+      def expose(action_name, settings = nil)
+        action_name = action_name.to_sym
+        unless settings.nil? && @actions.key?(action_name)
+          @actions[action_name] = self.class.normalize_action_settings(action_name, settings)
+        end
+
+        action_config = ActiveScaffold::MCP::ActionConfig.new(self, action_name)
+        yield action_config if block_given?
+        action_config
+      end
+
+      def exposed?(action_name)
+        @actions.key?(:all) || @actions.key?(action_name.to_sym)
+      end
+
+      def settings_for(action_name)
+        return unless exposed?(action_name)
+
+        settings = self.class.duplicate_settings(
+          @actions.fetch(:all, {}).merge(@actions.fetch(action_name.to_sym, {}))
+        )
+
+        if action_name.to_sym == :list && !settings.key?(:filter_column_sets) && @filter_column_sets.any?
+          settings[:filter_column_sets] = @filter_column_sets.deep_dup
+        end
+
+        settings
+      end
+      alias action_settings settings_for
+
+      def mcp_setting_for(action_name, setting)
+        settings_for(action_name)&.[](setting.to_sym)
+      end
+
+      def set_mcp_setting(action_name, setting, value)
+        action_name = action_name.to_sym
+        setting = setting.to_sym
+        settings = @actions.fetch(action_name, {}).merge(setting => value)
+        @actions[action_name] = self.class.normalize_settings(settings)
+        value
+      end
+
+      def validate_mcp_setting!(action_name, setting, value)
+        self.class.validate_mcp_setting!(action_name, setting, value)
+      end
+
+      def method_missing(name, *args)
+        if args.empty? && mcp_action?(name)
+          ActiveScaffold::MCP::ActionConfig.new(self, name)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_all = false)
+        mcp_action?(name) || super
+      end
+
+      private
+
+      def mcp_action?(name)
+        ActiveScaffold::Config::Core.config_class?(name) || @actions.key?(name.to_sym)
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/action_config.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    class ActionConfig
+      attr_reader :action_name
+
+      def initialize(owner, action_name)
+        @owner = owner
+        @action_name = action_name.to_sym
+      end
+
+      def [](setting)
+        @owner.mcp_setting_for(@action_name, setting)
+      end
+
+      def []=(setting, value)
+        @owner.validate_mcp_setting!(@action_name, setting, value)
+        @owner.set_mcp_setting(@action_name, setting, value)
+      end
+
+      def method_missing(name, *args)
+        method_name = name.to_s
+        if method_name.end_with?("=") && args.length == 1
+          self[method_name.delete_suffix("=")] = args.first
+        elsif args.empty?
+          self[name]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(_name, _include_all = false)
+        true
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    class Engine < Rails::Engine
+      rake_tasks do
+        load File.expand_path("../../tasks/active_scaffold_mcp_tasks.rake", __dir__)
+      end
+
+      initializer "active_scaffold_mcp.initialize", after: "initialize_active_scaffold" do
+        ActiveScaffold.defaults do |config|
+          config.actions << :mcp unless config.actions.include?(:mcp)
+        end
+      end
+
+      config.to_prepare do
+        if Rails.application.config.reloading_enabled?
+          ActiveScaffold::MCP.reload_generated_tools!
+        end
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/filtered_tools.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    module FilteredTools
+      def filtered_tools
+        super.select do |entry|
+          tool_class = entry.klass
+          !tool_class.respond_to?(:tool_authorized?) || tool_class.tool_authorized?
+        end
+      end
+    end
+  end
+end
+
+unless ActionMCP::Configuration.ancestors.include?(ActiveScaffold::MCP::FilteredTools)
+  ActionMCP::Configuration.prepend(ActiveScaffold::MCP::FilteredTools)
+end

data/lib/active_scaffold/mcp/flash.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    class Flash < ActiveSupport::HashWithIndifferentAccess
+      def messages
+        values.flatten.compact
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/generator_factory.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    class GeneratorFactory
+      class GeneratorNotFound < StandardError; end
+
+      Rule = Data.define(:generator, :attributes, :position) do
+        def matches?(values)
+          attributes.all? { |name, expected| expected.nil? || values[name] == expected }
+        end
+
+        def specificity
+          attributes.values.count { |value| !value.nil? }
+        end
+      end
+
+      def initialize
+        @action_generators = {}
+        @crud_rules = []
+        @custom_action_rules = []
+        @registration_position = 0
+        register ActiveScaffold::MCP::ListToolGenerator, actions: :list
+        register ActiveScaffold::MCP::ShowToolGenerator, actions: :show
+      end
+
+      def register(generator, actions:)
+        Array(actions).each { |action_name| @action_generators[action_name.to_sym] = generator }
+        self
+      end
+
+      def register_default(generator, crud_type: nil, columns: nil)
+        add_rule(@crud_rules, generator, crud_type: crud_type&.to_sym, columns: columns)
+      end
+
+      # This registry is ready for ActiveScaffold's future custom_actions
+      # configuration. nil values are wildcards.
+      def register_custom(generator, submit_method: nil, columns: nil, destructive: nil)
+        add_rule(
+          @custom_action_rules,
+          generator,
+          submit_method: submit_method&.to_sym,
+          columns: columns,
+          destructive: destructive
+        )
+      end
+
+      def generate_tools_for(controller_class, mcp_config)
+        exposed_action_names(mcp_config).flat_map do |action_name|
+          action_config, custom = action_config_for(mcp_config.core, action_name)
+          generator = generator_for(action_name, action_config, custom: custom)
+          unless generator
+            raise GeneratorNotFound,
+                  "no MCP tool generator registered for #{controller_class.name}##{action_name}"
+          end
+
+          result = generate_tool(
+            generator,
+            controller_class: controller_class,
+            action_name: action_name,
+            action_config: action_config,
+            mcp_config: mcp_config,
+            settings: mcp_config.settings_for(action_name)
+          )
+          Array(result).compact
+        end
+      end
+
+      private
+
+      def add_rule(collection, generator, **attributes)
+        @registration_position += 1
+        collection << Rule.new(generator:, attributes:, position: @registration_position)
+        self
+      end
+
+      def exposed_action_names(mcp_config)
+        names = mcp_config.actions.keys - [:all]
+        available_names = (
+          mcp_config.core.actions.to_a + custom_action_names(mcp_config.core)
+        ).uniq
+        return names & available_names unless mcp_config.actions.key?(:all)
+
+        (names + available_names).uniq & available_names
+      end
+
+      def action_config_for(core_config, action_name)
+        custom_config = custom_action_config_for(core_config, action_name)
+        return [custom_config, true] if custom_config
+
+        action_config = core_config[action_name] if core_config.actions.include?(action_name.to_sym)
+        [action_config, false]
+      end
+
+      def generator_for(action_name, action_config, custom:)
+        explicit_generator = @action_generators[action_name.to_sym]
+        return explicit_generator if explicit_generator
+
+        if custom
+          matching_rule(
+            @custom_action_rules,
+            submit_method: value_for(action_config, :submit_method)&.to_sym,
+            columns: columns?(action_config),
+            destructive: value_for(action_config, :destructive)
+          )
+        elsif action_config
+          matching_rule(
+            @crud_rules,
+            crud_type: value_for(action_config, :crud_type)&.to_sym,
+            columns: columns?(action_config)
+          )
+        end
+      end
+
+      def matching_rule(rules, **values)
+        rules.select { |rule| rule.matches?(values) }
+             .max_by { |rule| [rule.specificity, rule.position] }
+             &.generator
+      end
+
+      def columns?(action_config)
+        return false unless action_config.respond_to?(:columns)
+
+        columns = action_config.columns
+        !columns.respond_to?(:empty?) || !columns.empty?
+      end
+
+      def value_for(config, name)
+        config.public_send(name) if config.respond_to?(name)
+      end
+
+      def custom_action_names(core_config)
+        custom_actions = value_for(core_config, :custom_actions)
+        return [] unless custom_actions
+
+        if custom_actions.respond_to?(:keys)
+          custom_actions.keys.map(&:to_sym)
+        elsif custom_actions.respond_to?(:names)
+          custom_actions.names.map(&:to_sym)
+        else
+          []
+        end
+      end
+
+      def custom_action_config_for(core_config, action_name)
+        custom_actions = value_for(core_config, :custom_actions)
+        return unless custom_actions&.respond_to?(:[])
+
+        custom_actions[action_name.to_sym] || custom_actions[action_name.to_s]
+      end
+
+      def generate_tool(generator, **arguments)
+        generator.generate_tool_for(**arguments)
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/list_tool.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ActiveScaffold
+  module MCP
+    class ListTool < Tool
+      DEFAULT_LIMIT = 25
+      MAX_LIMIT = 100
+
+      abstract!
+
+      include ActiveScaffold::Actions::List
+
+      def find_page_options
+        super.merge(
+          pagination: true,
+          per_page: limit.to_i.clamp(1, MAX_LIMIT),
+          page: [page.to_i, 1].max
+        )
+      end
+
+      def perform
+        if mcp_argument_provided?(:search)
+          store_search_params_into_session
+          do_search
+        end
+        set_default_sorting if mcp_argument_provided?(:list_view)
+        do_list
+        return if report_disallowed_filters
+
+        columns = mcp_output_columns
+        render(text: JSON.generate(
+          records: @records.map { |record| mcp_record_hash(record, columns) },
+          page: @page.number,
+          total_count: @page.pager.count,
+          total_pages: @page.pager.number_of_pages
+        ))
+      end
+
+      private
+
+      def build_active_scaffold_params
+        super.tap do |active_scaffold_params|
+          if mcp_argument_provided?(:list_view)
+            active_scaffold_params[:config_list_view] = list_view
+          end
+          next unless mcp_argument_provided?(:sort)
+
+          active_scaffold_params[:sort] = sort
+          active_scaffold_params[:sort_direction] = sort_direction.presence || "asc"
+        end
+      end
+
+      def report_disallowed_filters
+        disallowed_filters = Array(@filter_states).filter_map do |name, state|
+          next unless state[:requested] && state[:status] == :disallowed
+
+          selection = (state[:option]&.name || params[name]).to_s
+          ["`#{name}`", "`#{name}=#{selection.inspect}`"]
+        end
+        return false if disallowed_filters.empty?
+
+        filter_names = disallowed_filters.map(&:first)
+        filter_selections = disallowed_filters.map(&:last)
+
+        report_error(
+          "The following requested filter selections could not be applied in this call because they were not allowed " \
+          "for its current arguments and context: #{filter_selections.to_sentence}. No records were returned. " \
+          "Retry the same call with only #{filter_names.to_sentence} omitted and keep all other arguments unchanged. " \
+          "Filter availability is evaluated for each call, so the selection may be allowed with different arguments " \
+          "or context."
+        )
+        true
+      end
+
+      def action_not_allowed_message
+        return super unless params[:config_list_view].present?
+
+        "List view #{params[:config_list_view].inspect} is not allowed for the current user."
+      end
+
+      # MCP tools render their own result and do not participate in HTTP
+      # conditional GET handling. Disabling it also avoids the controller-only
+      # request dependency while ActiveScaffold builds a page.
+      def conditional_get_support?
+        false
+      end
+
+      def tool_authorized?
+        super && list_authorized? && (!mcp_argument_provided?(:search) || search_authorized?)
+      end
+
+      def mcp_default_output_columns
+        list_columns
+      end
+
+      def mcp_configured_output_column_names
+        return if mcp_argument_provided?(:list_view)
+
+        super
+      end
+
+      def controller_name
+        self.class.active_scaffold_controller_class.controller_name
+      end
+
+      def active_scaffold_session_storage_key(id = nil)
+        id ||= params[:eid] || self.class.active_scaffold_controller_class.controller_path
+        "as:#{id}"
+      end
+    end
+  end
+end