mcp_toolkit 0.3.0 → 0.5.0

data/lib/mcp_toolkit/protocol.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# MCP JSON-RPC protocol constants + helpers for the hand-rolled AUTHORITY
+# dispatcher (McpToolkit::Dispatcher). Based on the Model Context Protocol
+# specification.
+#
+# This is the wire vocabulary of a first-party MCP endpoint that serves its own
+# tools (and, as a gateway, aggregates upstream ones) WITHOUT the official `mcp`
+# SDK in the request path. The SDK-backed satellite path
+# (McpToolkit::Server.build) does not use this module; the two dispatch
+# front-ends coexist by design.
+#
+# The error codes, the success/error response envelopes, and the
+# version-negotiation constants here are the BYTE contract a monetized authority
+# endpoint depends on, so they are kept fixed. `SUPPORTED_VERSIONS` is the module
+# default; a host negotiates against `config.supported_protocol_versions`
+# (defaulting to the same list) so the set is overridable without editing this
+# file.
+module McpToolkit::Protocol
+  # Protocol versions the server supports, newest first. The version returned in
+  # the `initialize` response is the requested version (if supported) or the
+  # latest the server supports, per the MCP spec's version-negotiation rules.
+  SUPPORTED_VERSIONS = %w[2025-06-18 2025-03-26 2024-11-05].freeze
+  LATEST_VERSION = SUPPORTED_VERSIONS.first
+  # Kept for backwards compatibility; prefer LATEST_VERSION going forward.
+  VERSION = LATEST_VERSION
+
+  JSONRPC_VERSION = "2.0"
+
+  # Error codes per JSON-RPC 2.0 spec.
+  module ErrorCodes
+    PARSE_ERROR = -32_700
+    INVALID_REQUEST = -32_600
+    METHOD_NOT_FOUND = -32_601
+    INVALID_PARAMS = -32_602
+    INTERNAL_ERROR = -32_603
+  end
+
+  # Base protocol error. `code`/`data` land verbatim in the JSON-RPC `error`
+  # object via `#to_h`; the dispatcher turns a raised Error into a top-level
+  # JSON-RPC error response (the envelope a client sees for a bad tool arg or an
+  # unknown method).
+  class Error < StandardError
+    attr_reader :code, :data
+
+    def initialize(message, code:, data: nil)
+      super(message)
+      @code = code
+      @data = data
+    end
+
+    def to_h
+      error = { code:, message: }
+      error[:data] = data if data
+      error
+    end
+  end
+
+  class ParseError < Error
+    def initialize(message = "Parse error", data: nil)
+      super(message, code: ErrorCodes::PARSE_ERROR, data:)
+    end
+  end
+
+  class InvalidRequest < Error
+    def initialize(message = "Invalid request", data: nil)
+      super(message, code: ErrorCodes::INVALID_REQUEST, data:)
+    end
+  end
+
+  class MethodNotFound < Error
+    def initialize(method_name, data: nil)
+      super("Method not found: #{method_name}", code: ErrorCodes::METHOD_NOT_FOUND, data:)
+    end
+  end
+
+  class InvalidParams < Error
+    def initialize(message = "Invalid params", data: nil)
+      super(message, code: ErrorCodes::INVALID_PARAMS, data:)
+    end
+  end
+
+  class InternalError < Error
+    def initialize(message = "Internal error", data: nil)
+      super(message, code: ErrorCodes::INTERNAL_ERROR, data:)
+    end
+  end
+
+  module_function
+
+  def success_response(id:, result:)
+    {
+      jsonrpc: JSONRPC_VERSION,
+      id:,
+      result:
+    }
+  end
+
+  def error_response(id:, error:)
+    {
+      jsonrpc: JSONRPC_VERSION,
+      id:,
+      error: error.is_a?(Error) ? error.to_h : error
+    }
+  end
+end

data/lib/mcp_toolkit/rate_limiter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# A fixed-window request counter backing the authority transport's built-in rate
+# limiting (McpToolkit::Authority::ControllerMethods#mcp_rate_limit!). It is
+# storage-agnostic: it counts against the injected `cache_store` (any
+# ActiveSupport::Cache::Store — a shared Rails.cache in production, a MemoryStore
+# in a unit test), so a host enables per-principal throttling by setting
+# `config.rate_limit_max_requests` alone, without hand-rolling a limiter.
+#
+# The window is FIXED, not sliding: every request whose time falls in the same
+# `window`-second bucket shares one counter, keyed by that bucket's start
+# (`window_start`); the entry expires after `window` seconds. The counter is
+# incremented once per call, and the request is allowed while the running count is
+# `<= max_requests`, blocked once it exceeds it (so exactly `max_requests`
+# requests pass per window).
+#
+#   result = McpToolkit::RateLimiter.new(
+#     key: principal.id, max_requests: 1_000, window: 3_600, cache_store: Rails.cache
+#   ).call
+#   result.allowed?     # => false once the count exceeds max_requests
+#   result.limit        # => 1_000
+#   result.remaining    # => max_requests - count, floored at 0
+#   result.reset_at     # => epoch seconds of the next window boundary
+#   result.retry_after  # => seconds until reset_at (0 when already past)
+#
+# The cache key is namespaced (`mcp_toolkit:rate_limit:<key>:<window_start>`) so a
+# host's own cache entries never collide with the counter.
+class McpToolkit::RateLimiter
+  # The outcome of one #call: the throttling decision plus the values the
+  # transport renders into the `X-RateLimit-*` / `Retry-After` headers.
+  Result = Struct.new(:allowed, :limit, :remaining, :reset_at, :retry_after, keyword_init: true) do
+    def allowed?
+      allowed
+    end
+  end
+
+  def initialize(key:, max_requests:, cache_store:, window: 3_600, now: Time.now)
+    @key = key
+    @max_requests = max_requests
+    @cache_store = cache_store
+    @window = window
+    @now = now.to_i
+  end
+
+  # Increments this window's counter and returns the Result. Called once per
+  # request by the transport's rate-limit hook.
+  def call
+    count = @cache_store.increment(cache_key, 1, expires_in: @window) || 1
+    allowed = count <= @max_requests
+
+    Result.new(
+      allowed:,
+      limit: @max_requests,
+      remaining: allowed ? @max_requests - count : 0,
+      reset_at:,
+      retry_after: [reset_at - @now, 0].max
+    )
+  end
+
+  private
+
+  def window_start
+    @now - (@now % @window)
+  end
+
+  def reset_at
+    window_start + @window
+  end
+
+  def cache_key
+    "mcp_toolkit:rate_limit:#{@key}:#{window_start}"
+  end
+end

data/lib/mcp_toolkit/registry.rb

@@ -13,8 +13,33 @@ class McpToolkit::Registry
   def initialize
     @resources = {}
     @default_required_permissions_scope = nil
+    @resource_extension = nil
+    @resource_finalizer = nil
   end
 
+  # A Module MIXED INTO every Resource before its registration block runs, so a host
+  # can add its OWN declaration DSL (its "extras") on top of the gem's built-in
+  # `model` / `scope` / `serializer` / `filterable` / `superusers_only!` / `note` /
+  # `filter`. The host method typically stores into the generic `Resource#extra`
+  # bag; the `resource_finalizer` reads it back. nil (the default) mixes in nothing,
+  # so a host with no extras is unaffected. Set ONCE in `configure` (not per reload),
+  # since `reset!` preserves it.
+  #
+  #   McpToolkit.registry.resource_extension = MyApp::ResourceExtension  # adds `dependencies`
+  #
+  # @return [Module, nil]
+  attr_accessor :resource_extension
+
+  # A callable run against each Resource AFTER its registration block, so a host can
+  # derive gem-native fields from its declared extras — e.g. build a `serializer`
+  # from the `model` + declared `dependencies`, or a lazy `filterable`. `->(resource)`.
+  # nil (the default) is a no-op. This is the hook that lets a host avoid a parallel
+  # registration system: it declares resources DIRECTLY against the gem registry and
+  # fills the derived pieces here. Set ONCE in `configure`; preserved across `reset!`.
+  #
+  # @return [#call, nil]
+  attr_accessor :resource_finalizer
+
   # Registry-wide DEFAULT required scope, so a satellite declares its scope ONCE
   # for every resource instead of repeating it per resource:
   #
@@ -32,7 +57,9 @@ class McpToolkit::Registry
 
   def register(name, &)
     resource = McpToolkit::Resource.new(name)
+    resource.extend(@resource_extension) if @resource_extension
     resource.instance_eval(&)
+    @resource_finalizer&.call(resource)
     @resources[name.to_s] = resource
   end
 
@@ -59,8 +86,9 @@ class McpToolkit::Registry
   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.
+  # in `to_prepare`). The `default_required_permissions_scope`, `resource_extension`
+  # and `resource_finalizer` are PRESERVED, since they're declared once in
+  # `configure` rather than per-reload.
   def reset!
     @resources = {}
   end

data/lib/mcp_toolkit/resource.rb

@@ -16,6 +16,20 @@
 class McpToolkit::Resource
   class NotConfigured < StandardError; end
 
+  # A resource-specific ("custom") filter: a request-facing key whose value is
+  # applied to the relation by an arbitrary host-supplied block, rather than the
+  # generic equality/operator allowlist. The block is api-agnostic — it receives
+  # the already-scoped relation and the raw request value and returns a narrowed
+  # relation — so a host can express a relational or otherwise non-column filter
+  # (e.g. "only rows whose associated booking is in this rental") without the gem
+  # knowing anything about the query. `type`/`description` are surfaced by
+  # resource_schema so a client can discover the filter.
+  CustomFilter = Struct.new(:name, :type, :description, :applier, keyword_init: true)
+
+  # Sentinel distinguishing `extra(:key)` (read) from `extra(:key, nil)` (write nil).
+  UNSET = Object.new
+  private_constant :UNSET
+
   attr_reader :name
 
   def initialize(name)
@@ -24,10 +38,34 @@ class McpToolkit::Resource
     @serializer = nil
     @scope_block = nil
     @description = nil
+    @note = nil
+    @superusers_only = false
     @filterable = {}
+    @filterable_source = nil
+    @filter_requirements = {}
+    @filter_requirements_source = nil
+    @custom_filters = {}
     @required_permissions_scope = nil
+    @extras = {}
+  end
+
+  # A generic, api-agnostic metadata bag for host-defined "extras" — declarations
+  # the gem does not model itself (e.g. an app's ORM dependency list used to build a
+  # serializer). It is the storage behind `config.registry.resource_extension` (the
+  # host DSL that writes extras inside a registration block) and
+  # `config.registry.resource_finalizer` (which reads them back to derive gem-native
+  # fields such as `serializer` / `filterable`). Write with `extra(:key, value)`;
+  # read with `extra(:key)` (nil when unset). The gem never inspects the values.
+  def extra(key, value = UNSET)
+    return @extras[key] if value.equal?(UNSET)
+
+    @extras[key] = value
   end
 
+  # The full host-extras bag (symbol/whatever key => value). Read-only view for a
+  # resource_finalizer that wants to iterate every declared extra.
+  attr_reader :extras
+
   def model(klass = nil)
     @model = klass if klass
     @model
@@ -48,6 +86,59 @@ class McpToolkit::Resource
     @description
   end
 
+  # Free-form usage caveat surfaced by the `resources` / `resource_schema` tools,
+  # e.g. to flag a resource as internal-debugging-only and not to be interpreted
+  # without domain knowledge. Read with no arg. api-agnostic passthrough string.
+  def note(text = nil)
+    @note = text if text
+    @note
+  end
+
+  # Restricts this resource to superuser (cross-tenant) callers on the AUTHORITY
+  # path: an authority tool refuses `get` / `list` / `resource_schema` for a
+  # non-superuser and HIDES the resource from `resources` discovery. Declared in a
+  # resource's registration block:
+  #
+  #   McpToolkit.registry.register(:audit_events) do
+  #     superusers_only!
+  #     ...
+  #   end
+  #
+  # Generic and api-agnostic — the gem never names an app concept; the caller's
+  # superuser-ness is derived by the Authority::Context off the principal.
+  def superusers_only!
+    @superusers_only = true
+  end
+
+  # Whether this resource is restricted to superuser callers (default false).
+  def superusers_only?
+    @superusers_only
+  end
+
+  # Declares a resource-specific ("custom") filter: a request-facing `name` whose
+  # value is applied to the already-scoped relation by the given block. Unlike the
+  # `filterable` allowlist (generic equality/operator filters on a declared
+  # column), a custom filter runs ARBITRARY host logic, so a host can express a
+  # relational filter the gem could not derive:
+  #
+  #   filter :rental_id, type: :integer, description: "Only rows for this rental" do |relation, value|
+  #     relation.joins(:booking).where(bookings: { rental_id: value })
+  #   end
+  #
+  # The block receives `(relation, value)` and MUST return a relation (narrowing
+  # only). `type` / `description` are metadata surfaced by `resource_schema`. The
+  # value arrives from a TOP-LEVEL request param keyed by `name` (see ListExecutor),
+  # applied BEFORE the allowlist `filterable` filters. api-agnostic: the gem stores
+  # and calls the block without inspecting it.
+  def filter(name, type:, description:, &applier)
+    @custom_filters[name.to_sym] = CustomFilter.new(name: name.to_sym, type:, description:, applier:)
+  end
+
+  # Request-facing custom-filter key (symbol) => CustomFilter. Consumed by the list
+  # executor (which applies each block whose key is present in the request params)
+  # and by resource_schema (which surfaces each filter's type/description).
+  attr_reader :custom_filters
+
   # The OAuth-style scope a token MUST carry to reach this resource via the
   # generic tools (e.g. "notifications__read"). Declared explicitly per resource:
   #
@@ -80,24 +171,64 @@ class McpToolkit::Resource
   #
   # 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?
+  # Accepts a Hash (merged now) OR a callable returning a Hash (resolved LAZILY on
+  # first read). The lazy form lets a host derive the map from something that must
+  # NOT be touched at registration/boot time — e.g. a DB-backed column list
+  # (`Model.column_names`): registration typically runs inside an initializer's
+  # `to_prepare`, before the database may exist (e.g. CI's `db:create`), so hitting
+  # the DB there aborts boot. A callable source is invoked at most once — on the
+  # first read (a tool call, when the DB is present) — then memoized.
+  def filterable(mapping = nil, &block)
+    source = block || mapping
+    return filterable_columns if source.nil?
 
-    mapping.each do |request_key, column|
-      @filterable[request_key.to_sym] = column.to_sym
+    if source.respond_to?(:call)
+      @filterable_source = source
+    else
+      merge_filterable!(source)
     end
-    @filterable
+    self
   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
+    filterable_columns.keys.sort
+  end
+
+  # Declares companion-key requirements for filter keys: a request-facing key
+  # that is only valid when another key is passed alongside it (the canonical
+  # case is a polymorphic foreign key, type-ambiguous without its `*_type`):
+  #
+  #   filter_requirements created_by_id: :created_by_type
+  #
+  # The list executor rejects a filter using the key without its companion, and
+  # `resource_schema` surfaces the requirement (`relationships[].filter.requires`)
+  # so a client can discover it. The companion key MUST itself be declared
+  # `filterable` — otherwise the requirement is unsatisfiable (the executor
+  # rejects the companion as an unknown key) while the schema still advertises
+  # it. Like `filterable`, accepts a Hash (merged now) OR a callable returning
+  # one (resolved lazily on first successful read, then memoized) so a host can
+  # derive the map without touching the DB at boot. Read with no arg.
+  def filter_requirements(mapping = nil, &block)
+    source = block || mapping
+    if source.nil?
+      resolve_filter_requirements_source!
+      return @filter_requirements
+    end
+
+    if source.respond_to?(:call)
+      @filter_requirements_source = source
+    else
+      merge_filter_requirements!(source)
+    end
+    self
   end
 
   # Request-facing filter key (symbol) => backing column (symbol). Consumed by
   # the list executor to build the WHERE clause.
   def filterable_columns
+    resolve_filterable_source!
     @filterable
   end
 
@@ -126,4 +257,40 @@ class McpToolkit::Resource
 
     serializer.declared_associations
   end
+
+  private
+
+  # Resolves a lazily-provided filterable source (a callable) on the first
+  # SUCCESSFUL `filterable_columns` / `filterable_keys` read — then drops it, so
+  # later reads are pure Hash access. This is what keeps a DB-derived map (e.g.
+  # `Model.column_names`) out of registration/boot time. The source is cleared
+  # only AFTER it returns: a raising callable (a transient DB hiccup) stays
+  # registered and is retried on the next read, instead of permanently and
+  # silently resolving the allowlist to `{}`.
+  def resolve_filterable_source!
+    return unless @filterable_source
+
+    resolved = @filterable_source.call || {}
+    @filterable_source = nil
+    merge_filterable!(resolved)
+  end
+
+  def merge_filterable!(mapping)
+    mapping.each { |request_key, column| @filterable[request_key.to_sym] = column.to_sym }
+  end
+
+  # Same lazy-resolution contract as the filterable source: resolved on the
+  # first successful read, cleared only after the callable returns so a
+  # transient failure is retried rather than silently dropping the map.
+  def resolve_filter_requirements_source!
+    return unless @filter_requirements_source
+
+    resolved = @filter_requirements_source.call || {}
+    @filter_requirements_source = nil
+    merge_filter_requirements!(resolved)
+  end
+
+  def merge_filter_requirements!(mapping)
+    mapping.each { |key, required| @filter_requirements[key.to_sym] = required.to_sym }
+  end
 end

data/lib/mcp_toolkit/resource_schema.rb

@@ -38,11 +38,15 @@ class McpToolkit::ResourceSchema
     {
       name: resource.name,
       description: resource.description,
+      note: resource.note,
       attributes:,
       relationships:,
+      resource_filters:,
       standard_filters: STANDARD_FILTERS,
+      sparse_fieldsets: true,
+      filter_examples:,
       filters:
-    }
+    }.compact
   end
 
   private
@@ -50,7 +54,7 @@ class McpToolkit::ResourceSchema
   attr_reader :resource, :model, :registry
 
   def attributes
-    resource.attribute_names.map { |name| attribute_schema(name) }
+    @attributes ||= resource.attribute_names.map { |name| attribute_schema(name) }
   end
 
   def attribute_schema(name)
@@ -59,8 +63,20 @@ class McpToolkit::ResourceSchema
       name:,
       type: type ? type.to_s : COMPUTED_TYPE,
       format: type ? TYPE_FORMATS[type] : nil,
-      filterable: filterable_column_for(name).present?
-    }.compact
+      filterable: filterable_column_for(name).present?,
+      operators: operators_for(name)
+    }
+  end
+
+  # The filter operators an attribute accepts, derived from the backing column's
+  # type via McpToolkit::Filtering.operators_for. `[]` for a non-filterable
+  # attribute (or one with no backing column) — self-describing so a client
+  # knows exactly which `{ op:, value: }` conditions `list` will accept.
+  def operators_for(attribute_name)
+    pair = filterable_column_for(attribute_name)
+    return [] unless pair
+
+    McpToolkit::Filtering.operators_for(column_type(pair.last))
   end
 
   # Per-attribute equality filters this resource accepts on the `list` tool's
@@ -79,6 +95,88 @@ class McpToolkit::ResourceSchema
     end
   end
 
+  # The resource's custom filters (Resource#filter) — resource-specific filters
+  # passed as TOP-LEVEL params of the `list` tool (NOT inside `filter`), each
+  # applied by a host-supplied block. Surfaced with name/type/description so a
+  # client can discover them; `[]` for a resource that declares none.
+  # Entries keep nil type/description keys (rather than compacting) — the
+  # pre-gem contract emitted them, and an always-present shape is easier for a
+  # client to consume.
+  def resource_filters
+    resource.custom_filters.each_value.map do |custom_filter|
+      {
+        name: custom_filter.name.to_s,
+        type: custom_filter.type&.to_s,
+        description: custom_filter.description
+      }
+    end
+  end
+
+  # Ready-to-use `filter` payload examples built from this resource's own
+  # filterable attributes and relationships, so a client can copy a working
+  # shape instead of deriving it from the operator lists.
+  def filter_examples
+    [equality_example, comparison_example, range_example, relationship_example].compact
+  end
+
+  def equality_example
+    attribute = example_attributes.find { |candidate| candidate[:type] == "string" } || example_attributes.first
+    return unless attribute
+
+    { attribute[:name] => sample_value(attribute[:type]) }
+  end
+
+  def comparison_example
+    attribute = comparison_attribute
+    return unless attribute
+
+    { attribute[:name] => { op: "gt", value: sample_value(attribute[:type]) } }
+  end
+
+  def range_example
+    attribute = comparison_attribute
+    return unless attribute
+
+    {
+      attribute[:name] => [
+        { op: "gteq", value: sample_value(attribute[:type]) },
+        { op: "lt", value: sample_value(attribute[:type]) }
+      ]
+    }
+  end
+
+  def relationship_example
+    relationship = relationships.find { |candidate| candidate[:filter] }
+    return unless relationship
+
+    example = { relationship[:filter][:keys].first => 1 }
+    example[relationship[:filter][:requires]] = "User" if relationship[:filter][:requires]
+    example
+  end
+
+  def filterable_attributes
+    attributes.select { |attribute| attribute[:filterable] }
+  end
+
+  # `id` is filterable but uninteresting as an example (use the `ids` filter for that).
+  def example_attributes
+    filterable_attributes.reject { |attribute| attribute[:name] == :id }
+  end
+
+  def comparison_attribute
+    example_attributes.find { |attribute| attribute[:operators].include?("gt") }
+  end
+
+  def sample_value(type)
+    case type.to_s
+    when "integer" then 1
+    when "decimal", "float" then "100.0"
+    when "boolean" then true
+    when "datetime", "date" then "2026-01-01T00:00:00Z"
+    else "..."
+    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.
@@ -89,22 +187,46 @@ class McpToolkit::ResourceSchema
   end
 
   def relationships
-    resource.association_descriptors.map { |association| relationship_schema(association) }
+    @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).
+  # One relationship entry: the link key/kind/polymorphic flag, the registered
+  # resource the link resolves to — emitted BOTH as `resource` (nullable) and,
+  # when resolved, as `target_resource` (so e.g. a
+  # `scheduled_notifications.notification` link is discoverably the
+  # `notifications` resource rather than a name to guess) — and, when the
+  # link's foreign key is filterable, a `filter` block telling a client HOW to
+  # filter by the relationship (see #relationship_filter).
   def relationship_schema(association)
     target = target_resource_for(association)
-    {
+    schema = {
       name: association.links_key,
       kind: association.type.to_s,
       polymorphic: association.polymorphic || false,
-      target_resource: target&.name
+      resource: target&.name,
+      filter: relationship_filter(association.links_key)
+    }
+    schema[:target_resource] = target.name if target
+    schema
+  end
+
+  # How to filter by a relationship, when its foreign key is in the filter
+  # allowlist: the accepted request keys (the FK, plus the bare link name when
+  # aliased), the backing column's type, its operators, and — for a key that
+  # cannot be used alone (e.g. a polymorphic FK needing its `*_type`) — the
+  # companion key it `requires` (see Resource#filter_requirements).
+  def relationship_filter(name)
+    id_key = :"#{name}_id"
+    column = resource.filterable_columns[id_key]
+    return nil unless column
+
+    keys = [id_key]
+    keys << name.to_sym if resource.filterable_columns.key?(name.to_sym)
+    {
+      keys:,
+      type: column_type(column).to_s,
+      operators: operators_for(id_key),
+      requires: resource.filter_requirements[id_key]
     }.compact
   end
 

data/lib/mcp_toolkit/serializer/association_descriptor.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# The association shape the gem reads off a serializer's
+# `declared_associations` (ResourceSchema's relationship entries,
+# FieldSelection's valid `fields` names). A host adapting its OWN serializer
+# framework builds these rather than re-deriving the duck-type by hand:
+# `links_key` / `type` / `polymorphic` / `name`, plus an optional `serializer`
+# responding to `model_class` (see TargetRef) so the target resource resolves.
+McpToolkit::Serializer::AssociationDescriptor = Struct.new(
+  :name, :type, :polymorphic, :links_key, :serializer, keyword_init: true
+)

data/lib/mcp_toolkit/serializer/base.rb

@@ -144,8 +144,8 @@ class McpToolkit::Serializer::Base
 
   # 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
+  #   Api::WidgetSerializer                 -> Widget
+  #   Api::ScheduledWidgets::FilterSerializer -> ScheduledWidgets::Filter
   # Subclasses whose name doesn't follow the convention set `model_class`.
   def self.model_class
     @model_class ||= begin

data/lib/mcp_toolkit/serializer/target_ref.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Minimal object satisfying the gem's `association.serializer.model_class`
+# probe (ResourceSchema's target-resource resolution): carries the model an
+# association resolves to. Pair with AssociationDescriptor when adapting a
+# host serializer framework.
+McpToolkit::Serializer::TargetRef = Struct.new(:model_class)