mcp 1.0.0 → 1.2.0

data/lib/mcp/server_context.rb

@@ -4,12 +4,35 @@ module MCP
   class ServerContext
     attr_reader :cancellation
 
-    def initialize(context, progress:, notification_target:, related_request_id: nil, cancellation: nil)
+    # The SEP-2575 per-request envelope (`MCP::RequestEnvelope`) when the request was classified as modern;
+    # `nil` on legacy requests.
+    attr_reader :envelope
+
+    # SEP-2322 multi round-trip retry fields, present when the client re-issued the request after
+    # an `input_required` result: `input_responses` maps the keys of the earlier `inputRequests` to
+    # the client's answers, and `request_state` is the opaque continuation string echoed back byte-exactly.
+    # Both are `nil` on a first-round request. Only handlers that opt in to `server_context:` can read them
+    # (the same access model as the envelope readers).
+    attr_reader :input_responses, :request_state
+
+    def initialize(context, progress:, notification_target:, related_request_id: nil, cancellation: nil, envelope: nil,
+      input_responses: nil, request_state: nil)
       @context = context
       @progress = progress
       @notification_target = notification_target
       @related_request_id = related_request_id
       @cancellation = cancellation
+      @envelope = envelope
+      @input_responses = input_responses
+      @request_state = request_state
+    end
+
+    # Reads one entry of {#input_responses} by its `inputRequests` key, tolerating symbol or string keys.
+    def input_response(key)
+      return unless @input_responses.is_a?(Hash)
+
+      value = @input_responses[key.to_sym]
+      value.nil? ? @input_responses[key.to_s] : value
     end
 
     def cancelled?
@@ -20,6 +43,52 @@ module MCP
       @cancellation&.raise_if_cancelled!
     end
 
+    # Whether the current request follows the stateless modern lifecycle (SEP-2575).
+    def modern?
+      !@envelope.nil?
+    end
+
+    # Client identity for the current request. Modern requests carry it in the `_meta` envelope;
+    # legacy sessions fall back to the state stored by `initialize`. The envelope always wins
+    # because servers MUST NOT infer identity from prior requests.
+    def client_info
+      return @envelope.client_info if @envelope
+
+      @notification_target.client if @notification_target.respond_to?(:client)
+    end
+
+    # Client capabilities for the current request, with the same envelope-first resolution as {#client_info}.
+    def client_capabilities
+      return @envelope.client_capabilities if @envelope
+
+      @notification_target.client_capabilities if @notification_target.respond_to?(:client_capabilities)
+    end
+
+    # The protocol version the current request was made with. `nil` on legacy requests,
+    # where the version is a session-level negotiation result rather than per-request data.
+    def protocol_version
+      @envelope&.protocol_version
+    end
+
+    # Guards the current request on a declared client capability (SEP-2575). `path` names nested capability keys,
+    # e.g. `require_client_capability!(:elicitation, :form)`. Raises `Server::MissingRequiredClientCapabilityError`
+    # (JSON-RPC error `-32021` with `data: { requiredCapabilities: ... }`) when the capability was not declared.
+    def require_client_capability!(*path)
+      raise ArgumentError, "at least one capability key is required" if path.empty?
+
+      declared = client_capabilities
+      value = path.reduce(declared) do |acc, key|
+        break unless acc.is_a?(Hash)
+
+        symbol_value = acc[key.to_sym]
+        symbol_value.nil? ? acc[key.to_s] : symbol_value
+      end
+      return unless value.nil?
+
+      required = path.reverse.inject({}) { |acc, key| { key.to_sym => acc } }
+      raise Server::MissingRequiredClientCapabilityError, required
+    end
+
     # Reports progress for the current tool operation.
     # The notification is automatically scoped to the originating session.
     #
@@ -41,6 +110,14 @@ module MCP
     def notify_log_message(data:, level:, logger: nil)
       return unless @notification_target
 
+      # Modern requests opt in to logging per request (SEP-2575): without `io.modelcontextprotocol/logLevel` in `_meta`,
+      # the server MUST NOT send any `notifications/message` for the request, and an insufficient level drops
+      # the message the same way. Session- or server-level gating still applies downstream on delegation.
+      if @envelope
+        threshold = @envelope.log_level && LoggingMessageNotification.new(level: @envelope.log_level)
+        return unless threshold&.valid_level? && threshold.should_notify?(level)
+      end
+
       @notification_target.notify_log_message(data: data, level: level, logger: logger, related_request_id: @related_request_id)
     end
 
@@ -61,9 +138,9 @@ module MCP
     #   `notifications/roots/list_changed`) is deprecated as of MCP protocol
     #   version 2026-07-28 (SEP-2577). Use tool parameters, resource URIs,
     #   server configuration, or environment variables instead.
-    def list_roots
+    def list_roots(timeout: nil)
       if @notification_target.respond_to?(:list_roots)
-        @notification_target.list_roots(related_request_id: @related_request_id)
+        @notification_target.list_roots(related_request_id: @related_request_id, **timeout_kwarg(timeout))
       else
         raise NoMethodError, "undefined method 'list_roots' for #{self}"
       end
@@ -83,9 +160,9 @@ module MCP
     #   end
     #
     # @see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping
-    def ping
+    def ping(timeout: nil)
       if @notification_target.respond_to?(:ping)
-        @notification_target.ping(related_request_id: @related_request_id)
+        @notification_target.ping(related_request_id: @related_request_id, **timeout_kwarg(timeout))
       else
         raise NoMethodError, "undefined method 'ping' for #{self}"
       end
@@ -168,5 +245,15 @@ module MCP
     def respond_to_missing?(name, include_private = false)
       @context.respond_to?(name) || super
     end
+
+    private
+
+    # An omitted `timeout:` is not forwarded at all, so the delegated call keeps the shape it had
+    # before per-request timeouts existed. A notification target that predates the keyword
+    # (a custom object standing in for a session) keeps working until a caller actually asks for a timeout,
+    # and the transport applies its own default in that case.
+    def timeout_kwarg(timeout)
+      timeout.nil? ? {} : { timeout: timeout }
+    end
   end
 end

data/lib/mcp/server_session.rb

@@ -7,15 +7,26 @@ module MCP
   # Holds per-connection state for a single client session.
   # Created by the transport layer; delegates request handling to the shared `Server`.
   class ServerSession
-    attr_reader :session_id, :client, :logging_message_notification
+    ERAS = [:legacy, :modern].freeze
+
+    attr_reader :session_id, :client, :logging_message_notification, :protocol_version
+
+    # Connection-era lock of the dual-era serving model (SEP-2575): `nil` until the first era-distinctive message succeeds,
+    # then `:legacy` or `:modern` for the connection's lifetime. Modern-era transports construct their per-request sessions
+    # with `era: :modern` up front.
+    attr_reader :era
+
+    def initialize(server:, transport:, session_id: nil, era: nil)
+      validate_era!(era) if era
 
-    def initialize(server:, transport:, session_id: nil)
       @server = server
       @transport = transport
       @session_id = session_id
+      @era = era
       @client = nil
       @client_capabilities = nil
       @logging_message_notification = nil
+      @protocol_version = nil
       @in_flight = {}
       @in_flight_mutex = Mutex.new
       @initialized = false
@@ -29,8 +40,22 @@ module MCP
     # Called by `Server#init` after a successful `initialize` response, so subsequent
     # `initialize` requests on the same session can be rejected per MCP spec
     # (the initialization phase MUST be the first interaction).
-    def mark_initialized!
+    def mark_initialized!(protocol_version: nil)
       @initialized = true
+      @protocol_version = protocol_version
+      # A successful `initialize` is the legacy-distinctive message of the dual-era serving model (SEP-2575),
+      # so it also locks the connection era.
+      @era ||= :legacy
+    end
+
+    # One-shot era lock. Locking the already-locked era is a no-op; flipping an established era raises,
+    # because a connection can never change eras.
+    def lock_era!(era)
+      validate_era!(era)
+      return if @era == era
+      raise "Session era already locked to #{@era}" if @era
+
+      @era = era
     end
 
     # Registers a `Cancellation` token for an in-flight request.
@@ -106,19 +131,19 @@ module MCP
     #   `notifications/roots/list_changed`) is deprecated as of MCP protocol
     #   version 2026-07-28 (SEP-2577). Use tool parameters, resource URIs,
     #   server configuration, or environment variables instead.
-    def list_roots(related_request_id: nil)
+    def list_roots(related_request_id: nil, timeout: nil)
       warn_unassociated_request(__method__, related_request_id)
 
       unless client_capabilities&.dig(:roots)
         raise "Client does not support roots."
       end
 
-      send_to_transport_request(Methods::ROOTS_LIST, nil, related_request_id: related_request_id)
+      send_to_transport_request(Methods::ROOTS_LIST, nil, related_request_id: related_request_id, timeout: timeout)
     end
 
     # Sends a `ping` request scoped to this session.
-    def ping(related_request_id: nil)
-      result = send_to_transport_request(Methods::PING, nil, related_request_id: related_request_id)
+    def ping(related_request_id: nil, timeout: nil)
+      result = send_to_transport_request(Methods::PING, nil, related_request_id: related_request_id, timeout: timeout)
       raise Server::ValidationError, "Response validation failed: invalid `result`" unless result.is_a?(Hash)
 
       result
@@ -132,11 +157,16 @@ module MCP
     # @deprecated MCP Sampling (`sampling/createMessage`) is deprecated as of
     #   MCP protocol version 2026-07-28 (SEP-2577). Use direct LLM provider
     #   APIs instead.
-    def create_sampling_message(related_request_id: nil, **kwargs)
+    def create_sampling_message(related_request_id: nil, timeout: nil, **kwargs)
       warn_unassociated_request(__method__, related_request_id)
 
       params = @server.build_sampling_params(client_capabilities, **kwargs)
-      send_to_transport_request(Methods::SAMPLING_CREATE_MESSAGE, params, related_request_id: related_request_id)
+      send_to_transport_request(
+        Methods::SAMPLING_CREATE_MESSAGE,
+        params,
+        related_request_id: related_request_id,
+        timeout: timeout,
+      )
     end
 
     # Sends an `elicitation/create` request (form mode) scoped to this session.
@@ -144,7 +174,7 @@ module MCP
     # Per SEP-2260, the request must be associated with an originating client
     # request; prefer `server_context.create_form_elicitation` inside a handler,
     # which stamps the association automatically.
-    def create_form_elicitation(message:, requested_schema:, related_request_id: nil)
+    def create_form_elicitation(message:, requested_schema:, related_request_id: nil, timeout: nil)
       warn_unassociated_request(__method__, related_request_id)
 
       unless client_capabilities&.dig(:elicitation)
@@ -153,7 +183,12 @@ module MCP
       end
 
       params = { mode: "form", message: message, requestedSchema: requested_schema }
-      send_to_transport_request(Methods::ELICITATION_CREATE, params, related_request_id: related_request_id)
+      send_to_transport_request(
+        Methods::ELICITATION_CREATE,
+        params,
+        related_request_id: related_request_id,
+        timeout: timeout,
+      )
     end
 
     # Sends an `elicitation/create` request (URL mode) scoped to this session.
@@ -161,7 +196,7 @@ module MCP
     # Per SEP-2260, the request must be associated with an originating client
     # request; prefer `server_context.create_url_elicitation` inside a handler,
     # which stamps the association automatically.
-    def create_url_elicitation(message:, url:, elicitation_id:, related_request_id: nil)
+    def create_url_elicitation(message:, url:, elicitation_id:, related_request_id: nil, timeout: nil)
       warn_unassociated_request(__method__, related_request_id)
 
       unless client_capabilities&.dig(:elicitation, :url)
@@ -170,7 +205,21 @@ module MCP
       end
 
       params = { mode: "url", message: message, url: url, elicitationId: elicitation_id }
-      send_to_transport_request(Methods::ELICITATION_CREATE, params, related_request_id: related_request_id)
+      send_to_transport_request(
+        Methods::ELICITATION_CREATE,
+        params,
+        related_request_id: related_request_id,
+        timeout: timeout,
+      )
+    end
+
+    # Sends an embedded SEP-2322 `inputRequests` entry as a real server-to-client request on the legacy wire,
+    # for the server's dual-era fulfilment shim.
+    # The entry is forwarded verbatim - per the spec, clients treat each entry exactly like the equivalent
+    # standalone request - and stays associated with the originating client request per SEP-2260.
+    # Returns the client's result.
+    def fulfill_input_request(method, params, related_request_id:)
+      send_to_transport_request(method, params, related_request_id: related_request_id)
     end
 
     # Sends `notifications/cancelled` to the peer for a nested server-to-client request
@@ -223,7 +272,15 @@ module MCP
     #   is deprecated as of MCP protocol version 2026-07-28 (SEP-2577).
     #   Use stderr or OpenTelemetry instead.
     def notify_log_message(data:, level:, logger: nil, related_request_id: nil)
-      effective_logging = @logging_message_notification || @server.logging_message_notification
+      # In the modern lifecycle, log delivery is authorized per request through the `_meta` envelope's `logLevel` member
+      # (applied via `configure_logging`); without it no `notifications/message` is sent, and the server-wide level
+      # does not apply (SEP-2575).
+      effective_logging = if @era == :modern
+        @logging_message_notification
+      else
+        @logging_message_notification || @server.logging_message_notification
+      end
+
       return unless effective_logging&.should_notify?(level)
 
       params = { "data" => data, "level" => level }
@@ -236,6 +293,10 @@ module MCP
 
     private
 
+    def validate_era!(era)
+      raise ArgumentError, "era must be one of #{ERAS.inspect}" unless ERAS.include?(era)
+    end
+
     # Forwards `send_notification` to the transport with only the kwargs the transport's method signature
     # actually accepts. Custom transports that implement the abstract `send_notification(method, params = nil)`
     # contract continue to work unchanged; bundled transports that declare `session_id:` / `related_request_id:`
@@ -255,7 +316,7 @@ module MCP
     # `parent_cancellation:` / `server_session:` receive the nested-cancellation plumbing.
     # When `related_request_id` names an in-flight request, its `Cancellation` token is looked up
     # so that cancelling the parent also cancels this nested server-to-client request.
-    def send_to_transport_request(method, params, related_request_id: nil)
+    def send_to_transport_request(method, params, related_request_id: nil, timeout: nil)
       parent_cancellation = related_request_id ? lookup_in_flight(related_request_id) : nil
 
       kwargs = {
@@ -263,6 +324,7 @@ module MCP
         related_request_id: related_request_id,
         parent_cancellation: parent_cancellation,
         server_session: self,
+        timeout: timeout,
       }.compact
 
       forward_to_transport(@transport.method(:send_request), method, params, kwargs)

data/lib/mcp/tool/response.rb

@@ -7,18 +7,24 @@ module MCP
 
       attr_reader :content, :structured_content, :meta
 
-      def initialize(content = nil, deprecated_error = NOT_GIVEN, error: false, structured_content: nil, meta: nil)
+      def initialize(content = NOT_GIVEN, deprecated_error = NOT_GIVEN, error: false, structured_content: nil, meta: nil)
         if deprecated_error != NOT_GIVEN
           warn("Passing `error` with the 2nd argument of `Response.new` is deprecated. Use keyword argument like `Response.new(content, error: error)` instead.", uplevel: 1)
           error = deprecated_error
         end
 
-        @content = content || []
+        content_given = !content.equal?(NOT_GIVEN)
+        @content_provided = content_given && !content.nil?
+        @content = content_given ? (content || []) : []
         @error = error
         @structured_content = structured_content
         @meta = meta
       end
 
+      def content_provided?
+        @content_provided
+      end
+
       def error?
         !!@error
       end

data/lib/mcp/transport.rb

@@ -50,6 +50,13 @@ module MCP
       raise NotImplementedError, "Subclasses must implement send_request"
     end
 
+    # Whether the transport serves the `subscriptions/listen` notification stream (MCP 2026-07-28, SEP-2575).
+    # `Server#discover` strips the `listChanged`/`subscribe` capability flags when the transport cannot deliver
+    # those notifications in the modern lifecycle.
+    def serves_subscriptions_listen?
+      false
+    end
+
     private
 
     def generate_request_id

data/lib/mcp/version.rb

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

data/lib/mcp.rb

@@ -2,6 +2,7 @@
 
 require_relative "json_rpc_handler"
 require_relative "mcp/configuration"
+require_relative "mcp/protocol_deprecations"
 require_relative "mcp/string_utils"
 require_relative "mcp/transport"
 require_relative "mcp/version"
@@ -13,9 +14,11 @@ module MCP
   autoload :CancelledError, "mcp/cancelled_error"
   autoload :Client, "mcp/client"
   autoload :Content, "mcp/content"
+  autoload :Elicitation, "mcp/elicitation"
   autoload :ErrorCodes, "mcp/error_codes"
   autoload :Icon, "mcp/icon"
   autoload :Prompt, "mcp/prompt"
+  autoload :RequestEnvelope, "mcp/request_envelope"
   autoload :Resource, "mcp/resource"
   autoload :ResourceTemplate, "mcp/resource_template"
   autoload :ResultType, "mcp/result_type"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -43,6 +43,8 @@ files:
 - lib/mcp/client.rb
 - lib/mcp/client/elicitation.rb
 - lib/mcp/client/http.rb
+- lib/mcp/client/mcp_param_headers.rb
+- lib/mcp/client/modern_envelope.rb
 - lib/mcp/client/oauth.rb
 - lib/mcp/client/oauth/client_credentials_provider.rb
 - lib/mcp/client/oauth/cross_app_access_provider.rb
@@ -59,6 +61,8 @@ files:
 - lib/mcp/client/tool.rb
 - lib/mcp/configuration.rb
 - lib/mcp/content.rb
+- lib/mcp/elicitation.rb
+- lib/mcp/elicitation/enum_schema.rb
 - lib/mcp/error_codes.rb
 - lib/mcp/icon.rb
 - lib/mcp/instrumentation.rb
@@ -69,6 +73,8 @@ files:
 - lib/mcp/prompt/argument.rb
 - lib/mcp/prompt/message.rb
 - lib/mcp/prompt/result.rb
+- lib/mcp/protocol_deprecations.rb
+- lib/mcp/request_envelope.rb
 - lib/mcp/resource.rb
 - lib/mcp/resource/contents.rb
 - lib/mcp/resource/embedded.rb
@@ -76,7 +82,10 @@ files:
 - lib/mcp/result_type.rb
 - lib/mcp/server.rb
 - lib/mcp/server/capabilities.rb
+- lib/mcp/server/input_required_result.rb
 - lib/mcp/server/pagination.rb
+- lib/mcp/server/pending_response.rb
+- lib/mcp/server/request_state_security.rb
 - lib/mcp/server/transports.rb
 - lib/mcp/server/transports/stdio_transport.rb
 - lib/mcp/server/transports/streamable_http_transport.rb
@@ -97,7 +106,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.0.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.2.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