mcp 0.23.0 → 0.24.0

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
+
+    # 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
 
-    # 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])
-      []
+    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)

data/lib/mcp/server_context.rb

@@ -54,6 +54,9 @@ module MCP
     end
 
     # Delegates to the session so the request is scoped to the originating client.
+    # The originating request id is stamped as `related_request_id`, satisfying
+    # SEP-2260's requirement that server-to-client requests be associated with
+    # the client request being processed.
     # @deprecated MCP Roots (`roots/list` and
     #   `notifications/roots/list_changed`) is deprecated as of MCP protocol
     #   version 2026-07-28 (SEP-2577). Use tool parameters, resource URIs,
@@ -91,6 +94,11 @@ module MCP
     # Delegates to the session so the request is scoped to the originating client.
     # Falls back to `@context` (via `method_missing`) when `@notification_target`
     # does not support sampling.
+    #
+    # The originating request id is stamped as `related_request_id` and cannot be
+    # overridden by callers (the literal keyword after `**kwargs` wins),
+    # satisfying SEP-2260's requirement that server-to-client requests be
+    # associated with the client request being processed.
     # @deprecated MCP Sampling (`sampling/createMessage`) is deprecated as of
     #   MCP protocol version 2026-07-28 (SEP-2577). Use direct LLM provider
     #   APIs instead.
@@ -107,6 +115,8 @@ module MCP
     # Delegates to the session so the request is scoped to the originating client.
     # Falls back to `@context` (via `method_missing`) when `@notification_target`
     # does not support elicitation.
+    # The originating request id is stamped as a non-overridable
+    # `related_request_id`, as with `create_sampling_message` (SEP-2260).
     def create_form_elicitation(**kwargs)
       if @notification_target.respond_to?(:create_form_elicitation)
         @notification_target.create_form_elicitation(**kwargs, related_request_id: @related_request_id)
@@ -119,6 +129,8 @@ module MCP
 
     # Delegates to the session so the request is scoped to the originating client.
     # Falls back to `@context` when `@notification_target` does not support URL mode elicitation.
+    # The originating request id is stamped as a non-overridable `related_request_id`,
+    # as with `create_sampling_message` (SEP-2260).
     def create_url_elicitation(**kwargs)
       if @notification_target.respond_to?(:create_url_elicitation)
         @notification_target.create_url_elicitation(**kwargs, related_request_id: @related_request_id)

data/lib/mcp/server_session.rb

@@ -98,11 +98,17 @@ module MCP
     end
 
     # Sends a `roots/list` request scoped to this session.
+    #
+    # Per SEP-2260, the request must be associated with an originating client
+    # request; prefer `server_context.list_roots` inside a handler, which stamps
+    # the association automatically.
     # @deprecated MCP Roots (`roots/list` and
     #   `notifications/roots/list_changed`) is deprecated as of MCP protocol
     #   version 2026-07-28 (SEP-2577). Use tool parameters, resource URIs,
     #   server configuration, or environment variables instead.
     def list_roots(related_request_id: nil)
+      warn_unassociated_request(__method__, related_request_id)
+
       unless client_capabilities&.dig(:roots)
         raise "Client does not support roots."
       end
@@ -119,16 +125,28 @@ module MCP
     end
 
     # Sends a `sampling/createMessage` request scoped to this session.
+    #
+    # Per SEP-2260, the request must be associated with an originating client
+    # request; prefer `server_context.create_sampling_message` inside a handler,
+    # which stamps the association automatically.
     # @deprecated MCP Sampling (`sampling/createMessage`) is deprecated as of
     #   MCP protocol version 2026-07-28 (SEP-2577). Use direct LLM provider
     #   APIs instead.
     def create_sampling_message(related_request_id: nil, **kwargs)
+      warn_unassociated_request(__method__, related_request_id)
+
       params = @server.build_sampling_params(client_capabilities, **kwargs)
       send_to_transport_request(Methods::SAMPLING_CREATE_MESSAGE, params, related_request_id: related_request_id)
     end
 
     # Sends an `elicitation/create` request (form mode) scoped to this session.
+    #
+    # Per SEP-2260, the request must be associated with an originating client
+    # request; prefer `server_context.create_form_elicitation` inside a handler,
+    # which stamps the association automatically.
     def create_form_elicitation(message:, requested_schema:, related_request_id: nil)
+      warn_unassociated_request(__method__, related_request_id)
+
       unless client_capabilities&.dig(:elicitation)
         raise "Client does not support elicitation. " \
           "The client must declare the `elicitation` capability during initialization."
@@ -139,7 +157,13 @@ module MCP
     end
 
     # Sends an `elicitation/create` request (URL mode) scoped to this session.
+    #
+    # Per SEP-2260, the request must be associated with an originating client
+    # request; prefer `server_context.create_url_elicitation` inside a handler,
+    # which stamps the association automatically.
     def create_url_elicitation(message:, url:, elicitation_id:, related_request_id: nil)
+      warn_unassociated_request(__method__, related_request_id)
+
       unless client_capabilities&.dig(:elicitation, :url)
         raise "Client does not support URL mode elicitation. " \
           "The client must declare the `elicitation.url` capability during initialization."
@@ -264,5 +288,21 @@ module MCP
       # The explicit splat suppresses that conversion and is a no-op when `supported` is empty.
       transport_method.call(method, params, **supported)
     end
+
+    # Per SEP-2260, servers MUST send `roots/list`, `sampling/createMessage`, and `elicitation/create` only
+    # in association with an originating client request (`ping` is exempt). A request without `related_request_id:` is
+    # delivered on the standalone GET stream by the Streamable HTTP transport, which the 2026-07-28 spec forbids;
+    # warn so callers migrate to the `server_context` helpers before this becomes an error.
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2260
+    def warn_unassociated_request(method_name, related_request_id)
+      return if related_request_id
+
+      warn(
+        "Calling `ServerSession##{method_name}` without `related_request_id:` is deprecated (SEP-2260): " \
+          "server-to-client #{method_name} requests must be associated with an originating client request. " \
+          "Use `server_context.#{method_name}` inside a handler, or pass `related_request_id:` explicitly.",
+        uplevel: 2,
+      )
+    end
   end
 end

data/lib/mcp/version.rb

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

data/lib/mcp.rb

@@ -8,14 +8,17 @@ require_relative "mcp/version"
 
 module MCP
   autoload :Annotations, "mcp/annotations"
+  autoload :Apps, "mcp/apps"
   autoload :Cancellation, "mcp/cancellation"
   autoload :CancelledError, "mcp/cancelled_error"
   autoload :Client, "mcp/client"
   autoload :Content, "mcp/content"
+  autoload :ErrorCodes, "mcp/error_codes"
   autoload :Icon, "mcp/icon"
   autoload :Prompt, "mcp/prompt"
   autoload :Resource, "mcp/resource"
   autoload :ResourceTemplate, "mcp/resource_template"
+  autoload :ResultType, "mcp/result_type"
   autoload :Server, "mcp/server"
   autoload :ServerSession, "mcp/server_session"
   autoload :Tool, "mcp/tool"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -37,15 +37,18 @@ files:
 - lib/json_rpc_handler.rb
 - lib/mcp.rb
 - lib/mcp/annotations.rb
+- lib/mcp/apps.rb
 - lib/mcp/cancellation.rb
 - lib/mcp/cancelled_error.rb
 - lib/mcp/client.rb
+- lib/mcp/client/elicitation.rb
 - lib/mcp/client/http.rb
 - lib/mcp/client/oauth.rb
 - lib/mcp/client/oauth/client_credentials_provider.rb
 - lib/mcp/client/oauth/discovery.rb
 - lib/mcp/client/oauth/flow.rb
 - lib/mcp/client/oauth/in_memory_storage.rb
+- lib/mcp/client/oauth/jwt_client_assertion.rb
 - lib/mcp/client/oauth/pkce.rb
 - lib/mcp/client/oauth/provider.rb
 - lib/mcp/client/oauth/storage_backed_provider.rb
@@ -54,6 +57,7 @@ files:
 - lib/mcp/client/tool.rb
 - lib/mcp/configuration.rb
 - lib/mcp/content.rb
+- lib/mcp/error_codes.rb
 - lib/mcp/icon.rb
 - lib/mcp/instrumentation.rb
 - lib/mcp/logging_message_notification.rb
@@ -67,6 +71,7 @@ files:
 - lib/mcp/resource/contents.rb
 - lib/mcp/resource/embedded.rb
 - lib/mcp/resource_template.rb
+- lib/mcp/result_type.rb
 - lib/mcp/server.rb
 - lib/mcp/server/capabilities.rb
 - lib/mcp/server/pagination.rb
@@ -90,7 +95,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.23.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.24.0
   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