mcp 1.2.0 → 1.4.0

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.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.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.4.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