mcp 0.16.0 → 0.17.0

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    module OAuth
+      # Pluggable OAuth client configuration handed to `MCP::Client::HTTP` via
+      # the `oauth:` keyword. Inspired by the OAuthClientProvider in the TypeScript SDK
+      # and httpx.Auth-based provider in the Python SDK.
+      #
+      # Required keyword arguments:
+      # - `client_metadata`  - Hash sent to the authorization server's Dynamic Client
+      #   Registration endpoint. Must include at minimum `redirect_uris`,
+      #   `grant_types`, `response_types`, and `token_endpoint_auth_method`.
+      # - `redirect_uri`     - String: the redirect URI used for the authorization
+      #   request. Must be one of `redirect_uris` in `client_metadata`.
+      # - `redirect_handler` - Callable invoked with the fully-built authorization
+      #   URL (a `URI`). Implementations typically open the user's browser.
+      # - `callback_handler` - Callable invoked after `redirect_handler`. Returns
+      #   `[code, state]` where `code` is the authorization code and `state` is
+      #   the `state` parameter received on the redirect URI.
+      #
+      # Optional keyword arguments:
+      # - `scope`   - String of space-separated scopes to request when the server's
+      #   `WWW-Authenticate` does not specify one.
+      # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
+      #   `client_information`, and `save_client_information(info)`. Defaults to
+      #   an `InMemoryStorage`.
+      class Provider
+        # Raised when `Provider#initialize` is called with a `redirect_uri` that
+        # is neither HTTPS nor a loopback `http://` URL, per the MCP
+        # authorization spec's Communication Security requirement.
+        class InsecureRedirectURIError < ArgumentError; end
+
+        # Raised when the `redirect_uri` argument is not listed in
+        # `client_metadata[:redirect_uris]` / `["redirect_uris"]`. Registering
+        # the URI with the authorization server but then sending a different
+        # one with the authorization request would be rejected by the AS at
+        # runtime; failing at construction surfaces the bug earlier.
+        class UnregisteredRedirectURIError < ArgumentError; end
+
+        attr_reader :client_metadata,
+          :redirect_uri,
+          :scope,
+          :storage,
+          :redirect_handler,
+          :callback_handler
+
+        def initialize(
+          client_metadata:,
+          redirect_uri:,
+          redirect_handler:,
+          callback_handler:,
+          scope: nil,
+          storage: nil
+        )
+          unless Discovery.secure_url?(redirect_uri)
+            raise InsecureRedirectURIError,
+              "redirect_uri #{redirect_uri.inspect} must use https or be a loopback http URL " \
+                "(localhost, 127.0.0.0/8, or ::1) per the MCP authorization Communication Security requirement."
+          end
+
+          registered = Array(client_metadata[:redirect_uris] || client_metadata["redirect_uris"])
+          unless registered.include?(redirect_uri)
+            raise UnregisteredRedirectURIError,
+              "redirect_uri #{redirect_uri.inspect} must be listed in client_metadata[:redirect_uris] " \
+                "(got #{registered.inspect}); otherwise the authorization server will reject the authorization request."
+          end
+
+          @client_metadata = client_metadata
+          @redirect_uri = redirect_uri
+          @redirect_handler = redirect_handler
+          @callback_handler = callback_handler
+          @scope = scope
+          @storage = storage || InMemoryStorage.new
+        end
+
+        def access_token
+          tokens&.dig("access_token") || tokens&.dig(:access_token)
+        end
+
+        def tokens
+          @storage.tokens
+        end
+
+        def save_tokens(tokens)
+          @storage.save_tokens(tokens)
+        end
+
+        def client_information
+          @storage.client_information
+        end
+
+        def save_client_information(info)
+          @storage.save_client_information(info)
+        end
+
+        def clear_tokens!
+          @storage.save_tokens(nil)
+        end
+      end
+    end
+  end
+end

data/lib/mcp/client/oauth.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "oauth/discovery"
+require_relative "oauth/flow"
+require_relative "oauth/in_memory_storage"
+require_relative "oauth/pkce"
+require_relative "oauth/provider"
+
+module MCP
+  class Client
+    # OAuth client support for the MCP Authorization spec (PRM discovery,
+    # Authorization Server metadata discovery, Dynamic Client Registration,
+    # OAuth 2.1 Authorization Code + PKCE).
+    # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
+    module OAuth
+    end
+  end
+end

data/lib/mcp/client.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "client/oauth"
 require_relative "client/stdio"
 require_relative "client/http"
 require_relative "client/paginated_result"

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

@@ -16,6 +16,8 @@ module MCP
   class Server
     module Transports
       class StreamableHTTPTransport < Transport
+        class InvalidJsonError < StandardError; end
+
         SSE_HEADERS = {
           "Content-Type" => "text/event-stream",
           "Cache-Control" => "no-cache",
@@ -339,24 +341,51 @@ module MCP
           body_string = request.body.read
           session_id = extract_session_id(request)
 
-          body = parse_request_body(body_string)
-          return body unless body.is_a?(Hash) # Error response
+          begin
+            body = parse_request_body(body_string)
+          rescue InvalidJsonError
+            return invalid_json_response
+          end
 
-          if body[:method] == "initialize"
-            handle_initialization(body_string, body)
-          else
+          # Streamable HTTP (2025-11-25) requires a single JSON-RPC message object per POST.
+          # Batched/array bodies are not supported; reject with `-32600` instead of falling through to
+          # a malformed Rack response.
+          unless body.is_a?(Hash)
+            return invalid_request_response("Invalid Request: JSON-RPC body must be a single request object")
+          end
+
+          # The `MCP-Protocol-Version` header is only meaningful after negotiation, so on `initialize`
+          # the JSON-RPC body `params.protocolVersion` is authoritative and the header (if any) is ignored.
+          # This matches the TypeScript and Python SDKs.
+          unless initialize_request?(body)
             return missing_session_id_response if !@stateless && !session_id
 
-            if notification?(body)
-              dispatch_notification(body_string, session_id)
-              handle_accepted
-            elsif response?(body)
-              return session_not_found_response if !@stateless && !session_exists?(session_id)
+            protocol_version_error = validate_protocol_version_header(request)
+            return protocol_version_error if protocol_version_error
+          end
 
-              handle_response(body, session_id: session_id)
-            else
-              handle_regular_request(body_string, session_id, related_request_id: body[:id])
+          if initialize_request?(body)
+            if !@stateless && session_id
+              # An `initialize` request carrying an `Mcp-Session-Id` header is either a duplicate
+              # initialization attempt against a live session, or a retry against an unknown/expired
+              # one. In the live case, reject with `-32600` so the original session is not abandoned.
+              # In the unknown/expired case, return 404 so the client retries from scratch instead
+              # of silently inheriting a fresh session under the old ID.
+              return already_initialized_response(body[:id]) if session_active?(session_id)
+
+              return session_not_found_response
             end
+
+            handle_initialization(body_string, body)
+          elsif notification?(body)
+            dispatch_notification(body_string, session_id)
+            handle_accepted
+          elsif response?(body)
+            return session_not_found_response if !@stateless && !session_exists?(session_id)
+
+            handle_response(body, session_id: session_id)
+          else
+            handle_regular_request(body_string, session_id, related_request_id: body[:id])
           end
         rescue StandardError => e
           MCP.configuration.exception_reporter.call(e, { request: body_string })
@@ -377,6 +406,10 @@ module MCP
 
           error_response = validate_and_touch_session(session_id)
           return error_response if error_response
+
+          protocol_version_error = validate_protocol_version_header(request)
+          return protocol_version_error if protocol_version_error
+
           return session_already_connected_response if get_session_stream(session_id)
 
           setup_sse_stream(session_id)
@@ -386,6 +419,9 @@ module MCP
           success_response = [200, { "Content-Type" => "application/json" }, [{ success: true }.to_json]]
 
           if @stateless
+            protocol_version_error = validate_protocol_version_header(request)
+            return protocol_version_error if protocol_version_error
+
             # Stateless mode doesn't support sessions, so we can just return a success response
             return success_response
           end
@@ -393,6 +429,9 @@ module MCP
           return missing_session_id_response unless (session_id = request.env["HTTP_MCP_SESSION_ID"])
           return session_not_found_response unless session_exists?(session_id)
 
+          protocol_version_error = validate_protocol_version_header(request)
+          return protocol_version_error if protocol_version_error
+
           cleanup_session(session_id)
 
           success_response
@@ -492,9 +531,34 @@ module MCP
         def parse_request_body(body_string)
           JSON.parse(body_string, symbolize_names: true)
         rescue JSON::ParserError, TypeError
+          raise InvalidJsonError
+        end
+
+        def invalid_json_response
           [400, { "Content-Type" => "application/json" }, [{ error: "Invalid JSON" }.to_json]]
         end
 
+        def initialize_request?(body)
+          body.is_a?(Hash) && body[:method] == Methods::INITIALIZE
+        end
+
+        def validate_protocol_version_header(request)
+          header_value = request.env["HTTP_MCP_PROTOCOL_VERSION"]
+          return if header_value.nil?
+          return if MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(header_value)
+
+          supported = MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.join(", ")
+          body = {
+            jsonrpc: "2.0",
+            id: nil,
+            error: {
+              code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+              message: "Bad Request: Unsupported protocol version: #{header_value}. Supported versions: #{supported}",
+            },
+          }
+          [400, { "Content-Type" => "application/json" }, [body.to_json]]
+        end
+
         def notification?(body)
           !body[:id] && !!body[:method]
         end
@@ -560,6 +624,15 @@ module MCP
             @server.handle_json(body_string)
           end
 
+          # If `Server#init` produced an error response (e.g., malformed JSON-RPC envelope),
+          # `mark_initialized!` was never called. Discard the orphaned session and omit
+          # the `Mcp-Session-Id` header so the client retries from a clean state instead of
+          # reusing a never-initialized ID that would later look like a duplicate `initialize`.
+          if server_session && !server_session.initialized?
+            cleanup_session(session_id)
+            session_id = nil
+          end
+
           headers = {
             "Content-Type" => "application/json",
           }
@@ -694,6 +767,31 @@ module MCP
           @mutex.synchronize { @sessions.key?(session_id) }
         end
 
+        # Returns true iff a session exists and is not past its idle timeout. Expired sessions
+        # are evicted as a side effect so a live request never observes a zombie session that
+        # the reaper hasn't yet pruned. Does NOT update `last_active_at`; callers that are
+        # rejecting a request must not extend the session's lifetime.
+        def session_active?(session_id)
+          removed = nil
+          active = @mutex.synchronize do
+            next false unless (session = @sessions[session_id])
+
+            if session_expired?(session)
+              removed = cleanup_session_unsafe(session_id)
+              next false
+            end
+
+            true
+          end
+
+          if removed
+            close_stream_safely(removed[:get_sse_stream])
+            close_post_request_streams(removed)
+          end
+
+          active
+        end
+
         def method_not_allowed_response
           [405, { "Content-Type" => "application/json" }, [{ error: "Method not allowed" }.to_json]]
         end
@@ -706,6 +804,22 @@ module MCP
           [404, { "Content-Type" => "application/json" }, [{ error: "Session not found" }.to_json]]
         end
 
+        def already_initialized_response(request_id)
+          invalid_request_response("Invalid Request: Server already initialized", request_id: request_id)
+        end
+
+        def invalid_request_response(message, request_id: nil)
+          body = {
+            jsonrpc: "2.0",
+            id: request_id,
+            error: {
+              code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+              message: message,
+            },
+          }
+          [400, { "Content-Type" => "application/json" }, [body.to_json]]
+        end
+
         def session_already_connected_response
           [
             409,

data/lib/mcp/server.rb

@@ -497,6 +497,13 @@ module MCP
     end
 
     def init(params, session: nil)
+      # MCP spec: the initialization phase MUST be the first interaction between client and server.
+      # Reject duplicate `initialize` on an already-initialized session so the negotiated
+      # client identity and capabilities cannot be silently overwritten.
+      if session&.initialized?
+        raise RequestHandlerError.new("Invalid Request: Server already initialized", params, error_type: :invalid_request)
+      end
+
       if params
         if session
           session.store_client_info(client: params[:clientInfo], capabilities: params[:capabilities])
@@ -524,6 +531,8 @@ module MCP
         response_instructions = nil
       end
 
+      session&.mark_initialized!
+
       {
         protocolVersion: negotiated_version,
         capabilities: capabilities,

data/lib/mcp/server_session.rb

@@ -18,6 +18,19 @@ module MCP
       @logging_message_notification = nil
       @in_flight = {}
       @in_flight_mutex = Mutex.new
+      @initialized = false
+    end
+
+    # Whether `initialize` has already completed for this session.
+    def initialized?
+      @initialized
+    end
+
+    # 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!
+      @initialized = true
     end
 
     # Registers a `Cancellation` token for an in-flight request.

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -41,6 +41,12 @@ files:
 - lib/mcp/cancelled_error.rb
 - lib/mcp/client.rb
 - lib/mcp/client/http.rb
+- lib/mcp/client/oauth.rb
+- lib/mcp/client/oauth/discovery.rb
+- lib/mcp/client/oauth/flow.rb
+- lib/mcp/client/oauth/in_memory_storage.rb
+- lib/mcp/client/oauth/pkce.rb
+- lib/mcp/client/oauth/provider.rb
 - lib/mcp/client/paginated_result.rb
 - lib/mcp/client/stdio.rb
 - lib/mcp/client/tool.rb
@@ -81,7 +87,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.16.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.17.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