mcp 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7268234a54e4c0b422a916aabc08de04a4cde157b9a6b3909274ab4629885137
-  data.tar.gz: 1f48ca777ef0269c8c1f946a23efed1cd990e9ac1898568d8143d84e6c8d7fcb
+  metadata.gz: 959e38a26541c9681c11e8bc227e84c42d20e3d98de1568c0afd45c80f3b4474
+  data.tar.gz: e2bf6b0c7926e1803f9dff1279c1f5a35d96f1cf8a1e3c6141b22a97871c8ec2
 SHA512:
-  metadata.gz: bb859fc7e68f54f1a1d7c3d523a3487799c7b5ff8e3ddb5c01cd84101be79c9b5f81eeeb65b8fb06d620b87898f6c3466492e57ad921eac729c113cd5a609f8d
-  data.tar.gz: 0bf7b67aa29e8211c97168a9e9472e5fdfb1ea5a97db16d917ab1602f584db6076854e354abe0456384c70e712a797832c0949f12d5a5e76bea6761fcecab0c1
+  metadata.gz: 5f347a7259f4e728df5edad217d6963cb3428188e46244efd9be9908e84bf4a7134600c6f453249eedc87e33f998f3f51811922659f116811251a64d78f1bbee
+  data.tar.gz: 3d8d25f65c590d07157db74d87423bbde82250b5d99cf2e3182c8adbc198f534f96809265c8615160f49f963a3b2dc2a07a85db2f6f2cc83e11b068583f405de

data/README.md

@@ -1913,6 +1913,9 @@ pass an `MCP::Client::OAuth::Provider` to the transport instead of a static `Aut
 - On a `401 Unauthorized`, parse the `WWW-Authenticate` header, discover the authorization server (Protected Resource Metadata + RFC 8414 Authorization Server Metadata),
   perform Dynamic Client Registration if needed, run the OAuth 2.1 Authorization Code flow with PKCE (S256), and retry the failed request with the acquired token.
 - On subsequent 401s with a saved `refresh_token`, exchange it at the token endpoint before falling back to the full interactive flow (RFC 6749 Section 6).
+- Request the `offline_access` scope when `client_metadata[:grant_types]` includes `refresh_token` and the authorization server advertises `offline_access` in its metadata
+  `scopes_supported` (SEP-2207). This is what lets the server issue the `refresh_token` used above. As an SDK-level safeguard, when the authorization server does not advertise
+  `offline_access` the scope is also stripped from any other source (challenge, PRM, or provider-supplied scope) so a server that does not support it never receives it.
 
 ```ruby
 require "mcp"
@@ -1958,6 +1961,17 @@ Optional keyword arguments:
 - `scope`: Space-separated scopes to request when the server's `WWW-Authenticate` does not specify one.
 - `storage`: Object responding to `tokens`, `save_tokens(t)`, `client_information`, `save_client_information(info)`. Defaults to `MCP::Client::OAuth::InMemoryStorage`,
   which keeps credentials in process memory only.
+- `client_id_metadata_document_url`: URL where you publish a Client ID Metadata Document
+  (`draft-ietf-oauth-client-id-metadata-document` and the MCP authorization specification).
+  When the authorization server advertises `client_id_metadata_document_supported: true`,
+  the SDK uses this URL as the OAuth `client_id` and skips Dynamic Client Registration.
+  Spec-required: the URL MUST be `https://` with a non-root path and MUST NOT include a fragment,
+  userinfo, or `.`/`..` segments. The SDK additionally rejects query strings (the draft only marks
+  them SHOULD NOT include, but the SDK refuses to send any) for `client_id` stability.
+  Any of these failures raise `Provider::InvalidClientIDMetadataDocumentURLError`. The CIMD document
+  served at the URL is a separate JSON artifact from the `client_metadata` keyword above:
+  the DCR `client_metadata` MUST NOT include `client_id`, while the CIMD document MUST include
+  `client_id` set to the document URL, `client_name`, and `redirect_uris` covering `redirect_uri`.
 
 To persist credentials across restarts, supply your own storage:
 

data/lib/mcp/client/oauth/discovery.rb

@@ -183,6 +183,50 @@ module MCP
             false
           end
 
+          # Returns true when `url` satisfies the structural requirements for
+          # a Client ID Metadata Document URL per the MCP 2025-11-25
+          # authorization specification and `draft-ietf-oauth-client-id-metadata-document-00`.
+          #
+          # Spec-required:
+          #
+          # - scheme MUST be `https` (the loopback-`http` carve-out used for discovery does not apply:
+          #   the document URL is sent verbatim to the authorization server as the OAuth `client_id`
+          #   and travels off-loopback)
+          # - host MUST be present
+          # - path MUST be non-empty and MUST NOT be the root (`/`); the document is a discrete resource,
+          #   not the origin
+          # - URL MUST NOT carry a fragment or userinfo: a fragment is not sent to the server, and userinfo
+          #   would leak credentials into every `client_id` log line
+          # - path MUST be already free of `.` / `..` dot segments after percent-decoding, so two URLs with
+          #   the same effective path do not produce different `client_id` strings
+          #
+          # SDK policy (stricter than the draft):
+          #
+          # - URL MUST NOT carry a query string. The draft marks query components only SHOULD NOT include,
+          #   but different encodings of the same query (`?a=1&b=2` vs `?b=2&a=1`) would yield distinct
+          #   `client_id` values for the same logical document.
+          def client_id_metadata_document_url?(url)
+            return false if url.nil? || url.to_s.empty?
+
+            uri = URI.parse(url.to_s)
+            return false unless uri.scheme&.downcase == "https"
+            return false if uri.host.nil? || uri.host.empty?
+            return false unless uri.fragment.nil?
+            return false unless uri.query.nil?
+            return false if uri.respond_to?(:user) && (uri.user || uri.password)
+
+            path = uri.path.to_s
+            return false if path.empty? || path == "/"
+
+            decoded = path.gsub(/%2[eE]/, ".")
+            segments = decoded.split("/", -1)
+            return false if segments.any? { |segment| segment == "." || segment == ".." }
+
+            true
+          rescue URI::InvalidURIError
+            false
+          end
+
           # Like `canonicalize_url` but also strips query string, fragment, and
           # userinfo. This variant is used for identity comparison against
           # the request URL Faraday actually sends, which differs from the value

data/lib/mcp/client/oauth/flow.rb

@@ -59,6 +59,7 @@ module MCP
           client_info = ensure_client_registered(as_metadata: as_metadata)
 
           effective_scope = resolve_scope(scope: scope, prm: prm)
+          effective_scope = normalize_offline_access_scope(effective_scope, as_metadata: as_metadata)
           pkce = PKCE.generate
           state = SecureRandom.urlsafe_base64(32)
 
@@ -104,8 +105,16 @@ module MCP
           refresh_token = read_token("refresh_token")
           raise AuthorizationError, "Cannot refresh: no refresh_token in provider storage." unless refresh_token
 
-          client_info = @provider.client_information
-          unless client_info.is_a?(Hash) && client_info_required_value(client_info, "client_id")
+          stored_client_info = @provider.client_information
+          have_stored_client_info = stored_client_info.is_a?(Hash) && client_info_required_value(stored_client_info, "client_id")
+
+          # A CIMD-configured provider stores no `client_information` on purpose
+          # (the CIMD URL is re-resolved against the live AS metadata on every flow).
+          # Allow refresh to proceed in that case so the `refresh_token` obtained via
+          # the CIMD flow remains usable.
+          have_cimd_url = !@provider.client_id_metadata_document_url.nil?
+
+          unless have_stored_client_info || have_cimd_url
             raise AuthorizationError, "Cannot refresh: no client_information in provider storage."
           end
 
@@ -126,6 +135,18 @@ module MCP
           ensure_issuer_matches!(expected: authorization_server, returned: as_metadata["issuer"])
           ensure_secure_endpoints!(as_metadata)
 
+          client_info = if have_stored_client_info
+            # Pre-registered / DCR-issued `client_information` always wins: if the user picked an explicit identity,
+            # do not silently swap it for the CIMD URL even when the AS also advertises CIMD support.
+            stored_client_info
+          elsif as_metadata["client_id_metadata_document_supported"] == true
+            { "client_id" => @provider.client_id_metadata_document_url }
+          else
+            raise AuthorizationError,
+              "Cannot refresh: provider has a CIMD URL but the authorization server no longer advertises " \
+                "`client_id_metadata_document_supported: true`."
+          end
+
           new_tokens = exchange_refresh_token(
             as_metadata: as_metadata,
             client_info: client_info,
@@ -285,6 +306,24 @@ module MCP
           existing = @provider.client_information
           return existing if existing.is_a?(Hash) && client_info_required_value(existing, "client_id")
 
+          # Per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`,
+          # if the authorization server advertises Client ID Metadata Document support and the provider has
+          # a CIMD URL configured, use the URL as the OAuth `client_id` and skip Dynamic Client Registration.
+          #
+          # The `== true` comparison is intentional: only a JSON `boolean` `true` opts the flow in.
+          # A string `"false"`, an empty Hash, or any other truthy value MUST NOT be treated as CIMD support,
+          # otherwise a misconfigured AS could trick the client into using the CIMD `client_id` against
+          # a server that has not actually adopted it.
+          #
+          # The CIMD `client_id` is NOT persisted to storage. The AS may later stop advertising CIMD support
+          # (or the operator may rotate the CIMD URL), and a stale `client_information` entry would otherwise
+          # keep sending the old CIMD URL forever. Re-evaluating on every flow re-reads the current AS metadata
+          # and the current `provider.client_id_metadata_document_url`.
+          cimd_url = @provider.client_id_metadata_document_url
+          if cimd_url && as_metadata["client_id_metadata_document_supported"] == true
+            return { "client_id" => cimd_url }
+          end
+
           registration_endpoint = as_metadata["registration_endpoint"]
           unless registration_endpoint
             raise AuthorizationError,
@@ -403,6 +442,48 @@ module MCP
           nil
         end
 
+        # Applies the SDK's `offline_access` policy to the resolved scope. The policy has two halves:
+        #
+        # - Spec (SEP-2207): a client that wants a refresh token (signalled here by listing
+        #   `refresh_token` in its registered `grant_types`) MAY request `offline_access`
+        #   when the authorization server advertises it in metadata `scopes_supported`.
+        #   When the server advertises it and the client opted in, add it if absent.
+        #
+        # - SDK policy (defensive hardening): when the server does NOT advertise `offline_access`,
+        #   strip it from the resolved scope no matter where it came from (the `WWW-Authenticate` challenge,
+        #   PRM `scopes_supported`, or the provider-supplied scope). SEP-2207 only says clients SHOULD NOT
+        #   request unsupported scopes, but a misbehaving RS that includes `offline_access` in its challenge,
+        #   or a misconfigured PRM that lists it under `scopes_supported`, would otherwise propagate into
+        #   the authorization request even though the AS will not honour it. Stripping here keeps the SDK's
+        #   own request consistent with the AS's advertisement.
+        #
+        # Returns `nil` when the result is empty so `build_authorization_url` omits the `scope` parameter entirely.
+        # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2207
+        def normalize_offline_access_scope(scope, as_metadata:)
+          scopes = scope.to_s.split
+
+          if server_supports_offline_access?(as_metadata)
+            scopes << "offline_access" if wants_refresh_token? && !scopes.include?("offline_access")
+          else
+            scopes.delete("offline_access")
+          end
+
+          scopes.empty? ? nil : scopes.join(" ")
+        end
+
+        def server_supports_offline_access?(as_metadata)
+          supported = as_metadata["scopes_supported"]
+
+          supported.is_a?(Array) && supported.include?("offline_access")
+        end
+
+        def wants_refresh_token?
+          metadata = @provider.client_metadata
+          grant_types = metadata[:grant_types] || metadata["grant_types"]
+
+          Array(grant_types).include?("refresh_token")
+        end
+
         def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_challenge:, resource:)
           authorization_endpoint = as_metadata["authorization_endpoint"]
           unless authorization_endpoint

data/lib/mcp/client/oauth/provider.rb

@@ -25,6 +25,16 @@ module MCP
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
       #   `client_information`, and `save_client_information(info)`. Defaults to
       #   an `InMemoryStorage`.
+      # - `client_id_metadata_document_url` - URL where the client publishes its Client ID Metadata Document
+      #   (`draft-ietf-oauth-client-id-metadata-document-00` and the MCP authorization specification).
+      #   When the authorization server advertises `client_id_metadata_document_supported: true`,
+      #   the SDK uses this URL as the OAuth `client_id` and skips Dynamic Client Registration.
+      #   Spec-required: `https://` scheme, a non-root path, and no fragment, userinfo, or `.`/`..` segments.
+      #   The SDK additionally refuses to send query strings (the draft marks them only SHOULD NOT include,
+      #   but different encodings of the same query would yield different `client_id` strings for the same document).
+      #   The document served at the URL is a separate JSON artifact from the `client_metadata` keyword:
+      #   DCR `client_metadata` MUST NOT include `client_id`, while the CIMD document MUST include `client_id` set
+      #   to the URL, `client_name`, and `redirect_uris` covering `redirect_uri`.
       class Provider
         # Raised when `Provider#initialize` is called with a `redirect_uri` that
         # is neither HTTPS nor a loopback `http://` URL, per the MCP
@@ -38,12 +48,21 @@ module MCP
         # runtime; failing at construction surfaces the bug earlier.
         class UnregisteredRedirectURIError < ArgumentError; end
 
+        # Raised when `client_id_metadata_document_url` is provided but does not meet
+        # the structural requirements for a Client ID Metadata Document URL:
+        # HTTPS, non-root path, and no fragment, query, userinfo, or `.`/`..` segments.
+        # The CIMD URL is sent to the authorization server as the OAuth `client_id`,
+        # so the same Communication Security guarantee that protects the redirect URI
+        # applies and the value must unambiguously identify the document.
+        class InvalidClientIDMetadataDocumentURLError < ArgumentError; end
+
         attr_reader :client_metadata,
           :redirect_uri,
           :scope,
           :storage,
           :redirect_handler,
-          :callback_handler
+          :callback_handler,
+          :client_id_metadata_document_url
 
         def initialize(
           client_metadata:,
@@ -51,7 +70,8 @@ module MCP
           redirect_handler:,
           callback_handler:,
           scope: nil,
-          storage: nil
+          storage: nil,
+          client_id_metadata_document_url: nil
         )
           unless Discovery.secure_url?(redirect_uri)
             raise InsecureRedirectURIError,
@@ -66,12 +86,20 @@ module MCP
                 "(got #{registered.inspect}); otherwise the authorization server will reject the authorization request."
           end
 
+          if client_id_metadata_document_url && !Discovery.client_id_metadata_document_url?(client_id_metadata_document_url)
+            raise InvalidClientIDMetadataDocumentURLError,
+              "client_id_metadata_document_url #{client_id_metadata_document_url.inspect} must be an https URL " \
+                "with a non-root path and no fragment, query, userinfo, or `.`/`..` segments, " \
+                "per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`."
+          end
+
           @client_metadata = client_metadata
           @redirect_uri = redirect_uri
           @redirect_handler = redirect_handler
           @callback_handler = callback_handler
           @scope = scope
           @storage = storage || InMemoryStorage.new
+          @client_id_metadata_document_url = client_id_metadata_document_url
         end
 
         def access_token

data/lib/mcp/client.rb

@@ -146,21 +146,7 @@ module MCP
     #   end
     def tools
       # TODO: consider renaming to `list_all_tools`.
-      all_tools = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_tools(cursor: cursor)
-        all_tools.concat(page.tools)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_tools
+      fetch_all_pages { |cursor| list_tools(cursor: cursor) }.flat_map(&:tools)
     end
 
     # Returns a single page of resources from the server.
@@ -189,21 +175,7 @@ module MCP
     # @return [Array<Hash>] An array of available resources.
     def resources
       # TODO: consider renaming to `list_all_resources`.
-      all_resources = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_resources(cursor: cursor)
-        all_resources.concat(page.resources)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_resources
+      fetch_all_pages { |cursor| list_resources(cursor: cursor) }.flat_map(&:resources)
     end
 
     # Returns a single page of resource templates from the server.
@@ -232,21 +204,7 @@ module MCP
     # @return [Array<Hash>] An array of available resource templates.
     def resource_templates
       # TODO: consider renaming to `list_all_resource_templates`.
-      all_templates = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_resource_templates(cursor: cursor)
-        all_templates.concat(page.resource_templates)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_templates
+      fetch_all_pages { |cursor| list_resource_templates(cursor: cursor) }.flat_map(&:resource_templates)
     end
 
     # Returns a single page of prompts from the server.
@@ -275,21 +233,7 @@ module MCP
     # @return [Array<Hash>] An array of available prompts.
     def prompts
       # TODO: consider renaming to `list_all_prompts`.
-      all_prompts = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_prompts(cursor: cursor)
-        all_prompts.concat(page.prompts)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_prompts
+      fetch_all_pages { |cursor| list_prompts(cursor: cursor) }.flat_map(&:prompts)
     end
 
     # Calls a tool via the transport layer and returns the full response from the server.
@@ -380,6 +324,27 @@ module MCP
 
     private
 
+    # Walks every page of a list endpoint, following `next_cursor`, and returns
+    # the page results. The `seen` set guards against a server that repeats or
+    # cycles cursors, so the loop always terminates.
+    def fetch_all_pages
+      pages = []
+      seen = Set.new
+      cursor = nil
+
+      loop do
+        page = yield(cursor)
+        pages << page
+        next_cursor = page.next_cursor
+        break if next_cursor.nil? || seen.include?(next_cursor)
+
+        seen << next_cursor
+        cursor = next_cursor
+      end
+
+      pages
+    end
+
     def request(method:, params: nil)
       request_body = {
         jsonrpc: JsonRpcHandler::Version::V2_0,

data/lib/mcp/resource.rb

@@ -5,15 +5,16 @@ require_relative "resource/embedded"
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :meta
+    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :size, :meta
 
-    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
+    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, size: nil, meta: nil)
       @uri = uri
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @size = size
       @meta = meta
     end
 
@@ -25,6 +26,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        size: size,
         _meta: meta,
       }.compact
     end

data/lib/mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MCP
-  VERSION = "0.18.0"
+  VERSION = "0.19.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -87,7 +87,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.18.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.19.0
   homepage_uri: https://ruby.sdk.modelcontextprotocol.io
   source_code_uri: https://github.com/modelcontextprotocol/ruby-sdk
   bug_tracker_uri: https://github.com/modelcontextprotocol/ruby-sdk/issues