mcp_toolkit 0.3.0

data/lib/mcp_toolkit/resource_schema.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# Builds a machine-readable schema for a single registered resource: its
+# serialized attributes (the response shape) with column types, and its
+# relationships (the `links` shape). Powers the `resource_schema` discovery tool
+# so an MCP client can learn a resource's shape without trial and error.
+#
+# Read-only with standard filters (ids/updated_since/limit/offset) plus the
+# resource's declared equality filters.
+class McpToolkit::ResourceSchema
+  TYPE_FORMATS = {
+    datetime: "ISO 8601",
+    date: "ISO 8601",
+    decimal: "number",
+    float: "number",
+    integer: "integer",
+    boolean: "true/false",
+    string: "string",
+    text: "string"
+  }.freeze
+  COMPUTED_TYPE = "computed"
+  STANDARD_FILTERS = %w[ids updated_since limit offset].freeze
+
+  # `registry` is used to resolve each relationship to the registered resource it
+  # points at (see #relationships). Defaults to the process-wide registry; the
+  # `resource_schema` tool passes the active config's registry explicitly.
+  def self.call(resource, registry: McpToolkit.registry)
+    new(resource, registry:).call
+  end
+
+  def initialize(resource, registry: McpToolkit.registry)
+    @resource = resource
+    @model = resource.model
+    @registry = registry
+  end
+
+  def call
+    {
+      name: resource.name,
+      description: resource.description,
+      attributes:,
+      relationships:,
+      standard_filters: STANDARD_FILTERS,
+      filters:
+    }
+  end
+
+  private
+
+  attr_reader :resource, :model, :registry
+
+  def attributes
+    resource.attribute_names.map { |name| attribute_schema(name) }
+  end
+
+  def attribute_schema(name)
+    type = column_type(name)
+    {
+      name:,
+      type: type ? type.to_s : COMPUTED_TYPE,
+      format: type ? TYPE_FORMATS[type] : nil,
+      filterable: filterable_column_for(name).present?
+    }.compact
+  end
+
+  # Per-attribute equality filters this resource accepts on the `list` tool's
+  # `filter` argument. Each entry is the request-facing key, the backing column
+  # it matches against, and the column's type — self-describing so an MCP client
+  # can construct a valid filter without trial and error.
+  def filters
+    resource.filterable_columns.sort.map do |request_key, column|
+      type = column_type(column)
+      {
+        key: request_key,
+        column:,
+        type: type ? type.to_s : COMPUTED_TYPE,
+        format: type ? TYPE_FORMATS[type] : nil
+      }.compact
+    end
+  end
+
+  # Backing column for a serialized attribute that is also a filter key, if any.
+  # A filter key may be a public alias (e.g. booking_id -> synced_booking_id) so
+  # we match on either the request key or the column.
+  def filterable_column_for(attribute_name)
+    resource.filterable_columns.find do |request_key, column|
+      request_key.to_s == attribute_name.to_s || column.to_s == attribute_name.to_s
+    end
+  end
+
+  def relationships
+    resource.association_descriptors.map { |association| relationship_schema(association) }
+  end
+
+  # One relationship entry. Beyond the link key/kind/polymorphic flag it now also
+  # names the `target_resource` — the registered resource this link resolves to,
+  # callable via `list`/`get` — so e.g. a `scheduled_notifications.notification`
+  # link is discoverably the `notifications` resource rather than a name to guess.
+  # It is omitted (additive/backward-compatible) when the target can't be resolved
+  # (e.g. a polymorphic link).
+  def relationship_schema(association)
+    target = target_resource_for(association)
+    {
+      name: association.links_key,
+      kind: association.type.to_s,
+      polymorphic: association.polymorphic || false,
+      target_resource: target&.name
+    }.compact
+  end
+
+  # The registered resource an association points at, or nil. Polymorphic links
+  # have no single target, so they are left unresolved (the `polymorphic` flag and
+  # the record's `{id:, type:}` link value already carry the target type). Prefers
+  # an explicit target serializer's model, then falls back to matching the link's
+  # (pluralized) name against registered resource names.
+  def target_resource_for(association)
+    return nil if association.polymorphic
+
+    target_from_serializer(association) || target_from_name(association)
+  end
+
+  def target_from_serializer(association)
+    serializer = association.serializer
+    return nil unless serializer.respond_to?(:model_class)
+
+    target_model = safe_model_class(serializer)
+    return nil unless target_model
+
+    registry.resources.find { |candidate| candidate.model == target_model }
+  end
+
+  def target_from_name(association)
+    candidate_names(association).each do |candidate|
+      match = registry.find(candidate)
+      return match if match
+    end
+    nil
+  end
+
+  # Names to try against the registry for a link, closest spelling first: the link
+  # key and association name as declared, then their pluralizations (resources are
+  # registered under plural names, so a singular `notification` link resolves to
+  # the `notifications` resource).
+  def candidate_names(association)
+    [association.links_key, association.name.to_s].flat_map do |base|
+      [base, base.pluralize]
+    end.uniq
+  end
+
+  def safe_model_class(serializer)
+    serializer.model_class
+  rescue StandardError
+    nil
+  end
+
+  # Reads an attribute's DB column type, tolerating models that don't expose
+  # `columns_hash` (returns nil => the attribute is reported as "computed").
+  def column_type(name)
+    return nil unless model.respond_to?(:columns_hash)
+
+    model.columns_hash[name.to_s]&.type
+  end
+end

data/lib/mcp_toolkit/serialization.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Bridges the executors to a resource's serializer while honoring a sparse
+# McpToolkit::FieldSelection. Built per call with the serializer and the (possibly
+# nil) selection; `#one` / `#collection` then mirror the serializer contract. This
+# is the single place that keeps the injectable serializer contract intact as
+# sparse fieldsets are added:
+#
+#   * selection nil (the default) -> the serializer is called EXACTLY as before
+#     (no `fields:` kwarg), so existing behavior and injected serializers are
+#     untouched.
+#   * selection present, serializer declares a `fields:` keyword (the gem's Base)
+#     -> applied NATIVELY, skipping the compute for unselected members.
+#   * selection present, serializer predates the kwarg -> the full output is
+#     PRUNED to the selection, so any contract-satisfying serializer stays
+#     sparse-able without change.
+class McpToolkit::Serialization
+  # `Method#parameters` types that mean a keyword the caller may pass by name.
+  FIELDS_KEYWORD_TYPES = %i[key keyreq].freeze
+
+  def initialize(serializer, selection)
+    @serializer = serializer
+    @selection = selection
+  end
+
+  def one(record, scope:)
+    return @serializer.serialize_one(record, scope:) if @selection.nil?
+
+    if accepts_fields?(:serialize_one)
+      @serializer.serialize_one(record, scope:, fields: @selection.names)
+    else
+      result = @serializer.serialize_one(record, scope:)
+      result && @selection.prune_record(result)
+    end
+  end
+
+  def collection(records, scope:, total_count:, limit:, offset:)
+    return full_collection(records, scope:, total_count:, limit:, offset:) if @selection.nil?
+
+    if accepts_fields?(:serialize_collection)
+      @serializer.serialize_collection(records, scope:, total_count:, limit:, offset:, fields: @selection.names)
+    else
+      @selection.prune_collection(full_collection(records, scope:, total_count:, limit:, offset:))
+    end
+  end
+
+  private
+
+  def full_collection(records, scope:, total_count:, limit:, offset:)
+    @serializer.serialize_collection(records, scope:, total_count:, limit:, offset:)
+  end
+
+  # True only when the method declares an EXPLICIT `fields:` keyword. A serializer
+  # that merely absorbs `**kwargs` is deliberately NOT treated as fields-aware — it
+  # would ignore the selection and silently return the full shape — so it falls
+  # through to output pruning, which guarantees the response is actually narrowed.
+  def accepts_fields?(method_name)
+    @serializer.method(method_name).parameters.any? do |type, name|
+      name == :fields && FIELDS_KEYWORD_TYPES.include?(type)
+    end
+  end
+end

data/lib/mcp_toolkit/serializer/base.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+# The DEFAULT serializer base shipped by the toolkit. A self-contained
+# implementation of the subset of an AMS-style serializer the MCP wire format
+# depends on, with NO dependency on `active_model_serializers` / `fast_jsonapi`.
+#
+# ## The injection contract
+#
+# The executors (`ListExecutor` / `GetExecutor`) only ever call two class
+# methods on a resource's serializer:
+#
+#   serializer.serialize_one(record, scope:)
+#     # => Hash (a single record's shape), or nil for a nil record
+#
+#   serializer.serialize_collection(records, scope:, total_count:, limit:, offset:)
+#     # => { <root_key> => [ <record_hash>, ... ],
+#     #      meta: { total_count:, limit:, offset: } }
+#
+# ANY class implementing those two methods can be registered as a resource's
+# serializer — that is the seam that lets an app's existing serializers slot in
+# unchanged alongside this base. The `resource_schema` tool additionally reads
+# `declared_attributes` and
+# `declared_associations` off the serializer (for shape discovery); a custom
+# serializer that wants to power `resource_schema` should expose those too, but
+# they are not required for `get` / `list`.
+#
+# ## Sparse fieldsets (optional)
+#
+# Both entry points also accept an OPTIONAL `fields:` keyword — an array of the
+# attribute and/or relationship link-key names to include (JSON:API's sparse
+# fieldset; the two share one flat namespace). `fields: nil` (the default) means
+# "everything", so the contract above is unchanged for callers that omit it. When
+# a subset is given, only those members are emitted AND only the selected
+# relationships are loaded (unselected `has_many` links are never queried). A
+# serializer that does NOT declare a `fields:` keyword still supports sparse
+# fieldsets — McpToolkit::Serialization prunes its output instead — so honoring
+# `fields:` natively is a performance optimization, not a contract requirement.
+#
+# `scope` is whatever the serializer needs (typically the account); it may be
+# nil for models without translations.
+#
+# ## Output shape
+#
+# A single record serializes to:
+#
+#   { <attr> => <value>, ..., "links" => { "<assoc>" => <id|[ids]|{id:,type:}|nil> } }
+#
+# * Declared `attributes` are emitted as symbol keys, in declaration order
+#   (an instance method named after the attribute overrides the column value).
+# * `"links"` is a string key whose value is a Hash with string keys, one per
+#   declared association, sorted alphabetically.
+#   - has_one / belongs_to whose FK lives on the record => the raw id (or nil)
+#   - polymorphic has_one / belongs_to => { id: <id>, type: <type> }
+#   - has_many => a sorted Array of associated ids ([] when none)
+# * created_at / updated_at, when present, are rendered as iso8601(6).
+#
+# A collection serializes to:
+#
+#   { <plural_resource_name>: [ <record_hash>, ... ],
+#     meta: { total_count:, limit:, offset: } }
+class McpToolkit::Serializer::Base
+  TIMESTAMP_COLUMNS = %i[created_at updated_at].freeze
+  HIGH_PRECISION_FOR_TIMESTAMPS = 6
+
+  # ---- class-level DSL -------------------------------------------------
+
+  Association = Struct.new(:name, :type, :key, :serializer, :polymorphic, :foreign_key, keyword_init: true) do
+    # Public-facing key used inside the `links` hash.
+    def links_key
+      (key || name).to_s
+    end
+  end
+
+  def self.attributes(*names)
+    names.each { |name| declared_attributes << name.to_sym }
+  end
+
+  # belongs_to / has_one - single id (or {id:,type:} when polymorphic).
+  #
+  # `foreign_key:` overrides the FK method read for the id (defaults to
+  # `<name>_id`). Use it when the model's FK column doesn't follow the
+  # `<name>_id` convention - e.g.
+  # `has_one :account, foreign_key: :synced_account_id` so the link reports
+  # the central account id straight off the already-loaded column.
+  def self.has_one(name, key: nil, root: nil, serializer: nil, polymorphic: false, foreign_key: nil)
+    declared_associations << Association.new(
+      name: name.to_sym, type: :has_one, key: key || root, serializer:, polymorphic:, foreign_key:
+    )
+  end
+
+  # has_many / has_and_belongs_to_many - sorted array of ids.
+  def self.has_many(name, key: nil, root: nil, serializer: nil)
+    declared_associations << Association.new(
+      name: name.to_sym, type: :has_many, key: key || root, serializer:, polymorphic: false
+    )
+  end
+
+  # Declares attributes whose value is a `{ locale => translation }` hash.
+  # An instance method is defined for each attribute that delegates to
+  # `#translate`. Only meaningful for Globalize models; harmless otherwise
+  # (returns {}).
+  def self.translates(*names)
+    names.each do |name|
+      declared_attributes << name.to_sym unless declared_attributes.include?(name.to_sym)
+      define_method(name) { translate(name) }
+    end
+  end
+
+  def self.declared_attributes
+    @declared_attributes ||= []
+  end
+
+  def self.declared_associations
+    @declared_associations ||= []
+  end
+
+  # ---- entry points used by the executors (the injection contract) -----
+
+  # Serialize a single record to its attributes+links hash. nil-safe.
+  # `fields:` (optional) restricts the output to a sparse fieldset — see the
+  # class-level docs.
+  def self.serialize_one(record, scope: nil, fields: nil)
+    return nil if record.nil?
+
+    new(record, scope:).serializable_hash(fields:)
+  end
+
+  # Serialize an array of records to the index wrapper, keyed by the
+  # pluralized resource name, with a `meta` pagination block. `fields:` (optional)
+  # restricts every row to a sparse fieldset — see the class-level docs.
+  def self.serialize_collection(records, scope: nil, total_count: nil, limit: nil, offset: nil, fields: nil)
+    rows = Array(records).map { |record| new(record, scope:).serializable_hash(fields:) }
+    {
+      root_key => rows,
+      meta: { total_count: total_count.nil? ? rows.size : total_count, limit:, offset: }
+    }
+  end
+
+  # Pluralized resource name used as the collection root key, derived from
+  # the serialized model (`model.model_name.plural`).
+  def self.root_key
+    model_class.model_name.plural.to_sym
+  end
+
+  # Infer the serialized model from the serializer class name by stripping a
+  # trailing "Serializer" and the host namespace, e.g.
+  #   Mcp::NotificationSerializer            -> Notification
+  #   Mcp::PushNotifications::FilterSerializer -> PushNotifications::Filter
+  # Subclasses whose name doesn't follow the convention set `model_class`.
+  def self.model_class
+    @model_class ||= begin
+      without_suffix = name.delete_suffix("Serializer")
+      # Drop the leading serializer namespace segment (e.g. "Mcp::") so the
+      # remainder names the model. If there is no namespace, use as-is.
+      without_namespace = without_suffix.sub(/\A[^:]+::/, "")
+      (without_namespace.empty? ? without_suffix : without_namespace).constantize
+    end
+  end
+
+  # Lets subclasses point at a model whose name doesn't follow the
+  # convention (e.g. namespacing differences). Written as an explicit class
+  # method (not `attr_writer`, which would define an instance writer) to set the
+  # class-level @model_class the convention-inference memoizes.
+  def self.model_class=(klass) # rubocop:disable Style/TrivialAccessors
+    @model_class = klass
+  end
+
+  # ---- instance API ----------------------------------------------------
+
+  attr_reader :object, :scope
+
+  def initialize(object, scope: nil)
+    @object = object
+    @scope = scope
+  end
+
+  # `fields:` (optional) is a sparse fieldset — an array of attribute and/or
+  # relationship link-key names to include. nil (default) emits everything.
+  def serializable_hash(fields: nil)
+    selected = fields&.map(&:to_sym)
+    hash = {}
+    self.class.declared_attributes.each do |attr|
+      next if selected && !selected.include?(attr)
+
+      hash[attr] = read_attribute(attr)
+    end
+    apply_high_precision_timestamps(hash)
+    link_hash = links(selected)
+    hash["links"] = link_hash unless link_hash.nil?
+    hash
+  end
+  alias as_json serializable_hash
+
+  private
+
+  def read_attribute(attr)
+    # An instance method named after the attribute overrides the column value
+    # (AMS convention). Globalize `translates` uses exactly this hook.
+    if respond_to?(attr, true) && method(attr).owner != McpToolkit::Serializer::Base
+      public_send(attr)
+    else
+      object.public_send(attr)
+    end
+  end
+
+  def apply_high_precision_timestamps(hash)
+    TIMESTAMP_COLUMNS.each do |column|
+      value = hash[column]
+      hash[column] = value.iso8601(HIGH_PRECISION_FOR_TIMESTAMPS) if value.present? && value.respond_to?(:iso8601)
+    end
+  end
+
+  # Builds the `links` hash: association links_key => ids, sorted.
+  #
+  # `selected` is a sparse fieldset (array of symbols) or nil. With nil the block
+  # is always returned (possibly empty `{}`), preserving the default shape. Under
+  # a selection only the selected associations are included, AND the whole block
+  # is OMITTED (returns nil) when none were selected — so narrowing to a few
+  # attributes drops the `links` noise entirely.
+  def links(selected = nil)
+    associations = self.class.declared_associations
+    if selected
+      associations = associations.select { |association| selected.include?(association.links_key.to_sym) }
+      return nil if associations.empty?
+    end
+    pairs = associations.map do |association|
+      [association.links_key, serialize_ids(association)]
+    end
+    pairs.sort_by(&:first).to_h
+  end
+
+  # Serializes an association to its id(s):
+  #   * FK present on the record -> the raw id (polymorphic -> {id:,type:})
+  #   * otherwise load the association -> sorted array of ids (has_many)
+  #     or single id (has_one).
+  def serialize_ids(association)
+    fk_method = association.foreign_key || :"#{association.name}_id"
+
+    if object.respond_to?(fk_method)
+      if association.polymorphic
+        { id: object.public_send(fk_method), type: object.public_send(:"#{association.name}_type") }
+      else
+        object.public_send(fk_method)
+      end
+    else
+      associated = object.public_send(association.name)
+      if associated.respond_to?(:to_ary) || associated.respond_to?(:pluck)
+        associated.pluck(:id).sort
+      elsif associated
+        associated.id
+      end
+    end
+  end
+
+  # Globalize-backed translation: `{ locale => value }`, restricted to the
+  # account's selected locales when a scope account is present. Returns {} when
+  # the model is not translatable.
+  def translate(attribute)
+    return {} unless object.respond_to?(:"#{attribute}_translations")
+
+    translations = object.public_send(:"#{attribute}_translations") || {}
+    locales = scope_locales
+    result = {}
+    translations.each do |locale, value|
+      locale = locale.to_sym
+      next if locales&.exclude?(locale)
+      next if value.blank?
+
+      result[locale] = value
+    end
+    result
+  end
+
+  # Locales to restrict translations to. nil means "no restriction" (emit all
+  # available translations).
+  def scope_locales
+    return nil if scope.nil?
+    return nil unless scope.respond_to?(:selected_locales)
+
+    selected = scope.selected_locales
+    return nil if selected.blank?
+
+    Array(selected).map(&:to_sym)
+  end
+end

data/lib/mcp_toolkit/server.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Builds the official-SDK `MCP::Server` for this app: the JSON-RPC dispatcher
+# with the toolkit's generic tools registered. The transport / session / HTTP
+# layer lives in McpToolkit::Transport::ControllerMethods; this is purely the
+# gem's dispatcher with tools + the per-request server_context.
+#
+# The official `mcp` gem is the JSON-RPC core (per the 2026-06-18 architecture
+# decision: standardize on the gem, wrapped, rather than a hand-rolled protocol).
+module McpToolkit::Server
+  # The generic, registry-driven toolset every server gets. Apps that want
+  # additional bespoke tools pass them via `extra_tools:`.
+  GENERIC_TOOLS = [
+    McpToolkit::Tools::Resources,
+    McpToolkit::Tools::ResourceSchema,
+    McpToolkit::Tools::Get,
+    McpToolkit::Tools::List
+  ].freeze
+
+  # @param server_context [Hash] per-request context threaded to tools:
+  #   :bearer_token, :header_account_id, :mcp_config, and (merged in by the gem)
+  #   :_meta.
+  # @param config [McpToolkit::Configuration]
+  # @param extra_tools [Array<Class>] additional MCP::Tool subclasses to expose.
+  # @return [MCP::Server]
+  def self.build(server_context:, config: McpToolkit.config, extra_tools: [])
+    context = server_context.dup
+    context[:mcp_config] ||= config
+
+    kwargs = {
+      name: config.server_name,
+      version: config.server_version,
+      instructions: config.server_instructions,
+      tools: GENERIC_TOOLS + Array(extra_tools),
+      server_context: context
+    }
+    if config.protocol_version
+      kwargs[:configuration] =
+        MCP::Configuration.new(protocol_version: config.protocol_version)
+    end
+
+    MCP::Server.new(**kwargs)
+  end
+end

data/lib/mcp_toolkit/session.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Server-side session for the MCP Streamable HTTP transport: created on
+# `initialize`, identified by an opaque `Mcp-Session-Id` header the client echoes
+# on every later request, stored in the configured cache with a sliding TTL.
+#
+# Cache-backed (rather than the gem's in-process StreamableHTTPTransport) so
+# sessions survive across Puma workers and interoperate with a gateway's client.
+# The cache store + TTL come from McpToolkit.config.
+class McpToolkit::Session
+  CACHE_KEY_PREFIX = "mcp_toolkit:session:"
+
+  def self.create!(config: McpToolkit.config)
+    id = SecureRandom.uuid
+    config.cache_store.write(cache_key(id), { created_at: Time.now.to_i }, expires_in: config.session_ttl)
+    new(id:)
+  end
+
+  def self.find(id, config: McpToolkit.config)
+    return nil if id.to_s.empty?
+
+    data = config.cache_store.read(cache_key(id))
+    return nil unless data
+
+    # Sliding expiry: bump TTL on every successful lookup.
+    config.cache_store.write(cache_key(id), data, expires_in: config.session_ttl)
+    new(id:)
+  end
+
+  def self.delete(id, config: McpToolkit.config)
+    return false if id.to_s.empty?
+
+    config.cache_store.delete(cache_key(id))
+  end
+
+  def self.cache_key(id)
+    "#{CACHE_KEY_PREFIX}#{id}"
+  end
+  private_class_method :cache_key
+
+  attr_reader :id
+
+  def initialize(id:)
+    @id = id
+  end
+end

data/lib/mcp_toolkit/sql_sanitizer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Escapes LIKE wildcards (`%`, `_`, `\`) in a string so a `matches` /
+# `does_not_match` filter value is matched literally rather than as a pattern.
+#
+# The default implementation delegates to ActiveRecord's
+# `sanitize_sql_like` (production); it is injected via
+# `Configuration#sql_sanitizer` so a non-Rails host (or a test) can supply its
+# own. Filtering calls `config.sql_sanitizer.sanitize_sql_like(value)`.
+class McpToolkit::SqlSanitizer
+  def sanitize_sql_like(string)
+    ActiveRecord::Base.sanitize_sql_like(string)
+  end
+end

data/lib/mcp_toolkit/token_kinds.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# The token "kind" domain values, shared by the collaborating auth objects so the
+# string literals live in exactly one place. The authority emits these in the
+# introspection payload (`kind`); the satellite reads them back
+# (`Auth::Introspection::Result#accounts_user?` / `#superuser?`).
+#
+#   ACCOUNTS_USER - a token bound to a single account.
+#   USER          - a superuser / multi-account token (advertises its set via
+#                   `account_ids`).
+module McpToolkit::TokenKinds
+  ACCOUNTS_USER = "accounts_user"
+  USER = "user"
+end