mcp 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6a956181733036c09b8431db1d1da47e3757165123efd5d5dab5fe1cc522e6a
-  data.tar.gz: fc611e55e4f88e9ca61ad64d4d2578c6e5a9680ceb4d667337787098ca59bbde
+  metadata.gz: 0d7b34843d1b915df5d3df424b025c93bba1d50a5e19486f2dcd4a646227a749
+  data.tar.gz: 4327576e74518a21d1dbe57f7f22a6f17c8e486b7a9fb9c281c11d206dcd007e
 SHA512:
-  metadata.gz: '010991cbd4a1b18214d12d8ce3cb09b3658cba4a1cf72c7475ff76688fe87eef4137bd76eb5ebd7b15309e1aec7ed84909125858accd474f052e1a915ec37ad8'
-  data.tar.gz: 5b9b2994a4fb3769bda007a39ce0cf02c2a9b4fbeeecb48dc74aa4ca66e4d6e066c545f5d473b339561af06cf14f8e546a6e87a92d4d9c0939fe90858cddb3a8
+  metadata.gz: afe69100125bcc47dbfca963983eca401f5bf29b31c01748dd1a5e99537542a4cb2b021573d3635c94bb410cdd430c0e3ff023796d91299da366cc32c7999fba
+  data.tar.gz: 815153266ba50a7e3045d7058af383d2ba852e1eefbaa62bc78299da89621bb1c0e22c5d2738f56470f50b4e8bf85f0d83135b1789f2faa9c841cff5e29fa766

data/README.md

@@ -38,7 +38,10 @@ 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
+- Supports server-side cancellation of in-flight requests (notifications/cancelled)
 
 ### Supported Methods
 
@@ -51,7 +54,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 +897,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.
@@ -989,9 +1097,164 @@ Notifications follow the JSON-RPC 2.0 specification and use these method names:
 - `notifications/tools/list_changed`
 - `notifications/prompts/list_changed`
 - `notifications/resources/list_changed`
+- `notifications/cancelled`
 - `notifications/progress`
 - `notifications/message`
 
+### Cancellation
+
+The MCP Ruby SDK supports server-side handling of the
+[MCP `notifications/cancelled` utility](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation).
+When a client sends `notifications/cancelled` for an in-flight request, the server stops
+processing cooperatively and suppresses the JSON-RPC response for that request.
+
+Cancellation is cooperative: the SDK does not forcibly terminate tool code. Instead,
+a `MCP::Cancellation` token is threaded through `server_context`, and long-running tools
+poll it to exit early. When a tool returns after cancellation has been observed,
+the server suppresses the JSON-RPC response, matching the spec. The `initialize` request
+is never cancellable per the spec.
+
+> [!NOTE]
+> Client-initiated cancellation (`Client#cancel` equivalent that would also abort
+> the calling thread's wait) is not yet implemented. Sending `notifications/cancelled`
+> from the client side can be done by constructing the notification payload and writing it
+> directly through the transport, but the calling thread does not yet unwind automatically.
+> This is tracked as a follow-up.
+
+#### Server-Side: Handlers that Check for Cancellation
+
+Any handler that opts in to `server_context:` - tools (`Tool.call`), prompt templates,
+`resources_read_handler`, `completion_handler`, `resources_subscribe_handler`,
+`resources_unsubscribe_handler`, and `define_custom_method` blocks - receives
+an `MCP::ServerContext` wired to the in-flight request's cancellation token.
+Handlers check `cancelled?` in their work loop, or call `raise_if_cancelled!` to raise
+`MCP::CancelledError` at a safe point:
+
+```ruby
+class LongRunningTool < MCP::Tool
+  description "A tool that supports cancellation"
+  input_schema(properties: { count: { type: "integer" } }, required: ["count"])
+
+  def self.call(count:, server_context:)
+    count.times do |i|
+      # Exit early if the client has sent `notifications/cancelled`.
+      break if server_context.cancelled?
+
+      do_work(i)
+    end
+
+    MCP::Tool::Response.new([{ type: "text", text: "Done" }])
+  end
+end
+```
+
+Alternatively, raise at the next safe point with `raise_if_cancelled!`:
+
+```ruby
+def self.call(count:, server_context:)
+  count.times do |i|
+    server_context.raise_if_cancelled!
+
+    do_work(i)
+  end
+
+  MCP::Tool::Response.new([{ type: "text", text: "Done" }])
+end
+```
+
+When a handler observes cancellation (either by returning early with `cancelled?` or
+by raising `MCP::CancelledError` via `raise_if_cancelled!`), the server drops the response and
+no JSON-RPC result is sent to the client.
+
+The same pattern works for other handler types:
+
+```ruby
+# resources/read
+server.resources_read_handler do |params, server_context:|
+  server_context.raise_if_cancelled!
+  # read the resource
+end
+
+# completion/complete
+server.completion_handler do |params, server_context:|
+  server_context.raise_if_cancelled!
+  # compute completions
+end
+
+# custom method
+server.define_custom_method(method_name: "custom/slow") do |params, server_context:|
+  server_context.raise_if_cancelled!
+  # do work
+end
+
+# prompts (via Prompt subclass)
+class SlowPrompt < MCP::Prompt
+  prompt_name "slow_prompt"
+
+  def self.template(args, server_context:)
+    server_context.raise_if_cancelled!
+    MCP::Prompt::Result.new(messages: [])
+  end
+end
+```
+
+Handlers that do not declare a `server_context:` keyword continue to work unchanged -
+the opt-in detection only wraps the context when the block signature asks for it.
+
+#### Nested Server-to-Client Requests Are Cancelled Automatically
+
+When a tool handler is waiting on a nested server-to-client request
+(`server_context.create_sampling_message`, `create_form_elicitation`, or
+`create_url_elicitation`), cancelling the parent tool call automatically raises
+`MCP::CancelledError` from the nested call, so the tool does not need to wrap it
+in its own `cancelled?` checks:
+
+```ruby
+def self.call(server_context:)
+  result = server_context.create_sampling_message(messages: messages, max_tokens: 100)
+  # If the parent tools/call is cancelled while waiting above, MCP::CancelledError
+  # is raised here and the tool can let it propagate or clean up as needed.
+  MCP::Tool::Response.new([{ type: "text", text: result[:content][:text] }])
+rescue MCP::CancelledError
+  # Optional: run cleanup. Re-raising (or letting it propagate) is fine; the server
+  # will still suppress the JSON-RPC response per the MCP spec.
+  raise
+end
+```
+
+Nested cancellation propagation is supported on `StreamableHTTPTransport` only.
+`StdioTransport` is single-threaded and blocks on `$stdin.gets`, so a nested
+`server_context.create_sampling_message` inside a tool runs to completion even if
+the parent `tools/call` is cancelled. The parent tool itself still observes cancellation
+via `server_context.cancelled?` between nested calls.
+
+### 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 +1554,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 +1578,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,21 +1715,18 @@ 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`)
 - Resource template listing via the `resources/templates/list` method (`MCP::Client#resource_templates`)
-- Resource reading via the `resources/read` method (`MCP::Client#read_resources`)
+- Resource reading via the `resources/read` method (`MCP::Client#read_resource`)
 - Prompt listing via the `prompts/list` method (`MCP::Client#prompts`)
 - Prompt retrieval via the `prompts/get` method (`MCP::Client#get_prompt`)
 - Completion requests via the `completion/complete` method (`MCP::Client#complete`)
@@ -1422,6 +1782,9 @@ stdio_transport = MCP::Client::Stdio.new(
 )
 client = MCP::Client.new(transport: stdio_transport)
 
+# Perform the MCP initialization handshake before sending any requests.
+client.connect
+
 # List available tools.
 tools = client.tools
 tools.each do |tool|
@@ -1448,11 +1811,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:
@@ -1461,6 +1825,9 @@ Example usage:
 http_transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp")
 client = MCP::Client.new(transport: http_transport)
 
+# Perform the MCP initialization handshake before sending any requests.
+client.connect
+
 # List available tools
 tools = client.tools
 tools.each do |tool|

data/lib/json_rpc_handler.rb

@@ -18,6 +18,11 @@ module JsonRpcHandler
 
   DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
 
+  # Sentinel return value from a handler. When a handler returns this,
+  # `process_request` emits no JSON-RPC response for the request,
+  # matching the notification-style semantics (id is ignored).
+  NO_RESPONSE = Object.new.freeze
+
   extend self
 
   def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
@@ -103,6 +108,7 @@ module JsonRpcHandler
       end
 
       result = method.call(params)
+      return if result.equal?(NO_RESPONSE)
 
       success_response(id: id, result: result)
     rescue MCP::Server::RequestHandlerError => e

data/lib/mcp/cancellation.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "cancelled_error"
+
+module MCP
+  class Cancellation
+    attr_reader :reason, :request_id
+
+    def initialize(request_id: nil)
+      @request_id = request_id
+      @reason = nil
+      @cancelled = false
+      @callbacks = []
+      @mutex = Mutex.new
+    end
+
+    def cancelled?
+      @mutex.synchronize { @cancelled }
+    end
+
+    def cancel(reason: nil)
+      callbacks = @mutex.synchronize do
+        return false if @cancelled
+
+        @cancelled = true
+        @reason = reason
+        @callbacks.tap { @callbacks = [] }
+      end
+
+      callbacks.each do |callback|
+        callback.call(reason)
+      rescue StandardError => e
+        MCP.configuration.exception_reporter.call(e, { error: "Cancellation callback failed" })
+      end
+
+      true
+    end
+
+    # Registers a callback invoked synchronously on the first `cancel` call.
+    # If already cancelled, fires immediately.
+    #
+    # Returns the block itself as a handle that can be passed to `off_cancel`
+    # to deregister it (e.g. when a nested request completes normally and the
+    # hook should not fire on a later parent cancellation).
+    def on_cancel(&block)
+      fire_now = false
+      @mutex.synchronize do
+        if @cancelled
+          fire_now = true
+        else
+          @callbacks << block
+        end
+      end
+
+      block.call(@reason) if fire_now
+      block
+    end
+
+    # Removes a previously-registered `on_cancel` callback. Returns `true`
+    # if the callback was still pending (i.e. had not yet fired), `false`
+    # otherwise. Safe to call with `nil`.
+    def off_cancel(handle)
+      return false unless handle
+
+      @mutex.synchronize { !@callbacks.delete(handle).nil? }
+    end
+
+    def raise_if_cancelled!
+      raise CancelledError.new(request_id: @request_id, reason: @reason) if cancelled?
+    end
+  end
+end

data/lib/mcp/cancelled_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MCP
+  class CancelledError < StandardError
+    attr_reader :request_id, :reason
+
+    def initialize(message = "Request was cancelled", request_id: nil, reason: nil)
+      super(message)
+      @request_id = request_id
+      @reason = reason
+    end
+  end
+end