mcpable 0.1.0

data/lib/mcpable/ports/schema_strategy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Ports
+    class SchemaStrategy
+      def input_schema(definition)
+        raise NotImplementedError, "#{self.class}#input_schema"
+      end
+    end
+  end
+end

data/lib/mcpable/ports/source.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Ports
+    class Source
+      Page = Data.define(:records, :total, :page, :per_page)
+
+      attr_reader :base
+
+      def initialize(base)
+        @base = base
+      end
+
+      def fetch(filters:, scope:, page:, per_page:, order:)
+        raise NotImplementedError, "#{self.class}#fetch"
+      end
+
+      def find(id, scope:)
+        raise NotImplementedError, "#{self.class}#find"
+      end
+    end
+  end
+end

data/lib/mcpable/ports/transport.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Ports
+    class Transport
+      attr_reader :registry, :runtime, :profile
+
+      def initialize(registry:, runtime:, profile: :default)
+        @registry = registry
+        @runtime = runtime
+        @profile = profile
+      end
+
+      def list_tools
+        raise NotImplementedError, "#{self.class}#list_tools"
+      end
+
+      def handle(raw_request, context: {})
+        raise NotImplementedError, "#{self.class}#handle"
+      end
+
+      def serve_stdio(context: {})
+        raise NotImplementedError, "#{self.class}#serve_stdio"
+      end
+    end
+  end
+end

data/lib/mcpable/pundit/authorize.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Pundit
+    class Authorize < Ports::Middleware
+      SCOPED_ACTIONS = %i[list show].freeze
+
+      def call(ctx)
+        policy_class = ctx.definition.metadata[:policy] or return @app.call(ctx)
+        record = ctx.definition.metadata[:model]
+        action = ctx.definition.metadata[:action]
+        policy = policy_class.new(ctx.user, record)
+        return Result.deny("not authorized") unless policy.public_send("#{action}?")
+
+        ctx.assigns[:scope] = resolve_scope(policy_class, ctx.user, record) if SCOPED_ACTIONS.include?(action)
+
+        @app.call(ctx)
+      end
+
+      private
+
+      def resolve_scope(policy_class, user, record)
+        scope_class = policy_class.const_defined?(:Scope, false) ? policy_class.const_get(:Scope, false) : nil
+        raise MissingScopeError, policy_class.name unless scope_class
+
+        base = record.respond_to?(:all) ? record.all : record
+        scope_class.new(user, base).resolve
+      end
+    end
+  end
+end

data/lib/mcpable/pundit.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "mcpable"
+require "mcpable/pundit/authorize"

data/lib/mcpable/rails/engine.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+require "mcpable/rails/loader"
+
+module Mcpable
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace Mcpable::Rails
+
+      config.mcpable = ActiveSupport::OrderedOptions.new
+      config.mcpable.eager_load_paths = %w[app/models app/tools]
+
+      initializer "mcpable.routes" do |app|
+        app.routes.append do
+          post "/mcp", to: "mcpable/rails/tools#create", as: :mcpable_root
+        end
+      end
+
+      config.to_prepare do
+        if Mcpable::Rails::Loader.schema_ready?
+          Mcpable::Rails::Loader.reload!
+        else
+          ::Rails.logger&.warn("[mcpable] database schema is not ready; no MCP tools were registered")
+        end
+      end
+    end
+  end
+end

data/lib/mcpable/rails/loader.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Rails
+    module Loader
+      module_function
+
+      def reload!(root: ::Rails.root, relative_paths: nil, autoloaders: ::Rails.autoloaders)
+        Mcpable.registry.reset!
+        resolve_paths(root, relative_paths).each { |path| load_path(path, autoloaders) }
+        Mcpable.registry
+      end
+
+      def schema_ready?
+        return true unless defined?(::ActiveRecord::Base)
+
+        table = ::ActiveRecord::Base.schema_migrations_table_name
+        ::ActiveRecord::Base.connection_pool.with_connection do |connection|
+          connection.data_source_exists?(table)
+        end
+      rescue StandardError
+        false
+      end
+
+      def resolve_paths(root, relative_paths)
+        paths = relative_paths || Engine.config.mcpable.eager_load_paths
+        paths.map { |relative| root.join(relative) }.select(&:exist?)
+      end
+
+      def load_path(path, autoloaders)
+        loader = autoloader_for(path, autoloaders)
+        return loader.eager_load_dir(path.to_s) if loader
+
+        Dir.glob(File.join(path.to_s, "**", "*.rb")).sort.each { |file| require file }
+      end
+
+      def autoloader_for(path, autoloaders)
+        return nil if autoloaders.nil?
+
+        autoloaders.find do |candidate|
+          candidate.respond_to?(:eager_load_dir) && managed?(candidate, path.to_s)
+        end
+      end
+
+      def managed?(loader, path)
+        roots(loader).any? { |root| path == root || path.start_with?("#{root}/") }
+      end
+
+      def roots(loader)
+        return [] unless loader.respond_to?(:dirs)
+
+        dirs = loader.dirs
+        dirs.respond_to?(:keys) ? dirs.keys : Array(dirs)
+      end
+    end
+  end
+end

data/lib/mcpable/rails.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "mcpable"
+require "mcpable/transports/official_mcp"
+require "mcpable/rails/engine"

data/lib/mcpable/registry.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Mcpable
+  class Registry
+    def initialize
+      @definitions = {}
+    end
+
+    def register(definition)
+      name = definition.name.to_s
+      raise DuplicateToolError, name if @definitions.key?(name)
+
+      @definitions[name] = definition
+    end
+
+    def fetch(name)
+      @definitions.fetch(name.to_s) { raise UnknownToolError, name.to_s }
+    end
+
+    def key?(name) = @definitions.key?(name.to_s)
+
+    def for_profile(profile)
+      @definitions.values.select { |d| d.profiles.include?(profile) }
+    end
+
+    def all = @definitions.values
+
+    def names = @definitions.keys
+
+    def reset!
+      @definitions = {}
+      self
+    end
+  end
+end

data/lib/mcpable/resource.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Resource
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      attr_reader :mcp_definitions
+
+      def mcpable(&block)
+        builder = Dsl::ResourceBuilder.new(self)
+        Dsl.evaluate(builder, &block)
+        @mcp_definitions = builder.compile
+        @mcp_definitions.each { |definition| Mcpable.registry.register(definition) }
+        @mcp_definitions
+      end
+    end
+  end
+end

data/lib/mcpable/result.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mcpable
+  Result = Data.define(:status, :payload, :error) do
+    def self.ok(payload) = new(status: :ok, payload: payload, error: nil)
+
+    def self.deny(msg) = new(status: :denied, payload: nil, error: msg)
+
+    def self.fail(msg) = new(status: :error, payload: nil, error: msg)
+
+    def ok? = status == :ok
+
+    def denied? = status == :denied
+
+    def error? = status == :error
+  end
+end

data/lib/mcpable/runtime.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Mcpable
+  class Runtime
+    PAGINATION_TYPES = { page: :integer, per_page: :integer, order: :string }.freeze
+
+    class CoercionError < StandardError; end
+
+    attr_reader :registry, :config
+
+    def initialize(registry: nil, config: nil)
+      @registry = registry
+      @config = config
+    end
+
+    def call_tool(name, args: {}, context: {})
+      definition = current_registry.fetch(name)
+      symbolized = symbolize(args)
+
+      known = allowed_types(definition)
+      unknown = symbolized.keys - known.keys
+      return Result.fail("unknown arguments: #{unknown.join(', ')}") if unknown.any?
+
+      missing = definition.arguments.select(&:required).map(&:name) - symbolized.keys
+      return Result.fail("missing required arguments: #{missing.join(', ')}") if missing.any?
+
+      coerced =
+        begin
+          coerce_all(symbolized, known)
+        rescue CoercionError => e
+          return Result.fail(e.message)
+        end
+
+      ctx = ToolCall.new(definition: definition, args: coerced, context: context)
+      current_config.pipeline.call(ctx)
+    end
+
+    private
+
+    def current_registry = @registry || Mcpable.registry
+
+    def current_config = @config || Mcpable.config
+
+    def symbolize(args)
+      (args || {}).each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+    end
+
+    def allowed_types(definition)
+      types = definition.arguments.to_h { |a| [a.name, a.type] }
+      types = PAGINATION_TYPES.merge(types) if definition.metadata[:paginated]
+      types
+    end
+
+    def coerce_all(args, types)
+      args.each_with_object({}) do |(key, value), out|
+        out[key] = coerce(key, value, types[key])
+      end
+    end
+
+    def coerce(key, value, type)
+      return nil if value.nil?
+
+      case type
+      when :integer then coerce_integer(key, value)
+      when :number then coerce_number(key, value)
+      when :boolean then coerce_boolean(key, value)
+      when :date then coerce_date(key, value)
+      when :datetime then coerce_datetime(key, value)
+      when :string then value.to_s
+      else value
+      end
+    end
+
+    def coerce_integer(key, value)
+      return value if value.is_a?(Integer)
+
+      Integer(value.to_s, 10)
+    rescue ArgumentError, TypeError
+      raise CoercionError, "#{key} is not an integer"
+    end
+
+    def coerce_number(key, value)
+      return value if value.is_a?(Numeric)
+
+      Float(value.to_s)
+    rescue ArgumentError, TypeError
+      raise CoercionError, "#{key} is not a number"
+    end
+
+    def coerce_boolean(key, value)
+      case value
+      when true, false then value
+      when "true", "1", 1 then true
+      when "false", "0", 0 then false
+      else raise CoercionError, "#{key} is not a boolean"
+      end
+    end
+
+    def coerce_date(key, value)
+      return value if value.is_a?(Date) && !value.is_a?(DateTime)
+
+      Date.iso8601(value.to_s)
+    rescue ArgumentError, TypeError
+      raise CoercionError, "#{key} is not an ISO8601 date"
+    end
+
+    def coerce_datetime(key, value)
+      return value if value.is_a?(Time)
+
+      Time.iso8601(value.to_s)
+    rescue ArgumentError, TypeError
+      raise CoercionError, "#{key} is not an ISO8601 datetime"
+    end
+  end
+end

data/lib/mcpable/schema_strategies/explicit_schema.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module SchemaStrategies
+    class ExplicitSchema < Ports::SchemaStrategy
+      JSON_TYPES = {
+        integer: "integer",
+        number: "number",
+        boolean: "boolean",
+        string: "string",
+        date: "string",
+        datetime: "string"
+      }.freeze
+
+      FORMATS = { date: "date", datetime: "date-time" }.freeze
+
+      PAGINATION_PROPERTIES = {
+        page: { type: "integer", description: "Page number, 1-based." },
+        per_page: { type: "integer", description: "Records per page." },
+        order: { type: "string", description: "Sort attribute, prefix with - for descending." }
+      }.freeze
+
+      def input_schema(definition)
+        properties = {}
+        required = []
+
+        definition.arguments.each do |argument|
+          properties[argument.name] = property_for(argument)
+          required << argument.name if argument.required
+        end
+
+        properties = properties.merge(PAGINATION_PROPERTIES) if definition.metadata[:paginated]
+
+        { type: "object", properties: properties, required: required }
+      end
+
+      private
+
+      def property_for(argument)
+        property = { type: JSON_TYPES.fetch(argument.type, "string") }
+        format = FORMATS[argument.type]
+        property[:format] = format if format
+        property[:description] = argument.description if argument.description
+        property[:enum] = argument.enum if argument.enum
+        property
+      end
+    end
+  end
+end

data/lib/mcpable/sources/enumerable_source.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Sources
+    class EnumerableSource < Ports::Source
+      DEFAULT_PER_PAGE = 25
+
+      def fetch(filters:, scope: nil, page: nil, per_page: nil, order: nil)
+        records = apply_scope(resolve_base, scope)
+        records = apply_filters(records, filters)
+        records = apply_order(records, order)
+
+        total = records.size
+        page = normalize_page(page)
+        per_page = normalize_per_page(per_page)
+
+        Page.new(
+          records: records.drop((page - 1) * per_page).take(per_page),
+          total: total,
+          page: page,
+          per_page: per_page
+        )
+      end
+
+      def find(id, scope: nil)
+        records = apply_scope(resolve_base, scope)
+        records.find { |record| read(record, :id).to_s == id.to_s }
+      end
+
+      private
+
+      def resolve_base
+        resolved = base.respond_to?(:call) ? base.call : base
+        resolved.to_a
+      end
+
+      def apply_scope(records, scope)
+        return records if scope.nil?
+        raise Error, "scope must be Enumerable" unless scope.is_a?(Enumerable)
+
+        records & scope.to_a
+      end
+
+      def apply_filters(records, filters)
+        (filters || {}).reduce(records) do |acc, (argument, value)|
+          apply_filter(acc, argument, value)
+        end
+      end
+
+      def apply_filter(records, argument, value)
+        return records if value.nil?
+
+        target = argument.filter_target || argument.name
+
+        case argument.filter_kind
+        when :eq then records.select { |r| read(r, target) == value }
+        when :match then records.select { |r| read(r, target).to_s.downcase.include?(value.to_s.downcase) }
+        when :range_from then records.select { |r| comparable?(read(r, target), value) && read(r, target) >= value }
+        when :range_to then records.select { |r| comparable?(read(r, target), value) && read(r, target) <= value }
+        when :scope then records
+        else records
+        end
+      end
+
+      def comparable?(left, right)
+        !left.nil? && left.respond_to?(:<=>) && !(left <=> right).nil?
+      end
+
+      def apply_order(records, order)
+        return records if order.nil? || order.to_s.empty?
+
+        raw = order.to_s
+        desc = raw.start_with?("-")
+        attribute = desc ? raw[1..] : raw
+        sorted = records.sort_by { |r| read(r, attribute) }
+        desc ? sorted.reverse : sorted
+      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
+
+      def read(record, attribute)
+        name = attribute.to_sym
+        return record.public_send(name) if record.respond_to?(name)
+        return record[name] if record.respond_to?(:[]) && record.respond_to?(:key?) && record.key?(name)
+        return record[name.to_s] if record.respond_to?(:[]) && record.respond_to?(:key?) && record.key?(name.to_s)
+
+        nil
+      end
+    end
+  end
+end

data/lib/mcpable/tool.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mcpable
+  module Tool
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    attr_accessor :mcp_call
+
+    def current_user = mcp_call&.user
+
+    def current_scope = mcp_call&.scope
+
+    def current_context = mcp_call&.context || {}
+
+    module ClassMethods
+      attr_reader :mcp_definition
+
+      def mcp_tool(&block)
+        builder = Dsl::ToolBuilder.new(self)
+        Dsl.evaluate(builder, &block)
+        @mcp_definition = builder.compile
+        Mcpable.registry.register(@mcp_definition)
+        @mcp_definition
+      end
+    end
+  end
+end

data/lib/mcpable/tool_call.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mcpable
+  class ToolCall
+    attr_reader :definition, :args, :context, :assigns
+
+    def initialize(definition:, args:, context:)
+      @definition = definition
+      @args = args
+      @context = context
+      @assigns = {}
+    end
+
+    def user = assigns[:user]
+
+    def scope = assigns[:scope]
+  end
+end