mcp 1.2.0 → 1.3.0

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    module OAuth
+      # Bounds an OAuth response body while it arrives, rather than after it has been buffered.
+      # Discovery documents, registration responses, and token responses are all small by definition,
+      # so a body that keeps growing is never something worth holding in memory. Matches the 4 MiB cap of
+      # `MCP::Client::HTTP::MAX_MESSAGE_BYTES` and `MCP::Client::Stdio::MAX_LINE_BYTES`.
+      class BoundedBody
+        MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+
+        # Raised while the body is read. Each caller translates it into its own error type,
+        # so this never reaches an embedder.
+        class TooLargeError < StandardError; end
+
+        # What the OAuth code reads from a response. The Faraday response itself is not passed on,
+        # so a later caller cannot reach the unbounded `response.body` by accident.
+        Response = Struct.new(:status, :body)
+
+        def initialize(max_bytes: MAX_RESPONSE_BYTES)
+          @max_bytes = max_bytes
+          @buffer = +""
+        end
+
+        # Faraday `on_data` streaming callback. The chunks arrive decompressed: the default `Net::HTTP` adapter negotiates
+        # `Accept-Encoding` itself and reads the body through `Net::HTTPResponse#inflater`, so a small compressed body
+        # that expands past the cap is refused partway through the expansion rather than after it. That holds only while
+        # the connection leaves `Accept-Encoding` to the adapter; see `Flow#default_http_client`.
+        def on_data
+          proc do |chunk, _received_bytes, _env|
+            @buffer << chunk
+
+            raise TooLargeError, too_large_message if @buffer.bytesize > @max_bytes
+          end
+        end
+
+        # The status paired with the bounded body. Adapters that ignore `on_data` leave the buffer empty and deliver
+        # the whole body in `response.body`, so that path is measured here instead; the bytes are already allocated by then,
+        # but refusing them still keeps an over-cap document out of `JSON.parse`.
+        def response_for(response)
+          Response.new(response.status, bounded_body(response))
+        end
+
+        private
+
+        def bounded_body(response)
+          return @buffer unless @buffer.empty?
+
+          body = response.body
+          body = body.is_a?(String) ? body : body.to_s
+          raise TooLargeError, too_large_message if body.bytesize > @max_bytes
+
+          body
+        end
+
+        def too_large_message
+          # Not "the authorization server": protected resource metadata comes from the MCP server's own origin,
+          # so this message covers endpoints on both sides of the flow.
+          "Response body from the OAuth endpoint exceeds #{@max_bytes} bytes"
+        end
+      end
+
+      private_constant :BoundedBody
+    end
+  end
+end

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

@@ -1021,26 +1021,54 @@ module MCP
         end
 
         def http_get(url)
-          http_client.get(url)
+          bounded_request do |on_data|
+            http_client.get(url) do |req|
+              req.options.on_data = on_data
+            end
+          end
         end
 
         def http_post_json(url, body)
-          http_client.post(url) do |req|
-            req.headers["Content-Type"] = "application/json"
-            req.headers["Accept"] = "application/json"
-            req.body = JSON.generate(body)
+          bounded_request do |on_data|
+            http_client.post(url) do |req|
+              req.headers["Content-Type"] = "application/json"
+              req.headers["Accept"] = "application/json"
+              req.options.on_data = on_data
+              req.body = JSON.generate(body)
+            end
           end
         end
 
         def http_post_form(url, form, headers: {})
-          http_client.post(url) do |req|
-            req.headers["Content-Type"] = "application/x-www-form-urlencoded"
-            req.headers["Accept"] = "application/json"
-            headers.each { |key, value| req.headers[key] = value }
-            req.body = URI.encode_www_form(form)
+          bounded_request do |on_data|
+            http_client.post(url) do |req|
+              req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+              req.headers["Accept"] = "application/json"
+
+              headers.each do |key, value|
+                req.headers[key] = value
+              end
+
+              req.options.on_data = on_data
+              req.body = URI.encode_www_form(form)
+            end
           end
         end
 
+        # Issues a request with the response body bounded as it arrives, and returns the status paired with
+        # that body. An over-cap response is refused rather than truncated: a partial discovery or token document
+        # cannot be validated, and `fetch_metadata_json` must not fall through to the next candidate URL either,
+        # since the same server would serve the same body.
+        def bounded_request
+          bounded = BoundedBody.new
+
+          response = yield(bounded.on_data)
+
+          bounded.response_for(response)
+        rescue BoundedBody::TooLargeError => e
+          raise AuthorizationError, "#{e.message}."
+        end
+
         def http_client
           @http_client ||= @http_client_factory.call
         end
@@ -1050,8 +1078,14 @@ module MCP
         # that transparently followed a `3xx` would let a server reach a host the checks just refused.
         # A caller passing `http_client_factory:` takes on that responsibility: add redirect following here
         # and the guards above only cover the first hop.
+        #
+        # `Accept-Encoding` is deliberately left unset. `Net::HTTP::GenericRequest` negotiates it and decodes
+        # the response only while the caller has not claimed that header; assigning it turns `decode_content` off,
+        # which would silently move `BoundedBody`'s cap onto compressed bytes and let a small body expand past it
+        # after the check.
         def default_http_client
           require "faraday"
+
           Faraday.new do |faraday|
             faraday.headers["Accept"] = "application/json"
           end

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

@@ -34,10 +34,13 @@ module MCP
           def request(token_endpoint:, id_token:, client_id:, audience:, resource:, http_client: nil)
             http_client ||= default_http_client
 
+            bounded = BoundedBody.new
+
             response = begin
-              http_client.post(token_endpoint) do |req|
+              raw_response = http_client.post(token_endpoint) do |req|
                 req.headers["Content-Type"] = "application/x-www-form-urlencoded"
                 req.headers["Accept"] = "application/json"
+                req.options.on_data = bounded.on_data
                 req.body = URI.encode_www_form(
                   "grant_type" => GRANT_TYPE,
                   "subject_token" => id_token,
@@ -48,6 +51,10 @@ module MCP
                   "client_id" => client_id,
                 )
               end
+
+              bounded.response_for(raw_response)
+            rescue BoundedBody::TooLargeError => e
+              raise ExchangeError, "#{e.message}."
             rescue Faraday::Error => e
               raise ExchangeError, "Token exchange request to #{token_endpoint} failed: #{e.class}: #{e.message}."
             end
@@ -88,8 +95,12 @@ module MCP
             assertion
           end
 
+          # `Accept-Encoding` is deliberately left unset, for the same reason as `Flow#default_http_client`:
+          # claiming that header turns Net::HTTP's `decode_content` off and would move `BoundedBody`'s cap
+          # onto compressed bytes.
           def default_http_client
             require "faraday"
+
             Faraday.new do |faraday|
               faraday.headers["Accept"] = "application/json"
             end

data/lib/mcp/client/oauth.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "oauth/bounded_body"
 require_relative "oauth/discovery"
 require_relative "oauth/flow"
 require_relative "oauth/in_memory_storage"

data/lib/mcp/server/transports/streamable_http_transport.rb

@@ -450,8 +450,13 @@ module MCP
 
           @mutex.synchronize do
             session = @sessions[session_id]
-            if related_request_id && session&.dig(:post_request_streams, related_request_id)
-              session[:post_request_streams].delete(related_request_id)
+            if related_request_id
+              # Unregister only our own stream: removing on the id alone would drop whichever stream currently holds it,
+              # which is not necessarily the one that failed. The failed stream is closed either way, and a request-scoped
+              # failure never reaches the session teardown below.
+              registered = session&.dig(:post_request_streams, related_request_id)
+              session[:post_request_streams].delete(related_request_id) if registered.equal?(stream)
+
               streams_to_close << stream
             else
               cleanup_and_collect_stream(session_id, streams_to_close)
@@ -1595,6 +1600,14 @@ module MCP
             end
           end
 
+          # `Server` refuses a duplicate id as well, but only once the request reaches it. The SSE branch below
+          # registers this request's stream under that id first, so without this check the colliding request
+          # would take over the routing entry for the moment it takes to be rejected, and its `ensure` would then
+          # clear the entry the original request still needs.
+          if related_request_id && server_session&.in_flight?(related_request_id)
+            return request_id_conflict_response
+          end
+
           if session_id && !@stateless && !@enable_json_response
             handle_request_with_sse_response(body_string, session_id, server_session, related_request_id: related_request_id)
           else
@@ -1618,7 +1631,11 @@ module MCP
               session = @sessions[session_id]
               if session && related_request_id
                 session[:post_request_streams] ||= {}
-                session[:post_request_streams][related_request_id] = stream
+
+                # Claim the id only while it is free. `handle_regular_request` already refused the colliding request,
+                # so reaching an occupied slot means a race got past that check; leaving the first stream in place keeps
+                # its messages going where they belong.
+                session[:post_request_streams][related_request_id] ||= stream
               end
             end
 
@@ -1630,7 +1647,11 @@ module MCP
               if related_request_id
                 @mutex.synchronize do
                   session = @sessions[session_id]
-                  session[:post_request_streams]&.delete(related_request_id) if session
+                  # Only retire our own registration: a request that never claimed the id, or one whose claim has
+                  # already been replaced, must not unregister the stream that owns it.
+                  registered = session&.dig(:post_request_streams, related_request_id)
+
+                  session[:post_request_streams].delete(related_request_id) if registered.equal?(stream)
                 end
               end
 
@@ -1849,6 +1870,16 @@ module MCP
           )
         end
 
+        # The POST counterpart of the GET conflict above. A request id already in flight cannot be given
+        # a stream of its own, because the id is what routes request-scoped messages back.
+        def request_id_conflict_response
+          json_rpc_error_response(
+            status: 409,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Conflict: Request id is already in flight for this session",
+          )
+        end
+
         def setup_sse_stream(session_id)
           body = create_sse_body(session_id)
 

data/lib/mcp/server.rb

@@ -219,6 +219,7 @@ module MCP
       @resources = resources
       @resource_templates = resource_templates
       @resource_index = index_resources_by_uri(resources)
+      @resources_list_handler = nil
       @server_context = server_context
       self.page_size = page_size
       self.ttl_ms = ttl_ms
@@ -426,6 +427,22 @@ module MCP
       @handlers[Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED] = block
     end
 
+    # Sets a custom handler for `resources/list` requests, letting the visible list depend on request context such as
+    # the authenticated principal or granted scope. The block returns the resource collection to serve;
+    # the framework paginates it and stamps SEP-2549 cache hints exactly as it does for the constructor-provided resources,
+    # so the block returns only the array, not the paginated result.
+    # A block that declares a `server_context:` keyword receives an `MCP::ServerContext`. When no handler is set,
+    # the constructor-provided `resources` array is served unchanged.
+    #
+    # The block is invoked once per page, so it must return a stable ordering across the pages of one logical query;
+    # the cursor is a positional offset into the returned collection.
+    #
+    # @yield [params, server_context:] The request params, and an `MCP::ServerContext` when declared.
+    # @yieldreturn [Array<MCP::Resource>] The resources to paginate.
+    def resources_list_handler(&block)
+      @resources_list_handler = block
+    end
+
     # Sets a custom handler for `resources/read` requests.
     # The block receives the parsed request params and should return resource
     # contents. The return value is set as the `contents` field of the response.
@@ -446,19 +463,25 @@ module MCP
     end
 
     # Sets a custom handler for `resources/subscribe` requests.
-    # The block receives the parsed request params. The return value is
-    # ignored; the response is always an empty result `{}` per the MCP specification.
+    # The block receives the parsed request params. The response is an empty result, except that
+    # a `_meta` hash the block returns is passed through - the spec defines no other member for this result,
+    # so any other field the block returns is dropped. Nest a subscription identifier or other advisory data
+    # under `_meta`.
     #
     # @yield [params] The request params containing `:uri`.
+    # @yieldreturn [Hash, nil] Optionally `{ _meta: { ... } }`; any other shape yields an empty result.
     def resources_subscribe_handler(&block)
       @handlers[Methods::RESOURCES_SUBSCRIBE] = block
     end
 
     # Sets a custom handler for `resources/unsubscribe` requests.
-    # The block receives the parsed request params. The return value is
-    # ignored; the response is always an empty result `{}` per the MCP specification.
+    # The block receives the parsed request params. The response is an empty result, except that
+    # a `_meta` hash the block returns is passed through - the spec defines no other member for this result,
+    # so any other field the block returns is dropped. Nest a subscription identifier or other advisory data
+    # under `_meta`.
     #
     # @yield [params] The request params containing `:uri`.
+    # @yieldreturn [Hash, nil] Optionally `{ _meta: { ... } }`; any other shape yields an empty result.
     def resources_unsubscribe_handler(&block)
       @handlers[Methods::RESOURCES_UNSUBSCRIBE] = block
     end
@@ -619,8 +642,24 @@ module MCP
 
       # `initialize` MUST NOT be cancelled (MCP spec 2025-11-25, cancellation item 2),
       # so do not track it in the in-flight registry.
-      cancellation = if related_request_id && method != Methods::INITIALIZE
-        session&.register_in_flight(related_request_id)
+      cancellation = nil
+      if related_request_id && method != Methods::INITIALIZE && session
+        cancellation = session.register_in_flight(related_request_id)
+
+        # The spec puts the uniqueness obligation on the sender - "The request ID MUST NOT have been previously used by
+        # the requestor within the same session" - and says nothing about what a receiver does with a duplicate.
+        # Answering one is the only option that stays correct: the id routes request-scoped messages back to
+        # the request that caused them, and the transport's rule is that those messages "SHOULD relate to
+        # the originating client request", which a second live request under the same id makes impossible to honor
+        # for either of them. Refused the same way a duplicate `initialize` is, and for the same reason:
+        # so that a repeated id cannot silently displace state negotiated by the first one.
+        if cancellation.nil?
+          raise RequestHandlerError.new(
+            "Invalid Request: request id #{related_request_id.inspect} is already in flight",
+            request,
+            error_type: :invalid_request,
+          )
+        end
       end
 
       ->(params) {
@@ -653,8 +692,9 @@ module MCP
             contents.is_a?(InputRequiredResult) ? contents : build_read_resource_result(contents)
           when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
             validate_resource_subscription_params!(params)
-            dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
-            {}
+            handler_result = dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
+
+            subscription_result(handler_result)
           when Methods::TOOLS_CALL
             call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
           when Methods::PROMPTS_GET
@@ -727,7 +767,10 @@ module MCP
           reported_exception = wrapped
           raise wrapped
         ensure
-          session&.unregister_in_flight(related_request_id) if related_request_id
+          # `cancellation` is non-nil exactly when this request claimed the id above, so this also keeps `initialize`
+          # (which never registers) from evicting an in-flight registration under a reused id when the duplicate-`initialize`
+          # refusal raises out of the handler.
+          session&.unregister_in_flight(related_request_id, cancellation: cancellation) if related_request_id && cancellation
         end
       }
     end
@@ -1080,6 +1123,18 @@ module MCP
       end
     end
 
+    # The `resources/subscribe` and `resources/unsubscribe` result is an empty object except for the optional `_meta`
+    # every result may carry: the TypeScript SDK validates it against `EmptyResultSchema.strict()`,
+    # which rejects any other member, so only `_meta` is passed through from the handler. A handler that returns
+    # anything else keeps the empty `{}` result it had before, so returning a subscription identifier or
+    # other advisory data means nesting it under `_meta`.
+    def subscription_result(handler_result)
+      return {} unless handler_result.is_a?(Hash)
+
+      meta = handler_result[:_meta] || handler_result["_meta"]
+      meta.is_a?(Hash) ? { _meta: meta } : {}
+    end
+
     def validate_initialize_params!(params)
       unless params.is_a?(Hash)
         raise RequestHandlerError.new("Invalid params", params, error_type: :invalid_params)
@@ -1273,12 +1328,28 @@ module MCP
       call_prompt_template_with_args(prompt, prompt_args, server_context)
     end
 
-    def list_resources(request)
-      page = paginate(@resources, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+    def list_resources(request, server_context: nil)
+      resources = if @resources_list_handler
+        invoke_resources_list_handler(request, server_context)
+      else
+        @resources
+      end
+
+      page = paginate(resources, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
 
       apply_cache_metadata({ resources: page[:items], nextCursor: page[:next_cursor] }.compact)
     end
 
+    # Calls the `resources_list_handler` block, forwarding `server_context:` only when the block opts in
+    # by declaring the keyword (the same rule `dispatch_optional_context_handler` applies).
+    def invoke_resources_list_handler(request, server_context)
+      if handler_declares_server_context?(@resources_list_handler)
+        @resources_list_handler.call(request, server_context: server_context)
+      else
+        @resources_list_handler.call(request)
+      end
+    end
+
     # Default `resources/read` handler: routes to class-based resources and resource templates.
     # Fully replaced when `resources_read_handler` is set. When no class-based resource or template is registered,
     # unknown URIs keep the historical no-op `[]` response instead of raising.
@@ -1507,7 +1578,7 @@ module MCP
       # Transports parse incoming JSON with `symbolize_names: true`, so `arguments` already arrives symbolized
       # at every nesting level. This top-level transform only guards callers that hand in string-keyed top-level arguments;
       # it does not recurse, and nested object keys remain symbols. Tools therefore receive symbol keys all the way down.
-      # See docs/building-servers.md ("Tool argument keys").
+      # See docs/server/tools.md ("Tool argument keys").
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))

data/lib/mcp/server_session.rb

@@ -58,19 +58,41 @@ module MCP
       @era = era
     end
 
-    # Registers a `Cancellation` token for an in-flight request.
+    # Registers a `Cancellation` token for an in-flight request, or returns `nil` when `request_id` is already in flight.
+    # The request id is the only key that routes request-scoped notifications, server-to-client requests,
+    # and `notifications/cancelled` back to the request that caused them, so a second live request under the same id
+    # has no destination of its own. Rather than let the newcomer displace the registration, report the collision
+    # and leave the first request intact; the caller turns that into an Invalid Request.
     def register_in_flight(request_id)
       return if request_id.nil?
 
       cancellation = Cancellation.new(request_id: request_id)
-      @in_flight_mutex.synchronize { @in_flight[request_id] = cancellation }
-      cancellation
+      registered = @in_flight_mutex.synchronize do
+        next false if @in_flight.key?(request_id)
+
+        @in_flight[request_id] = cancellation
+        true
+      end
+
+      registered ? cancellation : nil
     end
 
-    def unregister_in_flight(request_id)
+    # Removes an in-flight registration. Passing the `Cancellation` that `register_in_flight` returned removes
+    # the entry only while it is still that one, so a request can never evict a registration it does not own.
+    def unregister_in_flight(request_id, cancellation: nil)
       return if request_id.nil?
 
-      @in_flight_mutex.synchronize { @in_flight.delete(request_id) }
+      @in_flight_mutex.synchronize do
+        next if cancellation && !@in_flight[request_id].equal?(cancellation)
+
+        @in_flight.delete(request_id)
+      end
+    end
+
+    # Whether `request_id` is currently in flight, so a transport can refuse a colliding request
+    # before registering any state of its own for it.
+    def in_flight?(request_id)
+      !lookup_in_flight(request_id).nil?
     end
 
     def lookup_in_flight(request_id)

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -46,6 +46,7 @@ files:
 - lib/mcp/client/mcp_param_headers.rb
 - lib/mcp/client/modern_envelope.rb
 - lib/mcp/client/oauth.rb
+- lib/mcp/client/oauth/bounded_body.rb
 - lib/mcp/client/oauth/client_credentials_provider.rb
 - lib/mcp/client/oauth/cross_app_access_provider.rb
 - lib/mcp/client/oauth/discovery.rb
@@ -106,7 +107,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.2.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.3.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