mcp 1.6.0 → 1.7.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,8 +30,11 @@ 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.
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
@@ -38,6 +43,10 @@ module MCP
       #   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 +87,45 @@ 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,
           :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,
           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,
@@ -120,16 +149,33 @@ module MCP
 
           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
+          @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 +184,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/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