mcp_toolkit 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af5e847538e7fe188e7fb0b0b509f0f430d2c3d33c84fa21350e30367a409578
-  data.tar.gz: dc3233698fd64947b42330fe51bd230e249f37e9044d303eaf1915ea213e1695
+  metadata.gz: fa488bbd5b90e15c5f7e9a70f8792be1ec070b0fdd6ce6e89f1279bd24bf59cf
+  data.tar.gz: 2e8953c00c9b6dab828efcd9c92f71990d8e09477f15851aa9976f0b942456ae
 SHA512:
-  metadata.gz: a1fc3088f0a6532ed7a52e7cf13e13ce372edbdcddd61f255fd93cb28df6c0c5fe3a3c17ef98cedf8c5a3be5f8c72d58f8f9bdbc28eac1e7b5ae3308a83cd21f
-  data.tar.gz: fb9a05e81f3895dc89d65dc45a33deef371387d8ba14bf223454f666b8bdeb9c828876a66ba9f6c54b19019b416cd88dc6c66dd5ab562fdc577d1b5148872aae
+  metadata.gz: 1f478ffa9b25834f25e4481b964015e8a73719525109986cb59972b6acecd27f9b47c7238ad435f8c30c491c88fee8631b0cd174bd68b4b61440a7996161d05a
+  data.tar.gz: 887ada2ad7fd66ba42feae592e8cc2ede5e2e89a075a1d2581d78e93bc8a0cd0bdb0bb7e5ffcb487efa22944ce51d303fa236f146b291f0987a242c4f4ddc6a7

data/CHANGELOG.md

@@ -1,3 +1,43 @@
+## [0.6.2] - 2026-08-28
+
+RFC 9207 authorization server issuer identification. Additive hardening, and the
+fix for hosted clients that choose their redirect URI based on whether the
+authorization server supports it.
+
+### Added
+
+- **`iss` in the authorization response, and `authorization_response_iss_parameter_supported`
+  in the metadata** (RFC 9207). The parameter names which authorization server
+  produced a response, so a client registered with several cannot be induced to
+  redeem a code at the wrong one — the mixed-up authorization server attack.
+
+  This also unblocks **ChatGPT connectors**, which pick their `redirect_uri` from
+  whether the server meets RFC 9207: when it does, ChatGPT uses the stable
+  `https://chatgpt.com/connector_platform_oauth_redirect`; when it does not, it
+  mints a per-connector `https://chatgpt.com/connector/oauth/{callback_id}` that
+  no exact-match allowlist can express, and the connection fails with an
+  unregistered `redirect_uri`. Observed in production against a real customer
+  before this release.
+
+  Note for hosts: a client that picks its callback at *connector-creation* time
+  reads the metadata then. An existing connector created against a pre-0.6.2
+  server keeps the URI it already chose — **it has to be re-created** to pick up
+  the change.
+
+  `iss` is emitted on the one response this bridge redirects (`approve`); every
+  error path renders rather than redirecting, so there is no error response for it
+  to be absent from. It is byte-identical to the advertised `issuer` — clients
+  compare by exact string and do not normalise trailing slashes, paths, ports or
+  casing — and a spec pins the redirect against the discovery document rather than
+  against a literal.
+
+  `iss` is now response-owned alongside `code` and `state`: a caller that seeds one
+  into its own `redirect_uri` has it replaced, not appended. A value the caller
+  chose would defeat the point of the parameter.
+
+  **No control was relaxed.** The redirect allowlist is unchanged and still exact-match
+  (RFC 9700 §2.1); this release makes conforming clients ask for a URI already on it.
+
 ## [0.6.1] - 2026-07-20
 
 Two additive fixes for hosted MCP clients whose OAuth setup could not complete

data/README.md

@@ -244,6 +244,98 @@ discovery tool, a custom serializer may also expose `declared_attributes` /
 
 ---
 
+## Reading data: pagination, sparse fieldsets, filters
+
+The four generic tools serve the same grammar on both the satellite and authority
+paths (they share the executors). `list` accepts:
+
+| Argument | Shape | Notes |
+|---|---|---|
+| `resource` | String | the registered resource name |
+| `limit` / `offset` | Integer | page size (default 25, max 100) / offset (default 0) |
+| `fields` | Array or comma-separated String | sparse fieldset — attribute and/or relationship names, one flat namespace. Unknown names raise `InvalidParams` rather than being silently dropped |
+| `filter` | Object | per-attribute filters, applied **on top of** the account scope (they can only narrow, never widen) |
+| *(resource-specific)* | — | a resource's own `filter` declarations arrive as **top-level** arguments, not inside `filter` |
+
+`list` returns `{ "<resource>": [...], "meta": { total_count, limit, offset } }`.
+
+Clients discover all of this at runtime: `resources` lists each resource with
+`filterable` and its usage `note`, and `resource_schema` advertises every
+attribute's type and accepted `operators`, the valid `fields` values, the
+resource's own `resource_filters`, and any companion-key requirements.
+
+### Filter values
+
+A filter value is either a **bare value** or an `{ op:, value: }` condition.
+
+```jsonc
+{ "filter": { "status": "active" } }                    // equality
+{ "filter": { "status": "active,archived" } }           // IN set (comma-separated)
+{ "filter": { "status": ["active", "archived"] } }      // IN set (array)
+{ "filter": { "archived_at": "null" } }                 // IS NULL ("null" token, or a JSON null)
+{ "filter": { "created_at": { "op": "gteq", "value": "2026-01-01" } } }
+{ "filter": { "created_at": [                           // conditions AND together
+    { "op": "gteq", "value": "2026-01-01" },
+    { "op": "lt",   "value": "2026-02-01" }
+] } }
+```
+
+Under the default `:tokenized` semantics a bare `""` means "no filter", and a
+comma splits an IN set. Set `bare_filter_value_semantics = :literal` to match
+bare values verbatim instead; operator conditions behave identically in both.
+
+### Operators by column type
+
+`resource_schema` advertises these per attribute; `filter_operator_overrides`
+narrows them per type.
+
+| Column type | Operators |
+|---|---|
+| `integer` / `float` / `decimal` / `datetime` | `eq` `not_eq` `gt` `gteq` `lt` `lteq` |
+| `date` | `eq` `not_eq` `gt` `gteq` `lt` `lteq` `in` |
+| `string` / `text` | `eq` `in` `not_eq` `matches` `does_not_match` |
+| `boolean` | `eq` `not_eq` |
+| anything else (`uuid`, `enum`, `jsonb`, `citext`, …) | `eq` `in` |
+
+`matches` / `does_not_match` are SQL `LIKE`, with wildcards in the value escaped
+by `config.sql_sanitizer`. Only `eq` / `in` / `not_eq` accept a null (`IS NULL` /
+`IS NOT NULL`); a comparison or `LIKE` against null raises `InvalidParams`,
+because it could never match a row. IN-set elements must be non-null scalars —
+SQL `IN` cannot match NULL, so a null-or-nothing condition is expressed as the
+filter's single scalar value.
+
+These refusals are deliberate: each previously returned a silently wrong or empty
+result, which is far harder for a client to notice than an error.
+
+### Resource-specific filters and companion keys
+
+`filterable` maps public filter keys onto backing columns. When the generic
+equality/operator grammar cannot express a filter, declare a `filter` block —
+it takes a **top-level** request param and narrows the relation itself:
+
+```ruby
+filterable status: :status, owner_id: :owner_id
+
+filter :for_project, type: :integer, description: "Only widgets in this project" do |relation, id|
+  relation.joins(:board).where(boards: { project_id: id })
+end
+```
+
+`filter_requirements` declares that a key is meaningless alone — a polymorphic
+foreign key is type-ambiguous without its `*_type`, so filtering on it alone
+would silently match rows across types:
+
+```ruby
+filter_requirements subject_id: :subject_type
+```
+
+`list` then rejects `subject_id` unless `subject_type` comes with it, and
+`resource_schema` advertises the requirement under the relationship's
+`filter.requires` so a client can satisfy it without guessing. Both accept a Hash
+or a lazily-resolved callable.
+
+---
+
 ## Configuration reference
 
 | Setting | Default | Purpose |
@@ -262,9 +354,11 @@ discovery tool, a custom serializer may also expose `declared_attributes` /
 | `session_ttl` | `3600` | session sliding TTL (s) |
 | `protocol_version` | `nil` (negotiate) | pin an MCP protocol version (satellite/upstream client) |
 | `supported_protocol_versions` | `Protocol::SUPPORTED_VERSIONS` | version set the authority dispatcher negotiates |
-| `tool_provider` | `nil` | authority: the host's api-agnostic tool catalog (see below) |
+| `tool_provider` | composed (see below) | authority: the host's api-agnostic tool catalog. Left **unset it composes itself** — the generic `RegistryToolProvider` (only when resources are registered) followed by every `extra_tool_providers` entry — so the common case needs no provider plumbing. Assign explicitly to take full control |
+| `extra_tool_providers` | `[]` | authority: extra providers (or bare tool **classes**, auto-wrapped in a `SingleToolProvider`) composed after the generic tools when `tool_provider` is unset |
 | `generic_tool_name_prefix` | `""` | authority: prefix namespacing the four generic Registry-backed tools (e.g. `"foo_"` → `foo_resources` …) |
 | `rate_limiter` / `usage_recorder` / `usage_flusher` | `nil` | authority transport billing hooks (config callables) |
+| `session_data_builder` | `nil` | authority: builds the opaque `Session#data` payload (e.g. bind a session to a token id so revoking the token kills it) |
 | `rate_limit_max_requests` | `nil` (off) | authority: per-principal request cap for the built-in `RateLimiter`; `nil` disables rate limiting |
 | `rate_limit_window` | `3600` | authority: fixed rate-limit window (s); ignored while `rate_limit_max_requests` is `nil` |
 | `superuser_resolver` | `nil` | optional `->(principal) -> Boolean` for `Context#superuser?`; `nil` = duck-type `principal.superuser?` |
@@ -276,13 +370,48 @@ discovery tool, a custom serializer may also expose `declared_attributes` /
 | `upstream_list_ttl` | `900` | gateway: TTL (s) for an upstream's cached tool list |
 | `logger` | `nil` | optional logger for gateway/session diagnostics (`Rails.logger`) |
 
+### Data path, filtering, and safety caps
+
+These govern how `list` reads a filter and how much work one request may ask for.
+The defaults are the gem's own grammar; the first three exist so a host migrating
+an **existing** MCP endpoint onto the gem can preserve its pre-gem contract
+byte-for-byte (see [Migrating an existing endpoint](#migrating-an-existing-mcp-endpoint)).
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `bare_filter_value_semantics` | `:tokenized` | how a **bare** filter value is read. `:tokenized` applies the comma/IN/`"null"` grammar below; `:literal` sends the value to the WHERE clause verbatim (`"a,b"` is one string, `"null"` is the literal string). Operator conditions are identical either way |
+| `non_numeric_pk_order` | `:created_at` | ordering for non-numeric-PK resources. `:created_at` (with the PK as tiebreaker, so offset pagination is a total order) or `:primary_key` to preserve an `ORDER BY id` contract |
+| `filter_operator_overrides` | `{}` | per-column-type overrides of the advertised **and** enforced operator sets, e.g. `{ text: %w[eq in], date: %w[eq in] }`. Single source, so `resource_schema` and the executor cannot disagree. Rejects, at assignment, any operator outside `Filtering::AREL_PREDICATIONS` |
+| `max_filter_values` | `500` | caps how many values one IN-set may resolve to, and how many operator conditions may be ANDed on one attribute, so a valid token cannot emit an unbounded IN clause / AND-chain. `nil` disables |
+| `max_batch_size` | `50` | authority: caps the JSON-RPC calls one POST batch may carry. Rate limiting is per-HTTP-request, so an uncapped batch would fan out unbounded work under a single tick. `nil` disables |
+| `sql_sanitizer` | `McpToolkit::SqlSanitizer` | escapes LIKE wildcards in `matches` / `does_not_match`; injectable so a non-Rails host can supply its own |
+
+### OAuth bridge (authority-only, opt-in)
+
+All inert unless the bridge is switched on — see
+[OAuth authorization bridge](#oauth-authorization-bridge-authority-only-opt-in)
+for what it is and why the redirect policy is shaped the way it is.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `oauth_allowed_redirect_uris` | `[]` | exact-string allowlist of redirect targets. Validated at assignment (an unparseable, scheme-less, fragment-bearing or opaque URI raises, as does cleartext `http://` to a remote host and the `javascript:`/`data:`/`file:` schemes) and **frozen** once assigned |
+| `oauth_allow_loopback_redirects` | `false` | accept `http://127.0.0.1:*` / `localhost` / `[::1]` without an allowlist entry (RFC 8252 §7.3 — the client picks an ephemeral port, so no list could name it) |
+| `oauth_resource_path` | `"/mcp"` | must match the engine's mount point; `"/"` when the MCP endpoint IS the origin root |
+| `oauth_authorization_code_ttl` | `60` | authorization-code lifetime (s) |
+| `oauth_signing_secret` | Rails' `secret_key_base` | mixed into the key that seals a code's cache entry, so the cache, the logs and the code together still open nothing. Validated at assignment |
+| `oauth_parent_controller` | `"ActionController::Base"` | superclass of the bridge's controller, deliberately **separate** from `parent_controller` — the authorization page is HTML and `ActionController::API` cannot render it |
+
+Either naming a redirect target or enabling loopback is what flips
+`config.oauth_bridge?` on; with neither, no route is drawn.
+
 ## Public API surface
 
 - `McpToolkit.configure { |c| ... }`, `McpToolkit.config`, `McpToolkit.registry`,
   `McpToolkit.reset_config!`
 - `McpToolkit::Registry#register(name) { ... }` (DSL: `model`, `serializer`,
   `scope`, `description`, `note`, `filterable`, `filter(name, type:, description:,
-  &applier)`, `superusers_only!`, `required_permissions_scope`) +
+  &applier)`, `filter_requirements`, `superusers_only!`,
+  `required_permissions_scope`, `extra(key, value)` for host-defined metadata) +
   `#default_required_permissions_scope`
 - `McpToolkit::Serializer::Base` (DSL: `attributes`, `has_one`, `has_many`,
   `translates`)
@@ -342,6 +471,18 @@ McpToolkit.configure do |c|
 end
 ```
 
+Declaring the whole set from ENV has two gotchas every gateway host rediscovers —
+re-registering on a code reload duplicates entries, and a blank ENV var must not
+become an upstream. `register_upstreams_from_env` handles both (it resets the
+registry first, so it is idempotent, and skips blank urls):
+
+```ruby
+c.register_upstreams_from_env(
+  "notifications" => "NOTIFICATIONS_SERVER_URL",
+  "billing"       => "BILLING_SERVER_URL"
+)
+```
+
 ### Aggregate upstream tool lists
 
 `Aggregator#tool_definitions` returns every upstream's tools, namespaced, pulled
@@ -493,6 +634,25 @@ So **every target must be named by exact string**, with exactly one exception:
 | Private-use scheme (`cursor://…`, `com.example.app:/cb`) | Exact string, in `oauth_allowed_redirect_uris` | Keeps the code on the device, but its URI is a fixed string — so just name it. |
 | Loopback (`http://127.0.0.1:*`, `localhost`, `[::1]`) | `oauth_allow_loopback_redirects` | The only target that **cannot** be named: the client picks an ephemeral port at runtime (RFC 8252 §7.3). And it resolves on the operator's own machine, so the attack above cannot reach it. |
 
+### If a client's callback looks impossible to name, check RFC 9207 first
+
+Some hosted clients mint a **per-connector** callback (`https://vendor.example/connector/oauth/{id}`),
+which no exact-match list can express — and the obvious response, matching the
+host and path by pattern, is the wrong one. A prefix turns an attacker into
+someone who can **name their own destination inside it**: they create their own
+connector at that vendor, put their callback in the authorize URL, and the code
+goes somewhere they control. Exact matching leaves a weaker residual (a code sent
+to the vendor's *legitimate* shared callback, separated by the client binding
+`state` to the initiating session — RFC 6819 §4.4.1.7); a prefix removes the need
+for any of that to go wrong.
+
+At least one such client picks the per-connector form **only when the
+authorization server does not implement RFC 9207**, and uses a single stable
+callback when it does. Since 0.6.2 this gem implements it, so the fix for that
+class of failure is to be conforming, not to be permissive. Before relaxing the
+policy for a client that "cannot be named", check whether it is asking you for a
+capability instead.
+
 The loopback exception exists because an allowlist entry is *impossible* there,
 not because native clients are trusted. A private-use scheme keeps the code on the
 device too, but nothing forces it to be unnamed — and whole **schemes** cannot be
@@ -660,12 +820,18 @@ McpToolkit.configure do |c|
     note "Read-only projection; do not interpret status codes without domain context."
     scope { |account| Widget.where(account_id: account.id) }
   end
-
-  # The generic tools, served over config.registry:
-  c.tool_provider = McpToolkit::Authority::RegistryToolProvider.new(config: c)
 end
 ```
 
+That is the whole setup — **no `tool_provider` assignment is needed.** Left unset,
+it composes itself from the registry (plus any `extra_tool_providers`), so
+registering resources is enough to serve the generic tools. Assign one explicitly
+only to take full control of the catalog:
+
+```ruby
+c.tool_provider = McpToolkit::Authority::RegistryToolProvider.new(config: c)
+```
+
 Each generic tool resolves the `resource` argument against the registry, refuses a
 `superusers_only!` resource for a non-superuser (and hides it from `resources`),
 enforces the resource's `required_permissions_scope`, and requires a resolved
@@ -685,8 +851,16 @@ c.generic_tool_name_prefix = "foo_"   # advertised + resolved as foo_resources,
 The prefix applies only to these four generic tools; a composed bespoke provider's
 own tool names are unaffected.
 
-To serve the generic tools **and** your own bespoke tools behind one provider,
-compose them:
+To serve the generic tools **and** your own bespoke tools, just name the extras —
+they are composed after the generic ones, and a bare tool **class** is wrapped for
+you:
+
+```ruby
+c.extra_tool_providers = [MyApp::Tools::AuditLog]   # a class, or a provider object
+```
+
+Compose by hand only when you want to control the order or drop the generic tools
+entirely:
 
 ```ruby
 c.tool_provider = McpToolkit::Authority::CompositeToolProvider.new(
@@ -744,6 +918,27 @@ it to gate `superusers_only!` resources; with no resolver it duck-types
 Point your `POST /mcp` route at the subclass (or mount the engine for a pure host);
 keep `POST /mcp/tokens/introspect` on the gem's `TokensController`.
 
+### Migrating an existing MCP endpoint
+
+If you are moving an MCP endpoint you already ship onto the gem, your clients
+hold the *old* contract. Several seams exist purely so that contract survives the
+move — adopt them at first, then retire them deliberately rather than breaking
+clients on cutover:
+
+| If your endpoint… | Set |
+|---|---|
+| matched bare filter values verbatim (no comma/`"null"` grammar) | `bare_filter_value_semantics = :literal` |
+| ordered non-numeric-PK lists by `id` | `non_numeric_pk_order = :primary_key` |
+| advertised a narrower operator set | `filter_operator_overrides`, e.g. `{ text: %w[eq in], date: %w[eq in] }` |
+| namespaced its generic tool names | `generic_tool_name_prefix` |
+| filtered a polymorphic FK safely | `filter_requirements` on the resource |
+
+One deliberate delta is **not** revertible: `{ op: "in", value: "a,b" }` now
+splits into an IN set (previously only `eq` split, and `in` matched the literal
+string `'a,b'`). Under the tokenized operator grammar there is no way to express
+a literal comma inside an IN element — express such a match as a bare equality
+value, which `:literal` semantics match verbatim.
+
 ### Lazy `parent_controller`
 
 The gem's controllers subclass `config.parent_controller`. That parent is read

data/lib/mcp_toolkit/oauth/controller_methods.rb

@@ -31,7 +31,7 @@ module McpToolkit::Oauth::ControllerMethods
 
   # Query parameters the callback response owns: whatever a client put in its own
   # redirect_uri, these are set by the redirect and not carried over from it.
-  RESPONSE_OWNED_QUERY_KEYS = %w[code state].freeze
+  RESPONSE_OWNED_QUERY_KEYS = %w[code state iss].freeze
 
   # RFC 7636 §4.1: 43–128 unreserved characters. The challenge is §4.2's
   # base64url of a SHA-256, which is always exactly 43 of the same alphabet.
@@ -95,7 +95,8 @@ module McpToolkit::Oauth::ControllerMethods
       response_types_supported: SUPPORTED_RESPONSE_TYPES,
       grant_types_supported: SUPPORTED_GRANT_TYPES,
       code_challenge_methods_supported: ["S256"],
-      token_endpoint_auth_methods_supported: ["none"]
+      token_endpoint_auth_methods_supported: ["none"],
+      authorization_response_iss_parameter_supported: true
     }
   end
 
@@ -408,6 +409,7 @@ module McpToolkit::Oauth::ControllerMethods
     pairs = mcp_oauth_preserved_query_pairs(existing)
     pairs << ["code", code]
     pairs << ["state", params[:state].to_s] if params[:state].present?
+    pairs << ["iss", mcp_oauth_issuer]
     "#{base}?#{URI.encode_www_form(pairs)}"
   end
 

data/lib/mcp_toolkit/version.rb

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

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_toolkit
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Karol Galanciak
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -170,6 +171,7 @@ metadata:
   source_code_uri: https://github.com/BookingSync/mcp_toolkit
   changelog_uri: https://github.com/BookingSync/mcp_toolkit/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -184,7 +186,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Opinionated toolkit for building account-scoped, read-only MCP servers.
 test_files: []