active_scaffold_mcp 0.1.0

data/lib/active_scaffold/mcp/show_tool_generator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    class ShowToolGenerator < ToolGenerator
+      class << self
+        def generate_tool_for(controller_class:, action_name:, action_config:, mcp_config:, settings:)
+          core_config = mcp_config.core
+          primary_key = core_config.model.primary_key
+          raise ArgumentError, "cannot generate a show tool without a primary key" if primary_key.blank?
+          raise ArgumentError, "composite primary keys are not supported by the show tool" if primary_key.is_a?(Array)
+          lookup_columns = Array(settings[:lookup_columns]).map(&:to_sym).uniq - [primary_key.to_sym]
+          validate_lookup_columns!(core_config, lookup_columns)
+
+          Class.new(ActiveScaffold::MCP::ShowTool).tap do |tool_class|
+            configure_tool_class(tool_class, controller_class:, action_name:, core_config:, mcp_config:, settings:)
+            tool_class.mcp_lookup_column_names = lookup_columns.freeze
+            tool_class.mcp_primary_key_name = primary_key.to_sym
+            tool_class.include ActiveScaffold::Actions::List if core_config.actions.include?(:list)
+            tool_class.include ActiveScaffold::Actions::Show
+            tool_class.description(settings[:description] || description(tool_class.title, lookup_columns))
+            tool_class.read_only
+            tool_class.property :id,
+                                **schema_options(core_config._columns_hash[primary_key.to_s]),
+                                description: "Database ID of the #{singular_label(mcp_config)} to return",
+                                required: lookup_columns.empty?
+            mappings = {id: {target: :id, operator: :equal}}
+            lookup_columns.each do |column_name|
+              tool_class.property column_name,
+                                  **schema_options(core_config._columns_hash[column_name.to_s]),
+                                  description: "#{column_name.to_s.humanize} of the #{singular_label(mcp_config)} to return"
+              mappings[column_name] = {target: column_name, operator: :equal}
+            end
+            tool_class.mcp_param_mappings = mappings.freeze
+
+            include_extensions(tool_class, settings)
+          end
+        end
+
+        private
+
+        def validate_lookup_columns!(core_config, lookup_columns)
+          unknown_columns = lookup_columns.reject { |name| core_config._columns_hash.key?(name.to_s) }
+          return if unknown_columns.empty?
+
+          raise ArgumentError, "unknown show lookup columns: #{unknown_columns.to_sentence}"
+        end
+
+        def tool_resource_name(mcp_config)
+          super.singularize
+        end
+
+        def tool_resource_label(mcp_config, settings)
+          super.singularize
+        end
+
+        def description(generated_title, lookup_columns)
+          identifiers = ["id", *lookup_columns.map(&:to_s)]
+          human_identifiers = identifiers.map { |name| name.humanize.downcase }
+          arguments = identifiers.map { |name| "`#{name}`" }
+          resource_label = generated_title.delete_prefix("Show ").singularize
+          "Retrieve one #{resource_label} by #{human_identifiers.to_sentence(two_words_connector: ' or ', last_word_connector: ' or ')}. " \
+            "Use this tool when the user supplies one of these identifiers. " \
+            "Pass exactly one of #{arguments.to_sentence(two_words_connector: ' or ', last_word_connector: ' or ')}."
+        end
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/tool.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    class Tool < ActiveScaffold::Config::MCP.resolve_tool(:base)
+      abstract!
+
+      class_attribute :active_scaffold_config, instance_accessor: false
+      class_attribute :active_scaffold_controller_class, instance_accessor: false
+      class_attribute :mcp_action_name, instance_accessor: false
+      class_attribute :mcp_output_column_names, instance_accessor: false
+      class_attribute :mcp_param_mappings, instance_accessor: false, default: {}
+      class_attribute :mcp_presenter_class, instance_accessor: false, default: ActiveScaffold::MCP::Presenter
+
+      class << self
+        def parameter_filter
+          filters = Rails.application&.config&.filter_parameters || []
+          return @parameter_filter if @parameter_filter_filters == filters
+
+          @parameter_filter_filters = filters.dup.freeze
+          @parameter_filter = ActiveSupport::ParameterFilter.new(filters)
+        end
+
+        def tool_authorized?(user = ActionMCP::Current.user)
+          return true unless respond_to?(:active_scaffold_tool_authorized?)
+
+          active_scaffold_tool_authorized?(
+            controller_class: active_scaffold_controller_class,
+            action_name: mcp_action_name,
+            user: user
+          )
+        end
+
+        # ActiveScaffold action modules declare Rails controller callbacks and
+        # helpers when included. MCP tools invoke their operation methods
+        # directly, so these declarations intentionally do nothing.
+        def before_action(...); end
+        def prepend_before_action(...); end
+        def after_action(...); end
+        def around_action(...); end
+        def helper_method(...); end
+        def rescue_from(...); end
+      end
+
+      include ActiveScaffold::Finder
+      include ActiveScaffold::Constraints
+      include ActiveScaffold::Actions::Core
+
+      around_perform :with_active_scaffold_context
+
+      def initialize(attributes = {})
+        @provided_mcp_arguments = attributes.respond_to?(:keys) ? attributes.keys.map(&:to_s) : []
+        super
+      end
+
+      def active_scaffold_config
+        @active_scaffold_config ||= begin
+          config = self.class.active_scaffold_config
+          config.new_user_settings({}, params)
+          config.user
+        end
+      end
+
+      def params
+        @params ||= ::ActionController::Parameters.new(build_active_scaffold_params)
+      end
+
+      def flash
+        @flash ||= ActiveScaffold::MCP::Flash.new
+      end
+
+      def action_name
+        self.class.mcp_action_name.to_s
+      end
+
+      def active_scaffold_session_storage(_id = nil)
+        @active_scaffold_session_storage ||= ActiveSupport::HashWithIndifferentAccess.new
+      end
+
+      def mcp_presenter
+        @mcp_presenter ||= self.class.mcp_presenter_class.new(self)
+      end
+
+      private
+
+      def with_active_scaffold_context
+        previous_user_proc = ActiveScaffold::Registry.current_user_proc
+        ActiveScaffold::Registry.current_user_proc = -> { current_user }
+        if tool_authorized?
+          yield
+        else
+          unauthorized_tool!
+        end
+      rescue ActiveScaffold::ActionNotAllowed
+        report_error(action_not_allowed_message)
+      rescue StandardError => exception
+        report_active_scaffold_exception(exception)
+        raise
+      ensure
+        ActiveScaffold::Registry.current_user_proc = previous_user_proc
+      end
+
+      def report_active_scaffold_exception(exception)
+        arguments = mcp_exception_arguments
+        Rails.logger.error(
+          "[ActiveScaffold::MCP] #{self.class.tool_name} failed with arguments #{arguments.inspect}: " \
+          "#{exception.full_message(highlight: false, order: :top)}"
+        )
+        notify_active_scaffold_exception(exception) if respond_to?(:notify_active_scaffold_exception, true)
+      rescue StandardError => notification_exception
+        Rails.logger.error(
+          "[ActiveScaffold::MCP] exception notification failed for #{self.class.tool_name}: " \
+          "#{notification_exception.full_message(highlight: false, order: :top)}"
+        )
+      end
+
+      def action_not_allowed_message
+        "The requested #{action_name.humanize.downcase} action is not allowed for the current user or request context."
+      end
+
+      def mcp_exception_arguments
+        arguments = if defined?(@_wire_arguments)
+                      @_wire_arguments
+                    else
+                      attributes.compact.merge(@_provided_additional_attributes)
+                    end
+        ActiveScaffold::MCP::Tool.parameter_filter.filter(arguments.deep_dup)
+      end
+
+      # Let the configured base tool customize execution authorization failures.
+      # Its implementation replaces this fallback and is responsible for
+      # reporting the failure, normally by raising an application-specific error.
+      def unauthorized_tool!
+        return super if defined?(super)
+
+        raise ActiveScaffold::ActionNotAllowed
+      end
+
+      def tool_authorized?
+        self.class.tool_authorized?(current_user)
+      end
+
+      def build_active_scaffold_params
+        filter_values = {}
+        ranges = Hash.new { |hash, key| hash[key] = {} }
+
+        self.class.mcp_param_mappings.each do |property_name, mapping|
+          next unless @provided_mcp_arguments.include?(property_name.to_s)
+
+          value = public_send(property_name)
+          target = mapping.fetch(:target).to_s
+          case mapping.fetch(:operator)
+          when :equal, :in
+            filter_values[target] = value
+          when :not_equal, :not_in
+            filter_values["#{target}!"] = value
+          when :between_from, :between_to, :not_between_from, :not_between_to
+            ranges[[target, mapping[:operator].to_s.start_with?("not_")]][mapping[:operator].to_s.end_with?("from") ? :from : :to] = value
+          when :null
+            filter_values[target] = "" if value
+          when :not_null
+            filter_values["#{target}!"] = "" if value
+          end
+        end
+
+        ranges.each do |(target, negated), endpoints|
+          filter_values["#{target}#{'!' if negated}"] = "#{endpoints[:from]}..#{endpoints[:to]}"
+        end
+
+        filter_values.merge(format: "json")
+      end
+
+      def mcp_output_columns
+        configured_columns = mcp_configured_output_column_names
+        columns = if configured_columns
+                    configured_columns.filter_map do |column_name|
+                      next unless active_scaffold_config.model.authorized_for?(crud_type: :read, column: column_name)
+
+                      active_scaffold_config.columns[column_name]
+                    end
+                  else
+                    mcp_default_output_columns
+                  end
+
+        (mcp_primary_key_columns + columns).uniq(&:name).select do |column|
+          mcp_presenter.presentable_column?(column)
+        end
+      end
+
+      def mcp_configured_output_column_names
+        self.class.mcp_output_column_names
+      end
+
+      def mcp_record_hash(record, columns)
+        columns = columns.select do |column|
+          record.authorized_for?(crud_type: :read, column: column.name)
+        end
+        mcp_presenter.record(record, columns, association_counts_for(record, columns))
+      end
+
+      def mcp_primary_key_columns
+        Array(active_scaffold_config.model.primary_key).filter_map do |column_name|
+          next unless active_scaffold_config.model.authorized_for?(crud_type: :read, column: column_name)
+
+          active_scaffold_config.columns[column_name]
+        end
+      end
+
+      def association_counts_for(record, columns)
+        columns.each_with_object({}) do |column, result|
+          cached_counts = @counts&.dig(column.name)
+          next unless cached_counts
+
+          key = column.association.primary_key if count_on_association_class?(column)
+          result[column.name] = cached_counts[record.public_send(key || :id)] || 0
+        end
+      end
+
+      def mcp_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 mcp_default_output_columns
+        raise NotImplementedError
+      end
+
+      def mcp_argument_provided?(name)
+        @provided_mcp_arguments.include?(name.to_s)
+      end
+
+      # The controller implementation branches on request methods and renders
+      # an HTTP response. MCP operations already represent the submitted branch.
+      def process_action_link_action(_render_action = :action_update, crud_type_or_security_options = nil)
+        @action_link = active_scaffold_config.action_links[action_name]
+        if params[:id]
+          security_options = crud_type_or_security_options || {crud_type: :update, action: action_name.to_sym}
+          get_row(security_options)
+          if @record
+            yield @record
+          else
+            self.successful = false
+            flash[:error] = "Record is not available for #{action_name}"
+          end
+        else
+          raise ActiveScaffold::ActionNotAllowed unless action_link_authorized?(@action_link)
+
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/tool_generator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    class ToolGenerator
+      class << self
+        private
+
+        def configure_tool_class(tool_class, controller_class:, action_name:, core_config:, mcp_config:, settings:)
+          tool_class.active_scaffold_config = core_config
+          # Finder is included by the base MCP tool before a controller's
+          # ActiveScaffold config is known. Re-extending its class methods now
+          # lets Finder select the configured persistence adapter (and provide
+          # adapter-specific helpers such as like_pattern).
+          tool_class.extend ActiveScaffold::Finder::ClassMethods
+          tool_class.active_scaffold_controller_class = controller_class
+          tool_class.mcp_action_name = action_name
+          tool_class.mcp_output_column_names = settings[:columns]&.map(&:to_sym)
+          tool_class.mcp_presenter_class = build_presenter_class(settings)
+          tool_class.tool_name(settings[:name] || default_tool_name(action_name, mcp_config))
+          tool_class.title("#{action_name.to_s.humanize} #{tool_resource_label(mcp_config, settings)}")
+        end
+
+        def default_tool_name(action_name, mcp_config)
+          "#{action_name}_#{tool_resource_name(mcp_config)}"
+        end
+
+        def tool_resource_name(mcp_config)
+          mcp_config.name
+        end
+
+        def tool_resource_label(mcp_config, settings)
+          settings[:label] || mcp_config.label
+        end
+
+        def include_extensions(tool_class, settings)
+          Array(settings[:modules]).each { |extension| tool_class.include extension }
+        end
+
+        def build_presenter_class(settings)
+          presenter_class = settings[:presenter] || ActiveScaffold::MCP::Presenter
+          presenter_modules = Array(settings[:presenter_modules])
+          return presenter_class if presenter_modules.empty?
+
+          Class.new(presenter_class).tap do |configured_class|
+            presenter_modules.each { |extension| configured_class.include extension }
+          end
+        end
+
+        def singular_label(mcp_config)
+          mcp_config.label.to_s.singularize
+        end
+
+        def schema_options(column)
+          options = {type: json_type(column)}
+          format = json_format(column)
+          options[:format] = format if format
+          options
+        end
+
+        def json_type(column)
+          case column&.type&.to_sym
+          when :integer, :bigint
+            "integer"
+          when :float, :decimal
+            "number"
+          when :boolean
+            "boolean"
+          else
+            "string"
+          end
+        end
+
+        def json_format(column)
+          case column&.type&.to_sym
+          when :date
+            "date"
+          when :datetime, :timestamp, :timestamptz
+            "date-time"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_scaffold/mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module MCP
+    VERSION = "0.1.0"
+  end
+end

data/lib/active_scaffold/mcp.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "active_scaffold/mcp/filtered_tools"
+require "set"
+
+module ActiveScaffold
+  module Actions
+    autoload :MCP, "active_scaffold/actions/mcp"
+  end
+
+  module Config
+    autoload :MCP, "active_scaffold/config/mcp"
+  end
+
+  module MCP
+    autoload :ActionConfig, "active_scaffold/mcp/action_config"
+    autoload :Flash, "active_scaffold/mcp/flash"
+    autoload :GeneratorFactory, "active_scaffold/mcp/generator_factory"
+    autoload :ListToolGenerator, "active_scaffold/mcp/list_tool_generator"
+    autoload :Presenter, "active_scaffold/mcp/presenter"
+    autoload :ProfileUser, "active_scaffold/mcp/profile_user"
+    autoload :SettingsValidator, "active_scaffold/mcp/settings_validator"
+    autoload :Tool, "active_scaffold/mcp/tool"
+    autoload :ToolGenerator, "active_scaffold/mcp/tool_generator"
+    autoload :ListTool, "active_scaffold/mcp/list_tool"
+    autoload :ShowTool, "active_scaffold/mcp/show_tool"
+    autoload :ListViewsTool, "active_scaffold/mcp/list_views_tool"
+    autoload :ShowToolGenerator, "active_scaffold/mcp/show_tool_generator"
+    autoload :VERSION, "active_scaffold/mcp/version"
+
+    class << self
+      def generated_controller_names
+        @generated_controller_names ||= Set.new
+      end
+
+      def generated_tool_classes
+        @generated_tool_classes ||= Set.new
+      end
+
+      def generate_tools_for(controller_class, action_config)
+        generator = ActiveScaffold::Config::MCP.tool_generator
+        return [] unless generator
+
+        generated_controller_names << controller_class.name if controller_class.name.present?
+        generator.generate_tools_for(controller_class, action_config).tap do |tools|
+          generated_tool_classes.merge(Array(tools).compact)
+        end
+      end
+
+      def reload_generated_tools!
+        controller_classes = generated_controller_names.filter_map(&:safe_constantize)
+        stale_tool_classes = generated_tool_classes.dup
+        ActionMCP::ToolsRegistry.items.delete_if { |_name, tool_class| stale_tool_classes.include?(tool_class) }
+        generated_tool_classes.clear
+        controller_classes.each do |controller_class|
+          generate_tools_for(controller_class, controller_class.active_scaffold_config.mcp)
+        end
+      end
+    end
+  end
+end

data/lib/active_scaffold_mcp.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "action_mcp"
+require "active_scaffold"
+require "active_scaffold/extensions/localize"
+
+require "active_scaffold/mcp"
+require "active_scaffold/mcp/engine"

data/lib/tasks/active_scaffold_mcp_tasks.rake

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+namespace :action_mcp do
+  task load_profile_user: :environment do
+    next if ENV["MCP_USER"].blank?
+
+    ActionMCP::Current.user = ActiveScaffold::MCP::ProfileUser.resolve(ENV.fetch("MCP_USER"))
+  end
+
+  task show_profile: :load_profile_user
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: active_scaffold_mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sergio Cambra
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionmcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.200'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.200'
+- !ruby/object:Gem::Dependency
+  name: active_scaffold
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.3'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+description: An ActionMCP integration that generates MCP tools from ActiveScaffold
+  configuration.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/active_scaffold/actions/mcp.rb
+- lib/active_scaffold/config/mcp.rb
+- lib/active_scaffold/mcp.rb
+- lib/active_scaffold/mcp/action_config.rb
+- lib/active_scaffold/mcp/engine.rb
+- lib/active_scaffold/mcp/filtered_tools.rb
+- lib/active_scaffold/mcp/flash.rb
+- lib/active_scaffold/mcp/generator_factory.rb
+- lib/active_scaffold/mcp/list_tool.rb
+- lib/active_scaffold/mcp/list_tool_generator.rb
+- lib/active_scaffold/mcp/list_views_tool.rb
+- lib/active_scaffold/mcp/presenter.rb
+- lib/active_scaffold/mcp/profile_user.rb
+- lib/active_scaffold/mcp/settings_validator.rb
+- lib/active_scaffold/mcp/show_tool.rb
+- lib/active_scaffold/mcp/show_tool_generator.rb
+- lib/active_scaffold/mcp/tool.rb
+- lib/active_scaffold/mcp/tool_generator.rb
+- lib/active_scaffold/mcp/version.rb
+- lib/active_scaffold_mcp.rb
+- lib/tasks/active_scaffold_mcp_tasks.rake
+homepage: https://github.com/activescaffold/active_scaffold_mcp
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Expose ActiveScaffold actions as MCP tools
+test_files: []