mcp 1.6.1 → 1.8.0

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

@@ -20,6 +20,8 @@ module MCP
       #   request. Must be one of `redirect_uris` in `client_metadata`.
       # - `redirect_handler` - Callable invoked with the fully-built authorization
       #   URL (a `URI`). Implementations typically open the user's browser.
+      #
+      # Optional keyword arguments:
       # - `callback_handler` - Callable invoked after `redirect_handler`. Returns
       #   `[code, state]` or `[code, state, iss]`, where `code` is the authorization code,
       #   `state` is the `state` parameter received on the redirect URI, and `iss` is
@@ -28,16 +30,27 @@ module MCP
       #   must match the authorization server's issuer, and a nil `iss` is
       #   rejected when the AS advertises `authorization_response_iss_parameter_supported`.
       #   The 2-element form skips the check for backward compatibility.
-      #
-      # Optional keyword arguments:
+      #   Omit it when the redirect arrives in a later request, as it does in a web application:
+      #   the flow then stops after `redirect_handler` with a pending authorization saved in `storage`,
+      #   and the request that receives the redirect finishes it with `Flow#finish!`.
+      # - `pending_authorization_max_age` - Seconds a pending authorization stays redeemable, counted from the moment
+      #   `run!` saves it, when `callback_handler` is omitted. Defaults to `DEFAULT_PENDING_AUTHORIZATION_MAX_AGE`.
       # - `scope`   - String of space-separated scopes to request when the server's
       #   `WWW-Authenticate` does not specify one.
+      # - `scope_selector` - Callable receiving a read-only Array of PRM `scopes_supported` tokens when
+      #   those defaults are selected without a challenged scope. Return an Array containing a subset;
+      #   `[]` requests none of the PRM defaults. Challenged scopes and provider fallback bypass it.
+      #   The existing `offline_access` policy runs afterward; endpoint query parameters are unchanged.
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
       #   `client_information`, and `save_client_information(info)`. Defaults to
       #   an `InMemoryStorage`. Persisted `client_information` is stamped with
       #   an `"issuer"` member binding it to the authorization server that
       #   issued it (SEP-2352); when the authorization server changes, the SDK discards
       #   the stale registration and tokens and re-registers.
+      #   Without `callback_handler`, it must also respond to `save_pending_authorization(state, pending)`,
+      #   `pending_authorization(state)`, and `delete_pending_authorization(state)`; the last must remove the entry
+      #   and return it atomically, returning `nil` when there was none, and the storage should expire entries
+      #   older than `pending_authorization_max_age`, as `InMemoryStorage` does.
       # - `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`,
@@ -78,25 +91,47 @@ module MCP
         # applies and the value must unambiguously identify the document.
         class InvalidClientIDMetadataDocumentURLError < ArgumentError; end
 
+        # Raised when `Provider#initialize` is called without `callback_handler` and with a `storage`
+        # that cannot hold a pending authorization between the request that sends the user to the authorization server
+        # and the request that receives the redirect.
+        class PendingAuthorizationStorageError < ArgumentError; end
+
+        # Seconds a pending authorization stays redeemable, counted from the moment `run!` saves it, when the provider has
+        # no `callback_handler`; long enough for a user to sign in and consent at the authorization server. It is also
+        # the age past which `InMemoryStorage` drops an authorization that was never finished, at its next save, so that
+        # an abandoned one does not keep its PKCE verifier in memory for the life of the process; a custom storage should
+        # expire entries at the same age.
+        DEFAULT_PENDING_AUTHORIZATION_MAX_AGE = 600
+
+        PENDING_AUTHORIZATION_STORAGE_METHODS = [
+          :save_pending_authorization,
+          :pending_authorization,
+          :delete_pending_authorization,
+        ].freeze
+
         attr_reader :client_metadata,
           :redirect_uri,
           :scope,
+          :scope_selector,
           :storage,
           :redirect_handler,
           :callback_handler,
-          :client_id_metadata_document_url
+          :client_id_metadata_document_url,
+          :pending_authorization_max_age
 
         def initialize(
           client_metadata:,
           redirect_uri:,
           redirect_handler:,
-          callback_handler:,
+          callback_handler: nil,
           scope: nil,
+          scope_selector: nil,
           storage: nil,
           client_id_metadata_document_url: nil,
           authorization_request_validator: nil,
           token_request_params: nil,
-          http_client_customizer: nil
+          http_client_customizer: nil,
+          pending_authorization_max_age: DEFAULT_PENDING_AUTHORIZATION_MAX_AGE
         )
           unless Discovery.secure_url?(redirect_uri)
             raise InsecureRedirectURIError,
@@ -118,18 +153,40 @@ module MCP
                 "per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`."
           end
 
+          unless scope_selector.nil? || scope_selector.respond_to?(:call)
+            raise ArgumentError, "scope_selector must respond to call (got #{scope_selector.class})."
+          end
+
           http_client_customizer = validated_http_client_customizer(http_client_customizer)
 
+          unless pending_authorization_max_age.is_a?(Integer) && pending_authorization_max_age.positive?
+            raise ArgumentError, "pending_authorization_max_age must be a positive Integer number of seconds (got #{pending_authorization_max_age.inspect})."
+          end
+
+          # The default storage drops abandoned pending authorizations at the same age the flow stops redeeming them.
+          storage ||= InMemoryStorage.new(pending_authorization_max_age: pending_authorization_max_age)
+
+          if callback_handler.nil?
+            missing = PENDING_AUTHORIZATION_STORAGE_METHODS.reject { |method| storage.respond_to?(method) }
+            unless missing.empty?
+              raise PendingAuthorizationStorageError,
+                "Without a callback_handler the authorization finishes in a later request, so storage must also respond to " \
+                  "#{missing.join(", ")} (#{storage.class} does not)."
+            end
+          end
+
           @client_metadata = client_metadata
           @redirect_uri = redirect_uri
           @redirect_handler = redirect_handler
           @callback_handler = callback_handler
           @scope = scope
-          @storage = storage || InMemoryStorage.new
+          @scope_selector = scope_selector
+          @storage = storage
           @client_id_metadata_document_url = client_id_metadata_document_url
           @authorization_request_validator = authorization_request_validator
           @token_request_params = frozen_token_request_params(token_request_params)
           @http_client_customizer = http_client_customizer
+          @pending_authorization_max_age = pending_authorization_max_age
         end
 
         # Identifies the OAuth flow this provider drives.
@@ -138,6 +195,20 @@ module MCP
         def authorization_flow
           :authorization_code
         end
+
+        def save_pending_authorization(state, pending)
+          @storage.save_pending_authorization(state, pending)
+        end
+
+        def pending_authorization(state)
+          @storage.pending_authorization(state)
+        end
+
+        # Returns the entry the storage removed, or `nil`. `Flow#finish!` redeems the code only when it gets
+        # the entry back, so of two callbacks racing on the same `state`, only one can.
+        def delete_pending_authorization(state)
+          @storage.delete_pending_authorization(state)
+        end
       end
     end
   end

data/lib/mcp/client/stdio.rb

@@ -442,17 +442,22 @@ module MCP
           # other server-to-client requests over stdio stay unsupported as documented,
           # and notifications carry no id.
           if parsed.is_a?(Hash) && parsed.key?("method")
-            # A JSON-RPC id is a String or a Number; the reference SDKs reject other shapes at
-            # schema validation, so a ping carrying one is skipped rather than echoed back.
-            answer_ping(parsed) if parsed["method"] == MCP::Methods::PING && json_rpc_id?(parsed["id"])
+            # A JSON-RPC id is a String or a Number, and `jsonrpc` is "2.0"; the reference SDKs reject
+            # other shapes at schema validation, so a ping carrying one is skipped rather than echoed back.
+            answer_ping(parsed) if answerable_ping?(parsed)
             next
           end
 
           # A JSON-RPC message is an object; skip a non-object frame (array or scalar)
           # the same way as a frame without an id.
           next unless parsed.is_a?(Hash) && parsed.key?("id")
+          next unless parsed["id"] == request_id
 
-          return parsed if parsed["id"] == request_id
+          # Nothing else will answer the awaited request, so a response that is not JSON-RPC 2.0 fails it
+          # instead of being skipped: without a `read_timeout`, skipping would wait forever.
+          raise_invalid_response!(method, params) unless JsonRpcHandler.valid_version?(parsed["jsonrpc"])
+
+          return parsed
         end
       rescue JSON::ParserError => e
         raise RequestHandlerError.new(
@@ -475,6 +480,10 @@ module MCP
         # surface as an error of the unrelated request whose response the loop is reading.
       end
 
+      def answerable_ping?(parsed)
+        parsed["method"] == MCP::Methods::PING && json_rpc_id?(parsed["id"]) && JsonRpcHandler.valid_version?(parsed["jsonrpc"])
+      end
+
       def json_rpc_id?(id)
         id.is_a?(String) || id.is_a?(Numeric)
       end
@@ -532,6 +541,16 @@ module MCP
           error_type: :internal_error,
         )
       end
+
+      # The line framing is intact, so the transport stays usable; the received value is left out of
+      # the message because it can be any JSON value.
+      def raise_invalid_response!(method, params)
+        raise RequestHandlerError.new(
+          'Server response is not a valid JSON-RPC 2.0 message: "jsonrpc" must be "2.0"',
+          { method: method, params: params },
+          error_type: :internal_error,
+        )
+      end
     end
   end
 end

data/lib/mcp/icon.rb

@@ -9,9 +9,70 @@ module MCP
   # is not judged: `src` may be any non-empty `String` (the schema types it as a URI, which an empty `String`
   # is not, and the specification allows an HTTP/HTTPS URL or a `data:` URI), and a size may be any `String`
   # (the specification expects `WxH` or `"any"`).
+  #
+  # Wherever an `Icon` is accepted (`Server.new(icons:)` and the `icons` of a tool, prompt, resource, or resource template),
+  # a Hash is accepted too and converted through `Icon.from`, so it is checked the same way.
   class Icon
     SUPPORTED_THEMES = ["light", "dark"].freeze
 
+    # The keys `from` accepts in a Hash: the keyword names of `new` and the wire name `mimeType`,
+    # as Symbols or Strings.
+    HASH_KEYWORDS = {
+      "src" => :src,
+      "mimeType" => :mime_type,
+      "mime_type" => :mime_type,
+      "sizes" => :sizes,
+      "theme" => :theme,
+    }.freeze
+    private_constant :HASH_KEYWORDS
+
+    class << self
+      # Returns `value` when it is already an `Icon`, builds one from a Hash, and refuses anything else.
+      def from(value)
+        return value if value.is_a?(Icon)
+
+        unless value.is_a?(Hash)
+          raise ArgumentError, "An icon must be an MCP::Icon or a Hash (got #{value.class})."
+        end
+
+        keywords = {}
+        value.each do |key, member|
+          unless key.is_a?(Symbol) || key.is_a?(String)
+            raise ArgumentError, "An icon Hash key must be a Symbol or a String (got #{key.class})."
+          end
+
+          keyword = HASH_KEYWORDS[key.to_s]
+          unless keyword
+            raise ArgumentError, "An icon Hash may only hold src, mimeType (or mime_type), sizes, and theme (got #{key.inspect})."
+          end
+          raise ArgumentError, "An icon Hash gives #{keyword} twice." if keywords.key?(keyword)
+
+          keywords[keyword] = member
+        end
+
+        new(**keywords)
+      end
+
+      # Converts the `icons` argument of a server, tool, prompt, resource, or resource template: `nil` stays `nil`,
+      # each element of an Array goes through `from` into a frozen Array, and anything else is refused.
+      # The frozen Array keeps a later `<<` on a reader from adding an element these checks never saw.
+      def from_list(value)
+        return if value.nil?
+
+        unless value.is_a?(Array)
+          raise ArgumentError, "icons must be nil or an Array of MCP::Icon or Hash (got #{value.class})."
+        end
+
+        icons = value.each_with_index.map do |icon, index|
+          from(icon)
+        rescue ArgumentError => e
+          raise ArgumentError, "icons[#{index}]: #{e.message}"
+        end
+
+        icons.freeze
+      end
+    end
+
     attr_reader :mime_type, :sizes, :src, :theme
 
     def initialize(mime_type: nil, sizes: nil, src:, theme: nil)

data/lib/mcp/prompt.rb

@@ -72,7 +72,7 @@ module MCP
         if value == NOT_SET
           @icons_value
         else
-          @icons_value = value
+          @icons_value = Icon.from_list(value)
         end
       end
 

data/lib/mcp/resource.rb

@@ -88,7 +88,7 @@ module MCP
         if value == NOT_SET
           @icons_value
         else
-          @icons_value = value
+          @icons_value = Icon.from_list(value)
         end
       end
 
@@ -147,7 +147,7 @@ module MCP
       @name = name
       @title = title
       @description = description
-      @icons = icons
+      @icons = Icon.from_list(icons)
       @mime_type = mime_type
       @annotations = annotations
       @size = size

data/lib/mcp/resource_template.rb

@@ -89,7 +89,7 @@ module MCP
         if value == NOT_SET
           @icons_value
         else
-          @icons_value = value
+          @icons_value = Icon.from_list(value)
         end
       end
 
@@ -158,7 +158,7 @@ module MCP
       @name = name
       @title = title
       @description = description
-      @icons = icons
+      @icons = Icon.from_list(icons)
       @mime_type = mime_type
       @annotations = annotations
       @meta = meta

data/lib/mcp/server/oauth/access_token.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module MCP
+  class Server
+    module OAuth
+      # The result of a successful token verification: the resource-server-side view of an access token.
+      # Instances are produced by a `TokenVerifier` and reach tool/prompt/resource handlers as `server_context.auth_info`.
+      #
+      # The field set is the union of what the official SDKs converged on (Python `AccessToken` and TypeScript `AuthInfo`):
+      #
+      # - `token` - the raw bearer token as presented by the client
+      # - `client_id` - the OAuth client the token was issued to
+      # - `scopes` - granted scopes as an array of strings
+      # - `expires_at` - expiry as an Integer unix timestamp, or nil when the token does not expire
+      # - `subject` - the end user (`sub` claim), when known
+      # - `issuer` - the authorization server that issued the token (`iss` claim)
+      # - `audience` - the raw `aud` value (String or Array), when known
+      # - `resource` - the canonical RFC 8707 resource identifier the verifier matched the token against,
+      #   useful for tenancy checks inside handlers
+      # - `claims` - the full claim/introspection-response Hash for anything not covered by the named fields
+      class AccessToken
+        attr_reader :token, :client_id, :scopes, :expires_at, :subject, :issuer, :audience, :resource, :claims
+
+        def initialize(token:, client_id: nil, scopes: [], expires_at: nil, subject: nil, issuer: nil, audience: nil, resource: nil, claims: {})
+          @token = token
+          @client_id = client_id
+          @scopes = scopes
+          @expires_at = expires_at
+          @subject = subject
+          @issuer = issuer
+          @audience = audience
+          @resource = resource
+          @claims = claims
+          @scope_matcher = nil
+        end
+
+        # Per RFC 7519 Section 4.1.4, a token must not be accepted on or after its expiry time.
+        # Tokens without an expiry never count as expired here; verifiers that require an expiry must enforce that themselves
+        # (`JWTVerifier` does, the TypeScript SDK rejects such tokens outright, and Python accepts them like this class —
+        # the divergence is deliberate: opaque-token verifiers may have no expiry to report even though the authorization server enforces one).
+        def expired?(now: Time.now.to_i)
+          return false if expires_at.nil?
+
+          expires_at <= now
+        end
+
+        # Whether the token grants `scope`: exact membership by default. When the authenticator attached its `scope_matcher:`
+        # (see `with_scope_matcher`), that callable decides instead, so a hierarchical scope scheme is honored the same way
+        # at the endpoint gate and inside handlers via `require_scopes!`.
+        def scope?(scope)
+          return scopes.include?(scope.to_s) if @scope_matcher.nil?
+
+          !!@scope_matcher.call(scope.to_s, scopes)
+        end
+
+        # A copy of this token whose `scope?` consults `matcher`, a `(required_scope, granted_scopes) -> Boolean` callable.
+        # The receiver is left untouched; a nil matcher returns the receiver itself.
+        def with_scope_matcher(matcher)
+          return self if matcher.nil?
+
+          dup.tap { |copy| copy.scope_matcher = matcher }
+        end
+
+        # Mirrors `to_h`: the default `inspect` would print `@token`, leaking the credential into exception reports and debug output.
+        def inspect
+          "#<#{self.class.name} #{to_h.inspect}>"
+        end
+
+        # Omits `token` so the result is safe to log without leaking the credential.
+        def to_h
+          {
+            client_id: client_id,
+            scopes: scopes,
+            expires_at: expires_at,
+            subject: subject,
+            issuer: issuer,
+            audience: audience,
+            resource: resource,
+            claims: claims,
+          }.compact
+        end
+
+        protected
+
+        attr_writer :scope_matcher
+      end
+    end
+  end
+end

data/lib/mcp/server/oauth/authenticator.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "access_token"
+require_relative "challenge"
+require_relative "errors"
+
+module MCP
+  class Server
+    module OAuth
+      # The verification core shared by `Middleware` and the streamable HTTP transport's built-in enforcement:
+      # extracts the bearer token from a Rack env, runs it through the verifier, checks scopes, and maps each failure
+      # to the RFC 6750 challenge response it deserves.
+      #
+      # - `token_verifier` - anything responding to `verify(token)`; see `TokenVerifier` for the contract.
+      #   Built-ins: `JWTVerifier`, `IntrospectionVerifier`.
+      # - `required_scopes` - scopes the token must include, all of them; a shortfall produces 403 `insufficient_scope` (step-up).
+      # - `resource_metadata` - a `ProtectedResourceMetadata`; its well-known URL and `scopes_supported` feed the challenges.
+      #   Pass `resource_metadata_url:` instead to point at a document served elsewhere.
+      # - `scope_matcher` - optional callable `(required_scope, granted_scopes) -> Boolean` for deployments
+      #   whose scopes form a hierarchy; the MCP authorization specification requires a broader scope to satisfy
+      #   the narrower scopes it implies, which exact membership (the default) cannot express. The matcher also rides
+      #   on the returned `AccessToken`, so `require_scopes!` and `scope?` inside handlers apply the same semantics.
+      class Authenticator
+        # RFC 6750 Section 2.1: the scheme and the token are separated by spaces (`1*SP`), never by other whitespace.
+        BEARER_PATTERN = /\ABearer +(?<token>\S+)\z/i.freeze
+        # Whether the header names the Bearer scheme at all, well-formed or not. `Bearer` followed by anything other
+        # than a space names no Bearer credentials, the way the Python and TypeScript servers read it.
+        BEARER_SCHEME_PATTERN = /\ABearer(?: |\z)/i.freeze
+        private_constant :BEARER_PATTERN, :BEARER_SCHEME_PATTERN
+
+        # Upper bound on the presented token, applied before any verification so oversized garbage neither reaches
+        # cryptographic parsing nor gets forwarded to an introspection endpoint. Real-world access tokens stay far below this;
+        # web servers cap the whole header section around 16 KiB.
+        MAX_TOKEN_BYTES = 8192
+
+        def initialize(token_verifier:, required_scopes: [], resource_metadata: nil, resource_metadata_url: nil, scope_matcher: nil)
+          @verifier = token_verifier
+          @required_scopes = Array(required_scopes)
+          @resource_metadata = resource_metadata
+          @resource_metadata_url = resource_metadata_url || resource_metadata&.well_known_url
+          @scope_matcher = scope_matcher
+        end
+
+        # @param env [Hash] the Rack env
+        # @return [AccessToken]
+        # @raise [MissingTokenError, InvalidRequestError, InvalidTokenError, InsufficientScopeError]
+        def authenticate(env)
+          token = extract_bearer_token(env)
+
+          access_token = @verifier.verify(token)
+          raise InvalidTokenError if access_token.nil?
+
+          access_token = attach_scope_matcher(access_token)
+          check_scopes!(access_token)
+          access_token
+        end
+
+        # Maps an `OAuth::Error` raised by `authenticate` (or by a handler's `require_scopes!`) to the Rack response carrying
+        # the matching challenge. An `Error` outside the four built-in classes, such as one a custom verifier defines,
+        # is a token rejection and answers 401 like an invalid token; anything else is a programming error.
+        def challenge_response(error)
+          case error
+          when MissingTokenError
+            Challenge.missing_token_response(scope: scope_hint, resource_metadata: @resource_metadata_url)
+          when InvalidRequestError
+            Challenge.invalid_request_response(error_description: error.message, resource_metadata: @resource_metadata_url)
+          when InsufficientScopeError
+            Challenge.insufficient_scope_response(
+              error_description: error.message,
+              scope: scope_hint(error.required_scopes),
+              resource_metadata: @resource_metadata_url,
+            )
+          when Error
+            Challenge.invalid_token_response(
+              error_description: error.message,
+              scope: scope_hint,
+              resource_metadata: @resource_metadata_url,
+            )
+          else
+            raise ArgumentError, "unexpected error class: #{error.class}"
+          end
+        end
+
+        private
+
+        def extract_bearer_token(env)
+          header = env["HTTP_AUTHORIZATION"]
+          raise MissingTokenError if header.nil? || header.empty?
+
+          # Matched as bytes: a Rack server hands the header over as ASCII-8BIT, but a test request or a framework can tag it UTF-8,
+          # and a regexp raises on an invalid byte sequence in a UTF-8 string. As bytes, such a token simply fails verification.
+          bytes = header.b
+
+          # A header naming another scheme carries no Bearer credentials: RFC 6750 Section 3.1 counts a request that
+          # "attempted using an unsupported authentication method" among those lacking authentication information,
+          # which get the bare challenge, and the Python and TypeScript servers answer it 401 as well.
+          # A header that names Bearer but is malformed is a bad request (`invalid_request` in the same section).
+          raise MissingTokenError unless BEARER_SCHEME_PATTERN.match?(bytes)
+
+          match = BEARER_PATTERN.match(bytes)
+          raise InvalidRequestError, "Authorization header must carry a single Bearer token" if match.nil?
+
+          token = match[:token]
+          raise InvalidTokenError, "Token exceeds the maximum accepted length" if token.bytesize > MAX_TOKEN_BYTES
+
+          token
+        end
+
+        def check_scopes!(access_token)
+          missing_scopes = @required_scopes.reject { |scope| scope_satisfied?(scope, access_token) }
+          return if missing_scopes.empty?
+
+          raise InsufficientScopeError.new(
+            "Token is missing required scopes: #{missing_scopes.join(", ")}",
+            required_scopes: @required_scopes,
+          )
+        end
+
+        # A verifier result that is not an `AccessToken` (a duck-typed object from a custom verifier) keeps its own `scope?`;
+        # the endpoint gate below still applies the matcher to it directly.
+        def attach_scope_matcher(access_token)
+          return access_token if @scope_matcher.nil? || !access_token.respond_to?(:with_scope_matcher)
+
+          access_token.with_scope_matcher(@scope_matcher)
+        end
+
+        # A verifier result without a `scopes` reader (a duck-typed object offering only `scope?`) keeps its own judgement,
+        # since the matcher needs the granted list to reason about a hierarchy.
+        def scope_satisfied?(scope, access_token)
+          return access_token.scope?(scope) if @scope_matcher.nil? || !access_token.respond_to?(:scopes)
+
+          @scope_matcher.call(scope, access_token.scopes)
+        end
+
+        # The scope hint the spec recommends including in challenges: the scopes of the failing operation when known,
+        # the scopes this authenticator enforces otherwise, or the resource's advertised scopes as a fallback.
+        # `offline_access` is never advertised: refresh token issuance is not a resource requirement per
+        # the MCP authorization specification.
+        def scope_hint(operation_scopes = [])
+          scopes = operation_scopes
+          scopes = @required_scopes if scopes.empty?
+          scopes = Array(@resource_metadata&.scopes_supported) if scopes.empty?
+          scopes -= ["offline_access"]
+
+          scopes.empty? ? nil : scopes.join(" ")
+        end
+      end
+    end
+  end
+end