mcpable 0.1.0

data/app/controllers/mcpable/rails/tools_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Rails
+    class ToolsController < ActionController::API
+      def create
+        transport = Mcpable::Transports::OfficialMcp.new(
+          registry: Mcpable.registry,
+          runtime: Mcpable.runtime,
+          profile: (params[:profile] || :default).to_sym
+        )
+        context = Mcpable.config.context_builder.call(request.env)
+        response_body = transport.handle(request.body.read, context: context)
+
+        if response_body.nil?
+          head :accepted
+        else
+          render json: response_body
+        end
+      end
+    end
+  end
+end

data/lib/mcpable/active_record/column_inference.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module ActiveRecord
+    module ColumnInference
+      TYPE_MAP = {
+        integer: :integer,
+        bigint: :integer,
+        float: :number,
+        decimal: :number,
+        boolean: :boolean,
+        date: :date,
+        datetime: :datetime,
+        timestamp: :datetime
+      }.freeze
+
+      module_function
+
+      def infer(model, name)
+        return nil unless model.respond_to?(:columns_hash)
+
+        enum = enum_values(model, name)
+        return { type: :string, enum: enum } if enum
+
+        column = model.columns_hash[name.to_s]
+        return nil if column.nil?
+
+        { type: TYPE_MAP.fetch(column.type, :string), enum: nil }
+      end
+
+      def enum_values(model, name)
+        return nil unless model.respond_to?(:defined_enums)
+
+        values = model.defined_enums[name.to_s]
+        values && values.keys
+      end
+
+      def to_proc
+        method(:infer).to_proc
+      end
+    end
+  end
+end

data/lib/mcpable/active_record/source.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module ActiveRecord
+    class Source < Ports::Source
+      DEFAULT_PER_PAGE = 25
+
+      attr_reader :order_whitelist
+
+      def self.supports?(model)
+        model.respond_to?(:all) && model.respond_to?(:arel_table) && model.respond_to?(:columns_hash)
+      end
+
+      def initialize(base, order_whitelist: [])
+        super(base)
+        @order_whitelist = order_whitelist.map(&:to_s)
+      end
+
+      def fetch(filters:, scope: nil, page: nil, per_page: nil, order: nil)
+        relation = apply_scope(resolve_base, scope)
+        relation = apply_filters(relation, filters)
+        relation = apply_order(relation, order)
+
+        total = relation.count
+        page = normalize_page(page)
+        per_page = normalize_per_page(per_page)
+
+        Page.new(
+          records: relation.offset((page - 1) * per_page).limit(per_page).to_a,
+          total: total,
+          page: page,
+          per_page: per_page
+        )
+      end
+
+      def find(id, scope: nil)
+        apply_scope(resolve_base, scope).find_by(id: id)
+      end
+
+      private
+
+      def resolve_base
+        resolved = base.respond_to?(:call) ? base.call : base
+        resolved.respond_to?(:all) ? resolved.all : resolved
+      end
+
+      def apply_scope(relation, scope)
+        scope.nil? ? relation : relation.merge(scope)
+      end
+
+      def apply_filters(relation, filters)
+        (filters || {}).reduce(relation) do |acc, (argument, value)|
+          apply_filter(acc, argument, value)
+        end
+      end
+
+      def apply_filter(relation, argument, value)
+        return relation if value.nil?
+
+        target = (argument.filter_target || argument.name).to_s
+
+        case argument.filter_kind
+        when :eq then relation.where(target => value)
+        when :match then apply_match(relation, target, value)
+        when :range_from then relation.where(arel_column(relation, target).gteq(value))
+        when :range_to then relation.where(arel_column(relation, target).lteq(value))
+        when :scope then value ? relation.public_send(target) : relation
+        else relation
+        end
+      end
+
+      def apply_match(relation, target, value)
+        pattern = "%#{escape_like(relation, value.to_s)}%"
+        relation.where(arel_column(relation, target).matches(pattern, nil, false))
+      end
+
+      def arel_column(relation, target)
+        relation.klass.arel_table[target]
+      end
+
+      def escape_like(relation, value)
+        model = relation.klass
+        model.respond_to?(:sanitize_sql_like) ? model.sanitize_sql_like(value) : value
+      end
+
+      def apply_order(relation, order)
+        return relation if order.nil? || order.to_s.empty?
+
+        raw = order.to_s
+        desc = raw.start_with?("-")
+        column = desc ? raw[1..] : raw
+        return relation unless order_whitelist.include?(column)
+
+        relation.order(column => desc ? :desc : :asc)
+      end
+
+      def normalize_page(page)
+        value = page.to_i
+        value < 1 ? 1 : value
+      end
+
+      def normalize_per_page(per_page)
+        value = per_page.to_i
+        value < 1 ? DEFAULT_PER_PAGE : value
+      end
+    end
+  end
+end

data/lib/mcpable/active_record.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "mcpable"
+require "mcpable/active_record/column_inference"
+require "mcpable/active_record/source"
+
+Mcpable::Dsl::ResourceBuilder.type_inferrer = lambda do |model, name|
+  Mcpable::ActiveRecord::ColumnInference.infer(model, name)
+end
+
+Mcpable::Dsl::ResourceBuilder.source_factory = lambda do |model, order_whitelist:|
+  next nil unless Mcpable::ActiveRecord::Source.supports?(model)
+
+  Mcpable::ActiveRecord::Source.new(model, order_whitelist: order_whitelist)
+end

data/lib/mcpable/argument.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mcpable
+  Argument = Data.define(
+    :name,
+    :type,
+    :required,
+    :description,
+    :enum,
+    :filter
+  ) do
+    def self.build(name, type:, required: false, description: nil, enum: nil, filter: nil)
+      new(
+        name: name.to_sym,
+        type: type.to_sym,
+        required: required,
+        description: description,
+        enum: enum,
+        filter: filter
+      )
+    end
+
+    def filter? = !filter.nil?
+
+    def filter_kind = filter && filter[:kind]
+
+    def filter_target = filter && filter[:target]
+  end
+end

data/lib/mcpable/definition.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mcpable
+  Definition = Data.define(
+    :name,
+    :description,
+    :arguments,
+    :handler,
+    :annotations,
+    :profiles,
+    :metadata
+  ) do
+    def self.build(name:, description: nil, arguments: [], handler: nil, annotations: {},
+                   profiles: [:default], metadata: {})
+      new(
+        name: name.to_s,
+        description: description,
+        arguments: arguments,
+        handler: handler,
+        annotations: annotations,
+        profiles: profiles,
+        metadata: metadata
+      )
+    end
+
+    def read_only? = annotations.fetch(:read_only, true)
+
+    def destructive? = annotations.fetch(:destructive, false)
+
+    def open_world? = annotations.fetch(:open_world, false)
+
+    def profile?(profile) = profiles.include?(profile)
+
+    def argument(name) = arguments.find { |a| a.name == name.to_sym }
+  end
+end

data/lib/mcpable/dsl/resource_builder.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Dsl
+    class ResourceBuilder
+      class << self
+        attr_accessor :type_inferrer, :source_factory
+      end
+
+      DEFAULT_PER_PAGE = 25
+      SUPPORTED_ACTIONS = %i[list show].freeze
+
+      def initialize(target)
+        @target = target
+        @base_name = Naming.underscore(target.name.to_s.split("::").last)
+        @description = nil
+        @attributes = []
+        @conditional_attributes = []
+        @filters = []
+        @source = nil
+        @policy = nil
+        @actions = %i[list show]
+        @order_whitelist = nil
+        @per_page = DEFAULT_PER_PAGE
+        @profiles = [:default]
+        @annotations = { read_only: true }
+      end
+
+      def name(value) = @base_name = Naming.underscore(value.to_s)
+
+      def description(value) = @description = value
+
+      def attributes(*values) = @attributes = values.flatten.map(&:to_sym)
+
+      def attribute(name, **options)
+        condition = options[:if]
+        return @attributes |= [name.to_sym] if condition.nil?
+
+        @conditional_attributes << { name: name.to_sym, condition: condition }
+      end
+
+      def filter(name, type: nil, match: nil, range: false, required: false, description: nil,
+                enum: nil, scope: false)
+        @filters << {
+          name: name.to_sym,
+          type: type,
+          match: match,
+          range: range,
+          required: required,
+          description: description,
+          enum: enum,
+          scope: scope
+        }
+      end
+
+      def source(value) = @source = value
+
+      def order_whitelist(*values) = @order_whitelist = values.flatten.map(&:to_sym)
+
+      def policy(value) = @policy = value
+
+      def actions(*values) = @actions = values.flatten.map(&:to_sym)
+
+      def default_page_size(value) = @per_page = Integer(value)
+
+      def profiles(*values) = @profiles = values.flatten.map(&:to_sym)
+
+      def annotations(**values) = @annotations = @annotations.merge(values)
+
+      def compile
+        validate_actions!
+        validate_conditional_attributes!
+
+        @source ||= build_default_source
+        raise ArgumentError, "#{@target} needs a source" if @source.nil?
+
+        definitions = []
+        definitions << compile_list if @actions.include?(:list)
+        definitions << compile_show if @actions.include?(:show)
+        definitions
+      end
+
+      private
+
+      def validate_conditional_attributes!
+        hidden = @conditional_attributes.map { |a| a[:name] }
+        return if hidden.empty?
+
+        leaked = @filters.map { |f| f[:name] } & hidden
+        return if leaked.empty?
+
+        raise ArgumentError,
+              "#{@target} filters on conditionally visible attributes: #{leaked.join(', ')} " \
+              "(a filter would expose them to callers that cannot read them)"
+      end
+
+      def validate_actions!
+        raise ArgumentError, "#{@target} declares no actions" if @actions.empty?
+
+        unsupported = @actions - SUPPORTED_ACTIONS
+        return if unsupported.empty?
+
+        raise ArgumentError,
+              "#{@target} declares unsupported actions: #{unsupported.join(', ')} " \
+              "(supported: #{SUPPORTED_ACTIONS.join(', ')}; write actions are not implemented yet)"
+      end
+
+      def build_default_source
+        factory = self.class.source_factory
+        factory&.call(@target, order_whitelist: @order_whitelist || @attributes)
+      end
+
+      def list_name = "#{Naming.pluralize(@base_name)}_list"
+
+      def show_name = "#{Naming.pluralize(@base_name)}_show"
+
+      def compile_list
+        arguments = list_arguments
+        attributes = @attributes
+        conditional = @conditional_attributes
+        source_ref = @source
+        per_page = @per_page
+
+        handler = lambda do |ctx|
+          visible = ResourceBuilder.visible_attributes(attributes, conditional, ctx)
+          source = ResourceBuilder.resolve_source(source_ref)
+          filters = arguments.select(&:filter?).to_h { |a| [a, ctx.args[a.name]] }
+          page = source.fetch(
+            filters: filters,
+            scope: ctx.scope,
+            page: ctx.args[:page] || 1,
+            per_page: ctx.args[:per_page] || per_page,
+            order: ctx.args[:order]
+          )
+          Result.ok(
+            records: page.records.map { |r| ResourceBuilder.serialize(r, visible) },
+            total: page.total,
+            page: page.page,
+            per_page: page.per_page
+          )
+        end
+
+        Definition.build(
+          name: list_name,
+          description: @description,
+          arguments: arguments,
+          handler: handler,
+          annotations: @annotations,
+          profiles: @profiles,
+          metadata: {
+            model: @target,
+            action: :list,
+            policy: @policy,
+            per_page: @per_page,
+            paginated: true
+          }
+        )
+      end
+
+      def compile_show
+        attributes = @attributes
+        conditional = @conditional_attributes
+        source_ref = @source
+
+        handler = lambda do |ctx|
+          source = ResourceBuilder.resolve_source(source_ref)
+          record = source.find(ctx.args[:id], scope: ctx.scope)
+          next Result.fail("not found") if record.nil?
+
+          visible = ResourceBuilder.visible_attributes(attributes, conditional, ctx)
+          Result.ok(ResourceBuilder.serialize(record, visible))
+        end
+
+        Definition.build(
+          name: show_name,
+          description: @description,
+          arguments: [Argument.build(:id, type: :integer, required: true, description: "Record id.")],
+          handler: handler,
+          annotations: @annotations,
+          profiles: @profiles,
+          metadata: {
+            model: @target,
+            action: :show,
+            policy: @policy
+          }
+        )
+      end
+
+      def list_arguments
+        @filters.flat_map { |spec| expand_filter(spec) }
+      end
+
+      def expand_filter(spec)
+        type, enum = resolve_type(spec)
+
+        if spec[:range]
+          [
+            build_argument("#{spec[:name]}_from", spec, type, enum, :range_from),
+            build_argument("#{spec[:name]}_to", spec, type, enum, :range_to)
+          ]
+        elsif spec[:scope]
+          [build_argument(spec[:name], spec, type, enum, :scope)]
+        elsif spec[:match] == :partial
+          [build_argument(spec[:name], spec, type, enum, :match)]
+        else
+          [build_argument(spec[:name], spec, type, enum, :eq)]
+        end
+      end
+
+      def build_argument(name, spec, type, enum, kind)
+        Argument.build(
+          name,
+          type: type,
+          required: kind == :eq ? spec[:required] : false,
+          description: spec[:description],
+          enum: enum,
+          filter: { kind: kind, target: spec[:name] }
+        )
+      end
+
+      def resolve_type(spec)
+        return [spec[:type].to_sym, spec[:enum]] if spec[:type]
+
+        inferrer = self.class.type_inferrer
+        inferred = inferrer&.call(@target, spec[:name])
+        raise ArgumentError, "filter :#{spec[:name]} needs type:" if inferred.nil?
+
+        [inferred[:type], spec[:enum] || inferred[:enum]]
+      end
+
+      def self.resolve_source(source_ref)
+        return source_ref if source_ref.respond_to?(:fetch)
+
+        source_ref.respond_to?(:call) ? source_ref.call : source_ref
+      end
+
+      def self.visible_attributes(base, conditional, ctx)
+        return base if conditional.empty?
+
+        base + conditional.select { |a| visible?(a[:condition], ctx) }.map { |a| a[:name] }
+      end
+
+      def self.visible?(condition, ctx)
+        case condition
+        when Symbol then ctx.user.respond_to?(condition) && !!ctx.user.public_send(condition)
+        else condition.arity.zero? ? !!condition.call : !!condition.call(ctx)
+        end
+      end
+
+      def self.serialize(record, attributes)
+        attributes.each_with_object({}) do |attribute, out|
+          out[attribute] = read(record, attribute)
+        end
+      end
+
+      def self.read(record, attribute)
+        return record.public_send(attribute) if record.respond_to?(attribute)
+        return record[attribute] if record.respond_to?(:[])
+
+        nil
+      end
+    end
+  end
+end

data/lib/mcpable/dsl/tool_builder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Dsl
+    class ToolBuilder
+      def initialize(target)
+        @target = target
+        @name = default_name(target)
+        @description = nil
+        @arguments = []
+        @annotations = {}
+        @profiles = [:default]
+        @metadata = {}
+      end
+
+      def name(value) = @name = value.to_s
+
+      def description(value) = @description = value
+
+      def argument(name, type, required: false, description: nil, enum: nil)
+        @arguments << Argument.build(
+          name,
+          type: type,
+          required: required,
+          description: description,
+          enum: enum
+        )
+      end
+
+      def annotations(**values) = @annotations = @annotations.merge(values)
+
+      def profiles(*values) = @profiles = values.flatten.map(&:to_sym)
+
+      def metadata(**values) = @metadata = @metadata.merge(values)
+
+      def compile
+        target = @target
+        argument_names = @arguments.map(&:name)
+
+        handler = lambda do |ctx|
+          call_args = ctx.args.slice(*argument_names)
+          instance = target.new
+          instance.mcp_call = ctx if instance.respond_to?(:mcp_call=)
+          value = instance.call(**call_args)
+          value.is_a?(Result) ? value : Result.ok(value)
+        end
+
+        Definition.build(
+          name: @name,
+          description: @description,
+          arguments: @arguments,
+          handler: handler,
+          annotations: @annotations,
+          profiles: @profiles,
+          metadata: @metadata
+        )
+      end
+
+      private
+
+      def default_name(target)
+        Naming.underscore(target.name.to_s.gsub("::", "_"))
+      end
+    end
+  end
+end

data/lib/mcpable/dsl.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Dsl
+    module_function
+
+    def evaluate(builder, &block)
+      return builder if block.nil?
+
+      if block.arity == 1
+        block.call(builder)
+      else
+        builder.instance_eval(&block)
+      end
+      builder
+    end
+  end
+end

data/lib/mcpable/naming.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Naming
+    module_function
+
+    def underscore(value)
+      value
+        .to_s
+        .gsub("::", "_")
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr("-", "_")
+        .downcase
+    end
+
+    def pluralize(value)
+      word = value.to_s
+      case word
+      when /(?:s|x|z|ch|sh)\z/ then "#{word}es"
+      when /[^aeiou]y\z/ then "#{word[0..-2]}ies"
+      when /f\z/ then "#{word[0..-2]}ves"
+      when /fe\z/ then "#{word[0..-3]}ves"
+      else "#{word}s"
+      end
+    end
+  end
+end

data/lib/mcpable/pipeline.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Mcpable
+  class Pipeline
+    HANDLER = lambda do |ctx|
+      handler = ctx.definition.handler
+      raise Error, "definition #{ctx.definition.name} has no handler" if handler.nil?
+
+      handler.call(ctx)
+    end
+
+    attr_reader :middlewares
+
+    def initialize(config: nil)
+      @middlewares = []
+      @config = config
+    end
+
+    def use(mw, *args)
+      @middlewares << [mw, args]
+      self
+    end
+
+    def clear
+      @middlewares = []
+      self
+    end
+
+    def call(ctx)
+      result = build_stack.call(ctx)
+      result.is_a?(Result) ? result : Result.fail("invalid result")
+    rescue StandardError => e
+      mapped = error_mapper.call(e)
+      mapped.is_a?(Result) ? mapped : Result.fail("invalid result")
+    end
+
+    private
+
+    def error_mapper = (@config || Mcpable.config).error_mapper
+
+    def build_stack
+      @middlewares.reverse.reduce(HANDLER) do |app, (mw, args)|
+        mw.new(app, *args)
+      end
+    end
+  end
+end

data/lib/mcpable/ports/middleware.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Ports
+    class Middleware
+      attr_reader :app
+
+      def initialize(app, *args)
+        @app = app
+        @args = args
+      end
+
+      def call(ctx)
+        @app.call(ctx)
+      end
+    end
+  end
+end