mcp 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6a956181733036c09b8431db1d1da47e3757165123efd5d5dab5fe1cc522e6a
-  data.tar.gz: fc611e55e4f88e9ca61ad64d4d2578c6e5a9680ceb4d667337787098ca59bbde
+  metadata.gz: fd749db825bb7586ca38768025dbd6c4e6e9e9aa5805666a7d9ee4b5f54a59f3
+  data.tar.gz: a7dbc93581cfda1a22a6740f33047586902efcc30153a1ebda836a3623d267b0
 SHA512:
-  metadata.gz: '010991cbd4a1b18214d12d8ce3cb09b3658cba4a1cf72c7475ff76688fe87eef4137bd76eb5ebd7b15309e1aec7ed84909125858accd474f052e1a915ec37ad8'
-  data.tar.gz: 5b9b2994a4fb3769bda007a39ce0cf02c2a9b4fbeeecb48dc74aa4ca66e4d6e066c545f5d473b339561af06cf14f8e546a6e87a92d4d9c0939fe90858cddb3a8
+  metadata.gz: f9c6a4cc9f66449020c13220b5bb3d8c17cf2de3f6f40ea685eb3e56a47fc706c0d43514985914259c3e663877e9ef5b9396ed08200b8f73de0dea35f608e1a5
+  data.tar.gz: 8a2976e9a5870aa4ce6404fd8123e67522dc2eb86804676c1feb574238315a69f2fb691acd3aabe22197ec77afe7c129c8225a6c318f8932e8fcb70ef3c7c595

data/README.md

@@ -38,7 +38,9 @@ It implements the Model Context Protocol specification, handling model context r
 - Supports resource registration and retrieval
 - Supports stdio & Streamable HTTP (including SSE) transports
 - Supports notifications for list changes (tools, prompts, resources)
+- Supports roots (server-to-client filesystem boundary queries)
 - Supports sampling (server-to-client LLM completion requests)
+- Supports cursor-based pagination for list operations
 
 ### Supported Methods
 
@@ -51,7 +53,10 @@ It implements the Model Context Protocol specification, handling model context r
 - `resources/list` - Lists all registered resources and their schemas
 - `resources/read` - Retrieves a specific resource by name
 - `resources/templates/list` - Lists all registered resource templates and their schemas
+- `resources/subscribe` - Subscribes to updates for a specific resource
+- `resources/unsubscribe` - Unsubscribes from updates for a specific resource
 - `completion/complete` - Returns autocompletion suggestions for prompt arguments and resource URIs
+- `roots/list` - Requests filesystem roots from the client (server-to-client)
 - `sampling/createMessage` - Requests LLM completion from the client (server-to-client)
 - `elicitation/create` - Requests user input from the client (server-to-client)
 
@@ -891,6 +896,108 @@ server = MCP::Server.new(
 )
 ```
 
+### Roots
+
+The Model Context Protocol allows servers to request filesystem roots from clients through the `roots/list` method.
+Roots define the boundaries of where a server can operate, providing a list of directories and files the client has made available.
+
+**Key Concepts:**
+
+- **Server-to-Client Request**: Like sampling, roots listing is initiated by the server
+- **Client Capability**: Clients must declare `roots` capability during initialization
+- **Change Notifications**: Clients that support `roots.listChanged` send `notifications/roots/list_changed` when roots change
+
+**Using Roots in Tools:**
+
+Tools that accept a `server_context:` parameter can call `list_roots` on it.
+The request is automatically routed to the correct client session:
+
+```ruby
+class FileSearchTool < MCP::Tool
+  description "Search files within the client's project roots"
+  input_schema(
+    properties: {
+      query: { type: "string" }
+    },
+    required: ["query"]
+  )
+
+  def self.call(query:, server_context:)
+    roots = server_context.list_roots
+    root_uris = roots[:roots].map { |root| root[:uri] }
+
+    MCP::Tool::Response.new([{
+      type: "text",
+      text: "Searching in roots: #{root_uris.join(", ")}"
+    }])
+  end
+end
+```
+
+Result contains an array of root objects:
+
+```ruby
+{
+  roots: [
+    { uri: "file:///home/user/projects/myproject", name: "My Project" },
+    { uri: "file:///home/user/repos/backend", name: "Backend Repository" }
+  ]
+}
+```
+
+**Handling Root Changes:**
+
+Register a callback to be notified when the client's roots change:
+
+```ruby
+server.roots_list_changed_handler do
+  puts "Client's roots have changed, tools will see updated roots on next call."
+end
+```
+
+**Error Handling:**
+
+- Raises `RuntimeError` if client does not support `roots` capability
+- Raises `StandardError` if client returns an error response
+
+### Resource Subscriptions
+
+Resource subscriptions allow clients to monitor specific resources for changes.
+When a subscribed resource is updated, the server sends a notification to the client.
+
+The SDK does not track subscription state internally.
+Server developers register handlers and manage their own subscription state.
+Three methods are provided:
+
+- `Server#resources_subscribe_handler` - registers a handler for `resources/subscribe` requests
+- `Server#resources_unsubscribe_handler` - registers a handler for `resources/unsubscribe` requests
+- `ServerContext#notify_resources_updated` - sends a `notifications/resources/updated` notification to the subscribing client
+
+```ruby
+subscribed_uris = Set.new
+
+server = MCP::Server.new(
+  name: "my_server",
+  resources: [my_resource],
+  capabilities: { resources: { subscribe: true } },
+)
+
+server.resources_subscribe_handler do |params|
+  subscribed_uris.add(params[:uri].to_s)
+end
+
+server.resources_unsubscribe_handler do |params|
+  subscribed_uris.delete(params[:uri].to_s)
+end
+
+server.define_tool(name: "update_resource") do |server_context:, **args|
+  if subscribed_uris.include?("test://my-resource")
+    server_context.notify_resources_updated(uri: "test://my-resource")
+  end
+  MCP::Tool::Response.new([MCP::Content::Text.new("Resource updated").to_h])
+end
+```
+
 ### Sampling
 
 The Model Context Protocol allows servers to request LLM completions from clients through the `sampling/createMessage` method.
@@ -992,6 +1099,33 @@ Notifications follow the JSON-RPC 2.0 specification and use these method names:
 - `notifications/progress`
 - `notifications/message`
 
+### Ping
+
+The MCP Ruby SDK supports the
+[MCP `ping` utility](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping),
+which allows either side of the connection to verify that the peer is still responsive.
+A `ping` request has no parameters, and the receiver MUST respond promptly with an empty result.
+
+#### Server-Side
+
+Servers respond to incoming `ping` requests automatically - no setup is required.
+Any `MCP::Server` instance replies with an empty result.
+
+#### Client-Side
+
+`MCP::Client` exposes `ping` to send a ping to the server:
+
+```ruby
+client = MCP::Client.new(transport: transport)
+client.ping # => {} on success
+```
+
+`#ping` raises `MCP::Client::ServerError` when the server returns a JSON-RPC error.
+It raises `MCP::Client::ValidationError` when the response `result` is missing or
+is not a Hash (matching the spec requirement that `result` be an object).
+Transport-level errors (for example, `MCP::Client::Stdio`'s `read_timeout:` firing)
+propagate as exceptions raised by the transport layer.
+
 ### Progress
 
 The MCP Ruby SDK supports progress tracking for long-running tool operations,
@@ -1291,6 +1425,22 @@ Set `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`
 transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
 ```
 
+You can enable JSON response mode, where the server returns `application/json` instead of `text/event-stream`.
+Set `enable_json_response: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`:
+
+```ruby
+# JSON response mode
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, enable_json_response: true)
+```
+
+In JSON response mode, the POST response is a single JSON object, so server-to-client messages
+that need to arrive during request processing are not supported:
+request-scoped notifications (`progress`, `log`) are silently dropped, and all server-to-client requests
+(`sampling/createMessage`, `roots/list`, `elicitation/create`) raise an error.
+Session-scoped standalone notifications (`resources/updated`, `elicitation/complete`) and
+broadcast notifications (`tools/list_changed`, etc.) still flow to clients connected to the GET SSE stream.
+This mode is suitable for simple tool servers that do not need server-initiated requests.
+
 By default, sessions do not expire. To mitigate session hijacking risks, you can set a `session_idle_timeout` (in seconds).
 When configured, sessions that receive no HTTP requests for this duration are automatically expired and cleaned up:
 
@@ -1299,6 +1449,90 @@ When configured, sessions that receive no HTTP requests for this duration are au
 transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 1800)
 ```
 
+### Pagination
+
+The MCP Ruby SDK supports [pagination](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination)
+for list operations that may return large result sets. Pagination uses string cursor tokens carrying a zero-based offset,
+treated as opaque by clients: the server decides page size, and the client follows `nextCursor` until the server omits it.
+
+Pagination applies to `tools/list`, `prompts/list`, `resources/list`, and `resources/templates/list`.
+
+#### Server-Side: Enabling Pagination
+
+Pass `page_size:` to `MCP::Server.new` to split list responses into pages. When `page_size` is omitted (the default),
+list responses contain all items in a single response, preserving the pre-pagination behavior.
+
+```ruby
+server = MCP::Server.new(
+  name: "my_server",
+  tools: tools,
+  page_size: 50,
+)
+```
+
+When `page_size` is set, list responses include a `nextCursor` field whenever more pages are available:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "tools": [
+      { "name": "example_tool" }
+    ],
+    "nextCursor": "50"
+  }
+}
+```
+
+Invalid cursors (e.g. non-numeric, negative, or out-of-range) are rejected with JSON-RPC error code `-32602 (Invalid params)` per the MCP specification.
+
+#### Client-Side: Iterating Pages
+
+`MCP::Client` exposes `list_tools`, `list_prompts`, `list_resources`, and `list_resource_templates`.
+**Each call issues exactly one `*/list` JSON-RPC request and returns exactly one page** — not the full collection.
+The returned result object (`MCP::Client::ListToolsResult` etc.) exposes the page items and the next cursor as method accessors:
+
+```ruby
+client = MCP::Client.new(transport: transport)
+
+cursor = nil
+loop do
+  page = client.list_tools(cursor: cursor)
+  page.tools.each { |tool| process(tool) }
+  cursor = page.next_cursor
+  break unless cursor
+end
+```
+
+The same pattern applies to `list_prompts` (`page.prompts`), `list_resources` (`page.resources`), and
+`list_resource_templates` (`page.resource_templates`). `next_cursor` is `nil` on the final page.
+
+Because a single call returns a single page, how many items come back depends on the server's `page_size` configuration:
+
+| Server `page_size` | `client.list_tools(cursor: nil)`                                    |
+|--------------------|---------------------------------------------------------------------|
+| Not set (default)  | Returns every item in one response. `next_cursor` is `nil`.         |
+| Set to `N`         | Returns the first `N` items. `next_cursor` is set for continuation. |
+
+If your application needs the complete collection regardless of how the server is configured, either loop on
+`next_cursor` as shown above, or use the whole-collection methods described below.
+
+#### Fetching the Complete Collection
+
+`client.tools`, `client.resources`, `client.resource_templates`, and `client.prompts` auto-iterate
+through all pages and return a plain array of items, guaranteeing the full collection regardless
+of the server's `page_size` setting. When a server paginates, they issue multiple JSON-RPC round
+trips per call and break out of the pagination loop if the server returns the same `nextCursor`
+twice in a row as a safety measure.
+
+```ruby
+tools = client.tools # => Array<MCP::Client::Tool> of every tool on the server.
+```
+
+Use these when you want the complete list; use `list_tools(cursor:)` etc. when you need
+fine-grained iteration (e.g. to stream-process pages without loading everything into memory).
+
 ### Advanced
 
 #### Custom Methods
@@ -1352,16 +1586,13 @@ end
 - Raises `MCP::Server::MethodAlreadyDefinedError` if trying to override an existing method
 - Supports the same exception reporting and instrumentation as standard methods
 
-### Unsupported Features (to be implemented in future versions)
-
-- Resource subscriptions
-
 ## Building an MCP Client
 
 The `MCP::Client` class provides an interface for interacting with MCP servers.
 
 This class supports:
 
+- Liveness check via the `ping` method (`MCP::Client#ping`)
 - Tool listing via the `tools/list` method (`MCP::Client#tools`)
 - Tool invocation via the `tools/call` method (`MCP::Client#call_tools`)
 - Resource listing via the `resources/list` method (`MCP::Client#resources`)
@@ -1448,11 +1679,12 @@ The stdio transport automatically handles:
 
 Use the `MCP::Client::HTTP` transport to interact with MCP servers using simple HTTP requests.
 
-You'll need to add `faraday` as a dependency in order to use the HTTP transport layer:
+You'll need to add `faraday` as a dependency in order to use the HTTP transport layer. Add `event_stream_parser` as well if the server uses SSE (`text/event-stream`) responses:
 
 ```ruby
 gem 'mcp'
 gem 'faraday', '>= 2.0'
+gem 'event_stream_parser', '>= 1.0' # optional, required only for SSE responses
 ```
 
 Example usage:

data/lib/mcp/client/http.rb

@@ -1,25 +1,42 @@
 # frozen_string_literal: true
 
+require_relative "../methods"
+
 module MCP
   class Client
+    # TODO: HTTP GET for SSE streaming is not yet implemented.
+    #   https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#listening-for-messages-from-the-server
+    # TODO: Resumability and redelivery with Last-Event-ID is not yet implemented.
+    #   https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#resumability-and-redelivery
     class HTTP
       ACCEPT_HEADER = "application/json, text/event-stream"
+      SESSION_ID_HEADER = "Mcp-Session-Id"
+      PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version"
 
-      attr_reader :url
+      attr_reader :url, :session_id, :protocol_version
 
       def initialize(url:, headers: {}, &block)
         @url = url
         @headers = headers
         @faraday_customizer = block
+        @session_id = nil
+        @protocol_version = nil
       end
 
+      # Sends a JSON-RPC request and returns the parsed response body.
+      # After a successful `initialize` handshake, the session ID and protocol
+      # version returned by the server are captured and automatically included
+      # on subsequent requests.
       def send_request(request:)
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
 
-        response = client.post("", request)
-        validate_response_content_type!(response, method, params)
-        response.body
+        response = client.post("", request, session_headers)
+        body = parse_response_body(response, method, params)
+
+        capture_session_info(method, response, body)
+
+        body
       rescue Faraday::BadRequestError => e
         raise RequestHandlerError.new(
           "The #{method} request is invalid",
@@ -42,12 +59,25 @@ module MCP
           original_error: e,
         )
       rescue Faraday::ResourceNotFound => e
-        raise RequestHandlerError.new(
-          "The #{method} request is not found",
-          { method: method, params: params },
-          error_type: :not_found,
-          original_error: e,
-        )
+        # Per spec, 404 is the session-expired signal only when the request
+        # actually carried an `Mcp-Session-Id`. A 404 without a session attached
+        # (e.g. wrong URL or a stateless server) surfaces as a generic not-found.
+        # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+        if @session_id
+          clear_session
+          raise SessionExpiredError.new(
+            "The #{method} request is not found",
+            { method: method, params: params },
+            original_error: e,
+          )
+        else
+          raise RequestHandlerError.new(
+            "The #{method} request is not found",
+            { method: method, params: params },
+            error_type: :not_found,
+            original_error: e,
+          )
+        end
       rescue Faraday::UnprocessableEntityError => e
         raise RequestHandlerError.new(
           "The #{method} request is unprocessable",
@@ -64,6 +94,28 @@ module MCP
         )
       end
 
+      # Terminates the session by sending an HTTP DELETE to the MCP endpoint
+      # with the current `Mcp-Session-Id` header, and clears locally tracked
+      # session state afterward. No-op when no session has been established.
+      #
+      # Per spec, the server MAY respond with HTTP 405 Method Not Allowed when
+      # it does not support client-initiated termination, and returns 404 for
+      # a session it has already terminated. Both mean the session is gone —
+      # the desired end state. Other errors surface to the caller; local
+      # session state is cleared either way.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+      def close
+        return unless @session_id
+
+        begin
+          client.delete("", nil, session_headers)
+        rescue Faraday::ClientError => e
+          raise unless [404, 405].include?(e.response&.dig(:status))
+        ensure
+          clear_session
+        end
+      end
+
       private
 
       attr_reader :headers
@@ -84,6 +136,31 @@ module MCP
         end
       end
 
+      # Per spec, the client MUST include `MCP-Session-Id` (when the server assigned one)
+      # and `MCP-Protocol-Version` on all requests after `initialize`.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#protocol-version-header
+      def session_headers
+        request_headers = {}
+        request_headers[SESSION_ID_HEADER] = @session_id if @session_id
+        request_headers[PROTOCOL_VERSION_HEADER] = @protocol_version if @protocol_version
+        request_headers
+      end
+
+      def capture_session_info(method, response, body)
+        return unless method.to_s == Methods::INITIALIZE
+
+        # Faraday normalizes header names to lowercase.
+        session_id = response.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
+
+      def clear_session
+        @session_id = nil
+        @protocol_version = nil
+      end
+
       def require_faraday!
         require "faraday"
       rescue LoadError
@@ -92,14 +169,56 @@ module MCP
           "See https://rubygems.org/gems/faraday for more details."
       end
 
-      def validate_response_content_type!(response, method, params)
+      def require_event_stream_parser!
+        require "event_stream_parser"
+      rescue LoadError
+        raise LoadError, "The 'event_stream_parser' gem is required to parse SSE responses. " \
+          "Add it to your Gemfile: gem 'event_stream_parser', '>= 1.0'. " \
+          "See https://rubygems.org/gems/event_stream_parser for more details."
+      end
+
+      def parse_response_body(response, method, params)
+        # 202 Accepted is the server's ACK for a JSON-RPC notification or response; no body is expected.
+        # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server
+        return if response.status == 202
+
         content_type = response.headers["Content-Type"]
-        return if content_type&.include?("application/json")
+
+        if content_type&.include?("text/event-stream")
+          parse_sse_response(response.body, method, params)
+        elsif content_type&.include?("application/json")
+          response.body
+        else
+          raise RequestHandlerError.new(
+            "Unsupported Content-Type: #{content_type.inspect}. Expected application/json or text/event-stream.",
+            { method: method, params: params },
+            error_type: :unsupported_media_type,
+          )
+        end
+      end
+
+      def parse_sse_response(body, method, params)
+        require_event_stream_parser!
+
+        json_rpc_response = nil
+        parser = EventStreamParser::Parser.new
+        parser.feed(body.to_s) do |_type, data, _id|
+          next if data.empty?
+
+          begin
+            parsed = JSON.parse(data)
+            json_rpc_response = parsed if parsed.is_a?(Hash) && (parsed.key?("result") || parsed.key?("error"))
+          rescue JSON::ParserError
+            next
+          end
+        end
+
+        return json_rpc_response if json_rpc_response
 
         raise RequestHandlerError.new(
-          "Unsupported Content-Type: #{content_type.inspect}. This client only supports JSON responses.",
+          "No valid JSON-RPC response found in SSE stream",
           { method: method, params: params },
-          error_type: :unsupported_media_type,
+          error_type: :parse_error,
         )
       end
     end

data/lib/mcp/client/paginated_result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    # Result objects returned by `list_tools`, `list_prompts`, `list_resources`, and `list_resource_templates`.
+    # Each carries the page items, an optional opaque `next_cursor` string for continuing pagination,
+    # and an optional `meta` hash mirroring the MCP `_meta` response field.
+    ListToolsResult = Struct.new(:tools, :next_cursor, :meta, keyword_init: true)
+    ListPromptsResult = Struct.new(:prompts, :next_cursor, :meta, keyword_init: true)
+    ListResourcesResult = Struct.new(:resources, :next_cursor, :meta, keyword_init: true)
+    ListResourceTemplatesResult = Struct.new(:resource_templates, :next_cursor, :meta, keyword_init: true)
+  end
+end

data/lib/mcp/client.rb

@@ -2,6 +2,7 @@
 
 require_relative "client/stdio"
 require_relative "client/http"
+require_relative "client/paginated_result"
 require_relative "client/tool"
 
 module MCP
@@ -27,6 +28,21 @@ module MCP
       end
     end
 
+    # Raised when a server response fails client-side validation, e.g., a success response
+    # whose `result` field is missing or has the wrong type. This is distinct from a
+    # server-returned JSON-RPC error, which is raised as `ServerError`.
+    class ValidationError < StandardError; end
+
+    # Raised when the server responds 404 to a request containing a session ID,
+    # indicating the session has expired. Inherits from `RequestHandlerError` for
+    # backward compatibility with callers that rescue the generic error. Per spec,
+    # clients MUST start a new session with a fresh `initialize` request in response.
+    class SessionExpiredError < RequestHandlerError
+      def initialize(message, request, original_error: nil)
+        super(message, request, error_type: :not_found, original_error: original_error)
+      end
+    end
+
     # Initializes a new MCP::Client instance.
     #
     # @param transport [Object] The transport object to use for communication with the server.
@@ -43,8 +59,41 @@ module MCP
     # So keeping it public
     attr_reader :transport
 
-    # Returns the list of tools available from the server.
-    # Each call will make a new request – the result is not cached.
+    # Returns a single page of tools from the server.
+    #
+    # @param cursor [String, nil] Cursor from a previous page response.
+    # @return [MCP::Client::ListToolsResult] Result with `tools` (Array<MCP::Client::Tool>)
+    #   and `next_cursor` (String or nil).
+    #
+    # @example Iterate all pages
+    #   cursor = nil
+    #   loop do
+    #     page = client.list_tools(cursor: cursor)
+    #     page.tools.each { |tool| puts tool.name }
+    #     cursor = page.next_cursor
+    #     break unless cursor
+    #   end
+    def list_tools(cursor: nil)
+      params = cursor ? { cursor: cursor } : nil
+      response = request(method: "tools/list", params: params)
+      result = response["result"] || {}
+
+      tools = (result["tools"] || []).map do |tool|
+        Tool.new(
+          name: tool["name"],
+          description: tool["description"],
+          input_schema: tool["inputSchema"],
+        )
+      end
+
+      ListToolsResult.new(tools: tools, next_cursor: result["nextCursor"], meta: result["_meta"])
+    end
+
+    # Returns every tool available on the server. Iterates through all pages automatically
+    # when the server paginates, so the full collection is returned regardless of the server's `page_size` setting.
+    # Use {#list_tools} when you need fine-grained cursor control.
+    #
+    # Each call will make a new request - the result is not cached.
     #
     # @return [Array<MCP::Client::Tool>] An array of available tools.
     #
@@ -54,45 +103,151 @@ module MCP
     #     puts tool.name
     #   end
     def tools
-      response = request(method: "tools/list")
+      # TODO: consider renaming to `list_all_tools`.
+      all_tools = []
+      seen = Set.new
+      cursor = nil
 
-      response.dig("result", "tools")&.map do |tool|
-        Tool.new(
-          name: tool["name"],
-          description: tool["description"],
-          input_schema: tool["inputSchema"],
-        )
-      end || []
+      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
     end
 
-    # Returns the list of resources available from the server.
-    # Each call will make a new request – the result is not cached.
+    # Returns a single page of resources from the server.
+    #
+    # @param cursor [String, nil] Cursor from a previous page response.
+    # @return [MCP::Client::ListResourcesResult] Result with `resources` (Array<Hash>)
+    #   and `next_cursor` (String or nil).
+    def list_resources(cursor: nil)
+      params = cursor ? { cursor: cursor } : nil
+      response = request(method: "resources/list", params: params)
+      result = response["result"] || {}
+
+      ListResourcesResult.new(
+        resources: result["resources"] || [],
+        next_cursor: result["nextCursor"],
+        meta: result["_meta"],
+      )
+    end
+
+    # Returns every resource available on the server. Iterates through all pages automatically
+    # when the server paginates, so the full collection is returned regardless of the server's `page_size` setting.
+    # Use {#list_resources} when you need fine-grained cursor control.
+    #
+    # Each call will make a new request - the result is not cached.
     #
     # @return [Array<Hash>] An array of available resources.
     def resources
-      response = request(method: "resources/list")
+      # 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
+    end
 
-      response.dig("result", "resources") || []
+    # Returns a single page of resource templates from the server.
+    #
+    # @param cursor [String, nil] Cursor from a previous page response.
+    # @return [MCP::Client::ListResourceTemplatesResult] Result with `resource_templates`
+    #   (Array<Hash>) and `next_cursor` (String or nil).
+    def list_resource_templates(cursor: nil)
+      params = cursor ? { cursor: cursor } : nil
+      response = request(method: "resources/templates/list", params: params)
+      result = response["result"] || {}
+
+      ListResourceTemplatesResult.new(
+        resource_templates: result["resourceTemplates"] || [],
+        next_cursor: result["nextCursor"],
+        meta: result["_meta"],
+      )
     end
 
-    # Returns the list of resource templates available from the server.
-    # Each call will make a new request – the result is not cached.
+    # Returns every resource template available on the server. Iterates through all pages automatically
+    # when the server paginates, so the full collection is returned regardless of the server's `page_size` setting.
+    # Use {#list_resource_templates} when you need fine-grained cursor control.
+    #
+    # Each call will make a new request - the result is not cached.
     #
     # @return [Array<Hash>] An array of available resource templates.
     def resource_templates
-      response = request(method: "resources/templates/list")
+      # 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
+    end
+
+    # Returns a single page of prompts from the server.
+    #
+    # @param cursor [String, nil] Cursor from a previous page response.
+    # @return [MCP::Client::ListPromptsResult] Result with `prompts` (Array<Hash>)
+    #   and `next_cursor` (String or nil).
+    def list_prompts(cursor: nil)
+      params = cursor ? { cursor: cursor } : nil
+      response = request(method: "prompts/list", params: params)
+      result = response["result"] || {}
 
-      response.dig("result", "resourceTemplates") || []
+      ListPromptsResult.new(
+        prompts: result["prompts"] || [],
+        next_cursor: result["nextCursor"],
+        meta: result["_meta"],
+      )
     end
 
-    # Returns the list of prompts available from the server.
-    # Each call will make a new request – the result is not cached.
+    # Returns every prompt available on the server. Iterates through all pages automatically
+    # when the server paginates, so the full collection is returned regardless of the server's `page_size` setting.
+    # Use {#list_prompts} when you need fine-grained cursor control.
+    #
+    # Each call will make a new request - the result is not cached.
     #
     # @return [Array<Hash>] An array of available prompts.
     def prompts
-      response = request(method: "prompts/list")
+      # 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
 
-      response.dig("result", "prompts") || []
+      all_prompts
     end
 
     # Calls a tool via the transport layer and returns the full response from the server.
@@ -163,6 +318,24 @@ module MCP
       response.dig("result", "completion") || { "values" => [], "hasMore" => false }
     end
 
+    # Sends a `ping` request to the server to verify the connection is alive.
+    # Per the MCP spec, the server responds with an empty result.
+    #
+    # @return [Hash] An empty hash on success.
+    # @raise [ServerError] If the server returns a JSON-RPC error.
+    # @raise [ValidationError] If the response `result` is missing or not a Hash.
+    #
+    # @example
+    #   client.ping # => {}
+    #
+    # @see https://modelcontextprotocol.io/specification/latest/basic/utilities/ping
+    def ping
+      result = request(method: Methods::PING)["result"]
+      raise ValidationError, "Response validation failed: missing or invalid `result`" unless result.is_a?(Hash)
+
+      result
+    end
+
     private
 
     def request(method:, params: nil)

data/lib/mcp/methods.rb

@@ -73,14 +73,12 @@ module MCP
           require_capability!(method, capabilities, :completions)
         when ROOTS_LIST
           require_capability!(method, capabilities, :roots)
-        when NOTIFICATIONS_ROOTS_LIST_CHANGED
-          require_capability!(method, capabilities, :roots)
-          require_capability!(method, capabilities, :roots, :listChanged)
         when SAMPLING_CREATE_MESSAGE
           require_capability!(method, capabilities, :sampling)
         when ELICITATION_CREATE
           require_capability!(method, capabilities, :elicitation)
-        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED, NOTIFICATIONS_ELICITATION_COMPLETE
+        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_ROOTS_LIST_CHANGED,
+             NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED, NOTIFICATIONS_ELICITATION_COMPLETE
           # No specific capability required.
         end
       end

data/lib/mcp/server/pagination.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MCP
+  class Server
+    module Pagination
+      private
+
+      def cursor_from(request)
+        return if request.nil?
+
+        unless request.is_a?(Hash)
+          raise RequestHandlerError.new("Invalid params", request, error_type: :invalid_params)
+        end
+
+        request[:cursor]
+      end
+
+      def paginate(items, cursor:, page_size:, request:, &block)
+        start_index = 0
+
+        if cursor
+          unless cursor.is_a?(String)
+            raise RequestHandlerError.new("Invalid cursor", request, error_type: :invalid_params)
+          end
+
+          start_index = Integer(cursor, exception: false)
+          if start_index.nil? || start_index < 0 || start_index >= items.size
+            raise RequestHandlerError.new("Invalid cursor", request, error_type: :invalid_params)
+          end
+        end
+
+        end_index = page_size ? start_index + page_size : items.size
+        page = items[start_index...end_index]
+        page = page.map(&block) if block
+
+        result = { items: page }
+        result[:next_cursor] = end_index.to_s if end_index < items.size
+        result
+      end
+    end
+  end
+end

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

@@ -22,13 +22,14 @@ module MCP
           "Connection" => "keep-alive",
         }.freeze
 
-        def initialize(server, stateless: false, session_idle_timeout: nil)
+        def initialize(server, stateless: false, enable_json_response: false, session_idle_timeout: nil)
           super(server)
           # Maps `session_id` to `{ get_sse_stream: stream_object, server_session: ServerSession, last_active_at: float_from_monotonic_clock }`.
           @sessions = {}
           @mutex = Mutex.new
 
           @stateless = stateless
+          @enable_json_response = enable_json_response
           @session_idle_timeout = session_idle_timeout
           @pending_responses = {}
 
@@ -43,7 +44,8 @@ module MCP
           start_reaper_thread if @session_idle_timeout
         end
 
-        REQUIRED_POST_ACCEPT_TYPES = ["application/json", "text/event-stream"].freeze
+        REQUIRED_POST_ACCEPT_TYPES_SSE = ["application/json", "text/event-stream"].freeze
+        REQUIRED_POST_ACCEPT_TYPES_JSON = ["application/json"].freeze
         REQUIRED_GET_ACCEPT_TYPES = ["text/event-stream"].freeze
         STREAM_WRITE_ERRORS = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
         SESSION_REAP_INTERVAL = 60
@@ -94,6 +96,12 @@ module MCP
 
           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)
@@ -172,6 +180,10 @@ module MCP
             raise "Stateless mode does not support server-to-client requests."
           end
 
+          if @enable_json_response
+            raise "JSON response mode does not support server-to-client requests."
+          end
+
           unless session_id
             raise "session_id is required for server-to-client requests."
           end
@@ -269,16 +281,17 @@ module MCP
         def send_to_stream(stream, data)
           message = data.is_a?(String) ? data : data.to_json
           stream.write("data: #{message}\n\n")
-          stream.flush if stream.respond_to?(:flush)
+          stream.flush
         end
 
         def send_ping_to_stream(stream)
           stream.write(": ping #{Time.now.iso8601}\n\n")
-          stream.flush if stream.respond_to?(:flush)
+          stream.flush
         end
 
         def handle_post(request)
-          accept_error = validate_accept_header(request, REQUIRED_POST_ACCEPT_TYPES)
+          required_types = @enable_json_response ? REQUIRED_POST_ACCEPT_TYPES_JSON : REQUIRED_POST_ACCEPT_TYPES_SSE
+          accept_error = validate_accept_header(request, required_types)
           return accept_error if accept_error
 
           content_type_error = validate_content_type(request)
@@ -519,7 +532,7 @@ module MCP
             end
           end
 
-          if session_id && !@stateless
+          if session_id && !@stateless && !@enable_json_response
             handle_request_with_sse_response(body_string, session_id, server_session, related_request_id: related_request_id)
           else
             response = dispatch_handle_json(body_string, server_session)

data/lib/mcp/server.rb

@@ -6,6 +6,7 @@ require_relative "methods"
 require_relative "logging_message_notification"
 require_relative "progress"
 require_relative "server_context"
+require_relative "server/pagination"
 require_relative "server/transports"
 
 module MCP
@@ -65,9 +66,10 @@ module MCP
     end
 
     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 :client_capabilities
+    attr_reader :page_size, :client_capabilities
 
     def initialize(
       description: nil,
@@ -84,6 +86,7 @@ module MCP
       server_context: nil,
       configuration: nil,
       capabilities: nil,
+      page_size: nil,
       transport: nil
     )
       @description = description
@@ -100,6 +103,7 @@ module MCP
       @resource_templates = resource_templates
       @resource_index = index_resources_by_uri(resources)
       @server_context = server_context
+      self.page_size = page_size
       @configuration = MCP.configuration.merge(configuration)
       @client = nil
 
@@ -113,6 +117,8 @@ module MCP
         Methods::RESOURCES_LIST => method(:list_resources),
         Methods::RESOURCES_READ => method(:read_resource_no_content),
         Methods::RESOURCES_TEMPLATES_LIST => method(:list_resource_templates),
+        Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
+        Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
         Methods::TOOLS_LIST => method(:list_tools),
         Methods::TOOLS_CALL => method(:call_tool),
         Methods::PROMPTS_LIST => method(:list_prompts),
@@ -121,12 +127,9 @@ module MCP
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
         Methods::NOTIFICATIONS_PROGRESS => ->(_) {},
+        Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED => ->(_) {},
         Methods::COMPLETION_COMPLETE => ->(_) { DEFAULT_COMPLETION_RESULT },
         Methods::LOGGING_SET_LEVEL => method(:configure_logging_level),
-
-        # No op handlers for currently unsupported methods
-        Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
-        Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
       }
       @transport = transport
     end
@@ -182,6 +185,14 @@ module MCP
       @handlers[method_name] = block
     end
 
+    def page_size=(page_size)
+      unless page_size.nil? || (page_size.is_a?(Integer) && page_size > 0)
+        raise ArgumentError, "page_size must be nil or a positive integer"
+      end
+
+      @page_size = page_size
+    end
+
     def notify_tools_list_changed
       return unless @transport
 
@@ -218,6 +229,14 @@ module MCP
       report_exception(e, { notification: "log_message" })
     end
 
+    # Sets a handler for `notifications/roots/list_changed` notifications.
+    # Called when a client notifies the server that its filesystem roots have changed.
+    #
+    # @yield [params] The notification params (typically `nil`).
+    def roots_list_changed_handler(&block)
+      @handlers[Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED] = block
+    end
+
     # Sets a custom handler for `resources/read` requests.
     # The block receives the parsed request params and should return resource
     # contents. The return value is set as the `contents` field of the response.
@@ -237,6 +256,24 @@ module MCP
       @handlers[Methods::COMPLETION_COMPLETE] = block
     end
 
+    # Sets a custom handler for `resources/subscribe` requests.
+    # The block receives the parsed request params. The return value is
+    # ignored; the response is always an empty result `{}` per the MCP specification.
+    #
+    # @yield [params] The request params containing `:uri`.
+    def resources_subscribe_handler(&block)
+      @handlers[Methods::RESOURCES_SUBSCRIBE] = block
+    end
+
+    # Sets a custom handler for `resources/unsubscribe` requests.
+    # The block receives the parsed request params. The return value is
+    # ignored; the response is always an empty result `{}` per the MCP specification.
+    #
+    # @yield [params] The request params containing `:uri`.
+    def resources_unsubscribe_handler(&block)
+      @handlers[Methods::RESOURCES_UNSUBSCRIBE] = block
+    end
+
     def build_sampling_params(
       capabilities,
       messages:,
@@ -368,16 +405,11 @@ module MCP
           result = case method
           when Methods::INITIALIZE
             init(params, session: session)
-          when Methods::TOOLS_LIST
-            { tools: @handlers[Methods::TOOLS_LIST].call(params) }
-          when Methods::PROMPTS_LIST
-            { prompts: @handlers[Methods::PROMPTS_LIST].call(params) }
-          when Methods::RESOURCES_LIST
-            { resources: @handlers[Methods::RESOURCES_LIST].call(params) }
           when Methods::RESOURCES_READ
             { contents: @handlers[Methods::RESOURCES_READ].call(params) }
-          when Methods::RESOURCES_TEMPLATES_LIST
-            { resourceTemplates: @handlers[Methods::RESOURCES_TEMPLATES_LIST].call(params) }
+          when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
+            @handlers[method].call(params)
+            {}
           when Methods::TOOLS_CALL
             call_tool(params, session: session, related_request_id: related_request_id)
           when Methods::COMPLETION_COMPLETE
@@ -479,7 +511,9 @@ module MCP
     end
 
     def list_tools(request)
-      @tools.values.map(&:to_h)
+      page = paginate(@tools.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { tools: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
     def call_tool(request, session: nil, related_request_id: nil)
@@ -527,7 +561,9 @@ module MCP
     end
 
     def list_prompts(request)
-      @prompts.values.map(&:to_h)
+      page = paginate(@prompts.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { prompts: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
     def get_prompt(request)
@@ -547,7 +583,9 @@ module MCP
     end
 
     def list_resources(request)
-      @resources.map(&:to_h)
+      page = paginate(@resources, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { resources: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
     # Server implementation should set `resources_read_handler` to override no-op default
@@ -557,7 +595,9 @@ module MCP
     end
 
     def list_resource_templates(request)
-      @resource_templates.map(&:to_h)
+      page = paginate(@resource_templates, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { resourceTemplates: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
     def complete(params)

data/lib/mcp/server_context.rb

@@ -30,6 +30,24 @@ module MCP
       @notification_target.notify_log_message(data: data, level: level, logger: logger, related_request_id: @related_request_id)
     end
 
+    # Sends a resource updated notification scoped to the originating session.
+    #
+    # @param uri [String] The URI of the updated resource.
+    def notify_resources_updated(uri:)
+      return unless @notification_target
+
+      @notification_target.notify_resources_updated(uri: uri)
+    end
+
+    # Delegates to the session so the request is scoped to the originating client.
+    def list_roots
+      if @notification_target.respond_to?(:list_roots)
+        @notification_target.list_roots(related_request_id: @related_request_id)
+      else
+        raise NoMethodError, "undefined method 'list_roots' for #{self}"
+      end
+    end
+
     # 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.

data/lib/mcp/server_session.rb

@@ -41,6 +41,15 @@ module MCP
       @client_capabilities || @server.client_capabilities
     end
 
+    # Sends a `roots/list` request scoped to this session.
+    def list_roots(related_request_id: nil)
+      unless client_capabilities&.dig(:roots)
+        raise "Client does not support roots."
+      end
+
+      send_to_transport_request(Methods::ROOTS_LIST, nil, related_request_id: related_request_id)
+    end
+
     # Sends a `sampling/createMessage` request scoped to this session.
     def create_sampling_message(related_request_id: nil, **kwargs)
       params = @server.build_sampling_params(client_capabilities, **kwargs)
@@ -76,6 +85,13 @@ module MCP
       @server.report_exception(e, notification: "elicitation_complete")
     end
 
+    # Sends a resource updated notification to this session only.
+    def notify_resources_updated(uri:)
+      send_to_transport(Methods::NOTIFICATIONS_RESOURCES_UPDATED, { "uri" => uri })
+    rescue => e
+      @server.report_exception(e, notification: "resources_updated")
+    end
+
     # Sends a progress notification to this session only.
     def notify_progress(progress_token:, progress:, total: nil, message: nil, related_request_id: nil)
       params = {

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -39,6 +39,7 @@ files:
 - lib/mcp/annotations.rb
 - lib/mcp/client.rb
 - lib/mcp/client/http.rb
+- lib/mcp/client/paginated_result.rb
 - lib/mcp/client/stdio.rb
 - lib/mcp/client/tool.rb
 - lib/mcp/configuration.rb
@@ -58,6 +59,7 @@ files:
 - lib/mcp/resource_template.rb
 - lib/mcp/server.rb
 - lib/mcp/server/capabilities.rb
+- lib/mcp/server/pagination.rb
 - lib/mcp/server/transports.rb
 - lib/mcp/server/transports/stdio_transport.rb
 - lib/mcp/server/transports/streamable_http_transport.rb
@@ -73,13 +75,13 @@ files:
 - lib/mcp/transport.rb
 - lib/mcp/transports/stdio.rb
 - lib/mcp/version.rb
-homepage: https://github.com/modelcontextprotocol/ruby-sdk
+homepage: https://ruby.sdk.modelcontextprotocol.io
 licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.13.0
-  homepage_uri: https://github.com/modelcontextprotocol/ruby-sdk
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.14.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
   documentation_uri: https://rubydoc.info/gems/mcp