mcp 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 237a819736a62982990aafa3889226e94101be576d2a2c917b4ce3f9be8bc5e1
-  data.tar.gz: 12bb5f7d9b6ecc0399cd3d6f591a21dbc2c0f087b7c8b0ffd9d38621d496671d
+  metadata.gz: 402b424bd7e0cf6abce69f6613b929d63a259d8d71fbc479378a0de40e2b6bde
+  data.tar.gz: b4fa00e094ab14bf0adf36165cb6cda2e0747cb369fff727227bad16edbd4090
 SHA512:
-  metadata.gz: aed9090f1de375b2fbd54432e7dd5f2b59c50f0a1875594f6319c07fb213047e296579e85ecfc23941df58512b52eae8a4ba34e1b298156306f470b0632180f4
-  data.tar.gz: 179d5d8e4a88985fb1e5e50cc66a9b5b8860abdf3484d935cde65b04d1f9f9295ddec625c037984698e9e5ad5e993091ac082243202132292cde100a8830dabc
+  metadata.gz: 50741bdb178837e7f87458c91f1b5c0d678139f4949099321d093c0c9936542e6c01b7666b393c5009ad88c78aacac2aa32c28ab5c6c2cdb871bbb09326b9a96
+  data.tar.gz: 75f6bce397dd2034e6315ed33ad9bf908656e5e4ecb53f625d40053d38a7b7373561d87a13798551517cb338798083dabe8e46d4cf4218c76fbcd99536bdf35c

data/README.md

@@ -9,7 +9,7 @@ Detailed guides are available at https://ruby.sdk.modelcontextprotocol.io.
 - Build [MCP servers](https://ruby.sdk.modelcontextprotocol.io/server/) that expose tools, prompts, and resources to any MCP host
 - Build [MCP clients](https://ruby.sdk.modelcontextprotocol.io/client/) that connect to any MCP server, with automatic lifecycle negotiation and OAuth 2.1 authorization
 - Speak every standard transport: stdio and Streamable HTTP (including SSE), with a Rails integration
-- Cover the full protocol surface: server-to-client requests, multi round-trip results, notifications, progress, logging, cancellation, completions, and pagination
+- Cover the full protocol surface: server-to-client requests, multi round-trip requests, notifications, progress, logging, cancellation, completions, and pagination
 
 ## Installation
 

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

@@ -129,6 +129,12 @@ module MCP
         #   on a `subscriptions/listen` stream; the periodic write frees the stream's slot when the peer
         #   has gone away. Defaults to `DEFAULT_LISTEN_KEEPALIVE_INTERVAL` (15); pass `nil` to disable
         #   when an upstream proxy already keeps the stream alive.
+        # @param serve_subscriptions_listen [Boolean] whether `subscriptions/listen` opens a stream.
+        #   A host that buffers responses and cannot serve an open SSE stream (e.g. the Rails controller pattern,
+        #   which builds a fresh transport per request and renders the body) passes `false`:
+        #   the method then answers 404 with JSON-RPC `-32601` like any unimplemented method,
+        #   and `Server#discover` stops advertising the `listChanged`/`subscribe` capability flags,
+        #   keeping the advertisement and the actual behavior in agreement. Defaults to `true`.
         # @param server_to_client_request_timeout [Numeric] seconds a server-to-client request waits for its
         #   response before the transport stops waiting and raises `MCP::Server::RequestTimeoutError`.
         #   Defaults to `DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT` (600); individual calls override it with `timeout:`.
@@ -145,6 +151,7 @@ module MCP
           max_request_bytes: DEFAULT_MAX_REQUEST_BYTES,
           max_listen_subscriptions: DEFAULT_MAX_LISTEN_SUBSCRIPTIONS,
           listen_keepalive_interval: DEFAULT_LISTEN_KEEPALIVE_INTERVAL,
+          serve_subscriptions_listen: true,
           server_to_client_request_timeout: DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT
         )
           super(server)
@@ -162,7 +169,8 @@ module MCP
           @allowed_origins = Array(allowed_origins).map(&:downcase).freeze
           @pending_responses = {}
 
-          # Maps a `subscriptions/listen` request id to `{ stream: stream_object, filter: honored_subscription_filter }` (SEP-2575).
+          # Maps a `subscriptions/listen` request id to
+          # `{ stream: stream_object, filter: honored_subscription_filter, active: boolean, write_mutex: Mutex }` (SEP-2575).
           # In-process only; a multi-worker deployment needs an external event bus to fan notifications out across processes,
           # which is a follow-up.
           @listen_subscriptions = {}
@@ -211,6 +219,7 @@ module MCP
           end
 
           @listen_keepalive_interval = listen_keepalive_interval
+          @serve_subscriptions_listen = serve_subscriptions_listen
 
           unless server_to_client_request_timeout.is_a?(Numeric) && server_to_client_request_timeout.positive?
             raise ArgumentError, "server_to_client_request_timeout must be a positive number"
@@ -260,10 +269,12 @@ module MCP
           handle_request(Rack::Request.new(env))
         end
 
-        # The `subscriptions/listen` notification stream (SEP-2575) is served on the modern path,
-        # so `Server#discover` may advertise `listChanged`/`subscribe` capability flags.
+        # Whether this transport serves the `subscriptions/listen` notification stream (SEP-2575).
+        # Gates both the route (a refusing transport answers the method as unimplemented) and
+        # the `listChanged`/`subscribe` capability flags `Server#discover` advertises,
+        # so the two always agree. Set via the `serve_subscriptions_listen:` constructor keyword.
         def serves_subscriptions_listen?
-          true
+          @serve_subscriptions_listen
         end
 
         def handle_request(request)
@@ -723,8 +734,13 @@ module MCP
           return mismatch_error if mismatch_error
 
           # `subscriptions/listen` is a long-lived notification stream served at the transport layer;
-          # it never dispatches through `Server#handle`.
-          return handle_subscriptions_listen(body) if body[:method] == Methods::SUBSCRIPTIONS_LISTEN
+          # it never dispatches through `Server#handle`. A transport constructed with
+          # `serve_subscriptions_listen: false` skips the interception, so the method falls through
+          # to the dispatcher as unimplemented (404 with `-32601`) - the refusal a host that cannot
+          # serve an open SSE stream needs, instead of a `Proc` body it can never call.
+          if body[:method] == Methods::SUBSCRIPTIONS_LISTEN && serves_subscriptions_listen?
+            return handle_subscriptions_listen(body)
+          end
 
           session = modern_session
           notifications = @mutex.synchronize { @modern_request_sinks[session.session_id] = [] }
@@ -881,17 +897,47 @@ module MCP
           )
         end
 
-        # The proc registers the stream and returns, leaving the response open like
+        # The Rack streaming body of a `subscriptions/listen` response. It responds to `call`
+        # and deliberately not to `each`, so Rack keeps classifying it as a streaming body;
+        # `first` exists only to turn the buffered-host mistake (e.g. `render(json: body.first)`
+        # in the Rails controller pattern) from a bare `NoMethodError` into guidance naming the fix.
+        class ListenStreamBody
+          def initialize(&block)
+            @block = block
+          end
+
+          def call(stream)
+            @block.call(stream)
+          end
+
+          def first
+            raise <<~MESSAGE
+              subscriptions/listen returned a streaming SSE body, which cannot be buffered into a JSON response. \
+              A host that cannot hold an SSE response open should construct the transport with `serve_subscriptions_listen: false`, \
+              so the method is answered as unimplemented instead.
+              See the Rails (controller) section at https://ruby.sdk.modelcontextprotocol.io/server/transports/ for the hosting patterns.
+            MESSAGE
+          end
+        end
+        private_constant :ListenStreamBody
+
+        # The body registers the stream and returns, leaving the response open like
         # the legacy GET stream (`create_sse_body`).
+        #
+        # Registration and activation are split on purpose: the entry is inserted inactive
+        # (reserving the id and the cap slot atomically), the acknowledgement is written outside the lock,
+        # and only then does the entry become eligible for delivery. A concurrent notification between
+        # the insert and the acknowledgement write skips the inactive entry,
+        # enforcing the SEP-2575 rule that no notification precedes the acknowledgement.
         def listen_sse_body(request_id, honored)
-          proc do |stream|
+          ListenStreamBody.new do |stream|
             rejected = false
             @mutex.synchronize do
               if @listen_subscriptions.key?(request_id) ||
                   (@max_listen_subscriptions && @listen_subscriptions.size >= @max_listen_subscriptions)
                 rejected = true
               else
-                @listen_subscriptions[request_id] = { stream: stream, filter: honored }
+                @listen_subscriptions[request_id] = { stream: stream, filter: honored, active: false, write_mutex: Mutex.new }
               end
             end
 
@@ -909,6 +955,7 @@ module MCP
 
               begin
                 send_to_stream(stream, acknowledgement)
+                activate_listen_subscription(request_id)
                 start_listen_keepalive_thread(request_id)
               rescue *STREAM_WRITE_ERRORS
                 remove_listen_subscription(request_id)
@@ -918,6 +965,15 @@ module MCP
           end
         end
 
+        # Marks a listen subscription eligible for delivery once its acknowledgement write has completed.
+        # The entry may already be gone when the transport closed concurrently.
+        def activate_listen_subscription(request_id)
+          @mutex.synchronize do
+            subscription = @listen_subscriptions[request_id]
+            subscription[:active] = true if subscription
+          end
+        end
+
         # Periodically writes an SSE keepalive comment frame to a listen stream so a silently dropped
         # connection is detected and its slot freed, rather than held until the next fan-out write.
         # Mirrors the legacy GET stream's `start_keepalive_thread`; a comment frame (not a data frame)
@@ -999,6 +1055,10 @@ module MCP
           # a slow or stalled subscriber must not block the transport, matching the legacy delivery paths.
           matched = @mutex.synchronize do
             @listen_subscriptions.filter_map do |request_id, subscription|
+              # An inactive entry has not finished writing its acknowledgement yet;
+              # delivering to it would put a notification ahead of the acknowledgement.
+              next unless subscription[:active]
+
               hit = if field
                 subscription[:filter][field]
               else
@@ -1007,24 +1067,32 @@ module MCP
                 uris.is_a?(Array) && uris.include?(uri)
               end
 
-              [request_id, subscription[:stream]] if hit
+              [request_id, subscription] if hit
             end
           end
 
-          matched.each do |request_id, stream|
+          matched.each do |request_id, subscription|
             meta = { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => request_id }
             notification_params = (params || {}).merge(_meta: meta)
             notification = { jsonrpc: "2.0", method: method, params: notification_params }
 
             begin
-              send_to_stream(stream, notification)
+              # The per-stream write mutex orders this write against a concurrent graceful teardown:
+              # once teardown has marked the entry closed and written its `SubscriptionsListenResult`,
+              # a delivery that snapshotted the entry before the registry was cleared skips it instead
+              # of writing after the final message.
+              subscription[:write_mutex].synchronize do
+                next if subscription[:closed]
+
+                send_to_stream(subscription[:stream], notification)
+              end
             rescue *STREAM_WRITE_ERRORS => e
               MCP.configuration.exception_reporter.call(
                 e,
                 { subscription_id: request_id, error: "Failed to send notification" },
               )
               remove_listen_subscription(request_id)
-              close_stream_safely(stream)
+              close_stream_safely(subscription[:stream])
             end
           end
         end
@@ -1043,20 +1111,27 @@ module MCP
           end
 
           removed.each do |request_id, subscription|
-            begin
-              send_to_stream(subscription[:stream], {
-                jsonrpc: "2.0",
-                id: request_id,
-                result: {
-                  # `SubscriptionsListenResult` is served at the transport layer and never
-                  # passes through the dispatch path, so the REQUIRED 2026-07-28 `resultType` is
-                  # stamped at its construction site.
-                  resultType: ResultType::COMPLETE,
-                  _meta: { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => request_id },
-                },
-              })
-            rescue *STREAM_WRITE_ERRORS
-              nil
+            # Marking the entry closed and writing the result under the stream's write mutex orders
+            # this against in-flight deliveries: each one either lands before the result or observes
+            # `closed` and skips, keeping the graceful result the stream's final message.
+            subscription[:write_mutex].synchronize do
+              subscription[:closed] = true
+
+              begin
+                send_to_stream(subscription[:stream], {
+                  jsonrpc: "2.0",
+                  id: request_id,
+                  result: {
+                    # `SubscriptionsListenResult` is served at the transport layer and never
+                    # passes through the dispatch path, so the REQUIRED 2026-07-28 `resultType` is
+                    # stamped at its construction site.
+                    resultType: ResultType::COMPLETE,
+                    _meta: { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => request_id },
+                  },
+                })
+              rescue *STREAM_WRITE_ERRORS
+                nil
+              end
             end
             close_stream_safely(subscription[:stream])
           end

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -107,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.3.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