mcp_toolkit 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 375206ea98c72a64738894427abd86bf0e272f5fad3c359860cd684707e38da7
-  data.tar.gz: e37f4ca9689b78c871daabc65110c7b5676760806d9eadaec45b30ea687f9b79
+  metadata.gz: fa488bbd5b90e15c5f7e9a70f8792be1ec070b0fdd6ce6e89f1279bd24bf59cf
+  data.tar.gz: 2e8953c00c9b6dab828efcd9c92f71990d8e09477f15851aa9976f0b942456ae
 SHA512:
-  metadata.gz: 5920ce2f6e47c077d6f89a4078b74b82935a4be18f5a44cc415168b78e65f85aec6354ba7a3d81d1246f63d0c4d621503f5445b198ad42d80db2ab1ad129d750
-  data.tar.gz: '091c72fd1efc0d5dbea0298af70355f21436e194d37534aa98629ea786442fa4477b00b656de0a03b8ac31485ea38d8ad783de1a59bb927f82df75922f028f79'
+  metadata.gz: 1f478ffa9b25834f25e4481b964015e8a73719525109986cb59972b6acecd27f9b47c7238ad435f8c30c491c88fee8631b0cd174bd68b4b61440a7996161d05a
+  data.tar.gz: 887ada2ad7fd66ba42feae592e8cc2ede5e2e89a075a1d2581d78e93bc8a0cd0bdb0bb7e5ffcb487efa22944ce51d303fa236f146b291f0987a242c4f4ddc6a7

data/CHANGELOG.md

@@ -1,3 +1,95 @@
+## [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
+against the 0.6.0 bridge: it now answers the metadata documents at the path-APPENDED
+discovery locations as well as the RFC 8414 path-inserted ones, and its Dynamic
+Client Registration response now states the registration (per RFC 7591) instead of
+returning a bare `client_id`. Both are bridge-gated and change nothing for a host
+with the bridge off, or for a client that already worked.
+
+### Fixed
+
+- **Authorization-server discovery for clients that path-APPEND the well-known
+  segment.** For an MCP endpoint at `https://host/mcp`, the issuer is path-ful,
+  and RFC 8414 §3.1 places its metadata at the path-INSERTED
+  `/.well-known/oauth-authorization-server/mcp` — which the bridge already served.
+  But some MCP clients (observed with a hosted client in the wild) instead request
+  the path-APPENDED `https://host/mcp/.well-known/oauth-authorization-server`, got
+  a 404 with no fallback, never obtained a `registration_endpoint`, and reported a
+  registration failure. The bridge now answers the metadata at BOTH forms.
+
+- **Dynamic Client Registration response now states the registration.** The stub
+  returned only a `client_id`. A strict client validates that the `redirect_uris`
+  it registered come back and abandons a registration that drops them — a plausible
+  cause of the same "couldn't register" failure, independent of the discovery gap
+  above. `register` now returns the client's `redirect_uris` and `client_name`
+  alongside `client_id_issued_at` (RFC 7591 §3.2.1). Echoing a `redirect_uri`
+  AUTHORIZES nothing: the bridge still stores no client, and `authorize`/`token`
+  check every one against the host allowlist independently, so a value reflected
+  here is not thereby permitted.
+
+  The `token_endpoint_auth_method` and the grant/response types are **substituted,
+  not echoed** — RFC 7591 §3.2.1 states the metadata as REGISTERED and lets a server
+  replace what it does not support. Reflecting the client's request would contradict
+  the discovery document that named this endpoint (`token_endpoint_auth_methods_supported:
+  ["none"]`, `grant_types_supported: ["authorization_code"]`) and promise a flow the
+  token endpoint rejects — a reflected `refresh_token` is a refresh answered
+  `unsupported_grant_type`. The supported sets are now named once and shared by both
+  documents, so they cannot drift apart.
+
+### Added
+
+- **Path-appended metadata routes under the engine mount** (drawn only when
+  `oauth_bridge?`): `GET <mcp>/.well-known/oauth-authorization-server`,
+  `GET <mcp>/.well-known/oauth-protected-resource`, and the OIDC discovery alias
+  `GET <mcp>/.well-known/openid-configuration` (which returns the
+  authorization-server document). All stay UNDER the mount, so they claim nothing
+  origin-global and cannot collide with an OAuth provider the host already runs;
+  the RFC 8414 path-inserted documents the host draws at the origin root are
+  unchanged. Every identifier is still derived from the live request origin, so
+  the document served at an appended location is byte-identical to the inserted
+  one, and both carry `Cache-Control: no-store`.
+
 ## [0.6.0] - 2026-07-16
 
 An OAuth 2.1 authorization bridge for the authority role, so hosted MCP clients

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
@@ -543,16 +703,26 @@ origin-global.** The flow endpoints live under the engine's mount
 `/oauth/*` — as an app with Doorkeeper for its own API does — you keep every one of
 those routes.
 
-The metadata documents are **path-scoped** to the mount
-(`/.well-known/oauth-protected-resource/mcp`), never the bare
-`/.well-known/oauth-authorization-server`. That matters: the bare paths are
-origin-global and mean *"the authorization server of this whole origin"*, which
-belongs to a provider you already run, not to an MCP server sharing the host.
+The metadata documents are **path-scoped** to the mount, never the bare
+origin-global `/.well-known/oauth-authorization-server`. That matters: the bare
+paths are origin-global and mean *"the authorization server of this whole origin"*,
+which belongs to a provider you already run, not to an MCP server sharing the host.
 RFC 8414 §3.1 exists for exactly this — *"Using path components enables supporting
 multiple issuers per host"* — and the MCP authorization spec (2025-11-25) requires
 a client given a path-ful issuer to try the path-**inserted** URLs, with no root
 fallback. So the issuer is your MCP endpoint URL, and both documents hang off it.
 
+A path-ful issuer, though, has two readings of *where* under the origin its
+metadata lives, and MCP clients disagree: some **insert** the well-known segment
+before the resource path (`/.well-known/oauth-authorization-server/mcp` — the RFC
+form the host draws), others **append** it after
+(`/mcp/.well-known/oauth-authorization-server`). The bridge serves both: the
+inserted forms at the origin root (`draw_oauth_metadata_routes`), and the appended
+forms — plus the `openid-configuration` OIDC alias — under the engine mount,
+automatically whenever the bridge is on. Both stay path-scoped and claim nothing
+origin-global; a client discovers the authorization server whichever convention it
+follows.
+
 If your MCP endpoint IS its origin root (a dedicated MCP domain), there is no path
 to insert and you get the bare paths — correct there, since your server really is
 that origin's only authorization server. Set `oauth_resource_path = "/"`.
@@ -650,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
@@ -675,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(
@@ -734,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/config/routes.rb

@@ -38,17 +38,31 @@ McpToolkit::Engine.routes.draw do
   # route above: the routes file is evaluated through the routes_reloader, after
   # the host's initializers/to_prepare, so the config is already set.
   #
-  # The two metadata documents are NOT here: a client looks for them at the origin
-  # root, which an engine mounted under a path cannot draw. The host draws them
-  # with `McpToolkit.draw_oauth_metadata_routes(self)`.
-  # `format: false` on each, as on the metadata routes the host draws: without it
-  # Rails' optional `(.:format)` segment matches, so `/mcp/oauth/authorize.json`
-  # reaches the action, finds no JSON template, and 500s — an unauthenticated
-  # error on a public endpoint, for a format the bridge never speaks.
+  # `format: false` on each: without it Rails' optional `(.:format)` segment
+  # matches, so `/mcp/oauth/authorize.json` reaches the action, finds no JSON
+  # template, and 500s — an unauthenticated error on a public endpoint, for a
+  # format the bridge never speaks.
   if McpToolkit.config.oauth_bridge?
     get "oauth/authorize", to: "oauth#authorize", format: false
     post "oauth/authorize", to: "oauth#approve", format: false
     post "oauth/token", to: "oauth#token", format: false
     post "oauth/register", to: "oauth#register", format: false
+
+    # The metadata documents, ALSO served path-APPENDED to the mount
+    # (`/mcp/.well-known/oauth-authorization-server`), in addition to the RFC 8414
+    # §3.1 / RFC 9728 §3.1 path-INSERTED locations the host draws at the origin
+    # root via `McpToolkit.draw_oauth_metadata_routes`. A path-ful issuer has two
+    # readings of where its metadata lives, and MCP clients disagree: some INSERT
+    # the well-known segment before the resource path (the RFC form), others APPEND
+    # it after. Observed in the wild — a hosted client requesting
+    # `<mcp>/.well-known/oauth-authorization-server` and getting a 404 it could not
+    # recover from, so it never reached registration. Serving both meets either
+    # convention. Unlike the origin-root bare paths, these stay UNDER the mount, so
+    # they claim nothing origin-global and cannot collide with an OAuth provider
+    # the host already runs. `openid-configuration` is the OIDC discovery alias a
+    # client may probe instead; it answers the same authorization-server document.
+    get ".well-known/oauth-authorization-server", to: "oauth#authorization_server", format: false
+    get ".well-known/oauth-protected-resource", to: "oauth#protected_resource", format: false
+    get ".well-known/openid-configuration", to: "oauth#authorization_server", format: false
   end
 end

data/lib/mcp_toolkit/oauth/controller_methods.rb

@@ -31,12 +31,18 @@ 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.
   PKCE_VALUE = /\A[A-Za-z0-9\-._~]{43,128}\z/
 
+  # What the token endpoint actually honours. Named once because the discovery
+  # document and the registration response MUST agree — a client reads the first
+  # to find the second, so a disagreement is this server contradicting itself.
+  SUPPORTED_GRANT_TYPES = %w[authorization_code].freeze
+  SUPPORTED_RESPONSE_TYPES = %w[code].freeze
+
   included do
     # Safe to disable: the token endpoint is called server-to-server without a CSRF
     # token, and `approve` never acts on ambient authority — it reads no session and
@@ -86,22 +92,39 @@ module McpToolkit::Oauth::ControllerMethods
       authorization_endpoint: mcp_oauth_endpoint_url("authorize"),
       token_endpoint: mcp_oauth_endpoint_url("token"),
       registration_endpoint: mcp_oauth_endpoint_url("register"),
-      response_types_supported: ["code"],
-      grant_types_supported: ["authorization_code"],
+      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
 
-  # Stateless: persisting a `client_id` nothing reads would only grow a table of
-  # strings the bridge never consults.
+  # Stateless: nothing here is persisted (no endpoint reads a `client_id`). The
+  # response still names the `redirect_uris` the client sent, because a strict
+  # client validates that they come back and abandons a registration that drops
+  # them — the failure a hosted client hit against the pre-0.6.1 stub, which
+  # returned only a `client_id`. That echo AUTHORIZES nothing: `authorize` and
+  # `token` check every `redirect_uri` against the host's allowlist independently.
+  #
+  # The auth method and the grant/response types are SUBSTITUTED rather than
+  # echoed — RFC 7591 §3.2.1 states the metadata as REGISTERED, and lets a server
+  # replace what it does not support. Reflecting the client's request instead
+  # would contradict `authorization_server`, which is where that client got this
+  # endpoint, and would promise a flow `token` rejects: a `refresh_token` echoed
+  # back is a refresh answered `unsupported_grant_type`. No `client_secret` is
+  # issued, so `none` is the only auth method a client here could perform.
   def register
-    render json: {
+    body = {
       client_id: SecureRandom.uuid,
+      client_id_issued_at: Time.now.to_i,
+      redirect_uris: mcp_oauth_param_list(:redirect_uris),
       token_endpoint_auth_method: "none",
-      grant_types: ["authorization_code"],
-      response_types: ["code"]
-    }, status: :created
+      grant_types: mcp_oauth_registered_subset(:grant_types, SUPPORTED_GRANT_TYPES),
+      response_types: mcp_oauth_registered_subset(:response_types, SUPPORTED_RESPONSE_TYPES)
+    }
+    body[:client_name] = params[:client_name].to_s if params[:client_name].present?
+    render json: body, status: :created
   end
 
   # `formats: [:html]` because there is only an HTML template and `Accept` picks
@@ -151,6 +174,19 @@ module McpToolkit::Oauth::ControllerMethods
     McpToolkit.config
   end
 
+  # A registration parameter as a plain array of strings — RFC 7591 lists arrive
+  # as JSON arrays; empty when the client sent none.
+  def mcp_oauth_param_list(key)
+    Array(params[key]).map(&:to_s)
+  end
+
+  # What the client asked for, narrowed to what this server honours. A client that
+  # asked for NOTHING supported gets the default rather than an empty array, which
+  # would state a registration able to do nothing at all.
+  def mcp_oauth_registered_subset(key, supported)
+    (mcp_oauth_param_list(key) & supported).presence || supported
+  end
+
   # ---- request validation ---------------------------------------------------
 
   # Halts both legs before their action runs. Both problems RENDER rather than
@@ -373,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.0"
+  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.0
+  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: []