mcp_toolkit 0.4.0 → 0.6.0

data/lib/mcp_toolkit/resource_schema.rb

@@ -41,9 +41,12 @@ class McpToolkit::ResourceSchema
       note: resource.note,
       attributes:,
       relationships:,
+      resource_filters:,
       standard_filters: STANDARD_FILTERS,
+      sparse_fieldsets: true,
+      filter_examples:,
       filters:
-    }
+    }.compact
   end
 
   private
@@ -51,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)
@@ -62,18 +65,18 @@ class McpToolkit::ResourceSchema
       format: type ? TYPE_FORMATS[type] : nil,
       filterable: filterable_column_for(name).present?,
       operators: operators_for(name)
-    }.compact
+    }
   end
 
   # The filter operators an attribute accepts, derived from the backing column's
-  # type via McpToolkit::Filtering::OPERATORS_BY_TYPE. `[]` for a non-filterable
-  # attribute (or one whose column type has no operator set) — self-describing so
-  # a client knows exactly which `{ op:, value: }` conditions `list` will accept.
+  # 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_BY_TYPE.fetch(column_type(pair.last), [])
+    McpToolkit::Filtering.operators_for(column_type(pair.last))
   end
 
   # Per-attribute equality filters this resource accepts on the `list` tool's
@@ -92,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.
@@ -102,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/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)

data/lib/mcp_toolkit/session.rb

@@ -28,9 +28,9 @@ class McpToolkit::Session
     stored = config.cache_store.read(cache_key(id))
     return nil unless stored
 
-    # Sliding expiry: bump TTL on every successful lookup.
+    # Sliding expiry: bump TTL on every successful lookup, re-writing the row
+    # untouched.
     config.cache_store.write(cache_key(id), stored, expires_in: config.session_ttl)
-    # `data` defaults to {} for legacy rows written before the payload existed.
     new(id:, data: stored[:data] || {})
   end
 

data/lib/mcp_toolkit/tool_reference_rewriter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Rewrites backticked generic-tool references ("use the `resources` tool") inside
+# tool prose so they always name the tools exactly as they appear in the serving
+# server's `tools/list`. Two serving paths need this: the authority's own generic
+# tools when the host configures a `generic_tool_name_prefix` (a client would
+# otherwise be pointed at an unprefixed tool that does not exist), and the
+# gateway's aggregated upstream tools, whose names are re-keyed into the
+# `<app>__<tool>` namespace while their prose would otherwise keep naming the
+# upstream's bare tools.
+#
+# Only EXACT backticked base names are rewritten; other backticked terms
+# (`resource`, `filter`, `target_resource`, ...) never match.
+module McpToolkit::ToolReferenceRewriter
+  GENERIC_TOOL_REFERENCES = /`(resource_schema|resources|list|get)`/
+
+  module_function
+
+  # Rewrites `node` (a String, or a Hash/Array structure such as a tool
+  # definition or input schema, walked recursively) with `name_prefix` applied to
+  # every backticked generic-tool reference. Non-string leaves pass through
+  # untouched; an empty prefix returns the node verbatim.
+  def rewrite(node, name_prefix)
+    return node if name_prefix.to_s.empty?
+
+    case node
+    when String then node.gsub(GENERIC_TOOL_REFERENCES) { "`#{name_prefix}#{Regexp.last_match(1)}`" }
+    when Hash then node.transform_values { |value| rewrite(value, name_prefix) }
+    when Array then node.map { |value| rewrite(value, name_prefix) }
+    else node
+    end
+  end
+end

data/lib/mcp_toolkit/tools/authority_base.rb

@@ -105,6 +105,15 @@ class McpToolkit::Tools::AuthorityBase
     raise McpToolkit::Protocol::InvalidRequest, "#{resource.name} is restricted to superuser (user-scoped) MCP tokens"
   end
 
+  # ArgumentErrors Ruby itself raises while binding the request arguments to the
+  # subclass's `#call` signature: a missing/unknown keyword or wrong arity. Their
+  # messages carry only keyword names (the tool's own declared params) and counts,
+  # so surfacing them tells a client how to fix the call. Every OTHER ArgumentError
+  # is raised from inside the tool's business logic (e.g. `Integer("x")`) and its
+  # message may carry SQL, internal class names, or a value — so it is sanitized
+  # like any unexpected error rather than relayed verbatim.
+  ARGUMENT_BINDING_ERROR_MESSAGE = /\A(missing keyword|unknown keyword|wrong number of arguments)/
+
   # Runs the tool's business logic (the subclass's `#call`) with error mapping.
   # Arrives with symbol-keyed arguments from the dispatcher.
   def execute(**arguments)
@@ -114,9 +123,11 @@ class McpToolkit::Tools::AuthorityBase
     # (e.g. InvalidParams); let it bubble untouched so the client sees it.
     raise
   rescue ArgumentError => e
-    raise McpToolkit::Protocol::InvalidParams, e.message
+    raise McpToolkit::Protocol::InvalidParams, e.message if ARGUMENT_BINDING_ERROR_MESSAGE.match?(e.message)
+
+    raise sanitized_internal_error(e)
   rescue StandardError => e
-    raise McpToolkit::Protocol::InternalError, e.message
+    raise sanitized_internal_error(e)
   end
 
   # The subclass implements its business logic here, receiving the tool arguments
@@ -124,4 +135,14 @@ class McpToolkit::Tools::AuthorityBase
   def call(**_arguments)
     raise NotImplementedError, "#{self.class} must implement #call"
   end
+
+  private
+
+  # An UNEXPECTED error's message may carry SQL, internal class names, or a
+  # hostname — it must not reach the caller (the dispatcher relays a
+  # Protocol::Error's message verbatim). Log the detail; return a generic error.
+  def sanitized_internal_error(error)
+    McpToolkit.config.logger&.error("MCP tool #{self.class} error: #{error.message}\n#{error.backtrace&.join("\n")}")
+    McpToolkit::Protocol::InternalError.new("Internal error")
+  end
 end

data/lib/mcp_toolkit/tools/base.rb

@@ -26,7 +26,7 @@ class McpToolkit::Tools::Base < MCP::Tool
   # `required_scope` is the explicitly-declared scope a token must carry (the
   # caller resolves it from the resource — see Registry#required_scope_for).
   # Empty/nil => no scope check (authorized_for_scope? treats "" as a pass).
-  def self.with_account(server_context, account_id: nil, required_scope: nil)
+  def self.with_account(server_context, account_id: nil, required_scope: nil, resource: nil)
     config = config_from(server_context)
     context = McpToolkit::Auth::Authenticator.call(
       token: server_context[:bearer_token],
@@ -40,6 +40,9 @@ class McpToolkit::Tools::Base < MCP::Tool
       return error_response("Unauthorized: token lacks the #{required_scope.inspect} scope")
     end
 
+    superuser_refusal = superuser_only_refusal(resource, context.introspection)
+    return superuser_refusal if superuser_refusal
+
     text_response(yield(context.scope_root))
   rescue McpToolkit::Errors::Unauthorized => e
     error_response("Unauthorized: #{e.message}")
@@ -52,7 +55,7 @@ class McpToolkit::Tools::Base < MCP::Tool
   # which reveal shape, not tenant data, so a superuser shouldn't have to pin an
   # account just to discover what exists. Empty/nil `required_scope` => no scope
   # check.
-  def self.with_authentication(server_context, required_scope: nil)
+  def self.with_authentication(server_context, required_scope: nil, resource: nil)
     config = config_from(server_context)
     introspection = McpToolkit::Auth::Introspection.call(server_context[:bearer_token], config:)
     return error_response("Unauthorized: invalid or expired token") unless introspection.valid?
@@ -61,11 +64,28 @@ class McpToolkit::Tools::Base < MCP::Tool
       return error_response("Unauthorized: token lacks the #{required_scope.inspect} scope")
     end
 
-    text_response(yield)
+    superuser_refusal = superuser_only_refusal(resource, introspection)
+    return superuser_refusal if superuser_refusal
+
+    # Yields the introspection so a discovery tool (`resources`) can HIDE
+    # superuser-only resources from a non-superuser caller (get/list/resource_schema
+    # instead pass `resource:` above to REFUSE a specific one).
+    text_response(yield(introspection))
   rescue McpToolkit::Errors::InvalidParams => e
     error_response("Invalid request: #{e.message}")
   end
 
+  # Refuses a superuser-only resource for a non-superuser caller (get / list /
+  # resource_schema); nil = allowed. Mirrors the authority path's
+  # `ensure_resource_accessible!`. `resources` HIDES such resources instead of
+  # refusing — it filters on `introspection.superuser?` directly.
+  def self.superuser_only_refusal(resource, introspection)
+    return nil unless resource&.superusers_only?
+    return nil if introspection.superuser?
+
+    error_response("Unauthorized: #{resource.name} is restricted to superuser (user-scoped) MCP tokens")
+  end
+
   def self.text_response(payload)
     text = payload.is_a?(String) ? payload : JSON.generate(payload)
     MCP::Tool::Response.new([{ type: "text", text: }])

data/lib/mcp_toolkit/tools/get.rb

@@ -48,7 +48,7 @@ class McpToolkit::Tools::Get < McpToolkit::Tools::Base
     # the scope check (and so an unknown resource is a clean tool error).
     descriptor = resolve_descriptor(resource, config)
     required_scope = config.registry.required_scope_for(descriptor)
-    with_account(server_context, account_id:, required_scope:) do |scope_root|
+    with_account(server_context, account_id:, required_scope:, resource: descriptor) do |scope_root|
       McpToolkit::GetExecutor.call(resource: descriptor, scope_root:, id:, fields:)
     end
   rescue McpToolkit::Errors::InvalidParams => e

data/lib/mcp_toolkit/tools/list.rb

@@ -15,11 +15,26 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
       - limit: page size (default 25, max 100)
       - offset: pagination offset (default 0)
 
-    Per-attribute equality filters:
-      - filter: an object of { <key>: <value> } exact-match filters, applied ON TOP of the
-        account scope (they can only narrow, never widen). Each resource advertises its
-        available filter keys via `resource_schema` (the `filters` array). Unknown keys are
-        rejected.
+    Per-attribute filters:
+      - filter: an object of { <key>: <value> } filters, applied ON TOP of the account scope
+        (they can only narrow, never widen). Each resource advertises its available filter keys
+        and operators via `resource_schema`. Unknown keys are rejected.
+      - A bare value matches by equality. A comma-separated string or an array of scalars
+        matches ANY of the values (IN), e.g. { "status": "booked,canceled" } or
+        { "status": ["booked", "canceled"] }. The string "null" (or a JSON null) matches
+        records where the value is NULL.
+      - An operator condition is an object { "op": <operator>, "value": <value> }, e.g.
+        { "price": { "op": "gteq", "value": 100 } }. An array of conditions ANDs them into a
+        range: { "price": [{ "op": "gteq", "value": 100 }, { "op": "lt", "value": 200 }] }.
+        Each attribute's supported operators are listed in `resource_schema`.
+      - Some filter keys require a companion key (e.g. a polymorphic id and its type) —
+        `resource_schema` advertises these under a relationship's `filter.requires`; pass
+        both keys together.
+
+    Resource-specific filters:
+      - Some resources accept additional filters advertised in `resource_schema` under
+        `resource_filters`. Pass each as a TOP-LEVEL argument (NOT inside `filter`), e.g.
+        { "resource": "...", "<name>": <value> }.
 
     Sparse fieldset:
       - fields: names of the attributes and/or relationships to include in each record, as an
@@ -50,8 +65,8 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
       },
       filter: {
         type: "object",
-        description: "Per-attribute exact-match equality filters, e.g. { \"booking_id\": 42 }. " \
-                     "See a resource's `resource_schema` `filters` for the keys it accepts.",
+        description: "Per-attribute filters, e.g. { \"booking_id\": 42 }. See a resource's " \
+                     "`resource_schema` `filters` for the keys and operators it accepts.",
         additionalProperties: true
       },
       limit: { type: "integer", description: "Page size (default 25, max 100)" },
@@ -65,7 +80,10 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
                      "resource's `resource_schema` for valid attribute and relationship names."
       }
     },
-    required: ["resource"]
+    required: ["resource"],
+    # Resource-specific filters (resource_schema's `resource_filters`) arrive as
+    # top-level arguments, so the schema must not advertise a closed shape.
+    additionalProperties: true
   )
 
   def self.call(server_context:, resource: nil, account_id: nil, **params)
@@ -74,7 +92,7 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
     # the scope check (and so an unknown resource is a clean tool error).
     descriptor = resolve_descriptor(resource, config)
     required_scope = config.registry.required_scope_for(descriptor)
-    with_account(server_context, account_id:, required_scope:) do |scope_root|
+    with_account(server_context, account_id:, required_scope:, resource: descriptor) do |scope_root|
       McpToolkit::ListExecutor.call(resource: descriptor, scope_root:, params:)
     end
   rescue McpToolkit::Errors::InvalidParams => e

data/lib/mcp_toolkit/tools/resource_schema.rb

@@ -7,11 +7,19 @@ class McpToolkit::Tools::ResourceSchema < McpToolkit::Tools::Base
   description <<~DESC.strip
     Describe a single read-only resource in detail. Pass the resource name as `resource` (use
     the `resources` tool to discover names). Returns:
-      - attributes: every field in the response, each with its `type` and a value `format` hint
+      - attributes: every field in the response, each with its `type`, a value `format` hint,
+        whether it is `filterable`, and the filter `operators` it accepts
       - relationships: associated resources emitted in the record's `links`; each names the
         `target_resource` it resolves to (callable via `list`/`get`)
       - standard_filters: ids, updated_since, limit, offset (accepted by the `list` tool)
-      - filters: the per-attribute equality filter keys the `list` tool accepts
+      - filters: the per-attribute equality/operator filter keys the `list` tool accepts in
+        its `filter` argument
+      - resource_filters: resource-specific filters, if any — each is passed as a TOP-LEVEL
+        argument of the `list` tool (NOT inside `filter`), e.g. { "resource": "...",
+        "<name>": <value> }
+      - filter_examples: ready-to-use `filter` payloads for this resource
+    A relationship's `filter` block lists the keys that filter by it; when it names a
+    `requires` key (e.g. a polymorphic id needing its type), pass BOTH keys together.
     The `attributes` and `relationships` names are also the valid values for the `fields` sparse
     fieldset argument on `get` / `list`. Call this before `list` to learn a resource's shape.
   DESC
@@ -31,7 +39,8 @@ class McpToolkit::Tools::ResourceSchema < McpToolkit::Tools::Base
     # Resolve the resource FIRST so its effective required scope gates discovery
     # of THIS resource's shape (and an unknown resource is a clean tool error).
     descriptor = resolve_descriptor(resource, config)
-    with_authentication(server_context, required_scope: config.registry.required_scope_for(descriptor)) do
+    with_authentication(server_context, required_scope: config.registry.required_scope_for(descriptor),
+                                        resource: descriptor) do
       McpToolkit::ResourceSchema.call(descriptor, registry: config.registry)
     end
   rescue McpToolkit::Errors::InvalidParams => e

data/lib/mcp_toolkit/tools/resources.rb

@@ -5,9 +5,10 @@ class McpToolkit::Tools::Resources < McpToolkit::Tools::Base
   tool_name "resources"
   description <<~DESC.strip
     List all read-only resources available via the `list` and `get` tools. Returns each
-    resource's name and a short description. Call this once at the start of a session to learn
-    what exists, then use `resource_schema` for a specific resource's attributes and
-    relationships.
+    resource's name, a short description, whether it accepts filters (`filterable`) and — when
+    present — a usage `note` (read it before interpreting the resource's data). Call this once
+    at the start of a session to learn what exists, then use `resource_schema` for a specific
+    resource's attributes, relationships and filters.
   DESC
 
   input_schema(properties: {})
@@ -16,12 +17,34 @@ class McpToolkit::Tools::Resources < McpToolkit::Tools::Base
     config = config_from(server_context)
     # Discovery requires the registry-level default scope (the satellite's
     # app-wide scope); per-resource scopes are enforced by `get` / `list`.
-    with_authentication(server_context, required_scope: config.registry.default_required_permissions_scope) do
+    with_authentication(server_context,
+                        required_scope: config.registry.default_required_permissions_scope) do |introspection|
       {
-        resources: config.registry.resources.map do |resource|
-          { name: resource.name, description: resource.description }
-        end
+        resources: config.registry.resources
+                         .reject { |resource| resource.superusers_only? && !introspection.superuser? }
+                         .map do |resource|
+                           {
+                             name: resource.name,
+                             description: resource.description,
+                             filterable: filterable?(resource, config),
+                             note: resource.note
+                           }.compact
+                         end
       }
     end
   end
+
+  # Whether the resource can be filtered at all — via the generic allowlist OR a
+  # resource-specific custom filter. Mirrors the authority-path resources tool:
+  # resolving a lazily-declared allowlist may run host code, and one resource's
+  # failing resolution must not take down the whole discovery index, so a raise
+  # degrades to nil (the key is omitted) and the source is retried on the next
+  # read (see Resource#filterable).
+  def self.filterable?(resource, config)
+    resource.filterable_columns.any? || resource.custom_filters.any?
+  rescue StandardError => e
+    config.logger&.warn("mcp_toolkit: filterable resolution failed for #{resource.name}: #{e.message}")
+    nil
+  end
+  private_class_method :filterable?
 end

data/lib/mcp_toolkit/usage_metering/recorder.rb

@@ -65,18 +65,44 @@ class McpToolkit::UsageMetering::Recorder
   end
 
   # `config.usage_flusher` target. Persists the request's accumulated events via the
-  # sink in one shot. No-op when nothing was accumulated.
+  # sink in one shot. No-op when nothing was accumulated. If the batch write fails,
+  # falls back to per-event writes so one un-persistable ("poison") event can't drop
+  # metering for the whole request.
   def flush(controller:)
     events = buffer_for(controller)
     return if events.empty?
 
     @sink.call(events)
   rescue StandardError => e
-    report("failed to flush #{events&.size} event(s)", e)
+    flush_individually(events, e)
   end
 
   private
 
+  # The batch write failed. Retry each event on its own so a single un-persistable
+  # event (a constraint violation, bad encoding) loses ONLY itself instead of
+  # dropping every sibling call's metering — which a caller could otherwise
+  # exploit to evade billing for a whole batch by appending one poison call.
+  # Assumes the batch sink is atomic (nothing persisted on failure — true for
+  # `insert_all`); a non-atomic sink could double-write the events that did land,
+  # so this stays a fallback, not the default path.
+  def flush_individually(events, batch_error)
+    @logger&.warn(
+      "MCP usage tracking: batch flush of #{events.size} event(s) failed " \
+      "(#{batch_error.message}), retrying individually"
+    )
+    events.each do |event|
+      @sink.call([event])
+    rescue StandardError => e
+      report("dropped 1 unpersistable usage event", e)
+    end
+  rescue StandardError
+    # Metering MUST NEVER affect the MCP response. `flush` already runs this from
+    # its rescue, so a raise here (e.g. a misbehaving logger or error_reporter)
+    # would escape into the after_action. Swallow it as the last resort.
+    nil
+  end
+
   def scrub(arguments)
     hash = arguments.to_h
     @parameter_filter ? @parameter_filter.filter(hash) : hash

data/lib/mcp_toolkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module McpToolkit
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/mcp_toolkit.rb

@@ -8,12 +8,15 @@ require "zeitwerk"
 # subfiles that happen to touch them:
 #
 #   json          - JSON.parse / JSON.generate (introspection parse, tools, transport)
-#   digest        - Digest::SHA256 (introspection cache key)
+#   digest        - Digest::SHA256 (introspection cache key; OAuth bridge PKCE digest)
 #   time          - Time.iso8601 / Time.parse (introspection expiry parsing)
-#   securerandom  - SecureRandom.uuid (Session ids)
+#   securerandom  - SecureRandom.uuid (Session ids; OAuth bridge codes/client ids)
+#   uri           - URI.parse / encode_www_form (OAuth bridge redirect construction)
 #   mcp           - the official MCP SDK (Server wraps it; Tools::Base subclasses MCP::Tool)
 #   active_support/concern - Transport::ControllerMethods is an includable concern
 #   active_support/cache   - the default MemoryStore cache_store
+#   active_support/security_utils    - constant-time compare (OAuth bridge PKCE)
+#   active_support/message_encryptor - encrypts the OAuth bridge's cached code payload
 #
 # Two third-party libs are the exception to the centralize-here rule: each is
 # required alongside its owner file rather than up front.
@@ -25,9 +28,12 @@ require "json"
 require "digest"
 require "time"
 require "securerandom"
+require "uri"
 require "mcp"
 require "active_support/concern"
 require "active_support/cache"
+require "active_support/security_utils"
+require "active_support/message_encryptor"
 
 # External dependencies (NOT autoloaded by Zeitwerk — only the gem's own tree is).
 # ActiveSupport's specific core extensions are required up front (rather than full

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp_toolkit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Karol Galanciak
@@ -98,6 +98,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- app/views/mcp_toolkit/oauth/authorize.html.erb
 - config/routes.rb
 - lib/mcp_toolkit.rb
 - lib/mcp_toolkit/auth/authenticator.rb
@@ -109,6 +110,7 @@ files:
 - lib/mcp_toolkit/authority/context.rb
 - lib/mcp_toolkit/authority/controller_methods.rb
 - lib/mcp_toolkit/authority/registry_tool_provider.rb
+- lib/mcp_toolkit/authority/single_tool_provider.rb
 - lib/mcp_toolkit/authority/token.rb
 - lib/mcp_toolkit/authority/tools/base.rb
 - lib/mcp_toolkit/authority/tools/get.rb
@@ -133,17 +135,22 @@ files:
 - lib/mcp_toolkit/gateway/upstream_registry.rb
 - lib/mcp_toolkit/get_executor.rb
 - lib/mcp_toolkit/list_executor.rb
+- lib/mcp_toolkit/oauth.rb
+- lib/mcp_toolkit/oauth/controller_methods.rb
 - lib/mcp_toolkit/protocol.rb
 - lib/mcp_toolkit/rate_limiter.rb
 - lib/mcp_toolkit/registry.rb
 - lib/mcp_toolkit/resource.rb
 - lib/mcp_toolkit/resource_schema.rb
 - lib/mcp_toolkit/serialization.rb
+- lib/mcp_toolkit/serializer/association_descriptor.rb
 - lib/mcp_toolkit/serializer/base.rb
+- lib/mcp_toolkit/serializer/target_ref.rb
 - lib/mcp_toolkit/server.rb
 - lib/mcp_toolkit/session.rb
 - lib/mcp_toolkit/sql_sanitizer.rb
 - lib/mcp_toolkit/token_kinds.rb
+- lib/mcp_toolkit/tool_reference_rewriter.rb
 - lib/mcp_toolkit/tools/authority_base.rb
 - lib/mcp_toolkit/tools/base.rb
 - lib/mcp_toolkit/tools/get.rb