mcp_toolkit 0.3.0

data/lib/mcp_toolkit/field_selection.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# A parsed, validated sparse-fieldset request (JSON:API's `fields[type]`) for a
+# single resource. Requested names share ONE flat namespace covering both declared
+# ATTRIBUTES and relationship link keys — exactly as JSON:API conflates them.
+#
+# Built by the List/Get executors from the tool's `fields` argument. A nil
+# selection (blank/absent `fields`) means "all fields": the executors skip it
+# entirely and serialize as before, so the default path is completely untouched.
+#
+# A present selection is applied one of two ways, decided by McpToolkit::Serialization:
+#   * NATIVELY — `names` is passed to a serializer whose `serialize_one` /
+#     `serialize_collection` declares a `fields:` keyword (the gem's Base does),
+#     so unselected attributes and relationships are never computed at all.
+#   * By PRUNING the fully-serialized hash (`prune_record` / `prune_collection`)
+#     for an injected serializer that predates the `fields:` kwarg — a pure
+#     shape-level filter, so ANY contract-satisfying serializer stays sparse-able.
+class McpToolkit::FieldSelection
+  LINKS_KEY = "links"
+
+  # Parse the raw tool argument (a comma-separated string OR an array of names)
+  # into a selection, or nil when nothing was requested. Validates the requested
+  # names against the resource's known members when the resource can describe them
+  # (the Base serializer exposes `declared_attributes`); an unknown name is a
+  # clean InvalidParams so a typo is actionable rather than silently dropped.
+  def self.build(resource:, raw:)
+    names = parse(raw)
+    return nil if names.empty?
+
+    new(resource:, names:).tap(&:validate!)
+  end
+
+  # Normalizes a CSV string or an array into a de-duplicated list of symbols.
+  def self.parse(raw)
+    list = raw.is_a?(Array) ? raw : raw.to_s.split(",")
+    list.map { |name| name.to_s.strip }.reject(&:empty?).map(&:to_sym).uniq
+  end
+
+  # The validated requested field names (symbols), passed to a fields-aware
+  # serializer as its `fields:` argument.
+  attr_reader :names
+
+  def initialize(resource:, names:)
+    @resource = resource
+    @names = names
+  end
+
+  # Raises InvalidParams if any requested name is neither a declared attribute nor
+  # a relationship link key. Skipped for serializers that can't describe their
+  # members (resource_schema degrades the same way) — those are pruned leniently.
+  def validate!
+    return unless @resource.serializer.respond_to?(:declared_attributes)
+
+    unknown = @names - known_members
+    return if unknown.empty?
+
+    selectable = known_members.map(&:to_s).sort.join(", ").presence || "(none)"
+    raise McpToolkit::Errors::InvalidParams,
+          "unknown field(s): #{unknown.join(", ")}. Selectable fields for this resource: #{selectable}"
+  end
+
+  # Prune a single serialized record hash down to the requested members.
+  # Shape-driven (needs no serializer metadata): every key is an attribute except
+  # the string `"links"` block, which is itself narrowed to the requested link
+  # keys and dropped entirely when nothing under it was requested.
+  def prune_record(hash)
+    requested = @names.map(&:to_s)
+    hash.each_with_object({}) do |(key, value), pruned|
+      if key.to_s == LINKS_KEY
+        links = (value || {}).select { |link_key, _| requested.include?(link_key.to_s) }
+        pruned[LINKS_KEY] = links unless links.empty?
+      elsif requested.include?(key.to_s)
+        pruned[key] = value
+      end
+    end
+  end
+
+  # Prune the collection wrapper: each array value holds the rows (prune each);
+  # the `meta` hash and any other non-array entry pass through untouched.
+  def prune_collection(wrapper)
+    wrapper.transform_values do |value|
+      value.is_a?(Array) ? value.map { |row| prune_record(row) } : value
+    end
+  end
+
+  private
+
+  def known_members
+    @known_members ||=
+      @resource.attribute_names.map(&:to_sym) +
+      @resource.association_descriptors.map { |assoc| assoc.links_key.to_sym }
+  end
+end

data/lib/mcp_toolkit/filtering.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# Applies the `list` tool's `filter` params to an already-scoped relation, with
+# the following semantics:
+#
+#   * a BARE value filters by equality:               filter: { booking_id: 42 }
+#     (a comma-separated string becomes an IN lookup:  filter: { status: "a,b" })
+#   * an { op:, value: } HASH filters with an operator: filter: { price: { op: "gteq", value: 100 } }
+#   * an ARRAY of those hashes ANDs them (ranges):
+#       filter: { price: [{ op: "gteq", value: 100 }, { op: "lt", value: 200 }] }
+#
+# Supported operators (validated against the column's DB type):
+#   eq, not_eq, gt, gteq, lt, lteq        — numeric / datetime columns
+#   eq, not_eq, in, matches, does_not_match — string columns (matches => case-insensitive LIKE)
+#   eq, not_eq                            — boolean columns
+#
+# Allowlist-safe: only the resource's declared `filterable` keys may be filtered,
+# each resolved to its backing column. Unknown keys are rejected upstream by the
+# ListExecutor, and an operator unsupported for a column's type raises
+# InvalidParams — there is no arbitrary column or SQL injection surface.
+module McpToolkit::Filtering
+  OPERATORS_BY_TYPE = {
+    integer: %w[eq not_eq gt gteq lt lteq].freeze,
+    float: %w[eq not_eq gt gteq lt lteq].freeze,
+    decimal: %w[eq not_eq gt gteq lt lteq].freeze,
+    datetime: %w[eq not_eq gt gteq lt lteq].freeze,
+    date: %w[eq not_eq gt gteq lt lteq].freeze,
+    string: %w[eq not_eq in matches does_not_match].freeze,
+    text: %w[eq not_eq in matches does_not_match].freeze,
+    boolean: %w[eq not_eq].freeze
+  }.freeze
+
+  # Operators that map straight onto an Arel predication method.
+  AREL_PREDICATIONS = %w[eq not_eq gt gteq lt lteq in matches does_not_match].freeze
+
+  NULL_TOKEN = "null"
+
+  # @param relation the already account-scoped relation
+  # @param column [Symbol] the backing DB column (already resolved from the allowlist)
+  # @param value the filter value: a bare value, an { op:, value: } hash, or an
+  #   array of such hashes
+  # @param config [McpToolkit::Configuration] supplies the SQL sanitizer used to
+  #   escape LIKE wildcards
+  # @return the relation with the filter(s) applied
+  def self.apply(relation, column, value, config: McpToolkit.config)
+    if compound?(value)
+      apply_condition(relation, column, value, config:)
+    elsif collection?(value)
+      value.inject(relation) { |rel, condition| apply_condition(rel, column, condition, config:) }
+    else
+      # Bare value: equality. A comma-separated string becomes an IN lookup,
+      # matching the implicit `eq` semantics.
+      relation.where(column => equality_value(value))
+    end
+  end
+
+  # A single operator-based condition, e.g. { op: "gt", value: 1000 }.
+  def self.compound?(value)
+    condition_hash?(value) && (value.key?(:op) || value.key?("op"))
+  end
+
+  # Several operator-based conditions on one attribute, ANDed (ranges).
+  def self.collection?(value)
+    value.is_a?(Array) && value.any? && value.all? { |element| compound?(element) }
+  end
+
+  def self.condition_hash?(value)
+    value.is_a?(Hash)
+  end
+
+  def self.apply_condition(relation, column, condition, config:)
+    operator = fetch(condition, :op).to_s
+    raise McpToolkit::Errors::InvalidParams, "a filter operator is required" if operator.empty?
+
+    type = column_type(relation, column)
+    validate_operator!(operator, type, column)
+
+    raw = fetch(condition, :value)
+    relation.where(predicate_for(relation, column, operator, raw, config:))
+  end
+
+  # Reads a key regardless of symbol/string keys; checks presence (not
+  # truthiness) so a literal `false` / `nil` value survives.
+  def self.fetch(condition, key)
+    return condition[key] if condition.key?(key)
+
+    condition[key.to_s] if condition.key?(key.to_s)
+  end
+
+  def self.column_type(relation, column)
+    model = relation.respond_to?(:model) ? relation.model : nil
+    return nil unless model.respond_to?(:columns_hash)
+
+    model.columns_hash[column.to_s]&.type
+  end
+
+  def self.validate_operator!(operator, type, column)
+    allowed = OPERATORS_BY_TYPE[type]
+    if allowed.nil?
+      raise McpToolkit::Errors::InvalidParams,
+            "'#{column}' cannot be filtered with operators"
+    end
+    return if allowed.include?(operator)
+
+    raise McpToolkit::Errors::InvalidParams,
+          "'#{operator}' operator is not supported for #{column} (#{type}). " \
+          "Supported operators: #{allowed.join(", ")}."
+  end
+
+  # Builds the predicate to hand to `relation.where`. For a real ActiveRecord
+  # relation we build an Arel node (so it composes with the scope safely and is
+  # immune to SQL injection); a relation without an `arel_table` (the in-memory
+  # test fake) receives a portable Predicate value object it knows how to apply.
+  def self.predicate_for(relation, column, operator, raw, config:)
+    value = normalize_value(operator, raw, config:)
+    arel_operator = operator == "eq" ? "in" : operator
+
+    model = relation.respond_to?(:model) ? relation.model : nil
+    if model.respond_to?(:arel_table)
+      model.arel_table[column.to_sym].public_send(arel_operator, value)
+    else
+      Predicate.new(column.to_sym, arel_operator, value)
+    end
+  end
+
+  # `eq` against a (possibly comma-separated) value becomes an IN set. `matches`
+  # / `does_not_match` wrap the value in `%...%` with LIKE wildcards escaped so
+  # they match literally. `null` => nil for every operator.
+  def self.normalize_value(operator, raw, config:)
+    return nil if raw.to_s == NULL_TOKEN
+
+    case operator
+    when "eq", "in"
+      raw.to_s.split(",")
+    when "matches", "does_not_match"
+      "%#{config.sql_sanitizer.sanitize_sql_like(raw.to_s)}%"
+    else
+      raw
+    end
+  end
+
+  def self.equality_value(value)
+    return nil if value.to_s == NULL_TOKEN
+
+    str = value.to_s
+    str.include?(",") ? str.split(",") : value
+  end
+
+  # Portable representation of an operator predicate, applied by the in-memory
+  # test relation. Production uses Arel nodes instead (see .predicate_for).
+  Predicate = Struct.new(:column, :operator, :value)
+end

data/lib/mcp_toolkit/get_executor.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Runs a read-only "show" query for a registered resource by id, rooted on the
+# scoped relation so cross-scope ids are simply not found. Serializes via the
+# resource's serializer.
+class McpToolkit::GetExecutor
+  def self.call(resource:, scope_root:, id:, fields: nil)
+    new(resource:, scope_root:, id:, fields:).call
+  end
+
+  def initialize(resource:, scope_root:, id:, fields: nil)
+    @resource = resource
+    @scope_root = scope_root
+    @id = id
+    @fields = fields
+  end
+
+  def call
+    raise McpToolkit::Errors::InvalidParams, "id is required" if id.blank?
+
+    # Validate the sparse fieldset BEFORE the lookup so a bad `fields` fails fast.
+    selection = McpToolkit::FieldSelection.build(resource:, raw: fields)
+    record = resource.resolve_relation(scope_root).find_by(id:)
+    raise McpToolkit::Errors::InvalidParams, "#{resource.name} not found for id=#{id}" unless record
+
+    McpToolkit::Serialization.new(resource.serializer, selection).one(record, scope: scope_root)
+  end
+
+  private
+
+  attr_reader :resource, :scope_root, :id, :fields
+end

data/lib/mcp_toolkit/list_executor.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# Runs a read-only, paginated "list" query for a registered resource, rooted on
+# the scoped relation. Supports the standard `ids`, `updated_since`, `limit`,
+# `offset` filters plus the resource's declared per-attribute filters (equality
+# AND operator-based — see McpToolkit::Filtering), and serializes via the
+# resource's serializer, producing the `{ <root> => [...], meta: {...} }` wrapper.
+# An optional `fields` param applies a sparse fieldset to each row (see
+# McpToolkit::FieldSelection).
+class McpToolkit::ListExecutor
+  DEFAULT_LIMIT = 25
+  MAX_LIMIT = 100
+  # Column types whose primary key sorts naturally by `id`. Anything else (e.g. a
+  # string/uuid PK) sorts by `created_at` instead.
+  NUMERIC_PK_TYPES = %i[integer bigint].freeze
+
+  def self.call(resource:, scope_root:, params:)
+    new(resource:, scope_root:, params:).call
+  end
+
+  def initialize(resource:, scope_root:, params:)
+    @resource = resource
+    @scope_root = scope_root
+    @params = (params || {}).deep_symbolize_keys
+  end
+
+  def call
+    # Validate the sparse fieldset BEFORE running the query so a bad `fields`
+    # fails fast rather than after a needless count + fetch.
+    selection = McpToolkit::FieldSelection.build(resource:, raw: params[:fields])
+    relation = build_relation
+    total_count = relation.count
+    rows = paginate(relation).to_a
+
+    McpToolkit::Serialization.new(resource.serializer, selection).collection(
+      rows, scope: scope_root, total_count:, limit:, offset:
+    )
+  end
+
+  private
+
+  attr_reader :resource, :scope_root, :params
+
+  def build_relation
+    relation = resource.resolve_relation(scope_root)
+    relation = apply_ids(relation)
+    relation = apply_updated_since(relation)
+    relation = apply_attribute_filters(relation)
+    apply_order(relation)
+  end
+
+  # Order by `id` when the primary key is numeric; otherwise by `created_at`
+  # (a non-numeric PK does not sort meaningfully).
+  def apply_order(relation)
+    relation.order(numeric_primary_key? ? :id : :created_at)
+  end
+
+  def numeric_primary_key?
+    model = resource.model
+    return true unless model.respond_to?(:columns_hash) && model.respond_to?(:primary_key)
+
+    pk = model.primary_key
+    return true if pk.nil?
+
+    type = model.columns_hash[pk.to_s]&.type
+    type.nil? || NUMERIC_PK_TYPES.include?(type)
+  end
+
+  # Applies per-attribute filters (`filter: { key: value | { op:, value: } | [...] }`).
+  # Each request-facing key is resolved against the resource's declared allowlist
+  # (`Resource#filterable`) to its backing column, then added as WHERE clause(s) on
+  # TOP of the already scoped relation — filtering composes with scoping and can
+  # only ever NARROW it, never widen it. Equality and operator-based semantics are
+  # delegated to McpToolkit::Filtering.
+  #
+  # Unknown filter keys are rejected with InvalidParams, so the caller gets
+  # actionable feedback instead of a silently-ignored filter.
+  def apply_attribute_filters(relation)
+    filter = params[:filter]
+    return relation if filter.blank?
+
+    mapping = resource.filterable_columns
+    validate_filter_keys!(filter, mapping)
+
+    filter.each do |request_key, value|
+      next if value.nil? || value == ""
+
+      column = mapping[request_key.to_sym]
+      relation = McpToolkit::Filtering.apply(relation, column, value)
+    end
+    relation
+  end
+
+  def validate_filter_keys!(filter, mapping)
+    keys = filter.keys.map(&:to_sym)
+    unknown = keys - mapping.keys
+    return if unknown.empty?
+
+    allowed = mapping.keys.sort.join(", ")
+    raise McpToolkit::Errors::InvalidParams,
+          "unknown filter attribute(s): #{unknown.join(", ")}. " \
+          "Filterable attributes for this resource: #{allowed.presence || "(none)"}"
+  end
+
+  def apply_ids(relation)
+    return relation if params[:ids].blank?
+
+    ids = params[:ids].to_s.split(",").map(&:strip).compact_blank
+    ids.empty? ? relation : relation.where(id: ids)
+  end
+
+  def apply_updated_since(relation)
+    return relation if params[:updated_since].blank?
+
+    time = parse_time(params[:updated_since])
+    relation.where("#{relation.table_name}.updated_at > ?", time)
+  end
+
+  def parse_time(value)
+    Time.zone.parse(value.to_s) || raise(ArgumentError)
+  rescue ArgumentError, TypeError
+    raise McpToolkit::Errors::InvalidParams, "updated_since must be an ISO 8601 timestamp"
+  end
+
+  def paginate(relation)
+    relation.offset(offset).limit(limit)
+  end
+
+  def limit
+    raw = params[:limit] || DEFAULT_LIMIT
+    [[raw.to_i, 1].max, MAX_LIMIT].min # rubocop:disable Style/ComparableClamp
+  end
+
+  def offset
+    [params[:offset].to_i, 0].max
+  end
+end

data/lib/mcp_toolkit/registry.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Central registry of read-only resources exposed via the MCP server. Resources
+# are registered at boot (in a `to_prepare` initializer) and consumed by the
+# generic `resources` / `resource_schema` / `get` / `list` tools.
+#
+# Instances are addressable so tests (and, in principle, multiple mounted
+# servers) don't collide; the app-facing convenience is `McpToolkit.registry`,
+# which returns the process-wide instance.
+class McpToolkit::Registry
+  class UnknownResource < StandardError; end
+
+  def initialize
+    @resources = {}
+    @default_required_permissions_scope = nil
+  end
+
+  # Registry-wide DEFAULT required scope, so a satellite declares its scope ONCE
+  # for every resource instead of repeating it per resource:
+  #
+  #   McpToolkit.registry.default_required_permissions_scope "notifications__read"
+  #
+  # A resource's own `required_permissions_scope` overrides this. Default nil = no
+  # scope required unless a resource declares its own. Read with no arg.
+  #
+  # Declared in the satellite's `configure` block (NOT inside `to_prepare`), so it
+  # survives `reset!` and stays set across dev reloads.
+  def default_required_permissions_scope(scope = nil)
+    @default_required_permissions_scope = scope if scope
+    @default_required_permissions_scope
+  end
+
+  def register(name, &)
+    resource = McpToolkit::Resource.new(name)
+    resource.instance_eval(&)
+    @resources[name.to_s] = resource
+  end
+
+  # The scope a token must carry to reach `resource` via the generic tools: the
+  # resource's own declared scope, else the registry default, else nil (no check).
+  def required_scope_for(resource)
+    resource.effective_required_permissions_scope(@default_required_permissions_scope)
+  end
+
+  def fetch(name)
+    find(name) or raise(UnknownResource, McpToolkit::UnknownResourceMessage.new(name, resource_names).build)
+  end
+
+  def find(name)
+    @resources[name.to_s]
+  end
+
+  def resources
+    @resources.values
+  end
+
+  def resource_names
+    @resources.keys
+  end
+
+  # Clears registered resources for a dev reload (the satellite re-declares them
+  # in `to_prepare`). The `default_required_permissions_scope` is PRESERVED, since
+  # it's declared once in `configure` rather than per-reload.
+  def reset!
+    @resources = {}
+  end
+end

data/lib/mcp_toolkit/resource.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# Descriptor for a single read-only resource exposed via the MCP server. Built
+# via `McpToolkit.registry.register`; consumed by the List/Get executors and the
+# resource_schema tool.
+#
+# The `scope_block` is the account-rooting relation: it receives the resolved
+# local scope root (typically an `Account`) and MUST return a relation already
+# scoped so that every row belongs to that root (directly via a foreign key, or
+# transitively through an owning record). This is the single tenancy chokepoint —
+# every `get`/`list` query roots on it.
+#
+# The `serializer` is INJECTABLE per resource: it may be a subclass of the gem's
+# `McpToolkit::Serializer::Base`, or any class satisfying the serializer contract
+# (`serialize_one` / `serialize_collection`) — e.g. an app's existing serializer.
+class McpToolkit::Resource
+  class NotConfigured < StandardError; end
+
+  attr_reader :name
+
+  def initialize(name)
+    @name = name.to_s
+    @model = nil
+    @serializer = nil
+    @scope_block = nil
+    @description = nil
+    @filterable = {}
+    @required_permissions_scope = nil
+  end
+
+  def model(klass = nil)
+    @model = klass if klass
+    @model
+  end
+
+  def serializer(klass = nil)
+    @serializer = klass if klass
+    @serializer
+  end
+
+  def scope(&block)
+    @scope_block = block if block
+    @scope_block
+  end
+
+  def description(text = nil)
+    @description = text if text
+    @description
+  end
+
+  # The OAuth-style scope a token MUST carry to reach this resource via the
+  # generic tools (e.g. "notifications__read"). Declared explicitly per resource:
+  #
+  #   required_permissions_scope "notifications__read"
+  #
+  # Default nil = no scope required for this resource (unless the registry sets a
+  # default — see Registry#default_required_permissions_scope). Read with no arg.
+  def required_permissions_scope(scope = nil)
+    @required_permissions_scope = scope if scope
+    @required_permissions_scope
+  end
+
+  # The scope actually enforced for this resource: its own declared scope if set,
+  # otherwise the registry-level `default` passed in. nil = no scope required.
+  def effective_required_permissions_scope(default = nil)
+    @required_permissions_scope || default
+  end
+
+  # Declares the per-attribute filters this resource accepts on the `list` tool.
+  # Each entry maps a REQUEST-FACING filter key to the backing DATABASE COLUMN the
+  # WHERE is applied to. The mapping is what lets the consumer-facing key differ
+  # from the storage column (e.g. exposing a synced foreign key under its public
+  # name):
+  #
+  #   filterable booking_id: :synced_booking_id
+  #
+  # A declared key accepts both a bare equality value AND operator-based
+  # conditions (`{ op:, value: }` or an array of them, ANDed) — see
+  # McpToolkit::Filtering for the supported operators per column type.
+  #
+  # Unmapped/unknown keys are rejected by the list executor, never silently
+  # dropped, so a typo surfaces as actionable feedback.
+  def filterable(mapping = nil)
+    return @filterable if mapping.nil?
+
+    mapping.each do |request_key, column|
+      @filterable[request_key.to_sym] = column.to_sym
+    end
+    @filterable
+  end
+
+  # Request-facing filter keys (symbols, sorted) this resource can be filtered
+  # by. Surfaced via the `resource_schema` tool.
+  def filterable_keys
+    @filterable.keys.sort
+  end
+
+  # Request-facing filter key (symbol) => backing column (symbol). Consumed by
+  # the list executor to build the WHERE clause.
+  def filterable_columns
+    @filterable
+  end
+
+  # The account-scoped relation for this resource. Raises if misconfigured so a
+  # registry mistake fails loudly rather than leaking an unscoped query.
+  def resolve_relation(scope_root)
+    raise NotConfigured, "resource #{name.inspect} has no scope block" unless scope
+    raise NotConfigured, "resource #{name.inspect} has no model" unless model
+    raise NotConfigured, "resource #{name.inspect} has no serializer" unless serializer
+
+    scope.call(scope_root)
+  end
+
+  # Serialized attribute names (the response shape), read off the serializer's
+  # declared attributes. Requires a serializer that exposes `declared_attributes`
+  # (the gem's base does); resource_schema degrades gracefully otherwise.
+  def attribute_names
+    return [] unless serializer.respond_to?(:declared_attributes)
+
+    serializer.declared_attributes.map(&:to_sym)
+  end
+
+  # Association descriptors (the `links` shape) read off the serializer.
+  def association_descriptors
+    return [] unless serializer.respond_to?(:declared_associations)
+
+    serializer.declared_associations
+  end
+end