ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client.rb

@@ -2,6 +2,8 @@
 
 # Load all MCPClient components
 require_relative 'mcp_client/errors'
+require_relative 'mcp_client/deep_copy'
+require_relative 'mcp_client/deprecations'
 require_relative 'mcp_client/tool'
 require_relative 'mcp_client/prompt'
 require_relative 'mcp_client/resource'
@@ -12,14 +14,26 @@ require_relative 'mcp_client/resource_link'
 require_relative 'mcp_client/root'
 require_relative 'mcp_client/elicitation_validator'
 require_relative 'mcp_client/schema_validator'
+require_relative 'mcp_client/header_params'
+require_relative 'mcp_client/called_tool_definition'
 require_relative 'mcp_client/task'
+require_relative 'mcp_client/subscription'
 require_relative 'mcp_client/server_base'
 require_relative 'mcp_client/server_stdio'
 require_relative 'mcp_client/server_sse'
 require_relative 'mcp_client/server_http'
 require_relative 'mcp_client/server_streamable_http'
 require_relative 'mcp_client/server_factory'
+require_relative 'mcp_client/client/task_support'
+require_relative 'mcp_client/client/task_api'
 require_relative 'mcp_client/client'
+
+# The tasks extension's SubscriptionFilter field (extensions/tasks
+# "Subscriptions"): `taskIds`, beyond the four published core fields. Known
+# to the filter from the start so a host can spell it before declaring the
+# extension; MCPClient::Client#listen still refuses it on a client that has
+# not declared the extension.
+MCPClient::Subscription.register_filter_field('taskIds', :string_array, alias_name: 'task_ids')
 require_relative 'mcp_client/version'
 require_relative 'mcp_client/config_parser'
 require_relative 'mcp_client/auth'
@@ -32,11 +46,17 @@ module MCPClient
   # Simplified connection API - auto-detects transport and returns connected client
   #
   # @param target [String, Array<String>] URL(s) or command for connection
-  #   - URLs ending in /sse -> SSE transport
+  #   - URLs ending in /sse -> SSE transport. The HTTP+SSE transport has been
+  #     deprecated since MCP 2025-03-26 and is listed in the 2026-07-28
+  #     deprecated features registry (SEP-2596); earliest removal is three
+  #     months after SEP-2596 reaches Final. New integrations should use
+  #     Streamable HTTP.
   #   - URLs ending in /mcp -> Streamable HTTP transport
   #   - stdio://command or Array commands -> stdio transport
   #   - Commands starting with npx, node, python, ruby, etc. -> stdio transport
-  #   - Other HTTP URLs -> Try Streamable HTTP, fallback to SSE, then HTTP
+  #   - Other HTTP URLs -> Try Streamable HTTP, then the deprecated HTTP+SSE
+  #     transport (SEP-2596), then HTTP. The SSE step is a fallback for an
+  #     existing server, not a choice a new integration should rely on.
   # Accepts keyword arguments for connection options:
   # - headers [Hash] HTTP headers for remote transports
   # - read_timeout [Integer] Request timeout in seconds (default: 30)
@@ -47,19 +67,30 @@ module MCPClient
   # - env [Hash] Environment variables for stdio
   # - ping [Integer] Ping interval for SSE (default: 10)
   # - endpoint [String] JSON-RPC endpoint path (default: '/rpc')
-  # - transport [Symbol] Force transport type (:stdio, :sse, :http, :streamable_http)
-  # - sampling_handler [Proc] Handler for sampling requests
+  # - transport [Symbol] Force transport type (:stdio, :sse, :http, :streamable_http).
+  #   :sse forces the deprecated HTTP+SSE transport (SEP-2596); earliest
+  #   removal is three months after SEP-2596 reaches Final. Prefer
+  #   :streamable_http.
+  # - sampling_handler [Proc] Handler for sampling requests. Deprecated since MCP
+  #   2026-07-28 (SEP-2577); earliest removal is the first revision released on or
+  #   after 2027-07-28. Integrate directly with the LLM provider API instead.
+  # - protocol [Symbol] :auto (default), :modern or :legacy — which protocol era
+  #   to speak (stdio, HTTP and Streamable HTTP; :modern with transport: :sse
+  #   raises ArgumentError, the HTTP+SSE transport being legacy-only)
+  # - discover_timeout [Numeric] bound on the server/discover probe in seconds
+  # - extensions [Array<String>] MCP extensions the client declares, e.g.
+  #   'io.modelcontextprotocol/tasks'
   # @yield [Faraday::Connection] Optional block for Faraday customization
   # @return [MCPClient::Client] Connected client ready to use
   # @raise [MCPClient::Errors::ConnectionError] if connection fails
   # @raise [MCPClient::Errors::TransportDetectionError] if transport cannot be determined
   #
-  # @example Connect to SSE server
-  #   client = MCPClient.connect('http://localhost:8000/sse')
-  #
   # @example Connect to Streamable HTTP server
   #   client = MCPClient.connect('http://localhost:8000/mcp')
   #
+  # @example Connect to SSE server (deprecated transport; prefer Streamable HTTP)
+  #   client = MCPClient.connect('http://localhost:8000/sse')
+  #
   # @example Connect with options
   #   client = MCPClient.connect('http://api.example.com/mcp',
   #     headers: { 'Authorization' => 'Bearer token' },
@@ -72,7 +103,7 @@ module MCPClient
   #   client = MCPClient.connect(['npx', '-y', '@modelcontextprotocol/server-filesystem', '/home'])
   #
   # @example Connect to multiple servers
-  #   client = MCPClient.connect(['http://server1/mcp', 'http://server2/sse'])
+  #   client = MCPClient.connect(['http://server1/mcp', 'http://server2/mcp'])
   #
   # @example Force transport type
   #   client = MCPClient.connect('http://custom-server.com', transport: :streamable_http)
@@ -101,7 +132,7 @@ module MCPClient
 
     # Connect to a single server
     def connect_single(target, **options, &)
-      transport = options[:transport]&.to_sym || detect_transport(target)
+      transport = options[:transport]&.to_sym || detect_transport(target, options)
 
       case transport
       when :stdio
@@ -129,7 +160,8 @@ module MCPClient
       client = Client.new(
         mcp_server_configs: configs,
         logger: options[:logger],
-        sampling_handler: options[:sampling_handler]
+        sampling_handler: options[:sampling_handler],
+        extensions: options[:extensions]
       )
 
       # Connect all servers
@@ -167,7 +199,8 @@ module MCPClient
       client = Client.new(
         mcp_server_configs: [config],
         logger: options[:logger],
-        sampling_handler: options[:sampling_handler]
+        sampling_handler: options[:sampling_handler],
+        extensions: options[:extensions]
       )
       client.servers.first.connect
       client
@@ -183,7 +216,17 @@ module MCPClient
       begin
         logger.debug("MCPClient.connect: Attempting Streamable HTTP connection to #{url}")
         return connect_streamable_http(url, **options, &)
+      rescue Errors::ModernServerError
+        # The probe identified a modern (2026-07-28+) MCP server. The era is
+        # settled, so the legacy SSE and HTTP+POST fallbacks cannot do better
+        # — and trying them would hide the real, actionable failure.
+        raise
       rescue Errors::ConnectionError, Errors::TransportError => e
+        # protocol: :modern rules out the initialize handshake, and both
+        # remaining fallbacks are legacy-only transports that silently ignore
+        # the option.
+        raise if modern_only?(options)
+
         errors << "Streamable HTTP: #{e.message}"
         logger.debug("MCPClient.connect: Streamable HTTP failed: #{e.message}")
       end
@@ -210,8 +253,18 @@ module MCPClient
             "Failed to connect to #{url}. Tried all transports:\n  #{errors.join("\n  ")}"
     end
 
+    # Whether the caller demanded a modern (2026-07-28+) server, which rules
+    # out falling back to the legacy-only transports.
+    # @param options [Hash] the connect options
+    # @return [Boolean]
+    def modern_only?(options)
+      options[:protocol].respond_to?(:to_sym) && options[:protocol].to_sym == :modern
+    end
+
     # Detect transport type from target
-    def detect_transport(target)
+    # @param target [String, Array] the connection target
+    # @param options [Hash] the connect options, consulted for protocol:
+    def detect_transport(target, options = {})
       return :stdio if target.is_a?(Array) && stdio_command_array?(target)
       return :stdio if stdio_target?(target)
 
@@ -228,6 +281,11 @@ module MCPClient
       end
 
       path = uri.path.to_s.downcase
+      # A URL path is not a protocol declaration: protocol: :modern asks for a
+      # 2026-07-28 server, which only Streamable HTTP can speak. Honouring the
+      # /sse suffix there would select the legacy-only SSE transport, which
+      # drops the option and opens a GET stream instead of probing.
+      return :streamable_http if modern_only?(options)
       return :sse if path.end_with?('/sse')
       return :streamable_http if path.end_with?('/mcp')
 
@@ -295,12 +353,21 @@ module MCPClient
     def extract_http_options(options)
       extract_common_options(options).merge({
         headers: options[:headers] || {},
-        endpoint: options[:endpoint]
+        endpoint: options[:endpoint],
+        protocol: options[:protocol],
+        discover_timeout: options[:discover_timeout]
       }.compact)
     end
 
     # Extract SSE transport specific options
+    # @raise [ArgumentError] when protocol: :modern is combined with the SSE
+    #   transport, which cannot speak a 2026-07-28 server
     def extract_sse_options(options)
+      if modern_only?(options)
+        raise ArgumentError, 'transport: :sse cannot honour protocol: :modern: the HTTP+SSE transport is ' \
+                             'legacy-only (SEP-2596). Use transport: :streamable_http for a 2026-07-28 server.'
+      end
+
       extract_common_options(options).merge({
         headers: options[:headers] || {},
         ping: options[:ping]
@@ -310,13 +377,15 @@ module MCPClient
     # Extract stdio transport specific options
     def extract_stdio_options(options)
       extract_common_options(options).merge({
-        env: options[:env] || {}
+        env: options[:env] || {},
+        protocol: options[:protocol],
+        discover_timeout: options[:discover_timeout]
       }.compact)
     end
 
     # Build config hash for a target
     def build_config_for_target(target, **options, &)
-      transport = options[:transport]&.to_sym || detect_transport(target)
+      transport = options[:transport]&.to_sym || detect_transport(target, options)
 
       case transport
       when :stdio
@@ -379,18 +448,30 @@ module MCPClient
   # @param command [String, Array<String>] command to execute
   # @param name [String, nil] optional name for this server
   # @param logger [Logger, nil] optional logger for server operations
+  # @param env [Hash] environment variables for the subprocess
+  # @param protocol [Symbol] how to establish the server's MCP era: :auto (probe
+  #   with server/discover, fall back to the initialize handshake), :modern
+  #   (2026-07-28+ only) or :legacy (initialize handshake only)
+  # @param discover_timeout [Numeric, nil] seconds to wait for the server/discover probe
   # @return [Hash] server configuration
-  def self.stdio_config(command:, name: nil, logger: nil, env: {})
+  def self.stdio_config(command:, name: nil, logger: nil, env: {}, protocol: :auto, discover_timeout: nil)
     {
       type: 'stdio',
       command: command,
       name: name,
       logger: logger,
-      env: env || {}
+      env: env || {},
+      protocol: protocol,
+      discover_timeout: discover_timeout
     }
   end
 
   # Create a standard server configuration for SSE
+  #
+  # @deprecated The HTTP+SSE transport has been deprecated since MCP 2025-03-26
+  #   and is listed in the 2026-07-28 deprecated features registry (SEP-2596);
+  #   earliest removal is three months after SEP-2596 reaches Final. Use
+  #   {MCPClient.streamable_http_config} and {MCPClient::ServerStreamableHTTP}.
   # @param base_url [String] base URL for the server
   # @param headers [Hash] HTTP headers to include in requests
   # @param read_timeout [Integer] read timeout in seconds (default: 30)
@@ -424,11 +505,13 @@ module MCPClient
   # @param retry_backoff [Integer] backoff delay in seconds (default: 1)
   # @param name [String, nil] optional name for this server
   # @param logger [Logger, nil] optional logger for server operations
+  # @param protocol [Symbol] :auto (default), :modern or :legacy — which protocol era to speak
+  # @param discover_timeout [Numeric, nil] bound on the server/discover probe in seconds
   # @yieldparam faraday [Faraday::Connection] the configured connection instance for additional customization
   #   (e.g., SSL settings, custom middleware). The block is called after default configuration is applied.
   # @return [Hash] server configuration
   def self.http_config(base_url:, endpoint: '/rpc', headers: {}, read_timeout: 30, retries: 3, retry_backoff: 1,
-                       name: nil, logger: nil, &faraday_config)
+                       name: nil, logger: nil, protocol: :auto, discover_timeout: nil, &faraday_config)
     {
       type: 'http',
       base_url: base_url,
@@ -439,6 +522,8 @@ module MCPClient
       retry_backoff: retry_backoff,
       name: name,
       logger: logger,
+      protocol: protocol,
+      discover_timeout: discover_timeout,
       faraday_config: faraday_config
     }
   end
@@ -456,6 +541,8 @@ module MCPClient
   # @param max_decompressed_body_bytes [Integer] ceiling on how far a gzip-encoded
   #   response may expand before it is rejected, guarding against a small highly
   #   compressed body exhausting memory (default: 64 MiB)
+  # @param protocol [Symbol] :auto (default), :modern or :legacy — which protocol era to speak
+  # @param discover_timeout [Numeric, nil] bound on the server/discover probe in seconds
   # @yieldparam faraday [Faraday::Connection] the configured connection instance for additional customization
   #   (e.g., SSL settings, custom middleware). The block is called after default configuration is applied.
   # @return [Hash] server configuration
@@ -463,7 +550,7 @@ module MCPClient
                                   retry_backoff: 1, name: nil, logger: nil,
                                   max_decompressed_body_bytes:
                                     MCPClient::ServerStreamableHTTP::JsonRpcTransport::MAX_DECOMPRESSED_BODY_BYTES,
-                                  &faraday_config)
+                                  protocol: :auto, discover_timeout: nil, &faraday_config)
     {
       type: 'streamable_http',
       base_url: base_url,
@@ -475,6 +562,8 @@ module MCPClient
       name: name,
       logger: logger,
       max_decompressed_body_bytes: max_decompressed_body_bytes,
+      protocol: protocol,
+      discover_timeout: discover_timeout,
       faraday_config: faraday_config
     }
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Szymon Kurcab
@@ -130,26 +130,87 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- OAUTH.md
 - README.md
 - lib/mcp_client.rb
 - lib/mcp_client/audio_content.rb
 - lib/mcp_client/auth.rb
 - lib/mcp_client/auth/browser_oauth.rb
 - lib/mcp_client/auth/oauth_provider.rb
+- lib/mcp_client/auth/oauth_provider/challenge_handling.rb
+- lib/mcp_client/auth/oauth_provider/client_authentication.rb
+- lib/mcp_client/auth/oauth_provider/pending_requests.rb
+- lib/mcp_client/auth/oauth_provider/registration_store.rb
+- lib/mcp_client/auth/oauth_provider/response_validation.rb
+- lib/mcp_client/auth/oauth_provider/scope_selection.rb
+- lib/mcp_client/auth/oauth_provider/token_store.rb
+- lib/mcp_client/auth/peer_text.rb
+- lib/mcp_client/cached_result.rb
+- lib/mcp_client/called_tool_definition.rb
 - lib/mcp_client/client.rb
+- lib/mcp_client/client/cache_slices.rb
+- lib/mcp_client/client/list_aggregation.rb
+- lib/mcp_client/client/notification_routing.rb
+- lib/mcp_client/client/sampling_validation.rb
+- lib/mcp_client/client/task_api.rb
+- lib/mcp_client/client/task_lifetimes.rb
+- lib/mcp_client/client/task_registry.rb
+- lib/mcp_client/client/task_shape.rb
+- lib/mcp_client/client/task_support.rb
+- lib/mcp_client/client/task_updates.rb
+- lib/mcp_client/client/task_wait_boundaries.rb
+- lib/mcp_client/client/task_workers.rb
 - lib/mcp_client/config_parser.rb
+- lib/mcp_client/deep_copy.rb
+- lib/mcp_client/deprecation_notices.rb
+- lib/mcp_client/deprecations.rb
 - lib/mcp_client/elicitation_validator.rb
 - lib/mcp_client/errors.rb
+- lib/mcp_client/header_params.rb
 - lib/mcp_client/http_transport_base.rb
+- lib/mcp_client/http_transport_base/bounded_inflate.rb
+- lib/mcp_client/http_transport_base/cache_support.rb
+- lib/mcp_client/http_transport_base/era_detection.rb
+- lib/mcp_client/http_transport_base/listen_stream.rb
+- lib/mcp_client/http_transport_base/param_headers.rb
+- lib/mcp_client/http_transport_base/request_recovery.rb
+- lib/mcp_client/http_transport_base/session_recovery.rb
+- lib/mcp_client/http_transport_base/sse_event_scanner.rb
+- lib/mcp_client/http_transport_base/stream_capture.rb
+- lib/mcp_client/http_transport_base/stream_recovery.rb
+- lib/mcp_client/http_transport_base/tool_listing.rb
+- lib/mcp_client/input_round_trips.rb
 - lib/mcp_client/json_rpc_common.rb
+- lib/mcp_client/json_rpc_common/envelopes.rb
+- lib/mcp_client/json_rpc_common/error_bodies.rb
+- lib/mcp_client/json_rpc_common/input_waits.rb
 - lib/mcp_client/oauth_client.rb
 - lib/mcp_client/prompt.rb
+- lib/mcp_client/request_authorization.rb
+- lib/mcp_client/request_meta_scope.rb
+- lib/mcp_client/request_metadata.rb
 - lib/mcp_client/resource.rb
 - lib/mcp_client/resource_content.rb
 - lib/mcp_client/resource_link.rb
 - lib/mcp_client/resource_template.rb
+- lib/mcp_client/result_caching.rb
+- lib/mcp_client/result_completeness.rb
 - lib/mcp_client/root.rb
+- lib/mcp_client/round_trip_marker.rb
 - lib/mcp_client/schema_validator.rb
+- lib/mcp_client/schema_validator/annotations.rb
+- lib/mcp_client/schema_validator/composition.rb
+- lib/mcp_client/schema_validator/dialects.rb
+- lib/mcp_client/schema_validator/ecma_patterns.rb
+- lib/mcp_client/schema_validator/evaluation.rb
+- lib/mcp_client/schema_validator/input_requirements.rb
+- lib/mcp_client/schema_validator/instances.rb
+- lib/mcp_client/schema_validator/keyword_scan.rb
+- lib/mcp_client/schema_validator/normalization.rb
+- lib/mcp_client/schema_validator/references.rb
+- lib/mcp_client/schema_validator/scalars.rb
+- lib/mcp_client/schema_validator/shapes.rb
+- lib/mcp_client/schema_validator/uri_references.rb
 - lib/mcp_client/server_base.rb
 - lib/mcp_client/server_factory.rb
 - lib/mcp_client/server_http.rb
@@ -160,9 +221,14 @@ files:
 - lib/mcp_client/server_sse/reconnect_monitor.rb
 - lib/mcp_client/server_sse/sse_parser.rb
 - lib/mcp_client/server_stdio.rb
+- lib/mcp_client/server_stdio/child_session.rb
 - lib/mcp_client/server_stdio/json_rpc_transport.rb
 - lib/mcp_client/server_streamable_http.rb
 - lib/mcp_client/server_streamable_http/json_rpc_transport.rb
+- lib/mcp_client/session_pin.rb
+- lib/mcp_client/subscription.rb
+- lib/mcp_client/subscription/notification_dispatcher.rb
+- lib/mcp_client/subscription_support.rb
 - lib/mcp_client/task.rb
 - lib/mcp_client/tool.rb
 - lib/mcp_client/version.rb
@@ -178,7 +244,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="