mcp 1.8.0 → 1.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3585a92ae036b5018c7edf6b4c77a4a5c07903084314459a58180df16d3f0e28
-  data.tar.gz: d543ab701b3589e5728dba998e9b7d66b52baabfa4e9cf272834024bc57340a0
+  metadata.gz: 255e316335616783063d8a7374f385ff10b99c9ddef24571734e19b6ec6f5f93
+  data.tar.gz: 07021e227f5b1be05fd2c1e4dc88e0d563bc963b6f1190f998aa632ed6871031
 SHA512:
-  metadata.gz: 2d8cdd94c440d86ed5c317cc4bd94b21279ea613be75956bc49de0ddb008a0b574f3ee15751053be78c249d420709a168f0810674dbeeea34d9cd359dd9ac2f0
-  data.tar.gz: 9f131703b9db0f7fdfbc0a57ffe7b4132c522720bf841aaa4d70f20487644fe6ef428f89f4f39d4c1044312045553356fe87c3684f1deadc95dc81b45e441d42
+  metadata.gz: 3d496817c30ae59b7f99704fead73cc9dfe5d926a87455a5c51fcc766bdf299d943ce86c0d43ca859d870a488df191cc0a4bdeba302b95d8ebcf084730743a68
+  data.tar.gz: 6291785257c054baf3570fb9baef4ecb1db006c920608ad69239460e2494610fa9133341bdf903a4c127f7ab40146f2bf9eecb34266621cba172a08ef52812f0

data/lib/json_rpc_handler.rb

@@ -55,14 +55,19 @@ module JsonRpcHandler
 
   def handle_json(request_json, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
     begin
-      request = JSON.parse(request_json, symbolize_names: true)
+      begin
+        request = JSON.parse(request_json, symbolize_names: true)
+      rescue JSON::ParserError, EncodingError
+        # `symbolize_names` raises `EncodingError` for a key that is not valid UTF-8, a parse error as well.
+        # Rescued around the parse only, so an error raised while handling keeps its own classification.
+        return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+          code: ErrorCode::PARSE_ERROR,
+          message: "Parse error",
+          data: "Invalid JSON",
+        }).to_json
+      end
+
       response = handle(request, id_validation_pattern: id_validation_pattern, &method_finder)
-    rescue JSON::ParserError
-      response = error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
-        code: ErrorCode::PARSE_ERROR,
-        message: "Parse error",
-        data: "Invalid JSON",
-      })
     rescue StandardError
       # Last-resort guard so an unexpected handling error returns a JSON-RPC error
       # instead of escaping to the transport loop.
@@ -90,17 +95,25 @@ module JsonRpcHandler
 
     error = if !valid_version?(request[:jsonrpc])
       "JSON-RPC version must be 2.0"
+    elsif request.key?(:id) && id.nil?
+      # JSON-RPC 2.0 allows a null id; MCP rules it out: a request carries a string or an integer id,
+      # and a notification carries no id member at all. Refused rather than run as a notification,
+      # since a sender that wrote an id meant to be answered.
+      "Request ID must not be null"
     elsif !valid_id?(id, id_validation_pattern)
-      "Request ID must match validation pattern, or be an integer or null"
+      if id_validation_pattern
+        "Request ID must be a string matching the validation pattern, or an integer"
+      else
+        "Request ID must be a string or an integer"
+      end
     elsif !valid_method_name?(request[:method])
       'Method name must be a string and not start with "rpc."'
     end
 
     # Per JSON-RPC 2.0 (Response object, `id`), the error response must carry
-    # the same id as the request when the id could be detected; null is only
-    # for requests whose id could not be determined. `error_response` nils out
-    # ids that fail validation, and the `:unknown_id` sentinel keeps a response
-    # (with a null id) being emitted when the request carried no id at all.
+    # the same id as the request when the id could be detected. `error_response`
+    # leaves the id out for ids that fail validation, and the `:unknown_id` sentinel
+    # keeps a response (without an id) being emitted when the request carried no id at all.
     return error_response(id: id.nil? ? :unknown_id : id, id_validation_pattern: id_validation_pattern, error: {
       code: ErrorCode::INVALID_REQUEST,
       message: "Invalid Request",
@@ -176,7 +189,9 @@ module JsonRpcHandler
 
   def valid_id?(id, pattern = nil)
     return true if id.nil? || id.is_a?(Integer)
-    return false unless id.is_a?(String)
+    # A string that is not valid in its encoding cannot be written into the response,
+    # and matching a pattern against it raises, so it is refused before the method runs.
+    return false unless id.is_a?(String) && id.valid_encoding?
 
     pattern ? id.match?(pattern) : true
   end
@@ -197,11 +212,15 @@ module JsonRpcHandler
     } unless id.nil?
   end
 
+  # An error response for a request whose id could not be read carries no `id` member: JSON-RPC 2.0 puts
+  # a null there, but the MCP schema allows only a string or an integer, and the Streamable HTTP transport
+  # specification describes such a body as an error response that has no id.
   def error_response(id:, id_validation_pattern:, error:)
-    {
-      jsonrpc: Version::V2_0,
-      id: valid_id?(id, id_validation_pattern) ? id : nil,
-      error: error.compact,
-    } unless id.nil?
+    return if id.nil?
+
+    response = { jsonrpc: Version::V2_0 }
+    response[:id] = id if valid_id?(id, id_validation_pattern)
+    response[:error] = error.compact
+    response
   end
 end

data/lib/mcp/client/http.rb

@@ -120,7 +120,7 @@ module MCP
       # the incrementally parsed JSON-RPC response, the last received SSE event id (for `Last-Event-ID`),
       # and the server's `retry:` reconnection delay. Non-SSE bodies accumulate in `buffer` for the JSON path.
       class SSEStream
-        attr_reader :buffer, :response, :last_event_id, :retry_ms
+        attr_reader :buffer, :response, :response_headers, :last_event_id, :retry_ms
         attr_accessor :abortable
 
         def initialize(abortable:, max_message_bytes: MAX_MESSAGE_BYTES, on_request: nil)
@@ -132,6 +132,7 @@ module MCP
           @response = nil
           @last_event_id = nil
           @retry_ms = nil
+          @response_headers = nil
         end
 
         # Whether the server sent a SEP-1699 priming event (any event carrying an id),
@@ -146,9 +147,10 @@ module MCP
         # abort the stream so an over-limit tail cannot mask a response that already arrived.
         def on_data
           proc do |chunk, _received_bytes, env|
+            @response_headers ||= env.response_headers if env
             if event_stream?(env)
               feed(chunk)
-              raise StreamAbort if @abortable && @response
+              raise StreamAbort if @abortable && @response && !error_status?(env)
 
               if parser_buffered_bytes > @max_message_bytes
                 raise MessageTooLargeError, "Server SSE event exceeds #{@max_message_bytes} bytes without completing"
@@ -163,6 +165,16 @@ module MCP
           end
         end
 
+        # An error status must reach Faraday's `raise_error` middleware (which drives the
+        # OAuth and step-up retries in `send_request`), so the stream is read to EOF instead
+        # of aborting when the server answered with one. This is the behavior every
+        # method had before the abort shortcut. It is the only case that still needs
+        # the finished response object.
+        def error_status?(env)
+          status = env.status if env.respond_to?(:status)
+          status.is_a?(Integer) && status >= 400
+        end
+
         # A fresh parser for a new HTTP connection (reconnection GET),
         # so a partial line from the previous stream cannot corrupt the next one.
         def reset_parser!
@@ -408,10 +420,13 @@ module MCP
 
         begin
           # The response is consumed incrementally so that an SSE stream the server holds open
-          # (or closes early per SEP-1699) can be handled; `initialize` streams are read to EOF
-          # so the response object (and its `Mcp-Session-Id` header) is always available for capture.
+          # (or closes early per SEP-1699) can be handled. Every request, `initialize` included,
+          # aborts once its response event arrives: `SSEStream` has already captured the response
+          # headers from the streaming `env` by then, so `Mcp-Session-Id` survives the abort.
+          # When `env` is unavailable (Faraday < 2.5 or an adapter without `on_data` support)
+          # nothing aborts and the stream is still read to EOF, as before.
           stream = SSEStream.new(
-            abortable: method.to_s != MCP::Methods::INITIALIZE,
+            abortable: true,
             max_message_bytes: @max_message_bytes,
             on_request: ->(message) { dispatch_server_request(message) },
           )
@@ -434,7 +449,7 @@ module MCP
           # anything is learned from the body, and only for a request: a notification awaits no response.
           reject_invalid_response!(body, method, params) if request_id
 
-          capture_session_info(method, response, body) if response
+          capture_session_info(method, response ? response.headers : stream.response_headers, body)
           capture_mcp_param_declarations(method, params, body)
 
           body
@@ -963,11 +978,11 @@ module MCP
         !(tokens["refresh_token"] || tokens[:refresh_token]).to_s.empty?
       end
 
-      def capture_session_info(method, response, body)
+      def capture_session_info(method, headers, body)
         return unless method.to_s == Methods::INITIALIZE
 
         # Faraday normalizes header names to lowercase.
-        session_id = response.headers[SESSION_ID_HEADER.downcase]
+        session_id = headers[SESSION_ID_HEADER.downcase]
         @session_id ||= session_id unless session_id.to_s.empty?
         @protocol_version ||= body.is_a?(Hash) ? body.dig("result", "protocolVersion") : nil
       end

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

@@ -49,10 +49,26 @@ module MCP
             end
             break if line.nil?
 
-            line = line.strip
-            parsed = parse_line(line)
-            response = parsed ? dispatch_with_era(parsed) : @session.handle_json(line)
-            send_response(response) if response
+            line = strip_frame(line)
+
+            # Reset for each frame: the loop body shares one scope, so a frame whose parse raises would otherwise
+            # be answered with the previous frame's id.
+            parsed = nil
+
+            begin
+              parsed = parse_line(line)
+              response = parsed ? dispatch_with_era(parsed) : @session.handle_json(line)
+
+              send_response(response) if response
+            rescue StandardError => e
+              # One frame must not end the connection: a reply that cannot be generated (a request string
+              # the JSON parser passed through without being valid UTF-8, echoed by the SDK or a handler) or
+              # any other failure past the server's own error handling answers that frame with Internal error,
+              # unless the frame is a notification, which gets no response.
+              MCP.configuration.exception_reporter.call(e, { error: "Failed to handle stdio frame" })
+
+              send_response(internal_error_response(parsed)) unless parsed.is_a?(Hash) && !parsed.key?(:id)
+            end
           end
         rescue Interrupt
           warn("\nExiting...")
@@ -70,6 +86,16 @@ module MCP
           $stdout.flush
         end
 
+        # The error answering a frame whose handling failed. It carries the request id when the frame was
+        # a single request whose id can be written back, and no `id` otherwise, as for an id that could not be read.
+        def internal_error_response(parsed)
+          response = { jsonrpc: JsonRpcHandler::Version::V2_0 }
+          id = parsed[:id] if parsed.is_a?(Hash)
+          response[:id] = id if id.is_a?(Integer) || (id.is_a?(String) && id.valid_encoding?)
+          response[:error] = { code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR, message: "Internal error" }
+          response
+        end
+
         def send_notification(method, params = nil)
           notification = {
             jsonrpc: "2.0",
@@ -111,8 +137,8 @@ module MCP
 
           while @open && (line = read_line($stdin))
             begin
-              parsed = JSON.parse(line.strip, symbolize_names: true)
-            rescue JSON::ParserError => e
+              parsed = JSON.parse(strip_frame(line), symbolize_names: true)
+            rescue JSON::ParserError, EncodingError => e
               MCP.configuration.exception_reporter.call(e, { error: "Failed to parse response" })
               raise
             end
@@ -152,13 +178,22 @@ module MCP
           line
         end
 
+        # Strips a frame as bytes. `$stdin` is read as UTF-8, and `String#strip` raises for a UTF-8 string holding
+        # an invalid byte at either end on every supported Ruby, and anywhere in it from Ruby 3.2 on, so one such
+        # frame would end the read loop instead of being answered. As bytes, it reaches the parser, which refuses
+        # what is not JSON with a parse error.
+        def strip_frame(line)
+          line.b.strip.force_encoding(Encoding::UTF_8)
+        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
+        rescue JSON::ParserError, EncodingError
+          # `symbolize_names` raises `EncodingError` for a key that is not valid UTF-8; `handle_json` answers the parse error.
           nil
         end
 
@@ -168,7 +203,9 @@ module MCP
         # (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)
+          # Passing `auth_info:` keeps Ruby 2.7 from taking the request Hash as keyword arguments,
+          # which works but warns that the conversion is deprecated.
+          response = @session.handle(parsed, auth_info: nil)
           lock_modern_era_on_success(parsed, response)
           response
         end

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

@@ -406,6 +406,12 @@ module MCP
           @serve_subscriptions_listen
         end
 
+        # Stateless mode has no session streams to deliver notifications on (`send_notification` reports non-delivery),
+        # so `Server#init` advertises no `listChanged`/`subscribe` flags there.
+        def delivers_notifications?
+          !@stateless
+        end
+
         def handle_request(request)
           rebinding_error = validate_dns_rebinding(request)
           return rebinding_error if rebinding_error
@@ -1020,7 +1026,7 @@ module MCP
 
           # The id is echoed in every message of the stream, so one that cannot be written back as JSON
           # (a String holding bytes that are not valid UTF-8 parses, but does not generate) is refused here,
-          # while the refusal can still answer with a null id, rather than surfacing as a failed write after
+          # while the refusal can still answer without an id, rather than surfacing as a failed write after
           # the stream has been registered.
           unless json_encodable?(request_id)
             return invalid_request_response("Invalid Request: subscriptions/listen id must be valid UTF-8")
@@ -1881,10 +1887,10 @@ module MCP
           nil
         end
 
+        # Empty list members (`application/json,,text/event-stream`), which RFC 9110 section 5.6.1.2 has
+        # a recipient parse and ignore, are skipped.
         def parse_accept_header(header)
-          header.split(",").map do |part|
-            part.split(";").first.strip.downcase
-          end
+          header.split(",").map { |part| part.split(";").first.to_s.strip.downcase }.reject(&:empty?)
         end
 
         def validate_content_type(request)
@@ -1974,7 +1980,8 @@ module MCP
           # `max_nesting` bounds parse depth; a too-deep body raises `JSON::NestingError`,
           # a subclass of `JSON::ParserError`, so it is caught below as a parse error.
           JSON.parse(body_string, symbolize_names: true, max_nesting: MAX_JSON_NESTING)
-        rescue JSON::ParserError, TypeError
+        # `symbolize_names` raises `EncodingError`, not `JSON::ParserError`, for a key that is not valid UTF-8.
+        rescue JSON::ParserError, TypeError, EncodingError
           raise InvalidJsonError
         end
 
@@ -2028,15 +2035,21 @@ module MCP
           )
         end
 
+        # The body leaves the `id` member out when there is no request id to echo, as the MCP schema allows
+        # only a string or an integer there.
         def json_rpc_error_response(status:, code:, message:, data: nil, id: nil)
           error = { code: code, message: message }
           error[:data] = data if data
-          body = { jsonrpc: "2.0", id: id, error: error }
+          body = { jsonrpc: "2.0" }
+          body[:id] = id unless id.nil?
+          body[:error] = error
           [status, { "content-type" => "application/json" }, [body.to_json]]
         end
 
+        # A notification carries no id member at all; a message with `"id": null` is a malformed request,
+        # which the server answers with Invalid Request instead of running it unanswered.
         def notification?(body)
-          !body[:id] && !!body[:method]
+          !body.key?(:id) && !!body[:method]
         end
 
         # Dispatches a client-originated notification (e.g. `notifications/cancelled`,
@@ -2127,10 +2140,10 @@ module MCP
           response = server_session.handle_json(body_string, auth_info: auth_info)
 
           # `initialize_request?` matches on the method alone, so an `initialize` sent without
-          # an id (framed as a notification) reaches here. `Server#init` marks the session initialized,
-          # but JSON-RPC emits no response for an id-less request, so `response` is nil.
-          # Returning `[200, ..., [nil]]` would place nil in the Rack body (which the web server cannot serialize),
-          # and the session would be retained since it is marked initialized. Discard the orphaned session
+          # an id (framed as a notification) reaches here. `Server#init` does not run for it, as for
+          # any request method without an id, so `response` is nil and the session created above
+          # is never initialized. Returning `[200, ..., [nil]]` would place nil in the Rack body (which
+          # the web server cannot serialize), and the session would linger uninitialized. Discard it
           # and ack with 202, mirroring the nil-response handling in a regular request.
           if response.nil?
             cleanup_session(session_id) if session_id
@@ -2477,15 +2490,12 @@ module MCP
         end
 
         def invalid_request_response(message, request_id: nil)
-          body = {
-            jsonrpc: "2.0",
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: message,
             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

data/lib/mcp/server.rb

@@ -271,6 +271,9 @@ module MCP
         Methods::COMPLETION_COMPLETE => ->(_) { DEFAULT_COMPLETION_RESULT },
         Methods::LOGGING_SET_LEVEL => method(:configure_logging_level),
       }
+      # The protocol's own request methods, as opposed to the notifications above and to custom methods
+      # registered later: these need a request id to be run.
+      @protocol_request_methods = @handlers.keys.reject { |name| Methods.notification?(name) }.freeze
       @transport = transport
     end
 
@@ -285,7 +288,7 @@ module MCP
     #   handlers as `server_context.auth_info`.
     # @return [Hash, nil] The JSON-RPC response, or `nil` for notifications.
     def handle(request, session: nil, auth_info: nil)
-      JsonRpcHandler.handle(request) do |method, request_id|
+      JsonRpcHandler.handle(request, id_validation_pattern: nil) do |method, request_id|
         handle_request(request, method, session: session, related_request_id: request_id, auth_info: auth_info)
       end
     end
@@ -300,7 +303,7 @@ module MCP
     #   for the current request, as in `handle`.
     # @return [String, nil] The JSON-RPC response as JSON, or `nil` for notifications.
     def handle_json(request, session: nil, auth_info: nil)
-      JsonRpcHandler.handle_json(request) do |method, request_id|
+      JsonRpcHandler.handle_json(request, id_validation_pattern: nil) do |method, request_id|
         handle_request(request, method, session: session, related_request_id: request_id, auth_info: auth_info)
       end
     end
@@ -614,6 +617,12 @@ module MCP
       # the TypeScript and Python SDKs rather than emitting a spurious `result: null`.
       return if Methods.notification?(method) && !related_request_id.nil?
 
+      # The mirror case: a request method of the protocol sent without an id is framed as a notification,
+      # whose result the sender can never receive, so it is not run either; the TypeScript and Python servers
+      # drop such a message the same way, as a notification they have no handler for. A custom method keeps
+      # running without an id, since `define_custom_method` serves notifications too.
+      return if related_request_id.nil? && @protocol_request_methods.include?(method)
+
       # `notifications/cancelled` is dispatched directly: it is a notification (no JSON-RPC id)
       # and intentionally bypasses the `@handlers` lookup, capability check, in-flight registry,
       # and rescue blocks below.
@@ -645,10 +654,18 @@ module MCP
       begin
         Methods.ensure_capability!(method, capabilities)
       rescue Methods::MissingRequiredCapabilityError => e
-        # Re-raise through RequestHandlerError, the one channel whose message is
-        # deliberately surfaced to clients: `JsonRpcHandler`'s blind `rescue StandardError`
-        # no longer echoes exception messages into the error `data` member (CWE-209).
-        raise RequestHandlerError.new(e.message, request, error_type: :internal_error, original_error: e)
+        # A method of a capability the server does not declare is one the server does not implement, so it is answered as Method not found,
+        # which the TypeScript and Python servers return for a handler they never registered, and which the Streamable HTTP transport maps to
+        # 404 on the modern lifecycle. Re-raised through RequestHandlerError, the one channel whose message is deliberately surfaced to clients:
+        # `JsonRpcHandler`'s blind `rescue StandardError` no longer echoes exception messages into the error `data` member (CWE-209).
+        raise RequestHandlerError.new(
+          "Method not found",
+          request,
+          error_type: :method_not_found,
+          error_code: JsonRpcHandler::ErrorCode::METHOD_NOT_FOUND,
+          error_data: e.message,
+          original_error: e,
+        )
       end
 
       # `initialize` MUST NOT be cancelled (MCP spec 2025-11-25, cancellation item 2),
@@ -1131,7 +1148,7 @@ module MCP
 
       {
         protocolVersion: negotiated_version,
-        capabilities: capabilities,
+        capabilities: handshake_capabilities,
         serverInfo: info,
         instructions: response_instructions,
       }.compact
@@ -1208,6 +1225,19 @@ module MCP
     def discover_capabilities
       return capabilities if @transport.respond_to?(:serves_subscriptions_listen?) && @transport.serves_subscriptions_listen?
 
+      without_notification_flags(capabilities)
+    end
+
+    # Capabilities as advertised by `initialize`. A transport that delivers no notifications to its sessions
+    # (stateless Streamable HTTP) cannot keep the promise the `listChanged` and `subscribe` flags make, so they are
+    # left out, as `server/discover` leaves them out when `subscriptions/listen` is not served.
+    def handshake_capabilities
+      return capabilities unless @transport.respond_to?(:delivers_notifications?) && !@transport.delivers_notifications?
+
+      without_notification_flags(capabilities)
+    end
+
+    def without_notification_flags(capabilities)
       capabilities.each_with_object({}) do |(name, value), stripped|
         stripped[name] = if value.is_a?(Hash)
           value.reject { |flag, _| ["listChanged", "subscribe"].include?(flag.to_s) }

data/lib/mcp/transport.rb

@@ -57,6 +57,14 @@ module MCP
       false
     end
 
+    # Whether the transport delivers notifications to a connected client outside the response to one of its
+    # requests (`notifications/*/list_changed`, `notifications/resources/updated`). `Server#init` strips the
+    # `listChanged`/`subscribe` capability flags when it does not, since the handshake would promise notifications
+    # the transport drops.
+    def delivers_notifications?
+      true
+    end
+
     private
 
     def generate_request_id

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.8.1
 platform: ruby
 authors:
 - Model Context Protocol
@@ -119,7 +119,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.8.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.8.1
   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