mcp 0.18.0 → 0.21.0

data/lib/mcp/client.rb

@@ -77,7 +77,9 @@ module MCP
     #
     # @param client_info [Hash, nil] `{ name:, version: }` identifying the client.
     # @param protocol_version [String, nil] Protocol version to offer.
-    # @param capabilities [Hash] Capabilities advertised by the client.
+    # @param capabilities [Hash] Capabilities advertised by the client. May include
+    #   an `extensions` member per SEP-2133, keyed by reverse-DNS extension identifiers,
+    #   e.g. `{ extensions: { "com.example/feature" => {} } }`.
     # @return [Hash, nil] The server's `InitializeResult`, or `nil` when the transport
     #   does not expose an explicit handshake.
     # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization
@@ -103,6 +105,8 @@ module MCP
     # Returns a single page of tools from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListToolsResult] Result with `tools` (Array<MCP::Client::Tool>)
     #   and `next_cursor` (String or nil).
     #
@@ -114,9 +118,9 @@ module MCP
     #     cursor = page.next_cursor
     #     break unless cursor
     #   end
-    def list_tools(cursor: nil)
+    def list_tools(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "tools/list", params: params)
+      response = request(method: "tools/list", params: params, meta: meta)
       result = response["result"] || {}
 
       tools = (result["tools"] || []).map do |tool|
@@ -146,31 +150,19 @@ module MCP
     #   end
     def tools
       # TODO: consider renaming to `list_all_tools`.
-      all_tools = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_tools(cursor: cursor)
-        all_tools.concat(page.tools)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_tools
+      fetch_all_pages { |cursor| list_tools(cursor: cursor) }.flat_map(&:tools)
     end
 
     # Returns a single page of resources from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListResourcesResult] Result with `resources` (Array<Hash>)
     #   and `next_cursor` (String or nil).
-    def list_resources(cursor: nil)
+    def list_resources(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "resources/list", params: params)
+      response = request(method: "resources/list", params: params, meta: meta)
       result = response["result"] || {}
 
       ListResourcesResult.new(
@@ -189,31 +181,19 @@ module MCP
     # @return [Array<Hash>] An array of available resources.
     def resources
       # TODO: consider renaming to `list_all_resources`.
-      all_resources = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_resources(cursor: cursor)
-        all_resources.concat(page.resources)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_resources
+      fetch_all_pages { |cursor| list_resources(cursor: cursor) }.flat_map(&:resources)
     end
 
     # Returns a single page of resource templates from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListResourceTemplatesResult] Result with `resource_templates`
     #   (Array<Hash>) and `next_cursor` (String or nil).
-    def list_resource_templates(cursor: nil)
+    def list_resource_templates(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "resources/templates/list", params: params)
+      response = request(method: "resources/templates/list", params: params, meta: meta)
       result = response["result"] || {}
 
       ListResourceTemplatesResult.new(
@@ -232,31 +212,19 @@ module MCP
     # @return [Array<Hash>] An array of available resource templates.
     def resource_templates
       # TODO: consider renaming to `list_all_resource_templates`.
-      all_templates = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_resource_templates(cursor: cursor)
-        all_templates.concat(page.resource_templates)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_templates
+      fetch_all_pages { |cursor| list_resource_templates(cursor: cursor) }.flat_map(&:resource_templates)
     end
 
     # Returns a single page of prompts from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListPromptsResult] Result with `prompts` (Array<Hash>)
     #   and `next_cursor` (String or nil).
-    def list_prompts(cursor: nil)
+    def list_prompts(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "prompts/list", params: params)
+      response = request(method: "prompts/list", params: params, meta: meta)
       result = response["result"] || {}
 
       ListPromptsResult.new(
@@ -275,21 +243,7 @@ module MCP
     # @return [Array<Hash>] An array of available prompts.
     def prompts
       # TODO: consider renaming to `list_all_prompts`.
-      all_prompts = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_prompts(cursor: cursor)
-        all_prompts.concat(page.prompts)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_prompts
+      fetch_all_pages { |cursor| list_prompts(cursor: cursor) }.flat_map(&:prompts)
     end
 
     # Calls a tool via the transport layer and returns the full response from the server.
@@ -298,6 +252,10 @@ module MCP
     # @param tool [MCP::Client::Tool] The tool to be called.
     # @param arguments [Object, nil] The arguments to pass to the tool.
     # @param progress_token [String, Integer, nil] A token to request progress notifications from the server during tool execution.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. the W3C Trace Context keys reserved by SEP-414
+    #   (`MCP::TraceContext::TRACEPARENT_META_KEY`, `tracestate`, `baggage`).
+    #   `progress_token` takes precedence over a `progressToken` entry in `meta`.
     # @return [Hash] The full JSON-RPC response from the transport.
     #
     # @example Call by name
@@ -312,14 +270,17 @@ module MCP
     # @note
     #   The exact requirements for `arguments` are determined by the transport layer in use.
     #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
-    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil)
+    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil, meta: nil)
       tool_name = name || tool&.name
       raise ArgumentError, "Either `name:` or `tool:` must be provided." unless tool_name
 
       params = { name: tool_name, arguments: arguments }
+      meta_entries = meta ? meta.dup : {}
       if progress_token
-        params[:_meta] = { progressToken: progress_token }
+        meta_entries.delete("progressToken")
+        meta_entries[:progressToken] = progress_token
       end
+      params[:_meta] = meta_entries unless meta_entries.empty?
 
       request(method: "tools/call", params: params)
     end
@@ -327,9 +288,11 @@ module MCP
     # Reads a resource from the server by URI and returns the contents.
     #
     # @param uri [String] The URI of the resource to read.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [Array<Hash>] An array of resource contents (text or blob).
-    def read_resource(uri:)
-      response = request(method: "resources/read", params: { uri: uri })
+    def read_resource(uri:, meta: nil)
+      response = request(method: "resources/read", params: { uri: uri }, meta: meta)
 
       response.dig("result", "contents") || []
     end
@@ -337,9 +300,11 @@ module MCP
     # Gets a prompt from the server by name and returns its details.
     #
     # @param name [String] The name of the prompt to get.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [Hash] A hash containing the prompt details.
-    def get_prompt(name:)
-      response = request(method: "prompts/get", params: { name: name })
+    def get_prompt(name:, meta: nil)
+      response = request(method: "prompts/get", params: { name: name }, meta: meta)
 
       response.fetch("result", {})
     end
@@ -350,12 +315,14 @@ module MCP
     #   or `{ type: "ref/resource", uri: "file:///{path}" }`.
     # @param argument [Hash] The argument being completed, e.g. `{ name: "language", value: "py" }`.
     # @param context [Hash, nil] Optional context with previously resolved arguments.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [Hash] The completion result with `"values"`, `"hasMore"`, and optionally `"total"`.
-    def complete(ref:, argument:, context: nil)
+    def complete(ref:, argument:, context: nil, meta: nil)
       params = { ref: ref, argument: argument }
       params[:context] = context if context
 
-      response = request(method: "completion/complete", params: params)
+      response = request(method: "completion/complete", params: params, meta: meta)
 
       response.dig("result", "completion") || { "values" => [], "hasMore" => false }
     end
@@ -371,8 +338,8 @@ module MCP
     #   client.ping # => {}
     #
     # @see https://modelcontextprotocol.io/specification/latest/basic/utilities/ping
-    def ping
-      result = request(method: Methods::PING)["result"]
+    def ping(meta: nil)
+      result = request(method: Methods::PING, meta: meta)["result"]
       raise ValidationError, "Response validation failed: missing or invalid `result`" unless result.is_a?(Hash)
 
       result
@@ -380,7 +347,34 @@ module MCP
 
     private
 
-    def request(method:, params: nil)
+    # Walks every page of a list endpoint, following `next_cursor`, and returns
+    # the page results. The `seen` set guards against a server that repeats or
+    # cycles cursors, so the loop always terminates.
+    def fetch_all_pages
+      pages = []
+      seen = Set.new
+      cursor = nil
+
+      loop do
+        page = yield(cursor)
+        pages << page
+        next_cursor = page.next_cursor
+        break if next_cursor.nil? || seen.include?(next_cursor)
+
+        seen << next_cursor
+        cursor = next_cursor
+      end
+
+      pages
+    end
+
+    # Merges caller-supplied `meta` entries into the request params as `_meta`,
+    # without mutating the caller's hashes. Per SEP-414, `_meta` carries
+    # request-specific metadata such as W3C trace context (`traceparent`,
+    # `tracestate`, `baggage`); see {MCP::TraceContext}.
+    def request(method:, params: nil, meta: nil)
+      params = (params || {}).merge(_meta: meta) if meta && !meta.empty?
+
       request_body = {
         jsonrpc: JsonRpcHandler::Version::V2_0,
         id: request_id,

data/lib/mcp/configuration.rb

@@ -6,6 +6,7 @@ module MCP
     SUPPORTED_STABLE_PROTOCOL_VERSIONS = [
       LATEST_STABLE_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05",
     ]
+    DEFAULT_NEGOTIATED_PROTOCOL_VERSION = "2025-03-26"
 
     attr_writer :exception_reporter, :around_request
 

data/lib/mcp/resource.rb

@@ -5,15 +5,17 @@ require_relative "resource/embedded"
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :meta
+    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :annotations, :size, :meta
 
-    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
+    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, size: nil, meta: nil)
       @uri = uri
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @annotations = annotations
+      @size = size
       @meta = meta
     end
 
@@ -25,6 +27,8 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        annotations: annotations&.to_h,
+        size: size,
         _meta: meta,
       }.compact
     end

data/lib/mcp/resource_template.rb

@@ -2,15 +2,16 @@
 
 module MCP
   class ResourceTemplate
-    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :meta
+    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :annotations, :meta
 
-    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
+    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, meta: nil)
       @uri_template = uri_template
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @annotations = annotations
       @meta = meta
     end
 
@@ -22,6 +23,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        annotations: annotations&.to_h,
         _meta: meta,
       }.compact
     end

data/lib/mcp/server/capabilities.rb

@@ -6,6 +6,7 @@ module MCP
       def initialize(capabilities_hash = nil)
         @completions = nil
         @experimental = nil
+        @extensions = nil
         @logging = nil
         @prompts = nil
         @resources = nil
@@ -14,6 +15,7 @@ module MCP
         if capabilities_hash
           support_completions if capabilities_hash.key?(:completions)
           support_experimental(capabilities_hash[:experimental]) if capabilities_hash.key?(:experimental)
+          support_extensions(capabilities_hash[:extensions]) if capabilities_hash.key?(:extensions)
           support_logging if capabilities_hash.key?(:logging)
 
           if capabilities_hash.key?(:prompts)
@@ -45,6 +47,17 @@ module MCP
         @experimental = config || {}
       end
 
+      # Declares support for capability extensions per SEP-2133. Keys are
+      # extension identifiers using the reverse-DNS prefix convention
+      # (e.g. `"io.modelcontextprotocol/tasks"`, `"com.example/feature"`);
+      # values are arbitrary extension-defined configuration objects,
+      # with an empty hash meaning "supported with no settings".
+      # Repeated calls merge, so several extensions can be declared independently.
+      # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133
+      def support_extensions(extensions = {})
+        @extensions = (@extensions || {}).merge(extensions || {})
+      end
+
       def support_logging
         @logging ||= {}
       end
@@ -85,6 +98,7 @@ module MCP
         {
           completions: @completions,
           experimental: @experimental,
+          extensions: @extensions,
           logging: @logging,
           prompts: @prompts,
           resources: @resources,

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

@@ -85,8 +85,10 @@ module MCP
         end
 
         def send_notification(method, params = nil, session_id: nil, related_request_id: nil)
-          # Stateless mode doesn't support notifications
-          raise "Stateless mode does not support notifications" if @stateless
+          # Stateless mode has no streams to deliver notifications on. Report non-delivery instead of raising
+          # so the ephemeral per-request session's notify_* helpers (e.g. progress or log notifications from
+          # a tool handler) degrade gracefully rather than spamming the exception reporter on every call.
+          return false if @stateless
 
           notification = {
             jsonrpc: "2.0",
@@ -389,7 +391,11 @@ module MCP
           end
         rescue StandardError => e
           MCP.configuration.exception_reporter.call(e, { request: body_string })
-          [500, { "Content-Type" => "application/json" }, [{ error: "Internal server error" }.to_json]]
+          json_rpc_error_response(
+            status: 500,
+            code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+            message: "Internal server error",
+          )
         end
 
         def handle_get(request)
@@ -513,19 +519,19 @@ module MCP
           media_type = content_type&.split(";")&.first&.strip&.downcase
           return if media_type == "application/json"
 
-          [
-            415,
-            { "Content-Type" => "application/json" },
-            [{ error: "Unsupported Media Type: Content-Type must be application/json" }.to_json],
-          ]
+          json_rpc_error_response(
+            status: 415,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Unsupported Media Type: Content-Type must be application/json",
+          )
         end
 
         def not_acceptable_response(required_types)
-          [
-            406,
-            { "Content-Type" => "application/json" },
-            [{ error: "Not Acceptable: Accept header must include #{required_types.join(" and ")}" }.to_json],
-          ]
+          json_rpc_error_response(
+            status: 406,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Not Acceptable: Accept header must include #{required_types.join(" and ")}",
+          )
         end
 
         def parse_request_body(body_string)
@@ -535,7 +541,11 @@ module MCP
         end
 
         def invalid_json_response
-          [400, { "Content-Type" => "application/json" }, [{ error: "Invalid JSON" }.to_json]]
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::PARSE_ERROR,
+            message: "Parse error: Invalid JSON",
+          )
         end
 
         def initialize_request?(body)
@@ -543,20 +553,20 @@ module MCP
         end
 
         def validate_protocol_version_header(request)
-          header_value = request.env["HTTP_MCP_PROTOCOL_VERSION"]
-          return if header_value.nil?
+          header_value = request.env["HTTP_MCP_PROTOCOL_VERSION"] || MCP::Configuration::DEFAULT_NEGOTIATED_PROTOCOL_VERSION
           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]]
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Bad Request: Unsupported protocol version: #{header_value}. Supported versions: #{supported}",
+          )
+        end
+
+        def json_rpc_error_response(status:, code:, message:)
+          body = { jsonrpc: "2.0", id: nil, error: { code: code, message: message } }
+          [status, { "Content-Type" => "application/json" }, [body.to_json]]
         end
 
         def notification?(body)
@@ -567,7 +577,9 @@ module MCP
         # `notifications/initialized`) through the server so it can update session state.
         def dispatch_notification(body_string, session_id)
           server_session = nil
-          if session_id && !@stateless
+          if @stateless
+            server_session = ephemeral_session
+          elsif session_id
             @mutex.synchronize do
               session = @sessions[session_id]
               server_session = session[:server_session] if session
@@ -603,9 +615,10 @@ module MCP
 
         def handle_initialization(body_string, body)
           session_id = nil
-          server_session = nil
 
-          unless @stateless
+          if @stateless
+            server_session = ephemeral_session
+          else
             session_id = SecureRandom.uuid
             server_session = ServerSession.new(server: @server, transport: self, session_id: session_id)
 
@@ -618,17 +631,13 @@ module MCP
             end
           end
 
-          response = if server_session
-            server_session.handle_json(body_string)
-          else
-            @server.handle_json(body_string)
-          end
+          response = server_session.handle_json(body_string)
 
           # 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?
+          if session_id && !server_session.initialized?
             cleanup_session(session_id)
             session_id = nil
           end
@@ -649,15 +658,15 @@ module MCP
         def handle_regular_request(body_string, session_id, related_request_id: nil)
           server_session = nil
 
-          unless @stateless
-            if session_id
-              error_response = validate_and_touch_session(session_id)
-              return error_response if error_response
+          if @stateless
+            server_session = ephemeral_session
+          elsif session_id
+            error_response = validate_and_touch_session(session_id)
+            return error_response if error_response
 
-              @mutex.synchronize do
-                session = @sessions[session_id]
-                server_session = session[:server_session] if session
-              end
+            @mutex.synchronize do
+              session = @sessions[session_id]
+              server_session = session[:server_session] if session
             end
           end
 
@@ -767,6 +776,13 @@ module MCP
           @mutex.synchronize { @sessions.key?(session_id) }
         end
 
+        # Each stateless POST is self-contained (SEP-2567): handlers run against an ephemeral per-request `ServerSession`
+        # so client info, logging level, and initialized state never leak onto the shared `Server` instance or across concurrent requests.
+        # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567
+        def ephemeral_session
+          ServerSession.new(server: @server, transport: self, session_id: nil)
+        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
@@ -793,15 +809,27 @@ module MCP
         end
 
         def method_not_allowed_response
-          [405, { "Content-Type" => "application/json" }, [{ error: "Method not allowed" }.to_json]]
+          json_rpc_error_response(
+            status: 405,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Method not allowed",
+          )
         end
 
         def missing_session_id_response
-          [400, { "Content-Type" => "application/json" }, [{ error: "Missing session ID" }.to_json]]
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Missing session ID",
+          )
         end
 
         def session_not_found_response
-          [404, { "Content-Type" => "application/json" }, [{ error: "Session not found" }.to_json]]
+          json_rpc_error_response(
+            status: 404,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Session not found",
+          )
         end
 
         def already_initialized_response(request_id)
@@ -821,11 +849,11 @@ module MCP
         end
 
         def session_already_connected_response
-          [
-            409,
-            { "Content-Type" => "application/json" },
-            [{ error: "Conflict: Only one SSE stream is allowed per session" }.to_json],
-          ]
+          json_rpc_error_response(
+            status: 409,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Conflict: Only one SSE stream is allowed per session",
+          )
         end
 
         def setup_sse_stream(session_id)