mcp 1.8.1 → 1.9.0

data/lib/mcp/client.rb

@@ -7,6 +7,8 @@ require_relative "client/oauth"
 require_relative "client/stdio"
 require_relative "client/http"
 require_relative "client/paginated_result"
+require_relative "client/skill_errors"
+require_relative "client/skills"
 require_relative "client/tool"
 require_relative "result_type"
 
@@ -114,6 +116,9 @@ module MCP
     STATE_ONLY_BACKOFF_INITIAL_SECONDS = 0.05
     STATE_ONLY_BACKOFF_CAP_SECONDS = 0.25
 
+    # The Skills extension methods (SEP-2640): `list_skills`, `get_skill`, `read_skill_resource`, `skills_capability`.
+    include Skills
+
     # Initializes a new MCP::Client instance.
     #
     # @param transport [Object] The transport object to use for communication with the server.
@@ -144,6 +149,8 @@ module MCP
       # a SEP-2322 `input_required` result.
       @input_required_handlers = {}
       @input_required_max_rounds = input_required_max_rounds
+      # Skills extension state (SEP-2640), bound to the connection by `connect`; see `Client::Skills`.
+      @skills_state = Skills::State.new
     end
 
     # The user may want to access additional transport-specific methods/attributes
@@ -217,7 +224,15 @@ module MCP
 
       effective_mode = resolve_connect_mode(mode, protocol_version)
 
-      if effective_mode == :legacy
+      # Skills state (SEP-2640) follows the connection: a handshake about to run starts a new generation, its
+      # result is recorded only if no newer handshake started meanwhile, and a failure clears readiness under
+      # the same condition, so a stale completion or failure changes nothing. The bundled transports answer
+      # a repeated `connect` with their cached handshake result without any I/O, so when the transport is
+      # connected and Skills is ready nothing is reset: the latches of a live connection stay put.
+      generation = @skills_state.begin_handshake unless skills_ready_on_connected_transport?
+      completed = false
+
+      result = if effective_mode == :legacy
         transport.connect(
           client_info: client_info,
           protocol_version: protocol_version,
@@ -231,6 +246,11 @@ module MCP
           mode: effective_mode,
         )
       end
+      completed = true
+      @skills_state.handshake_completed(generation, result) if generation
+      result
+    ensure
+      @skills_state.handshake_failed(generation) if generation && !completed
     end
 
     # Sends `server/discover` (MCP 2026-07-28, SEP-2575): sessionless capability discovery
@@ -295,10 +315,14 @@ module MCP
 
         Tool.new(
           name: tool["name"],
+          title: tool["title"],
           description: tool["description"],
           input_schema: tool["inputSchema"],
           output_schema: tool["outputSchema"],
           annotations: tool["annotations"],
+          icons: tool["icons"],
+          execution: tool["execution"],
+          meta: tool["_meta"],
         )
       end
 
@@ -673,10 +697,19 @@ module MCP
       scan = McpParamHeaders.scan(tool["inputSchema"])
       return false if scan[:valid]
 
-      warn("MCP::Client: excluding tool #{tool["name"].inspect} from tools/list: #{scan[:reason]}")
+      name = tool["name"]
+      # Both pieces are the server's: `dump` keeps control characters and bidirectional overrides out of the log line.
+      warn("MCP::Client: excluding tool #{(name.is_a?(String) ? name : name.inspect).dump} from tools/list: #{scan[:reason].dump}")
       true
     end
 
+    # Whether a `connect` would only hand back the transport's cached handshake: the transport reports itself
+    # connected and Skills already recorded a handshake of this connection. A transport without connection
+    # state always starts a new generation.
+    def skills_ready_on_connected_transport?
+      transport.respond_to?(:connected?) && transport.connected? && @skills_state.ready?
+    end
+
     # Resolves the effective SEP-2575 lifecycle mode for `connect`:
     #
     # - An explicit `protocol_version` from a legacy generation pins the legacy handshake without a probe,

data/lib/mcp/methods.rb

@@ -22,6 +22,11 @@ module MCP
     RESOURCES_SUBSCRIBE = "resources/subscribe"
     RESOURCES_UNSUBSCRIBE = "resources/unsubscribe"
 
+    # Skills extension (SEP-2640): registered only when a server configures skills,
+    # so an unconfigured server answers `-32601` rather than a capability error.
+    SKILLS_LIST = "skills/list"
+    SKILLS_GET = "skills/get"
+
     TOOLS_CALL = "tools/call"
     TOOLS_LIST = "tools/list"
 

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

@@ -476,6 +476,9 @@ module MCP
         # with a `StandardError` does not stop the teardown below: `join` re-raises the exception a thread died with,
         # which is not this method's to raise. A reaper still alive after the wait is killed as before, leaving
         # the streams of that reap it had not closed yet as they were.
+        # A `close` running on the reaper thread itself, reached from a stream's `close` or from the exception reporter
+        # during a reap, neither joins nor kills it: the join would fail on its own thread and the kill would end
+        # this teardown with the reap that called it. The reaper leaves its loop on `@closing` once that reap returns.
         def close
           reaper = @mutex.synchronize do
             @closing = true
@@ -483,13 +486,15 @@ module MCP
             @reaper_thread
           end
 
-          begin
-            reaper&.join(REAPER_JOIN_TIMEOUT)
-          rescue StandardError
-            # The reaper is gone either way; the exception that ended it is not this method's to report.
-          end
+          if reaper && !reaper.equal?(Thread.current)
+            begin
+              reaper.join(REAPER_JOIN_TIMEOUT)
+            rescue StandardError
+              # The reaper is gone either way; the exception that ended it is not this method's to report.
+            end
 
-          reaper.kill if reaper&.alive?
+            reaper.kill if reaper.alive?
+          end
           @reaper_thread = nil
 
           teardown_listen_subscriptions
@@ -521,12 +526,19 @@ module MCP
           # a per-request sink for its ephemeral session and flushes it as SSE frames ahead of the final response.
           # Checked before the stateless guard, since modern requests are served in stateless deployments too.
           # The sink is bounded; past `MAX_MODERN_REQUEST_NOTIFICATIONS` the notification is dropped as
-          # non-delivery (`false`), never handed to the legacy paths below.
+          # non-delivery (`false`), never handed to the legacy paths below. It holds each notification as JSON,
+          # generated here so that one that cannot be generated is dropped on its own instead of failing
+          # the whole response when the sink is flushed.
           sink = @mutex.synchronize { session_id && @modern_request_sinks[session_id] }
           if sink
             return false if sink.size >= MAX_MODERN_REQUEST_NOTIFICATIONS
 
-            sink << notification
+            begin
+              sink << notification.to_json
+            rescue JSON::GeneratorError => e
+              MCP.configuration.exception_reporter.call(e, { session_id: session_id, error: "Failed to generate notification" })
+              return false
+            end
             return true
           end
 
@@ -931,16 +943,26 @@ module MCP
           # `nil` covers notifications and cancellation-suppressed responses; ack with 202 like the legacy notification path.
           return handle_accepted if response.nil?
 
+          # A response that cannot be generated answers its request with Internal error, as `JsonRpcHandler.handle_json`
+          # does on the legacy paths, instead of failing the whole exchange with a 500.
+          response_json = begin
+            response.to_json
+          rescue JSON::GeneratorError => e
+            MCP.configuration.exception_reporter.call(e, { error: "Failed to generate response" })
+            response = JsonRpcHandler.encodable_response(response)
+            response.to_json
+          end
+
           # Notifications a handler emitted during the request ride the request's own response stream as SSE frames ahead of
           # the final response (SEP-2575); a request that emitted none keeps the single JSON exchange and its HTTP status ladder.
           # Delivery is buffered: frames flush after the handler returns, preserving order but not real-time interleaving
           # (the TypeScript and Python SDKs stream live), and the sink grows with the handler's notification count.
           # Live streaming can follow without changing the wire shape.
           if notifications.empty?
-            [modern_http_status(response), { "content-type" => "application/json" }, [response.to_json]]
+            [modern_http_status(response), { "content-type" => "application/json" }, [response_json]]
           else
-            frames = notifications + [response]
-            sse_body = frames.map { |frame| "event: message\ndata: #{frame.to_json}\n\n" }.join
+            frames = notifications + [response_json]
+            sse_body = frames.map { |frame| "event: message\ndata: #{frame}\n\n" }.join
             [200, SSE_HEADERS.dup, [sse_body]]
           end
         rescue StandardError => e
@@ -958,7 +980,7 @@ module MCP
         # converge on enforcement.
         def validate_modern_headers(request, body, header_version)
           params = body[:params]
-          meta_version = params.is_a?(Hash) ? params.dig(:_meta, :"io.modelcontextprotocol/protocolVersion") : nil
+          meta_version = params.is_a?(Hash) && params[:_meta].is_a?(Hash) ? params.dig(:_meta, :"io.modelcontextprotocol/protocolVersion") : nil
           if meta_version && meta_version != header_version
             return header_mismatch_response(
               "MCP-Protocol-Version header value '#{header_version}' does not match body value '#{meta_version}'",
@@ -1034,7 +1056,7 @@ module MCP
 
           begin
             if RequestEnvelope.modern?(params)
-              RequestEnvelope.parse!(params, request: params)
+              envelope = RequestEnvelope.parse!(params, request: params)
             else
               return invalid_request_response("Invalid Request: modern requests require the SEP-2575 `_meta` envelope")
             end
@@ -1074,7 +1096,7 @@ module MCP
             return too_many_listen_subscriptions_response(request_id)
           end
 
-          honored = honored_filter(filter)
+          honored = honored_filter(filter, meta: params[:_meta], envelope: envelope, auth_info: auth_info)
 
           # The acknowledgement echoes the honored filter, whose resource URIs are client-supplied strings,
           # so it is encoded before the stream is committed to: a URI that cannot be written as JSON is
@@ -1321,8 +1343,9 @@ module MCP
 
         # Per SEP-2575, the server MUST NOT send notification types the client has not requested,
         # and the acknowledgement only includes types the server actually supports
-        # (derived from its declared capabilities).
-        def honored_filter(filter)
+        # (derived from its declared capabilities). Resource URIs are further narrowed to those
+        # the server's `resources_subscribe_handler` accepts; the field is omitted when none remain.
+        def honored_filter(filter, meta: nil, envelope: nil, auth_info: nil)
           capabilities = @server.capabilities
           honored = {}
           honored[:toolsListChanged] = true if filter[:toolsListChanged] && capability_flag?(capabilities, :tools, :listChanged)
@@ -1331,7 +1354,8 @@ module MCP
 
           subscriptions = filter[:resourceSubscriptions]
           if capability_flag?(capabilities, :resources, :subscribe) && subscriptions.is_a?(Array) && !subscriptions.empty?
-            honored[:resourceSubscriptions] = subscriptions.uniq
+            uris = @server.subscribable_resource_uris(subscriptions, meta: meta, envelope: envelope, auth_info: auth_info)
+            honored[:resourceSubscriptions] = uris unless uris.empty?
           end
 
           honored
@@ -1875,7 +1899,7 @@ module MCP
         end
 
         def validate_accept_header(request, required_types)
-          accept_header = request.env["HTTP_ACCEPT"]
+          accept_header = header_bytes(request, "HTTP_ACCEPT")
           return not_acceptable_response(required_types) unless accept_header
 
           accepted_types = parse_accept_header(accept_header)
@@ -1894,7 +1918,7 @@ module MCP
         end
 
         def validate_content_type(request)
-          content_type = request.env["CONTENT_TYPE"]
+          content_type = header_bytes(request, "CONTENT_TYPE")
           media_type = content_type&.split(";")&.first&.strip&.downcase
           return if media_type == "application/json"
 
@@ -2404,10 +2428,18 @@ module MCP
           validate_host(request) || validate_origin(request)
         end
 
+        # A header value as bytes. Rack servers hand header values over as ASCII-8BIT, where every byte is valid, but a framework
+        # or a test request can tag them UTF-8, and then `downcase`, `split`, and regexps raise on an invalid byte sequence
+        # before any rescue applies. Reading the value as bytes puts both on the same footing: a malformed value fails its comparison
+        # and gets the rejection that comparison produces, instead of failing the request.
+        def header_bytes(request, name)
+          request.env[name]&.b
+        end
+
         # Rejects a rebound `Host` (e.g. `evil.example.com` re-pointed at 127.0.0.1).
         # A request without a `Host` header (e.g. HTTP/1.0) is allowed; the rebinding vector this guards against always carries one.
         def validate_host(request)
-          host = request.env["HTTP_HOST"]
+          host = header_bytes(request, "HTTP_HOST")
           return if host.nil?
 
           # An `allowed_hosts:` entry matches either the bare host name (any port)
@@ -2422,7 +2454,7 @@ module MCP
         # A request without an `Origin` header (typical for non-browser MCP clients) is allowed. A browser cross-origin request is
         # rejected unless the origin is same-origin or explicitly allow-listed via `allowed_origins:`.
         def validate_origin(request)
-          origin = request.env["HTTP_ORIGIN"]
+          origin = header_bytes(request, "HTTP_ORIGIN")
           return if origin.nil?
           return if same_origin?(origin, request)
           return if @allowed_origins.include?(origin.downcase)
@@ -2443,7 +2475,7 @@ module MCP
         # but the `Origin`'s scheme is used to drop a redundant default port (`:80` for http, `:443` for https) from
         # both sides so `http://example.com` matches `Host: example.com:80`. Comparison is case-insensitive.
         def same_origin?(origin, request)
-          host = request.env["HTTP_HOST"]
+          host = header_bytes(request, "HTTP_HOST")
           return false if host.nil?
 
           normalized = origin.downcase