mcp_toolkit 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e99039b1f2109b3da40c5d271338fbefc565bce7fb472b36947caf322d0ab3f8
-  data.tar.gz: db79d656f89ce7566e5437956a8f0feac0ba9f4a906896078db3cee4879b512b
+  metadata.gz: d9e89469906c5d75ea46174ecf1e7368ffbe93669ec80526e559f683c778516b
+  data.tar.gz: 6c97881a9edbd3df1185069364c99457e90fecb4ecf95a7a6c85612e9f5d0d2e
 SHA512:
-  metadata.gz: '0804f99b21ac1cf54aa5d379957b1a3bec5af4a2aa3630bb2c0210d3b594cb98cf56dc3af4cc3693e1d872b2855ade1f1f2dc97a03760f56d16af85994f56547'
-  data.tar.gz: 07626c80512de4d475cd1cd4b7fbe31a210718dbc8a5d2b81a97009900f8cc1df91b79cae903bfc1b0769a049ab224232cccadfd2b86f61c50ce83e5e08766f5
+  metadata.gz: 21daf10ed0e045d978a698482d87581222994cb3ba7aba15f6252f236b5d102bb71a27c29e6d0f05f2e762889fd3dbc8fb58fb3ca5c8293870b46d81145bf540
+  data.tar.gz: 96ddb6e0fb9c72353b17d725a171b6c065537cabb55b8d9f3d208d6bad71bf76291c5394678dedba38e742474d6351234bef6d56240fff0dd9ed5649ce465196

data/CHANGELOG.md

@@ -1,3 +1,234 @@
+## [0.5.0] - 2026-07-14
+
+Authority-path discoverability + backward-compatibility work (driven by an
+adopting host's parity review against the API contract the gem replaced), plus a
+role-aware mountable engine so an authority mounts its transport in one line, and
+filter-path hardening from a security review.
+
+### Security
+
+- `config.filter_operator_overrides` now rejects, at assignment time, any
+  operator outside `Filtering::AREL_PREDICATIONS`. Those are the only operators
+  the gem maps onto an Arel predication that binds/quotes its value; a host that
+  configured anything else (e.g. `"extract"`) would have it `public_send` to an
+  Arel attribute with the request value passed through verbatim — an
+  SQL-injection surface. A defense-in-depth guard in `Filtering.predicate_for`
+  also refuses to dispatch any non-predication operator, so the metaprogramming
+  call can never be reached with an unvetted method name. The default and
+  intended (`{ text: %w[eq in] }`-style) configurations were never vulnerable.
+- New `config.max_filter_values` (default `500`, `nil` disables) caps how many
+  values an IN-set filter may resolve to and how many operator conditions may be
+  ANDed on one attribute, so a valid token can't emit an unbounded IN clause /
+  AND-chain (oversized SQL + Arel AST + expensive planning). Rate limiting
+  remains opt-in via `config.rate_limit_max_requests`.
+- Added an injection-safety regression spec that renders real Arel SQL through a
+  correctly-escaping connection and asserts hostile payloads stay inside escaped
+  string literals (the prior fake connection did not escape quotes, so it could
+  not have caught an escaping regression).
+- New `config.max_batch_size` (default `50`, `nil` disables) caps the number of
+  JSON-RPC calls a single authority POST batch may carry. Rate limiting is a
+  per-HTTP-request `before_action`, so an uncapped batch let one request fan out
+  unbounded work (N tool executions / N blocking upstream calls) under a single
+  rate-limit tick; an over-size batch is now rejected as a JSON-RPC error before
+  any element runs.
+- The top-level `list` `ids` filter now honors `config.max_filter_values` — it
+  built `WHERE id IN (...)` on its own path, bypassing the cap that already
+  bounds the per-attribute filters.
+- The authority dispatcher no longer relays an unexpected exception's message to
+  the caller: an unhandled `StandardError` returns a generic "Internal error"
+  (full detail still logged), so `ActiveRecord::StatementInvalid` SQL, internal
+  class names, or an internal hostname can't leak in the JSON-RPC error.
+- The gateway `tools/list` aggregator now degrades a single malformed upstream
+  tool entry (a non-Hash / name-less definition) by skipping it, and wraps each
+  upstream's processing so any unexpected error omits only that upstream instead
+  of 500-ing the whole aggregated list for every upstream.
+- Usage metering flush falls back to per-event writes when the batch write
+  fails, so one un-persistable ("poison") event can no longer drop metering for
+  a whole request's batch (a billing-evasion vector).
+- The satellite tool path (`get` / `list` / `resource_schema` / `resources`) now
+  enforces `Resource#superusers_only!` — previously only the authority path did,
+  so a superuser-only resource served via a satellite was readable/discoverable
+  by any valid token (still account-scoped, so not cross-tenant). `get`/`list`/
+  `resource_schema` refuse it for a non-superuser; `resources` hides it.
+- The authority dispatcher now strips a caller-supplied `context` from a tool's
+  arguments before the keyword splat. `tool.call(context:, **arguments)` let a
+  splatted `context` argument OVERRIDE the gem-resolved `Authority::Context`
+  (auth-context injection) — harmless for the gem's own tools (a JSON context
+  fails closed with a NoMethodError) but the gem handed attacker-controlled data
+  as `context` to arbitrary host tools.
+- The gateway's transport-failure relay no longer leaks the internal upstream
+  host:port. `translate_upstream_call_error` returned `InternalError.new(error.message)`
+  for a transport failure, whose message is `"Failed to open TCP connection to
+  <host>:<port>"`; it now returns a generic error (the proxy already logs the
+  detail). A first-party upstream JSON-RPC error is still relayed verbatim.
+- `Tools::AuthorityBase#execute` no longer relays an unexpected exception's
+  message to the caller — it returns a generic "Internal error" (detail logged),
+  matching the dispatcher's own catch-all.
+- Usage metering's per-event flush fallback now cannot escape into the response:
+  a misbehaving `logger`/`error_reporter` in `flush_individually` is swallowed as
+  a last resort, preserving the "metering never affects the MCP response"
+  invariant.
+
+### Added
+
+- The mountable `McpToolkit::Engine` is now ROLE-AWARE: the
+  `McpToolkit::ServerController` it mounts at POST/GET/DELETE /mcp is built from
+  `config.auth_role` — an authority host gets the hand-rolled dispatcher path
+  (local token auth, gateway proxying, usage metering, rate limiting), a
+  satellite gets the SDK-backed path. So an authority now mounts its whole
+  transport with `mount McpToolkit::Engine => "/mcp"` (identical to a satellite)
+  instead of hand-drawing the four routes against a subclass of
+  `McpToolkit::Authority::ServerController` — which is still supported for a host
+  that prefers to draw its own routes.
+- `resource_schema` surfaces a resource's custom filters (`Resource#filter`)
+  under `resource_filters` — name, type and description — so a client can
+  discover them. The `Resource#filter` docs always promised this; nothing
+  delivered it, leaving custom filters functional but unadvertised.
+- The `resources` tool returns `filterable` (whether the resource accepts any
+  filter — allowlist or custom) and the resource's usage `note` alongside
+  name/description, so caveats surface at browse time, before a client picks a
+  resource.
+- The `list` tool description documents the full filter grammar — bare
+  equality, comma/array IN sets, the `"null"` token, `{ op:, value: }`
+  conditions and AND-ed condition arrays — plus resource-specific top-level
+  filters. Previously the operator payload shape was not documented anywhere a
+  client could see at runtime.
+- Bare equality filters accept an Array of scalars as an IN set
+  (`filter: { status: ["a", "b"] }`). Previously the array was stringified and
+  comma-split into fragments that silently matched nothing.
+- A JSON null filter value filters for `IS NULL` (like the `"null"` string
+  token). Previously it was silently ignored.
+
+All of the above applies to the SATELLITE generic tools too: they share the
+executors and schema builder, so their `resources` output gains
+`filterable`/`note`, their `resource_schema` output gains `resource_filters`,
+and their descriptions document the same filter grammar.
+
+### Host-compatibility seams (full parity with a pre-gem API contract)
+
+For a host migrating an EXISTING MCP endpoint onto the gem, whose clients hold
+the pre-gem contract:
+
+- `config.bare_filter_value_semantics = :literal` — bare filter values reach
+  the WHERE clause verbatim (`"a,b"` is one literal string, `"null"` is the
+  literal string, `""` matches empty-string rows, an Array — including nil
+  elements — gets the adapter's native IN / OR-IS-NULL handling). The default
+  `:tokenized` keeps the gem's comma/IN/`"null"`-token grammar. Operator
+  conditions are identical in both modes.
+- `config.non_numeric_pk_order = :primary_key` — lists of non-numeric-PK
+  resources order by the primary key alone, preserving a pre-gem
+  ORDER BY id contract. The default `:created_at` keeps chronological pages
+  with the PK tiebreaker.
+- `Resource#filter_requirements` — declares companion-key requirements (e.g. a
+  polymorphic foreign key that is type-ambiguous without its `*_type`): the
+  list executor rejects the key without its companion ("filter attribute X
+  requires Y to also be provided") and `resource_schema` advertises the
+  requirement, restoring safe polymorphic-FK filtering instead of dropping the
+  key from the allowlist. Accepts a Hash or a lazily-resolved callable, like
+  `filterable`.
+- `resource_schema` output restores the remaining pre-gem keys: top-level
+  `sparse_fieldsets: true` and `filter_examples` (ready-to-use payloads built
+  from the resource's own attributes/relationships), `relationships[].resource`
+  (nullable; `target_resource` remains as the resolved alias) and
+  `relationships[].filter` (`keys` / `type` / `operators` / `requires`).
+  Top-level nil keys are compacted (a nil `note` is omitted again).
+- Operator conditions work on ANY column type: types outside the operator
+  table (uuid, enum, jsonb, ...) accept `eq` / `in` instead of failing with
+  "cannot be filtered with operators", and `date` columns accept `in` again.
+- The `list` tools' input schemas declare `additionalProperties: true`
+  explicitly (resource-specific filters arrive as top-level arguments).
+- `config.register_upstreams_from_env(mapping, env: ENV)` — declares gateway
+  upstreams from a `{ key => env var }` map: resets the registry first
+  (idempotent across code reloads) and skips blank urls, the two gotchas every
+  authority host re-discovers.
+- `config.tool_provider` composes a sensible default when unset: the generic
+  Registry-backed provider (only when resources are registered — a pure
+  gateway still contributes nothing) plus `config.extra_tool_providers`
+  (providers, or bare tool classes auto-wrapped in the new
+  `Authority::SingleToolProvider`). Hosts with one bespoke tool no longer
+  hand-roll provider plumbing; assigning `tool_provider` explicitly still
+  takes full control.
+- `McpToolkit::Serializer::AssociationDescriptor` + `TargetRef` — the exported
+  structs for the association duck-type the schema builder and field selection
+  probe, so a host adapting its own serializer framework doesn't re-derive the
+  field names by hand.
+- The authority `list` tool's served description states the bare-value grammar
+  the host ACTUALLY configured: under `:literal` semantics the comma/`"null"`
+  tokenization bullet is replaced by the literal-matching one, so served docs
+  never advertise filters that would silently match nothing.
+- The authority tools are advertised in alphabetical base-name order
+  (`get`, `list`, `resource_schema`, `resources`) and string/text operator
+  lists keep the pre-gem order (`eq, in, not_eq, matches, does_not_match`) —
+  JSON arrays are ordered, so byte-diffing clients see no reorder.
+- `get` / `resource_schema` reject arguments outside their input schema with
+  InvalidParams instead of silently ignoring them (pre-gem parity — they were
+  strict Ruby kwargs; `account_id` is always tolerated, the transport consumes
+  it). `resources` and `list` stay tolerant of extra arguments, also matching
+  the pre-gem contract (`list`'s extras are the resource-specific filters).
+- `config.filter_operator_overrides` — per-column-type overrides for the
+  operator sets advertised by `resource_schema` AND enforced by the executor
+  (single source, they cannot disagree), so a host can preserve a pre-gem
+  operator contract exactly (e.g. `{ text: %w[eq in], date: %w[eq in] }`).
+  Empty by default: the gem's own sets apply.
+- A companion key whose value the executor would SKIP (an empty string under
+  `:tokenized` semantics) no longer satisfies a `filter_requirements` pairing —
+  the foreign key is rejected rather than applied alone (type-ambiguous).
+- `resource_filters` entries keep nil `type`/`description` keys (pre-gem
+  shape) instead of compacting them; the relationship `filter_examples`
+  companion sample value is `"User"` (pre-gem sample) rather than `"..."`.
+
+### Known operator-path delta (documented, not reverted)
+
+- `{ op: "in", value: "a,b" }` now splits the comma-separated string into an
+  IN set (previously `in` matched the literal string `'a,b'` as a single
+  element; only `eq` split). Comma-separated STRING ELEMENTS inside an Array
+  value are split the same way — under the tokenized operator grammar there is
+  no way to express a literal comma inside an IN element; a literal
+  comma-containing match is expressed as a bare equality value (which hosts on
+  `:literal` semantics match verbatim).
+
+### Fixed
+
+- Generic tool descriptions and input schemas rewrite sibling-tool references
+  (e.g. "use the `resources` tool") to carry `config.generic_tool_name_prefix`,
+  so a host that namespaces its generic tools no longer serves prose pointing
+  at unprefixed tool names that do not exist on its server. The gateway
+  aggregator applies the same rewrite with the upstream namespace, so a proxied
+  `<app>__list` no longer points a client at the upstream's bare tool names
+  (`McpToolkit::ToolReferenceRewriter`).
+- `eq` / `in` operator conditions against `"null"` / null render `IS NULL`
+  instead of `IN (NULL)`, which matches no rows in SQL.
+- `eq` / `in` operator conditions accept an Array `value` (previously
+  stringified and comma-split into fragments).
+- Non-numeric-PK resources order by `created_at` WITH the primary key as a
+  tiebreaker, restoring a total order so offset pagination cannot duplicate or
+  skip rows that share a timestamp (e.g. bulk inserts).
+- An Array mixing `{ op:, value: }` conditions with bare values is rejected
+  with InvalidParams instead of being misread as bare equality values.
+- One resource's failing lazy `filterable` resolution (e.g. a transient DB
+  error inside a host-supplied callable) no longer fails the whole `resources`
+  discovery index: the `filterable` key is omitted for that resource and the
+  unresolved source is retried on the next read instead of permanently and
+  silently resolving the allowlist to `{}`.
+
+### Changed (explicit over silent — each previously returned a wrong or empty result)
+
+- IN-set elements must be non-null scalars: a nil, Hash or nested-Array element
+  inside an Array filter value raises InvalidParams (previously a Hash element
+  raised a TypeError at query time and a nil element rendered the
+  never-matching `IN (..., NULL)`). The `"null"` token is NOT resolved inside a
+  set — SQL `IN` cannot match NULL — so a null-or-nothing condition is
+  expressed as the filter's single scalar value.
+- A null value with an operator other than `eq` / `in` / `not_eq` (comparisons,
+  `matches` / `does_not_match`) raises InvalidParams; a comparison or LIKE
+  against NULL can never match a row (previously `matches` with a JSON null
+  matched every row via `LIKE '%%'`, and comparisons silently matched nothing).
+- An op-less Hash as a bare filter value raises InvalidParams (previously it
+  reached the database as a malformed condition).
+- `{ op: "eq", value: "" }` matches rows whose value IS the empty string
+  (previously it matched nothing via an empty IN set). A bare `""` filter value
+  still means "no filter".
+
 ## [0.4.0] - 2026-07-06
 
 ### Added

data/config/routes.rb

@@ -2,7 +2,7 @@
 
 # Engine routes, drawn through Rails' routes_reloader so they survive route
 # reloads (a class-body `routes.draw` is wiped when the app re-draws the engine's
-# route set on boot/reload). Mounted by a satellite via:
+# route set on boot/reload). Mounted by a satellite or an authority via:
 #
 #   mount McpToolkit::Engine => "/mcp"
 #

data/lib/mcp_toolkit/authority/controller_methods.rb

@@ -247,12 +247,27 @@ module McpToolkit::Authority::ControllerMethods
   # ---- request handling -----------------------------------------------
 
   def mcp_handle_batch(requests)
+    mcp_enforce_batch_limit!(requests)
     responses = requests.filter_map { |req| mcp_process_single_request(req) }
     return head :accepted if responses.empty?
 
     mcp_render_response(responses)
   end
 
+  # Rejects an oversized JSON-RPC batch BEFORE any element runs. Rate limiting is
+  # a per-HTTP-request before_action, so without this an authenticated caller
+  # could fan out unbounded work (N tool executions / N blocking upstream calls)
+  # under a single rate-limit tick. Raised as a boundary Protocol::Error →
+  # rendered as a JSON-RPC error envelope (null id) by the rescue_from hook.
+  # `config.max_batch_size = nil` disables the cap.
+  def mcp_enforce_batch_limit!(requests)
+    max = mcp_config.max_batch_size
+    return if max.nil? || requests.size <= max
+
+    raise McpToolkit::Protocol::InvalidRequest,
+          "JSON-RPC batch too large: #{requests.size} requests exceeds the maximum of #{max}"
+  end
+
   def mcp_handle_single(request_data)
     response_data = mcp_process_single_request(request_data)
     return head :accepted if response_data.nil?

data/lib/mcp_toolkit/authority/registry_tool_provider.rb

@@ -20,11 +20,13 @@ class McpToolkit::Authority::RegistryToolProvider
   # actually advertised in `tools/list` and matched in `tools/call` is this base
   # name PREFIXED with `config.generic_tool_name_prefix` (empty by default, so the
   # bare base name), letting a host namespace its generic tools.
+  # Alphabetical by base name — the order tools/list advertises them in
+  # (matches the pre-gem contract adopting hosts' clients observed).
   TOOLS = {
-    "resources" => McpToolkit::Authority::Tools::Resources,
-    "resource_schema" => McpToolkit::Authority::Tools::ResourceSchema,
     "get" => McpToolkit::Authority::Tools::Get,
-    "list" => McpToolkit::Authority::Tools::List
+    "list" => McpToolkit::Authority::Tools::List,
+    "resource_schema" => McpToolkit::Authority::Tools::ResourceSchema,
+    "resources" => McpToolkit::Authority::Tools::Resources
   }.freeze
 
   def initialize(config:)
@@ -32,9 +34,11 @@ class McpToolkit::Authority::RegistryToolProvider
   end
 
   # The four static generic tool definitions (context-independent), each advertised
-  # under its PREFIXED name so `tools/list` shows the host's namespaced names.
+  # under its PREFIXED name so `tools/list` shows the host's namespaced names. The
+  # prefix is threaded into each definition so sibling-tool references in the
+  # description / input schema name the prefixed tools too (see Tools::Base.definition).
   def tool_definitions(_context)
-    TOOLS.map { |base_name, klass| klass.definition.merge(name: prefixed(base_name)) }
+    TOOLS.map { |_base_name, klass| klass.definition(name_prefix: prefix, config: @config) }
   end
 
   # A tool instance bound to this provider's config, or nil for an unknown name.
@@ -54,11 +58,6 @@ class McpToolkit::Authority::RegistryToolProvider
     @config.generic_tool_name_prefix.to_s
   end
 
-  # The advertised name for a base tool: the configured prefix followed by the base.
-  def prefixed(base_name)
-    "#{prefix}#{base_name}"
-  end
-
   # Recovers the base tool name from an advertised name by stripping the configured
   # prefix, or nil when the name does not carry the (non-empty) prefix.
   def base_name_for(name)

data/lib/mcp_toolkit/authority/single_tool_provider.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# A `tool_provider` serving exactly one bespoke authority tool alongside the
+# generic Registry-backed ones — the shape every host with a single custom tool
+# would otherwise hand-roll. Used automatically by the composed default
+# provider for bare tool classes in `config.extra_tool_providers`.
+#
+# The tool must expose `.definition` (the tools/list entry) and `.tool_name`,
+# and itself satisfy the dispatcher's tool contract (`required_permissions_scope`
+# + `call`) — e.g. a class built on McpToolkit::Tools::AuthorityBase. It is
+# advertised unconditionally; its scope/authorization gates are enforced at
+# call time (by the dispatcher and the tool itself).
+class McpToolkit::Authority::SingleToolProvider
+  def initialize(tool)
+    @tool = tool
+  end
+
+  def tool_definitions(_context)
+    [@tool.definition]
+  end
+
+  def find(name)
+    name.to_s == @tool.tool_name ? @tool : nil
+  end
+end

data/lib/mcp_toolkit/authority/tools/base.rb

@@ -43,9 +43,26 @@ class McpToolkit::Authority::Tools::Base
     end
 
     # The static tool definition returned by the provider's `tool_definitions`
-    # (part of `tools/list`). Generic and context-independent.
-    def definition
-      { name: tool_name, description: _description, inputSchema: input_schema }
+    # (part of `tools/list`). Generic and context-independent. `name_prefix` is
+    # the host's `config.generic_tool_name_prefix`: it prefixes the advertised
+    # name AND is threaded through every sibling-tool reference in the
+    # description / input schema (see McpToolkit::ToolReferenceRewriter).
+    # `config` lets a tool adapt its prose to host configuration (see
+    # .description_text) — served docs must describe the behavior the host
+    # actually configured.
+    def definition(name_prefix: "", config: nil)
+      {
+        name: "#{name_prefix}#{tool_name}",
+        description: McpToolkit::ToolReferenceRewriter.rewrite(description_text(config), name_prefix),
+        inputSchema: McpToolkit::ToolReferenceRewriter.rewrite(input_schema, name_prefix)
+      }
+    end
+
+    # Hook for a tool whose description depends on host configuration
+    # (Tools::List swaps its bare-value grammar per
+    # config.bare_filter_value_semantics). Default: the static description.
+    def description_text(_config)
+      _description
     end
   end
 
@@ -119,4 +136,15 @@ class McpToolkit::Authority::Tools::Base
   rescue McpToolkit::Errors::InvalidParams => e
     raise McpToolkit::Protocol::InvalidParams, e.message
   end
+
+  # Rejects tool arguments outside the declared input schema (-32602) instead of
+  # silently ignoring them — a typo'd argument name should surface, not no-op.
+  # `list` deliberately does NOT use this: its extra top-level arguments are the
+  # resource-specific custom filters. (`account_id` is consumed by the
+  # transport's account resolution, so every tool tolerates it explicitly.)
+  def reject_unknown_arguments!(extra)
+    return if extra.empty?
+
+    raise McpToolkit::Protocol::InvalidParams, "unknown argument(s): #{extra.keys.join(", ")}"
+  end
 end

data/lib/mcp_toolkit/authority/tools/get.rb

@@ -45,7 +45,8 @@ class McpToolkit::Authority::Tools::Get < McpToolkit::Authority::Tools::Base
     }
   )
 
-  def call(context:, resource: nil, id: nil, fields: nil, **_args)
+  def call(context:, resource: nil, id: nil, fields: nil, **extra)
+    reject_unknown_arguments!(extra.except(:account_id))
     descriptor = resolve_descriptor(resource)
     ensure_resource_accessible!(descriptor, context)
     ensure_scope!(descriptor, context)

data/lib/mcp_toolkit/authority/tools/list.rb

@@ -7,6 +7,35 @@
 # custom filters, pagination, and sparse fieldsets are all handled by the reused
 # McpToolkit::ListExecutor.
 class McpToolkit::Authority::Tools::List < McpToolkit::Authority::Tools::Base
+  # The bare-value grammar bullet, per config.bare_filter_value_semantics: the
+  # served description must state the semantics the host ACTUALLY configured —
+  # advertising comma/"null" tokenization to clients of a :literal host would
+  # send them filters that silently match nothing. The :tokenized text is the
+  # exact bullet embedded in the static description below (spec-pinned), so
+  # .description_text can swap it by plain substring substitution; both use
+  # `<<-` (no dedent) to carry the description's rendered 2-space indentation.
+  BARE_VALUE_GRAMMAR = {
+    tokenized: <<-TEXT.rstrip,
+  - 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.
+    TEXT
+    literal: <<-TEXT.rstrip
+  - A bare value matches by equality, LITERALLY: a comma-separated string is a single
+    value and the string "null" is the literal string. A JSON null matches records
+    where the value is NULL. An array of scalars matches ANY of its values (IN).
+    TEXT
+  }.freeze
+
+  # Swaps the bare-value bullet for the host's configured semantics; the rest
+  # of the description is mode-independent.
+  def self.description_text(config)
+    return _description unless config && config.bare_filter_value_semantics == :literal
+
+    _description.sub(BARE_VALUE_GRAMMAR[:tokenized], BARE_VALUE_GRAMMAR[:literal])
+  end
+
   tool_name "list"
   description <<~DESC.strip
     Fetch a paginated list of records from a read-only resource. Pass the resource name as
@@ -23,6 +52,22 @@ class McpToolkit::Authority::Tools::List < McpToolkit::Authority::Tools::Base
       - 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
@@ -67,7 +112,10 @@ class McpToolkit::Authority::Tools::List < McpToolkit::Authority::Tools::Base
                        "field. Include \"id\" if you need it. Unknown names are rejected."
         }
       },
-      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
     }
   )
 

data/lib/mcp_toolkit/authority/tools/resource_schema.rb

@@ -16,7 +16,14 @@ class McpToolkit::Authority::Tools::ResourceSchema < McpToolkit::Authority::Tool
       - 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
@@ -34,7 +41,8 @@ class McpToolkit::Authority::Tools::ResourceSchema < McpToolkit::Authority::Tool
     }
   )
 
-  def call(context:, resource: nil, **_args)
+  def call(context:, resource: nil, **extra)
+    reject_unknown_arguments!(extra.except(:account_id))
     descriptor = resolve_descriptor(resource)
     ensure_resource_accessible!(descriptor, context)
     ensure_scope!(descriptor, context)

data/lib/mcp_toolkit/authority/tools/resources.rb

@@ -11,15 +11,23 @@ class McpToolkit::Authority::Tools::Resources < McpToolkit::Authority::Tools::Ba
   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
 
+  # Unlike get / resource_schema (strict kwargs pre-gem), the pre-gem resources
+  # tool tolerated ANY extra argument — so this one stays tolerant.
   def call(context:, **_args)
     {
       resources: visible_resources(context).map do |resource|
-        { name: resource.name, description: resource.description }
+        {
+          name: resource.name,
+          description: resource.description,
+          filterable: filterable?(resource),
+          note: resource.note
+        }.compact
       end
     }
   end
@@ -30,4 +38,18 @@ class McpToolkit::Authority::Tools::Resources < McpToolkit::Authority::Tools::Ba
   def visible_resources(context)
     registry.resources.reject { |resource| resource.superusers_only? && !context.superuser? }
   end
+
+  # Whether the resource can be filtered at all — via the generic allowlist OR a
+  # resource-specific custom filter. Reading `filterable_columns` resolves a
+  # lazily-declared allowlist, which may run host code (e.g. a DB-backed column
+  # list). One resource's failing resolution must not take down the whole
+  # discovery index — this is the tool every session calls first — so a raise
+  # degrades to nil (the `filterable` key is omitted for that resource) and the
+  # unresolved source is retried on the next read (see Resource#filterable).
+  def filterable?(resource)
+    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
 end