mcp 0.23.0 → 0.25.0

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

@@ -19,9 +19,9 @@ module MCP
         class InvalidJsonError < StandardError; end
 
         SSE_HEADERS = {
-          "Content-Type" => "text/event-stream",
-          "Cache-Control" => "no-cache",
-          "Connection" => "keep-alive",
+          "content-type" => "text/event-stream",
+          "cache-control" => "no-cache",
+          "connection" => "keep-alive",
         }.freeze
 
         # Secure defaults for stateful mode. Without a finite idle timeout, sessions live until an explicit client DELETE,
@@ -196,80 +196,107 @@ module MCP
           }
           notification[:params] = params if params
 
+          if session_id
+            deliver_targeted_notification(notification, session_id, related_request_id)
+          else
+            deliver_broadcast_notification(notification)
+          end
+        end
+
+        def deliver_targeted_notification(notification, session_id, related_request_id)
+          # JSON response mode returns a single JSON object as the POST response,
+          # so request-scoped notifications (e.g. progress, log) cannot be delivered
+          # alongside it. Session-scoped standalone notifications
+          # (e.g. `resources/updated`, `elicitation/complete`) still flow via GET SSE.
+          return false if @enable_json_response && related_request_id
+
           streams_to_close = []
 
-          result = @mutex.synchronize do
-            if session_id
-              # JSON response mode returns a single JSON object as the POST response,
-              # so request-scoped notifications (e.g. progress, log) cannot be delivered
-              # alongside it. Session-scoped standalone notifications
-              # (e.g. `resources/updated`, `elicitation/complete`) still flow via GET SSE.
-              next false if @enable_json_response && related_request_id
-
-              # Send to specific session
-              if (session = @sessions[session_id])
-                stream = active_stream(session, related_request_id: related_request_id)
-              end
-              next false unless stream
+          # Resolve the target stream under the lock, then write outside it: a stalled SSE reader
+          # must not block every other session that needs `@mutex`.
+          stream = @mutex.synchronize do
+            next unless (session = @sessions[session_id])
+
+            if session_expired?(session)
+              cleanup_and_collect_stream(session_id, streams_to_close)
+              next
+            end
+
+            active_stream(session, related_request_id: related_request_id)
+          end
+
+          close_streams(streams_to_close)
+          return false unless stream
+
+          write_notification(stream, notification, session_id, related_request_id)
+        end
+
+        def deliver_broadcast_notification(notification)
+          streams_to_close = []
+
+          # Snapshot the connected streams under the lock, then write to each outside it.
+          targets = @mutex.synchronize do
+            expired_session_ids = []
+
+            collected = @sessions.filter_map do |session_id, session|
+              next unless (stream = session[:get_sse_stream])
 
               if session_expired?(session)
-                cleanup_and_collect_stream(session_id, streams_to_close)
-                next false
+                expired_session_ids << session_id
+                next
               end
 
-              begin
-                send_to_stream(stream, notification)
-                true
-              rescue *STREAM_WRITE_ERRORS => e
-                MCP.configuration.exception_reporter.call(
-                  e,
-                  { session_id: session_id, error: "Failed to send notification" },
-                )
-                if related_request_id && session[:post_request_streams]&.key?(related_request_id)
-                  session[:post_request_streams].delete(related_request_id)
-                  streams_to_close << stream
-                else
-                  cleanup_and_collect_stream(session_id, streams_to_close)
-                end
-                false
-              end
-            else
-              # Broadcast to all connected SSE sessions
-              sent_count = 0
-              failed_sessions = []
+              [session_id, stream]
+            end
 
-              @sessions.each do |sid, session|
-                next unless (stream = session[:get_sse_stream])
+            expired_session_ids.each do |session_id|
+              cleanup_and_collect_stream(session_id, streams_to_close)
+            end
 
-                if session_expired?(session)
-                  failed_sessions << sid
-                  next
-                end
+            collected
+          end
 
-                begin
-                  send_to_stream(stream, notification)
-                  sent_count += 1
-                rescue *STREAM_WRITE_ERRORS => e
-                  MCP.configuration.exception_reporter.call(
-                    e,
-                    { session_id: sid, error: "Failed to send notification" },
-                  )
-                  failed_sessions << sid
-                end
-              end
+          close_streams(streams_to_close)
 
-              # Clean up failed sessions
-              failed_sessions.each { |sid| cleanup_and_collect_stream(sid, streams_to_close) }
+          targets.count do |session_id, stream|
+            write_notification(stream, notification, session_id, nil)
+          end
+        end
 
-              sent_count
+        # Writes a notification to an SSE stream without holding `@mutex`. On a write error,
+        # drops the broken stream and returns false; on success returns true.
+        def write_notification(stream, notification, session_id, related_request_id)
+          send_to_stream(stream, notification)
+          true
+        rescue *STREAM_WRITE_ERRORS => e
+          MCP.configuration.exception_reporter.call(e, { session_id: session_id, error: "Failed to send notification" })
+          drop_broken_stream(session_id, stream, related_request_id)
+          false
+        end
+
+        # Removes a stream that failed to accept a write. A request-scoped stream is dropped on its own;
+        # a session-scoped (GET SSE) failure tears down the whole session. The `@sessions` mutation runs
+        # under `@mutex`, and the affected streams are closed outside it.
+        def drop_broken_stream(session_id, stream, related_request_id)
+          streams_to_close = []
+
+          @mutex.synchronize do
+            session = @sessions[session_id]
+            if related_request_id && session&.dig(:post_request_streams, related_request_id)
+              session[:post_request_streams].delete(related_request_id)
+              streams_to_close << stream
+            else
+              cleanup_and_collect_stream(session_id, streams_to_close)
             end
           end
 
-          streams_to_close.each do |stream|
+          close_streams(streams_to_close)
+        end
+
+        def close_streams(streams)
+          streams.each do |stream|
             close_stream_safely(stream)
           end
-
-          result
         end
 
         # Sends a server-to-client JSON-RPC request (e.g., `sampling/createMessage`) and
@@ -299,27 +326,25 @@ module MCP
           request = { jsonrpc: "2.0", id: request_id, method: method }
           request[:params] = params if params
 
-          sent = false
-
-          @mutex.synchronize do
+          # Register the pending response and resolve the stream under the lock, but perform
+          # the write outside it so a stalled reader cannot block every other session on `@mutex`.
+          stream = @mutex.synchronize do
             unless (session = @sessions[session_id])
               raise "Session not found: #{session_id}."
             end
 
             @pending_responses[request_id] = { queue: queue, session_id: session_id }
 
-            if (stream = active_stream(session, related_request_id: related_request_id))
-              begin
-                send_to_stream(stream, request)
-                sent = true
-              rescue *STREAM_WRITE_ERRORS
-                if related_request_id && session[:post_request_streams]&.key?(related_request_id)
-                  session[:post_request_streams].delete(related_request_id)
-                  close_stream_safely(stream)
-                else
-                  cleanup_session_unsafe(session_id)
-                end
-              end
+            active_stream(session, related_request_id: related_request_id)
+          end
+
+          sent = false
+          if stream
+            begin
+              send_to_stream(stream, request)
+              sent = true
+            rescue *STREAM_WRITE_ERRORS
+              drop_broken_stream(session_id, stream, related_request_id)
             end
           end
 
@@ -461,7 +486,9 @@ module MCP
           # 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)
+          # `server/discover` (SEP-2575) is likewise exempt: it is sessionless capability discovery that
+          # happens before (or instead of) negotiation.
+          unless initialize_request?(body) || discover_request?(body)
             return missing_session_id_response if !@stateless && !session_id
 
             protocol_version_error = validate_protocol_version_header(request)
@@ -490,6 +517,11 @@ module MCP
             end
 
             if notification?(body)
+              # Reject a notification carrying an unknown or expired session ID instead of
+              # dispatching it against the shared `Server`. Mirrors the response and regular-request
+              # branches; without it a custom notification handler could run without a live session.
+              return session_not_found_response if !@stateless && !session_active?(session_id)
+
               dispatch_notification(body_string, session_id)
               handle_accepted
             elsif response?(body)
@@ -534,7 +566,7 @@ module MCP
         end
 
         def handle_delete(request)
-          success_response = [200, { "Content-Type" => "application/json" }, [{ success: true }.to_json]]
+          success_response = [200, { "content-type" => "application/json" }, [{ success: true }.to_json]]
 
           if @stateless
             protocol_version_error = validate_protocol_version_header(request)
@@ -712,6 +744,10 @@ module MCP
           body.is_a?(Hash) && body[:method] == Methods::INITIALIZE
         end
 
+        def discover_request?(body)
+          body.is_a?(Hash) && body[:method] == Methods::SERVER_DISCOVER
+        end
+
         def validate_protocol_version_header(request)
           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)
@@ -726,7 +762,7 @@ module MCP
 
         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]]
+          [status, { "content-type" => "application/json" }, [body.to_json]]
         end
 
         def notification?(body)
@@ -813,6 +849,17 @@ module MCP
 
           response = server_session.handle_json(body_string)
 
+          # `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
+          # and ack with 202, mirroring the nil-response handling in a regular request.
+          if response.nil?
+            cleanup_session(session_id) if session_id
+            return handle_accepted
+          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
@@ -823,10 +870,10 @@ module MCP
           end
 
           headers = {
-            "Content-Type" => "application/json",
+            "content-type" => "application/json",
           }
 
-          headers["Mcp-Session-Id"] = session_id if session_id
+          headers["mcp-session-id"] = session_id if session_id
 
           [200, headers, [response]]
         end
@@ -868,7 +915,7 @@ module MCP
             # which would produce an empty body the client cannot parse as JSON.
             return handle_accepted if response.nil?
 
-            [200, { "Content-Type" => "application/json" }, [response]]
+            [200, { "content-type" => "application/json" }, [response]]
           end
         end
 
@@ -1101,7 +1148,7 @@ module MCP
               message: message,
             },
           }
-          [400, { "Content-Type" => "application/json" }, [body.to_json]]
+          [400, { "content-type" => "application/json" }, [body.to_json]]
         end
 
         def session_already_connected_response
@@ -1158,11 +1205,15 @@ module MCP
         end
 
         def send_keepalive_ping(session_id)
-          @mutex.synchronize do
-            if @sessions[session_id] && @sessions[session_id][:get_sse_stream]
-              send_ping_to_stream(@sessions[session_id][:get_sse_stream])
-            end
+          # Resolve the stream under the lock, then write outside it so a stalled reader
+          # cannot block every other session on `@mutex`.
+          stream = @mutex.synchronize do
+            session = @sessions[session_id]
+            session && session[:get_sse_stream]
           end
+          return unless stream
+
+          send_ping_to_stream(stream)
         rescue *STREAM_WRITE_ERRORS => e
           MCP.configuration.exception_reporter.call(
             e,

data/lib/mcp/server.rb

@@ -102,8 +102,11 @@ module MCP
     include Instrumentation
     include Pagination
 
-    attr_accessor :description, :icons, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport, :logging_message_notification
-    attr_reader :page_size, :client_capabilities
+    # Allowed values for the SEP-2549 `cacheScope` cache hint.
+    CACHE_SCOPES = ["public", "private"].freeze
+
+    attr_accessor :description, :icons, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resource_templates, :server_context, :configuration, :capabilities, :transport, :logging_message_notification
+    attr_reader :resources, :page_size, :client_capabilities, :ttl_ms, :cache_scope
 
     def initialize(
       description: nil,
@@ -121,6 +124,8 @@ module MCP
       configuration: nil,
       capabilities: nil,
       page_size: nil,
+      ttl_ms: nil,
+      cache_scope: nil,
       transport: nil
     )
       @description = description
@@ -138,6 +143,8 @@ module MCP
       @resource_index = index_resources_by_uri(resources)
       @server_context = server_context
       self.page_size = page_size
+      self.ttl_ms = ttl_ms
+      self.cache_scope = cache_scope
       @configuration = MCP.configuration.merge(configuration)
       @client = nil
 
@@ -154,7 +161,7 @@ module MCP
 
       @handlers = {
         Methods::RESOURCES_LIST => method(:list_resources),
-        Methods::RESOURCES_READ => method(:read_resource_no_content),
+        Methods::RESOURCES_READ => method(:read_resource),
         Methods::RESOURCES_TEMPLATES_LIST => method(:list_resource_templates),
         Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
         Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
@@ -163,6 +170,7 @@ module MCP
         Methods::PROMPTS_LIST => method(:list_prompts),
         Methods::PROMPTS_GET => method(:get_prompt),
         Methods::INITIALIZE => method(:init),
+        Methods::SERVER_DISCOVER => method(:discover),
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
         Methods::NOTIFICATIONS_PROGRESS => ->(_) {},
@@ -216,6 +224,34 @@ module MCP
       validate!
     end
 
+    def define_resource(uri: nil, name: nil, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, size: nil, meta: nil, &block)
+      resource = Resource.define(
+        uri: uri, name: name, title: title, description: description, icons: icons,
+        mime_type: mime_type, annotations: annotations, size: size, meta: meta,
+        &block
+      )
+      @resources << resource
+      @resource_index[resource.uri] = resource
+
+      validate!
+    end
+
+    def define_resource_template(uri_template: nil, name: nil, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, meta: nil, &block)
+      resource_template = ResourceTemplate.define(
+        uri_template: uri_template, name: name, title: title, description: description, icons: icons,
+        mime_type: mime_type, annotations: annotations, meta: meta,
+        &block
+      )
+      @resource_templates << resource_template
+
+      validate!
+    end
+
+    def resources=(resources)
+      @resources = resources
+      @resource_index = index_resources_by_uri(resources)
+    end
+
     def define_custom_method(method_name:, &block)
       if @handlers.key?(method_name)
         raise MethodAlreadyDefinedError, method_name
@@ -232,6 +268,27 @@ module MCP
       @page_size = page_size
     end
 
+    # SEP-2549 cache hint: freshness lifetime in milliseconds for list and read results
+    # (max-age semantics; 0 means do not cache). Emission is opt-in: when both `ttl_ms`
+    # and `cache_scope` are nil, results are serialized exactly as before.
+    def ttl_ms=(ttl_ms)
+      unless ttl_ms.nil? || (ttl_ms.is_a?(Integer) && ttl_ms >= 0)
+        raise ArgumentError, "ttl_ms must be nil or a non-negative integer"
+      end
+
+      @ttl_ms = ttl_ms
+    end
+
+    # SEP-2549 cache hint: whether shared intermediaries may cache the result ("public")
+    # or only the requesting client ("private").
+    def cache_scope=(cache_scope)
+      unless cache_scope.nil? || CACHE_SCOPES.include?(cache_scope)
+        raise ArgumentError, "cache_scope must be nil, \"public\", or \"private\""
+      end
+
+      @cache_scope = cache_scope
+    end
+
     def notify_tools_list_changed
       return unless @transport
 
@@ -472,8 +529,9 @@ module MCP
           when Methods::INITIALIZE
             init(params, session: session)
           when Methods::RESOURCES_READ
-            { contents: read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation) }
+            build_read_resource_result(read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation))
           when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
+            validate_resource_subscription_params!(params)
             dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation)
             {}
           when Methods::TOOLS_CALL
@@ -548,6 +606,8 @@ module MCP
     end
 
     def init(params, session: nil)
+      validate_initialize_params!(params)
+
       # 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.
@@ -555,15 +615,13 @@ module MCP
         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])
-        else
-          @client = params[:clientInfo]
-          @client_capabilities = params[:capabilities]
-        end
-        protocol_version = params[:protocolVersion]
+      if session
+        session.store_client_info(client: params[:clientInfo], capabilities: params[:capabilities])
+      else
+        @client = params[:clientInfo]
+        @client_capabilities = params[:capabilities]
       end
+      protocol_version = params[:protocolVersion]
 
       negotiated_version = if Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(protocol_version)
         protocol_version
@@ -592,6 +650,47 @@ module MCP
       }.compact
     end
 
+    def validate_resource_subscription_params!(params)
+      unless params.is_a?(Hash) && params[:uri].is_a?(String)
+        raise RequestHandlerError.new("Missing or invalid uri", params, error_type: :invalid_params)
+      end
+    end
+
+    def validate_initialize_params!(params)
+      unless params.is_a?(Hash)
+        raise RequestHandlerError.new("Invalid params", params, error_type: :invalid_params)
+      end
+
+      unless params[:protocolVersion].is_a?(String)
+        raise RequestHandlerError.new("Missing or invalid protocolVersion", params, error_type: :invalid_params)
+      end
+
+      unless params[:capabilities].is_a?(Hash)
+        raise RequestHandlerError.new("Missing or invalid capabilities", params, error_type: :invalid_params)
+      end
+
+      client_info = params[:clientInfo]
+      if !client_info.is_a?(Hash) || client_info[:name].nil? || client_info[:version].nil?
+        raise RequestHandlerError.new("Missing or invalid clientInfo", params, error_type: :invalid_params)
+      end
+    end
+
+    # Handles `server/discover` (MCP 2026-07-28 draft, SEP-2575): sessionless capability discovery.
+    # Unlike `init`, this is state-free and idempotent: it stores no client info, does not mark
+    # the session initialized, and responds regardless of capability declarations or initialization state,
+    # so clients can probe a server before (or instead of) `initialize`. `serverInfo` is returned unfiltered
+    # because discovery happens before version negotiation. The draft's `ttlMs`/`cacheScope` cache hints
+    # are not included here yet.
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+    def discover(_request)
+      {
+        supportedVersions: Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS,
+        capabilities: capabilities,
+        serverInfo: server_info,
+        instructions: instructions,
+      }.compact
+    end
+
     def configure_logging_level(request, session: nil)
       if capabilities[:logging].nil?
         raise RequestHandlerError.new("Server does not support logging", request, error_type: :internal_error)
@@ -611,7 +710,7 @@ module MCP
     def list_tools(request)
       page = paginate(@tools.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
 
-      { tools: page[:items], nextCursor: page[:next_cursor] }.compact
+      apply_cache_metadata({ tools: page[:items], nextCursor: page[:next_cursor] }.compact)
     end
 
     def call_tool(request, session: nil, related_request_id: nil, cancellation: nil)
@@ -667,7 +766,7 @@ module MCP
     def list_prompts(request)
       page = paginate(@prompts.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
 
-      { prompts: page[:items], nextCursor: page[:next_cursor] }.compact
+      apply_cache_metadata({ prompts: page[:items], nextCursor: page[:next_cursor] }.compact)
     end
 
     def get_prompt(request, session: nil, related_request_id: nil, cancellation: nil)
@@ -696,19 +795,91 @@ module MCP
     def list_resources(request)
       page = paginate(@resources, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
 
-      { resources: page[:items], nextCursor: page[:next_cursor] }.compact
+      apply_cache_metadata({ resources: page[:items], nextCursor: page[:next_cursor] }.compact)
     end
 
-    # Server implementation should set `resources_read_handler` to override no-op default
-    def read_resource_no_content(request)
-      add_instrumentation_data(resource_uri: request[:uri])
-      []
+    # Default `resources/read` handler: routes to class-based resources and resource templates.
+    # Fully replaced when `resources_read_handler` is set. When no class-based resource or template is registered,
+    # unknown URIs keep the historical no-op `[]` response instead of raising.
+    def read_resource(request, server_context: nil)
+      uri = request[:uri]
+      add_instrumentation_data(resource_uri: uri)
+
+      resource = @resource_index[uri]
+      if resource.is_a?(Class)
+        return normalize_resource_contents(call_resource_contents(resource, server_context))
+      end
+
+      @resource_templates.each do |template|
+        next unless template.is_a?(Class)
+
+        params = template.match_uri(uri)
+        next unless params
+
+        add_instrumentation_data(resource_template: template.uri_template)
+        return normalize_resource_contents(call_template_contents(template, params, server_context))
+      end
+
+      return [] unless class_based_resources_registered?
+
+      raise ResourceNotFoundError.new(uri, request)
+    end
+
+    def call_resource_contents(resource, server_context)
+      if accepts_server_context?(resource.method(:contents))
+        resource.contents(server_context: server_context)
+      else
+        resource.contents
+      end
+    end
+
+    def call_template_contents(template, params, server_context)
+      if accepts_server_context?(template.method(:contents))
+        template.contents(**params, server_context: server_context)
+      else
+        template.contents(**params)
+      end
+    end
+
+    def normalize_resource_contents(result)
+      contents = result.is_a?(Array) ? result : [result]
+      contents.map(&:to_h)
+    end
+
+    def class_based_resources_registered?
+      @resources.any? { |resource| resource.is_a?(Class) } ||
+        @resource_templates.any? { |template| template.is_a?(Class) }
     end
 
     def list_resource_templates(request)
       page = paginate(@resource_templates, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
 
-      { resourceTemplates: page[:items], nextCursor: page[:next_cursor] }.compact
+      apply_cache_metadata({ resourceTemplates: page[:items], nextCursor: page[:next_cursor] }.compact)
+    end
+
+    # Builds the `resources/read` result. The documented handler contract is "return value becomes `contents`";
+    # a Hash with a `:contents` key is also accepted as a full result so a handler can override the server-level
+    # `ttlMs`/`cacheScope` cache hints per result (SEP-2549).
+    def build_read_resource_result(handler_result)
+      result = if handler_result.is_a?(Hash) && handler_result.key?(:contents)
+        handler_result
+      else
+        { contents: handler_result }
+      end
+
+      apply_cache_metadata(result)
+    end
+
+    # Adds the SEP-2549 cache hints (`ttlMs`, `cacheScope`) to a result. Emission is opt-in: nothing is added
+    # unless the server was configured with `ttl_ms`/`cache_scope` or the result already carries one of the fields, in
+    # which case the missing one is filled with the spec defaults (`ttlMs: 0` = do not cache, `cacheScope: "public"`).
+    # Values already in the result win, enabling per-result overrides.
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549
+    def apply_cache_metadata(result)
+      explicit = result.key?(:ttlMs) || result.key?(:cacheScope)
+      return result if @ttl_ms.nil? && @cache_scope.nil? && !explicit
+
+      { ttlMs: @ttl_ms || 0, cacheScope: @cache_scope || "public" }.merge(result)
     end
 
     def complete(params, session: nil, related_request_id: nil, cancellation: nil)
@@ -792,9 +963,7 @@ module MCP
     end
 
     def index_resources_by_uri(resources)
-      resources.each_with_object({}) do |resource, hash|
-        hash[resource.uri] = resource
-      end
+      resources.to_h { |resource| [resource.uri, resource] }
     end
 
     def error_tool_response(text)