mcp 1.0.0 → 1.2.0

data/lib/mcp/server/input_required_result.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative "../methods"
+require_relative "../result_type"
+
+module MCP
+  class Server
+    # A multi round-trip `input_required` result (SEP-2322, MCP 2026-07-28).
+    # Handlers for `tools/call`, `prompts/get`, and `resources/read` may return one instead of
+    # their normal result to ask the client for additional input: `input_requests` maps server-assigned keys
+    # to embedded request shapes (`elicitation/create`, `sampling/createMessage`, or `roots/list`),
+    # and `request_state` is an opaque continuation string the client echoes back byte-exactly when it retries
+    # the original request with `inputResponses` under the same keys.
+    #
+    # The server holds no memory between rounds: handlers re-run from the start on every retry and read
+    # the answers via `server_context.input_responses` / `server_context.request_state`
+    # (deterministic replay, matching the Python SDK). At least one of the two fields must be present;
+    # a `request_state`-only result is the load-shedding form ("retry later").
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322
+    class InputRequiredResult
+      EMBEDDABLE_METHODS = [
+        Methods::ELICITATION_CREATE,
+        Methods::SAMPLING_CREATE_MESSAGE,
+        Methods::ROOTS_LIST,
+      ].freeze
+
+      attr_reader :input_requests, :request_state
+
+      def initialize(input_requests: nil, request_state: nil)
+        if (input_requests.nil? || input_requests.empty?) && request_state.nil?
+          raise ArgumentError, "at least one of input_requests or request_state is required"
+        end
+        unless request_state.nil? || request_state.is_a?(String)
+          raise ArgumentError, "request_state must be a String"
+        end
+
+        @input_requests = normalize_input_requests(input_requests)
+        @request_state = request_state
+        freeze
+      end
+
+      def to_h
+        serialized_requests = @input_requests&.transform_values do |entry|
+          { method: entry[:method], params: entry[:params] }.compact
+        end
+
+        {
+          resultType: ResultType::INPUT_REQUIRED,
+          inputRequests: serialized_requests,
+          requestState: @request_state,
+        }.compact
+      end
+
+      # The client capabilities required to fulfill every embedded request, merged into one nested hash.
+      # The mapping matches the TypeScript SDK's `requiredClientCapabilitiesForInputRequest`:
+      # `elicitation/create` with `mode: "url"` requires `elicitation.url`, any other `elicitation/create`
+      # requires `elicitation.form`, `sampling/createMessage` with `tools`/`toolChoice` requires `sampling.tools`
+      # (plain sampling otherwise), and `roots/list` requires `roots`.
+      def required_client_capabilities
+        (@input_requests || {}).values.reduce({}) do |merged, entry|
+          deep_merge(merged, entry_capability(entry))
+        end
+      end
+
+      # The subset of {#required_client_capabilities} the request did not declare.
+      # Per SEP-2575, servers MUST NOT rely on capabilities the client has not declared,
+      # so a non-empty return means the result must not be sent (`-32021`).
+      def missing_client_capabilities(declared)
+        missing = missing_subtree(required_client_capabilities, declared)
+        prune_implied_form_elicitation(missing, declared)
+      end
+
+      private
+
+      def normalize_input_requests(input_requests)
+        return if input_requests.nil?
+
+        raise ArgumentError, "input_requests must be a Hash" unless input_requests.is_a?(Hash)
+
+        normalized = input_requests.each_with_object({}) do |(key, entry), result|
+          raise ArgumentError, "input_requests entries must be Hashes" unless entry.is_a?(Hash)
+
+          method = entry[:method] || entry["method"]
+          unless EMBEDDABLE_METHODS.include?(method)
+            raise ArgumentError,
+              "input_requests entry #{key.inspect} must have a method of " \
+                "#{EMBEDDABLE_METHODS.join(", ")} (got #{method.inspect})"
+          end
+
+          params = entry[:params] || entry["params"]
+          raise ArgumentError, "input_requests entry params must be a Hash" unless params.nil? || params.is_a?(Hash)
+
+          result[key.to_s] = { method: method, params: params }.compact.freeze
+        end
+
+        normalized.freeze
+      end
+
+      def entry_capability(entry)
+        params = entry[:params]
+
+        case entry[:method]
+        when Methods::ELICITATION_CREATE
+          mode = params && (params[:mode] || params["mode"])
+          mode == "url" ? { elicitation: { url: {} } } : { elicitation: { form: {} } }
+        when Methods::SAMPLING_CREATE_MESSAGE
+          with_tools = params && (params.key?(:tools) || params.key?("tools") ||
+            params.key?(:toolChoice) || params.key?("toolChoice"))
+          with_tools ? { sampling: { tools: {} } } : { sampling: {} }
+        when Methods::ROOTS_LIST
+          { roots: {} }
+        end
+      end
+
+      # Walks `required` and keeps only the branches absent from `declared`
+      # (symbol/string tolerant on the declared side).
+      def missing_subtree(required, declared)
+        required.each_with_object({}) do |(name, nested), missing|
+          declared_value = read_key(declared, name)
+
+          if declared_value.nil?
+            missing[name] = nested
+          elsif nested.is_a?(Hash) && !nested.empty?
+            nested_missing = missing_subtree(nested, declared_value)
+            missing[name] = nested_missing unless nested_missing.empty?
+          end
+        end
+      end
+
+      # 2025 back-compat implication shared with the TypeScript and Python SDKs:
+      # a bare `elicitation: {}` declaration implies form elicitation support, while
+      # an explicit url-only declaration does not.
+      def prune_implied_form_elicitation(missing, declared)
+        elicitation_missing = missing[:elicitation]
+        return missing unless elicitation_missing.is_a?(Hash) && elicitation_missing.key?(:form)
+
+        declared_elicitation = read_key(declared, :elicitation)
+        return missing unless declared_elicitation.is_a?(Hash)
+        return missing unless read_key(declared_elicitation, :url).nil?
+
+        pruned = elicitation_missing.reject { |key, _| key == :form }
+        pruned.empty? ? missing.reject { |key, _| key == :elicitation } : missing.merge(elicitation: pruned)
+      end
+
+      def read_key(hash, key)
+        return unless hash.is_a?(Hash)
+
+        value = hash[key.to_sym]
+        value.nil? ? hash[key.to_s] : value
+      end
+
+      def deep_merge(left, right)
+        left.merge(right) do |_key, left_value, right_value|
+          if left_value.is_a?(Hash) && right_value.is_a?(Hash)
+            deep_merge(left_value, right_value)
+          else
+            right_value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mcp/server/pending_response.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module MCP
+  class Server
+    # A one-shot, timeout-aware handoff between the thread awaiting a server-to-client response
+    # and whichever thread resolves it (the client's response, a cancellation, or session teardown).
+    #
+    # `Queue#pop` only accepts a `timeout:` on Ruby 3.2 and later, and this gem supports 2.7,
+    # so the wait is expressed with a `ConditionVariable`. The `push`/`pop` names mirror the `Queue`
+    # this replaces, keeping the resolving call sites unchanged.
+    #
+    # First writer wins: a second `push` is ignored, so a cancellation that races a real response
+    # cannot overwrite it. `pop` returns the pushed value, or the `on_timeout` result when
+    # the deadline passes with nothing pushed.
+    class PendingResponse
+      def initialize
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @delivered = false
+        @value = nil
+      end
+
+      # Resolves the wait. Ignored when a value was already delivered.
+      def push(value)
+        @mutex.synchronize do
+          next if @delivered
+
+          @delivered = true
+          @value = value
+          @condition.broadcast
+        end
+      end
+
+      # Blocks until a value is pushed or `timeout` seconds elapse, and yields to the caller
+      # on expiry so it can decide what a timeout means. `ConditionVariable#wait` can return spuriously,
+      # so the deadline is re-checked against the monotonic clock.
+      #
+      # The expiry block runs after the lock is released: it typically cancels the request,
+      # which resolves this same object, and Ruby's `Mutex` is not reentrant.
+      def pop(timeout:)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        expired = false
+
+        value = @mutex.synchronize do
+          until @delivered
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            if remaining <= 0
+              expired = true
+              break
+            end
+
+            @condition.wait(@mutex, remaining)
+          end
+
+          @value
+        end
+
+        expired ? yield : value
+      end
+    end
+  end
+end

data/lib/mcp/server/request_state_security.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module MCP
+  class Server
+    # Opt-in protection for the SEP-2322 `requestState` echo. The opaque continuation string leaves the server,
+    # sits in the client's hands, and comes back as client-controlled input, so it must be treated like
+    # any other untrusted data. Sealing encrypts the state with AES-256-GCM (clients cannot read it) and binds
+    # a claims envelope that unsealing verifies fail-closed:
+    #
+    # - `exp`: a TTL window (re-sealed each round)
+    # - `m` / `t`: the originating method and target (tool/prompt name or resource URI)
+    # - `a`: a digest of the originating arguments, so the state only resumes the same call with the same inputs
+    # - `aud`: an optional audience, so tokens cannot cross servers sharing a key
+    #
+    # Pass an instance via `Server.new(request_state_security:)` and the seal/unseal happens transparently;
+    # handlers keep reading plaintext through `server_context.request_state`. Without it, the state crosses
+    # the wire exactly as the handler wrote it (the author's responsibility, matching the Python SDK's low-level Server).
+    # The key must be shared across workers in multi-process
+    #
+    # deployments; a per-process random key makes retries that land on another worker fail with an invalid-state error,
+    # forcing clients to restart the flow.
+    #
+    # The token format is `v1.<base64url(iv || ciphertext || tag)>`, with the version prefix bound as GCM associated data,
+    # following the Python SDK's `AESGCMRequestStateCodec`.
+    class RequestStateSecurity
+      class InvalidStateError < StandardError; end
+
+      VERSION_PREFIX = "v1."
+      KEY_BYTES = 32
+      IV_BYTES = 12
+      TAG_BYTES = 16
+      DEFAULT_TTL = 300
+
+      def initialize(key:, ttl: DEFAULT_TTL, audience: nil)
+        unless key.is_a?(String) && key.bytesize == KEY_BYTES
+          raise ArgumentError, "key must be a #{KEY_BYTES}-byte String"
+        end
+        unless ttl.is_a?(Numeric) && ttl.positive?
+          raise ArgumentError, "ttl must be a positive number of seconds"
+        end
+
+        @key = key.dup.force_encoding(Encoding::BINARY).freeze
+        @ttl = ttl
+        @audience = audience
+      end
+
+      # Seals a plaintext state into an opaque token bound to the originating request.
+      def seal(state, method:, target:, arguments_digest:)
+        claims = {
+          v: 1,
+          exp: Time.now.to_i + @ttl,
+          m: method,
+          t: target,
+          a: arguments_digest,
+          aud: @audience,
+          s: state,
+        }.compact
+
+        cipher = OpenSSL::Cipher.new("aes-256-gcm").encrypt
+        cipher.key = @key
+        iv = cipher.random_iv
+        cipher.auth_data = VERSION_PREFIX
+        ciphertext = cipher.update(JSON.generate(claims)) + cipher.final
+
+        VERSION_PREFIX + base64url_encode(iv + ciphertext + cipher.auth_tag)
+      end
+
+      # Unseals a client-echoed token and verifies every claim, failing closed with
+      # `InvalidStateError` on tampering, expiry, or a claims mismatch.
+      def unseal(sealed, method:, target:, arguments_digest:)
+        unless sealed.is_a?(String) && sealed.start_with?(VERSION_PREFIX)
+          raise InvalidStateError, "malformed token"
+        end
+
+        blob = base64url_decode(sealed.delete_prefix(VERSION_PREFIX))
+        raise InvalidStateError, "malformed token" if blob.bytesize < IV_BYTES + TAG_BYTES
+
+        iv = blob.byteslice(0, IV_BYTES)
+        tag = blob.byteslice(-TAG_BYTES, TAG_BYTES)
+        ciphertext = blob.byteslice(IV_BYTES, blob.bytesize - IV_BYTES - TAG_BYTES)
+
+        cipher = OpenSSL::Cipher.new("aes-256-gcm").decrypt
+        cipher.key = @key
+        cipher.iv = iv
+        cipher.auth_tag = tag
+        cipher.auth_data = VERSION_PREFIX
+        plaintext = begin
+          cipher.update(ciphertext) + cipher.final
+        rescue OpenSSL::Cipher::CipherError
+          raise InvalidStateError, "authentication failed"
+        end
+
+        claims = begin
+          JSON.parse(plaintext, symbolize_names: true)
+        rescue JSON::ParserError
+          raise InvalidStateError, "malformed claims"
+        end
+
+        verify!(claims, method: method, target: target, arguments_digest: arguments_digest)
+        claims[:s]
+      end
+
+      private
+
+      def verify!(claims, method:, target:, arguments_digest:)
+        raise InvalidStateError, "unsupported version" unless claims[:v] == 1
+        raise InvalidStateError, "expired" unless claims[:exp].is_a?(Integer) && Time.now.to_i <= claims[:exp]
+        raise InvalidStateError, "method mismatch" unless claims[:m] == method
+        raise InvalidStateError, "target mismatch" unless claims[:t] == target
+        raise InvalidStateError, "arguments mismatch" unless claims[:a] == arguments_digest
+        raise InvalidStateError, "audience mismatch" unless claims[:aud] == @audience
+        raise InvalidStateError, "missing state" unless claims[:s].is_a?(String)
+      end
+
+      def base64url_encode(data)
+        [data].pack("m0").tr("+/", "-_").delete("=")
+      end
+
+      def base64url_decode(encoded)
+        padded = encoded.tr("-_", "+/")
+        padded += "=" * ((4 - padded.length % 4) % 4)
+        padded.unpack1("m0")
+      rescue ArgumentError
+        raise InvalidStateError, "malformed token"
+      end
+    end
+  end
+end

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

@@ -49,7 +49,9 @@ module MCP
             end
             break if line.nil?
 
-            response = @session.handle_json(line.strip)
+            line = line.strip
+            parsed = parse_line(line)
+            response = parsed ? dispatch_with_era(parsed) : @session.handle_json(line)
             send_response(response) if response
           end
         rescue Interrupt
@@ -90,6 +92,12 @@ module MCP
         # cancellation has very limited value here regardless; servers that need cancellation propagation for nested
         # server-to-client requests should use `StreamableHTTPTransport`.
         def send_request(method, params = nil)
+          # The modern lifecycle (SEP-2575) forbids server-initiated JSON-RPC requests;
+          # multi round-trip `input_required` results (SEP-2322) replace them.
+          if @session && @session.era == :modern
+            raise "Server-initiated requests are not available in the modern lifecycle (SEP-2575)."
+          end
+
           request_id = generate_request_id
           request = { jsonrpc: "2.0", id: request_id, method: method }
           request[:params] = params if params
@@ -116,7 +124,7 @@ module MCP
 
               return parsed[:result]
             else
-              response = @session ? @session.handle(parsed) : @server.handle(parsed)
+              response = @session ? dispatch_with_era(parsed) : @server.handle(parsed)
               send_response(response) if response
             end
           end
@@ -143,6 +151,35 @@ module MCP
 
           line
         end
+
+        # Parses a frame once so era classification can inspect its method and `_meta`.
+        # Returns `nil` for frames that are not JSON objects; those fall back to
+        # `ServerSession#handle_json` so protocol-level error responses stay identical.
+        def parse_line(line)
+          parsed = JSON.parse(line, symbolize_names: true)
+          parsed.is_a?(Hash) ? parsed : nil
+        rescue JSON::ParserError
+          nil
+        end
+
+        # Serves one frame under the dual-era model (SEP-2575): the first era-distinctive message to succeed locks
+        # the connection era. A successful `initialize` locks `:legacy` inside `Server#init`; a successful `server/discover`
+        # or a successful request carrying the full modern `_meta` triple locks `:modern`. Era-violating frames
+        # (an `initialize` after a modern lock, a modern envelope after a legacy lock, or a missing envelope after a modern lock)
+        # are rejected in-band by `Server#lift_request_envelope`.
+        def dispatch_with_era(parsed)
+          response = @session.handle(parsed)
+          lock_modern_era_on_success(parsed, response)
+          response
+        end
+
+        def lock_modern_era_on_success(parsed, response)
+          return if @session.era
+          return if !response.is_a?(Hash) || response.key?(:error)
+          return if parsed[:method] != Methods::SERVER_DISCOVER && !RequestEnvelope.modern?(parsed[:params])
+
+          @session.lock_era!(:modern)
+        end
       end
     end
   end