mcp_toolkit 0.4.0 → 0.6.0

data/lib/mcp_toolkit/engine_controllers.rb

@@ -28,7 +28,7 @@ module McpToolkit
   # The controllers built directly under McpToolkit (the engine's routes point at
   # these). McpToolkit::Authority::ServerController is built alongside them but is
   # fetched through McpToolkit::Authority's own const_missing.
-  ENGINE_CONTROLLER_NAMES = %i[ServerController TokensController].freeze
+  ENGINE_CONTROLLER_NAMES = %i[ServerController TokensController OauthController].freeze
 
   # (Re)builds the engine controllers + the authority base from the current
   # config. Idempotent: an existing constant is replaced so a rebuild reflects a
@@ -37,6 +37,11 @@ module McpToolkit
     parent = config.parent_controller.constantize
     define_controller(self, :ServerController, build_server_controller(parent))
     define_controller(self, :TokensController, build_tokens_controller(parent))
+    # Only when the bridge is on — matching its routes, which are equally gated.
+    # Its parent (default ActionController::Base) would otherwise be constantized
+    # on every host, pulling view machinery into an API-only app that never
+    # enables the bridge, and breaking a non-Rails host outright.
+    define_controller(self, :OauthController, build_oauth_controller) if config.oauth_bridge?
     define_controller(Authority, :ServerController, build_authority_server_controller(parent))
     ServerController
   end
@@ -44,15 +49,23 @@ module McpToolkit
   # Undefines the built controllers so the next reference rebuilds them from the
   # then-current config. Called from the engine's `to_prepare` on every reload.
   def self.reset_engine_controllers!
-    [[self, :ServerController], [self, :TokensController], [Authority, :ServerController]].each do |mod, name|
+    ENGINE_CONTROLLER_NAMES.map { |name| [self, name] }.push([Authority, :ServerController]).each do |mod, name|
       mod.send(:remove_const, name) if mod.const_defined?(name, false)
     end
   end
 
-  # The SATELLITE transport controller the engine mounts (unchanged behavior; the
-  # SDK-backed path). Built lazily only so its parent is read after config.
+  # The transport controller the engine mounts at POST/GET/DELETE /mcp, chosen by
+  # ROLE so a single `mount McpToolkit::Engine => "/mcp"` works for either kind of
+  # host: an AUTHORITY (`auth_role == :authority`) gets the hand-rolled dispatcher
+  # path (Authority::ControllerMethods — local token auth, gateway proxying, usage
+  # metering, rate limiting), a SATELLITE (the default) gets the SDK-backed path
+  # (Transport::ControllerMethods, which forwards tokens to a central app). Built
+  # lazily so both `config.parent_controller` and `config.auth_role` are read after
+  # the host's initializer/to_prepare has run. A host that would rather draw its own
+  # routes still subclasses McpToolkit::Authority::ServerController directly.
   def self.build_server_controller(parent)
-    Class.new(parent) { include McpToolkit::Transport::ControllerMethods }
+    concern = config.authority? ? McpToolkit::Authority::ControllerMethods : McpToolkit::Transport::ControllerMethods
+    Class.new(parent) { include concern }
   end
 
   # The AUTHORITY introspection endpoint the engine mounts at
@@ -88,12 +101,74 @@ module McpToolkit
     end
   end
 
+  # The OAuth authorization bridge the engine mounts at `<mcp>/oauth/*` and the
+  # host draws at the two `.well-known` metadata paths.
+  #
+  # Built from `config.oauth_parent_controller`, NOT the `parent_controller` its
+  # siblings use: the transport is a JSON-only endpoint that a host rightly points
+  # at ActionController::API, which cannot render an HTML view — and this
+  # controller's authorization page is one. Sharing the parent would force a host
+  # to weaken its transport's superclass just to enable the bridge. Read lazily
+  # here, like the rest, so the host's initializer/to_prepare has already run.
+  def self.build_oauth_controller
+    warn_about_per_process_cache_store
+    Class.new(config.oauth_parent_controller.constantize) { include McpToolkit::Oauth::ControllerMethods }
+  end
+
+  # Said once per boot (this runs from the engine's `to_prepare`), because the
+  # failure it predicts is otherwise hard to read as a misconfiguration at all:
+  # with a per-process cache the two legs of a flow land on different workers, so
+  # the exchange fails (N-1)/N of the time — intermittently, and only AFTER the
+  # operator has already pasted a live token. A warning rather than a gate,
+  # because one process is genuinely fine and `Rails.cache` is a MemoryStore in a
+  # stock development environment.
+  def self.warn_about_per_process_cache_store
+    return unless config.oauth_per_process_cache_store?
+
+    config.logger&.warn(
+      "[mcp_toolkit] The OAuth bridge is enabled but config.cache_store is an in-process MemoryStore. " \
+      "That is safe in a single process only: on a multi-worker deployment an authorization code issued " \
+      "by one worker is invisible to the worker that redeems it, so the flow fails intermittently AFTER " \
+      "the operator has pasted their token. Point config.cache_store at a shared store (Rails.cache " \
+      "backed by Redis/Memcached) before running the bridge in production."
+    )
+  end
+
   # The AUTHORITY base controller a host subclasses (the recommended path for a
   # host whose rate-limit/usage/account hooks touch app models).
   def self.build_authority_server_controller(parent)
     Class.new(parent) { include McpToolkit::Authority::ControllerMethods }
   end
 
+  # Draws the OAuth bridge's two metadata documents. A `/.well-known/*` path
+  # cannot be drawn by an engine mounted under a path, so it has to live in the
+  # host's own route set. The host calls this at the TOP LEVEL — not inside a
+  # locale/format/constraint scope, which would prefix the paths out of view:
+  #
+  #   # config/routes.rb
+  #   Rails.application.routes.draw do
+  #     McpToolkit.draw_oauth_metadata_routes(self)
+  #     mount McpToolkit::Engine => "/mcp"
+  #     # ...
+  #   end
+  #
+  # The paths are PATH-SCOPED to the engine's mount
+  # (`/.well-known/oauth-protected-resource/mcp`), so this claims NOTHING
+  # origin-global and cannot collide with an OAuth provider the host already runs
+  # — see Configuration#oauth_protected_resource_path for why that matters. A host
+  # mounted at its origin root gets the bare paths instead, which is correct there.
+  #
+  # A no-op unless the bridge is configured, so the call can sit in a host's routes
+  # unconditionally across environments.
+  def self.draw_oauth_metadata_routes(mapper)
+    return unless config.oauth_bridge?
+
+    mapper.get config.oauth_protected_resource_path,
+               to: "mcp_toolkit/oauth#protected_resource", format: false
+    mapper.get config.oauth_authorization_server_path,
+               to: "mcp_toolkit/oauth#authorization_server", format: false
+  end
+
   # Removes an existing same-named constant (avoiding a redefinition warning on a
   # rebuild) before setting the freshly-built class.
   def self.define_controller(mod, name, klass)

data/lib/mcp_toolkit/filtering.rb

@@ -4,15 +4,21 @@
 # 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" })
+#     - a comma-separated string becomes an IN lookup: filter: { status: "a,b" }
+#     - an Array of scalars becomes an IN lookup too:  filter: { status: ["a", "b"] }
+#     - the string "null" (or a JSON null) matches NULL rows: filter: { canceled_at: "null" }
+#       (as a SCALAR value only — inside an IN set, elements must be non-null
+#       scalars and "null" stays a literal string, because SQL `IN` cannot match
+#       NULL; a null-or-nothing condition is expressed as a scalar filter)
 #   * 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, gt, gteq, lt, lteq        — numeric / datetime columns (+ in for date)
 #   eq, not_eq, in, matches, does_not_match — string columns (matches => case-insensitive LIKE)
 #   eq, not_eq                            — boolean columns
+#   eq, in                                — any other column type (uuid, enum, jsonb, ...)
 #
 # 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
@@ -24,17 +30,29 @@ module McpToolkit::Filtering
     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,
+    date: %w[eq not_eq gt gteq lt lteq in].freeze,
+    string: %w[eq in not_eq matches does_not_match].freeze,
+    text: %w[eq in not_eq matches does_not_match].freeze,
     boolean: %w[eq not_eq].freeze
   }.freeze
 
+  # Operators for a column type OUTSIDE the table above (uuid, enum, jsonb,
+  # citext, ...): plain equality/IN still work on any column, so they stay
+  # available rather than turning "cannot be filtered with operators" — which
+  # also matches the API contract this replaces for adopting hosts.
+  DEFAULT_OPERATORS = %w[eq in].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"
 
+  # Operators for which a null value is meaningful: eq/in render `IS NULL`,
+  # not_eq renders `IS NOT NULL`. Every other operator rejects null explicitly —
+  # a comparison or LIKE against NULL can never match a row in SQL, so passing
+  # one through silently would return a wrong (empty) result.
+  NULL_ACCEPTING_OPERATORS = %w[eq in not_eq].freeze
+
   # @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
@@ -46,14 +64,40 @@ module McpToolkit::Filtering
     if compound?(value)
       apply_condition(relation, column, value, config:)
     elsif collection?(value)
+      enforce_filter_limit!(value.length, config)
       value.inject(relation) { |rel, condition| apply_condition(rel, column, condition, config:) }
+    elsif mixed_collection?(value)
+      raise McpToolkit::Errors::InvalidParams,
+            "a filter array must contain either only { op:, value: } conditions or only bare values"
     else
-      # Bare value: equality. A comma-separated string becomes an IN lookup,
-      # matching the implicit `eq` semantics.
-      relation.where(column => equality_value(value))
+      # Bare value(s): equality. Under the default :tokenized semantics a
+      # comma-separated string or an Array of scalars becomes an IN lookup and
+      # "null" / a JSON null matches NULL rows; under :literal the value is
+      # handed to the WHERE clause verbatim (see
+      # Configuration#bare_filter_value_semantics).
+      relation.where(column => bare_value(value, config))
     end
   end
 
+  def self.bare_value(value, config)
+    if value.is_a?(Hash)
+      raise McpToolkit::Errors::InvalidParams,
+            "unsupported filter value; use a bare scalar, an array of scalars, " \
+            "or { op:, value: } condition(s)"
+    end
+
+    # An Array bare value renders as `WHERE column IN (...)` under EITHER
+    # semantics, so bound its size before the branch below. The :literal path
+    # returns the array verbatim and would otherwise skip the limit that
+    # equality_value/equality_value_set enforce only on the :tokenized path —
+    # defeating the query-complexity guard on the new host-compatibility path.
+    enforce_filter_limit!(value.length, config) if value.is_a?(Array)
+
+    return value if config.bare_filter_value_semantics == :literal
+
+    equality_value(value, config:)
+  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"))
@@ -64,6 +108,13 @@ module McpToolkit::Filtering
     value.is_a?(Array) && value.any? && value.all? { |element| compound?(element) }
   end
 
+  # An Array mixing operator conditions with bare values — rejected explicitly:
+  # neither the AND-of-conditions nor the IN-set reading fits, and treating it as
+  # either would silently match the wrong rows.
+  def self.mixed_collection?(value)
+    value.is_a?(Array) && value.any? { |element| compound?(element) }
+  end
+
   def self.condition_hash?(value)
     value.is_a?(Hash)
   end
@@ -73,7 +124,7 @@ module McpToolkit::Filtering
     raise McpToolkit::Errors::InvalidParams, "a filter operator is required" if operator.empty?
 
     type = column_type(relation, column)
-    validate_operator!(operator, type, column)
+    validate_operator!(operator, type, column, config:)
 
     raw = fetch(condition, :value)
     relation.where(predicate_for(relation, column, operator, raw, config:))
@@ -94,12 +145,24 @@ module McpToolkit::Filtering
     model.columns_hash[column.to_s]&.type
   end
 
-  def self.validate_operator!(operator, type, column)
-    allowed = OPERATORS_BY_TYPE[type]
-    if allowed.nil?
+  # Operators an attribute of the given column type accepts — the single source
+  # for both the schema's advertisement and the executor's enforcement, so the
+  # two can never disagree. `[]` for an attribute with no backing column (which
+  # cannot be filtered with operators). A host can override sets per type via
+  # config.filter_operator_overrides (e.g. to preserve a pre-gem contract).
+  def self.operators_for(type, config: McpToolkit.config)
+    return [] if type.nil?
+
+    config.filter_operator_overrides.fetch(type) { OPERATORS_BY_TYPE.fetch(type, DEFAULT_OPERATORS) }
+  end
+
+  def self.validate_operator!(operator, type, column, config:)
+    if type.nil?
       raise McpToolkit::Errors::InvalidParams,
             "'#{column}' cannot be filtered with operators"
     end
+
+    allowed = operators_for(type, config:)
     return if allowed.include?(operator)
 
     raise McpToolkit::Errors::InvalidParams,
@@ -113,25 +176,55 @@ module McpToolkit::Filtering
   # 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
+    method = arel_operator(operator, value)
+
+    # Defense in depth: only a known-safe Arel predication may ever reach
+    # public_send. operators_for/validate_operator! already gate this and
+    # config.filter_operator_overrides is validated at assignment — but the
+    # value handed to any operator outside eq/in/matches is passed through
+    # VERBATIM (normalize_value's else branch), so an operator that slipped in
+    # (e.g. a host-configured "extract") must never be dispatched: Arel would
+    # interpolate the request value as raw SQL. This is the last guard before
+    # the metaprogramming call.
+    unless AREL_PREDICATIONS.include?(method)
+      raise McpToolkit::Errors::InvalidParams, "'#{operator}' is not a supported filter operator"
+    end
 
     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)
+      model.arel_table[column.to_sym].public_send(method, value)
     else
-      Predicate.new(column.to_sym, arel_operator, value)
+      Predicate.new(column.to_sym, method, 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.
+  # `eq` fans out to an IN lookup (normalize_value turns its value into a set) —
+  # EXCEPT against NULL: Arel renders `in(nil)` as `IN (NULL)`, which matches no
+  # rows in SQL, so eq/in with a nil value stay/become `eq` (rendered `IS NULL`).
+  def self.arel_operator(operator, value)
+    return operator unless %w[eq in].include?(operator)
+
+    value.nil? ? "eq" : "in"
+  end
+
+  # `eq` / `in` against a (possibly comma-separated string or Array) value
+  # becomes an IN set. `matches` / `does_not_match` wrap the value in `%...%`
+  # with LIKE wildcards escaped so they match literally. `null` / a JSON null
+  # => nil for the NULL_ACCEPTING_OPERATORS, rejected for every other operator.
   def self.normalize_value(operator, raw, config:)
-    return nil if raw.to_s == NULL_TOKEN
+    if raw.nil? || raw.to_s == NULL_TOKEN
+      unless NULL_ACCEPTING_OPERATORS.include?(operator)
+        raise McpToolkit::Errors::InvalidParams,
+              "'#{operator}' does not accept a null value " \
+              "(only #{NULL_ACCEPTING_OPERATORS.join("/")} do)"
+      end
+      return nil
+    end
 
     case operator
     when "eq", "in"
-      raw.to_s.split(",")
+      resolved = equality_value(raw, config:)
+      resolved.is_a?(Array) ? resolved : [resolved]
     when "matches", "does_not_match"
       "%#{config.sql_sanitizer.sanitize_sql_like(raw.to_s)}%"
     else
@@ -139,11 +232,63 @@ module McpToolkit::Filtering
     end
   end
 
-  def self.equality_value(value)
-    return nil if value.to_s == NULL_TOKEN
+  # A bare (non-operator) filter value resolved for equality: `"null"` / nil =>
+  # nil (matches NULL rows); a comma-separated string => its parts (IN); an
+  # Array => an IN set of non-null scalars (see .equality_value_set). Any other
+  # non-scalar (an op-less Hash) is rejected — passed through it would reach the
+  # database as a malformed condition.
+  def self.equality_value(value, config: McpToolkit.config)
+    return equality_value_set(value, config:) if value.is_a?(Array)
+    return nil if value.nil? || value.to_s == NULL_TOKEN
+
+    if value.is_a?(Hash)
+      raise McpToolkit::Errors::InvalidParams,
+            "unsupported filter value; use a bare scalar, an array of scalars, " \
+            "or { op:, value: } condition(s)"
+    end
 
     str = value.to_s
-    str.include?(",") ? str.split(",") : value
+    return value unless str.include?(",")
+
+    parts = str.split(",")
+    enforce_filter_limit!(parts.length, config)
+    parts
+  end
+
+  # Resolves an Array filter value into a flat IN set. Elements must be non-null
+  # scalars (comma-separated strings are split in); nil / nested Array / Hash
+  # elements are rejected explicitly — SQL `IN` cannot match NULL (Arel renders
+  # a nil element as the never-matching `IN (..., NULL)`), and a non-scalar
+  # element is a malformed condition either way. The `"null"` token is NOT
+  # resolved inside a set for the same reason: it stays a literal string, and a
+  # null-or-nothing condition is expressed as a scalar filter value instead.
+  def self.equality_value_set(values, config: McpToolkit.config)
+    resolved = values.flat_map do |element|
+      if element.nil? || element.is_a?(Array) || element.is_a?(Hash)
+        raise McpToolkit::Errors::InvalidParams,
+              "an IN-set filter must contain only non-null scalar values; " \
+              "to match NULL rows pass \"null\" as the filter's single value"
+      end
+
+      str = element.to_s
+      str.include?(",") ? str.split(",") : [element]
+    end
+    enforce_filter_limit!(resolved.length, config)
+    resolved
+  end
+
+  # Bounds how many values an IN-set resolves to (and how many operator
+  # conditions may be ANDed on one attribute, enforced by .apply), so a valid
+  # token can't emit an unbounded IN clause / AND-chain — oversized SQL + Arel
+  # AST and expensive query planning, which matters because rate limiting is
+  # opt-in (config.rate_limit_max_requests). Disabled when
+  # config.max_filter_values is nil.
+  def self.enforce_filter_limit!(count, config)
+    max = config.max_filter_values
+    return if max.nil? || count <= max
+
+    raise McpToolkit::Errors::InvalidParams,
+          "a filter may carry at most #{max} values or conditions (got #{count})"
   end
 
   # Portable representation of an operator predicate, applied by the in-memory

data/lib/mcp_toolkit/gateway/aggregator.rb

@@ -96,20 +96,40 @@ class McpToolkit::Gateway::Aggregator
     # Degrade gracefully: omit this upstream's tools, don't cache the failure.
     config.logger&.error("MCP upstream #{upstream.key} tools/list failed, omitting: #{e.message}")
     []
+  rescue StandardError => e
+    # Backstop: any OTHER error while processing ONE upstream (e.g. a malformed
+    # tool definition) must degrade just that upstream, never 500 the whole
+    # aggregated tools/list and take every sibling upstream down with it.
+    config.logger&.error("MCP upstream #{upstream.key} tools/list errored, omitting: #{e.class}: #{e.message}")
+    []
   end
 
   def live_definitions(upstream, bearer_token:)
     client = McpToolkit::Gateway::Client.new(upstream:, bearer_token:, config:)
-    client.tools_list.map do |definition|
+    client.tools_list.filter_map do |definition|
       namespaced(upstream, definition)
     end
   end
 
-  # Re-keys an upstream tool definition into the gateway's aggregate namespace.
+  # Re-keys an upstream tool definition into the gateway's aggregate namespace,
+  # rewriting backticked generic-tool references in its prose too — a proxied
+  # `list` saying "use the `resources` tool" must point at `<app>__resources`,
+  # the only name that exists on THIS server's tools/list. The rewrite returns a
+  # fresh structure, so the upstream's (possibly cached) definition is never
+  # mutated.
   def namespaced(upstream, definition)
-    definition = definition.dup
-    definition["name"] = upstream.name_for(definition["name"])
-    definition
+    # A hostile/broken upstream can return a non-Hash entry (or a Hash with no
+    # "name"); skip it (logging the shape, never its content) so one bad entry
+    # degrades to omission instead of raising through the whole aggregate.
+    unless definition.is_a?(Hash) && definition["name"]
+      config.logger&.warn("MCP upstream #{upstream.key}: skipping a malformed tool entry (#{definition.class})")
+      return nil
+    end
+
+    rewritten = McpToolkit::ToolReferenceRewriter.rewrite(definition, upstream.name_for(""))
+    rewritten = rewritten.dup if rewritten.equal?(definition)
+    rewritten["name"] = upstream.name_for(definition["name"])
+    rewritten
   end
 
   def cache

data/lib/mcp_toolkit/list_executor.rb

@@ -66,10 +66,20 @@ class McpToolkit::ListExecutor
     relation
   end
 
-  # Order by `id` when the primary key is numeric; otherwise by `created_at`
-  # (a non-numeric PK does not sort meaningfully).
+  # Order by `id` when the primary key is numeric; otherwise per
+  # `config.non_numeric_pk_order`: `created_at` with the primary key as a
+  # tiebreaker (default — rows bulk-inserted in one transaction share a
+  # `created_at`, and without a total order offset pagination could duplicate
+  # or skip rows), or the primary key alone for a host preserving a pre-gem
+  # order-by-id contract. `numeric_primary_key?` returning false guarantees the
+  # model exposes a non-nil primary key, so it can be read directly here.
   def apply_order(relation)
-    relation.order(numeric_primary_key? ? :id : :created_at)
+    return relation.order(:id) if numeric_primary_key?
+
+    pk = resource.model.primary_key.to_sym
+    return relation.order(pk) if McpToolkit.config.non_numeric_pk_order == :primary_key
+
+    relation.order(:created_at, pk)
   end
 
   def numeric_primary_key?
@@ -98,9 +108,10 @@ class McpToolkit::ListExecutor
 
     mapping = resource.filterable_columns
     validate_filter_keys!(filter, mapping)
+    validate_filter_companions!(filter)
 
     filter.each do |request_key, value|
-      next if value.nil? || value == ""
+      next if skipped_filter_value?(value)
 
       column = mapping[request_key.to_sym]
       relation = McpToolkit::Filtering.apply(relation, column, value)
@@ -108,6 +119,35 @@ class McpToolkit::ListExecutor
     relation
   end
 
+  # Under :tokenized semantics an empty string means "no filter" (a JSON null
+  # still flows through as an IS NULL filter, like the "null" token — see
+  # McpToolkit::Filtering); under :literal every value reaches the WHERE clause
+  # verbatim.
+  def skipped_filter_value?(value)
+    value == "" && McpToolkit.config.bare_filter_value_semantics != :literal
+  end
+
+  # A filter key may declare a companion key it cannot be used without (e.g. a
+  # polymorphic foreign key is type-ambiguous without its `*_type`) — see
+  # Resource#filter_requirements. Rejected up front rather than producing a
+  # subtly wrong WHERE. A key whose value the apply loop will SKIP counts as
+  # not provided — a skipped ("" under :tokenized) companion must not satisfy
+  # the requirement, or the FK would be applied alone: exactly the
+  # type-ambiguous WHERE the requirement exists to prevent.
+  def validate_filter_companions!(filter)
+    requirements = resource.filter_requirements
+    return if requirements.empty?
+
+    provided = filter.reject { |_key, value| skipped_filter_value?(value) }.keys.map(&:to_sym)
+    requirements.each do |key, required|
+      next unless provided.include?(key)
+      next if provided.include?(required)
+
+      raise McpToolkit::Errors::InvalidParams,
+            "filter attribute #{key} requires #{required} to also be provided"
+    end
+  end
+
   def validate_filter_keys!(filter, mapping)
     keys = filter.keys.map(&:to_sym)
     unknown = keys - mapping.keys
@@ -123,6 +163,10 @@ class McpToolkit::ListExecutor
     return relation if params[:ids].blank?
 
     ids = params[:ids].to_s.split(",").map(&:strip).compact_blank
+    # Bound the IN-set the same way the per-attribute filters are bounded — the
+    # top-level `ids` param builds `WHERE id IN (...)` on its own path, so it
+    # must honor config.max_filter_values too (else it's an unbounded IN clause).
+    McpToolkit::Filtering.enforce_filter_limit!(ids.length, McpToolkit.config)
     ids.empty? ? relation : relation.where(id: ids)
   end