a97e391353
## Motivation and Context The MCP specification defines `notifications/cancelled` so either party can stop a previously-issued in-flight request. The Ruby SDK declared the method constant but had no receive logic, no in-flight tracking, and no way for handlers to participate in cancellation; cancellation notifications fell through to the unsupported-method path. This PR implements the **server-side** half of the spec. The server stops processing the targeted request cooperatively and suppresses its JSON-RPC response, matching the Python SDK's anyio `CancelScope` and the TypeScript SDK's `RequestHandlerExtra.signal`. Cancellation is observable by every user-overridable request handler: - `Tool.call` (tools/call) - prompt templates (prompts/get) - blocks registered via `resources_read_handler` / `completion_handler` / `resources_subscribe_handler` / `resources_unsubscribe_handler` / `define_custom_method` Each handler opts in by declaring a `server_context:` keyword and polls `server_context.cancelled?` or calls `server_context.raise_if_cancelled!` (raising `MCP::CancelledError`) inside long-running work. Handlers that keep their existing `|params|` (or `|args|`) signature continue to work unchanged. On `StreamableHTTPTransport`, cancelling a parent `tools/call` automatically cancels n ested server-to-client requests (`sampling/createMessage`, `elicitation/create`); the nested `send_request` raises `MCP::CancelledError` and a cancel notification is routed to the peer on the parent's POST response stream. `StdioTransport` is single-threaded and blocks on `$stdin.gets`, so it deliberately does not propagate nested cancellation. Tools running on stdio still observe cancellation between calls via `server_context.cancelled?`. The design is cooperative-only (no `Thread#raise`) because preemptive cancellation is unsafe across Rack adapters and arbitrary handler code. The `initialize` request is never cancellable, satisfying the spec rule that it MUST NOT be cancelled. Unknown / completed / duplicate cancel notifications are silently ignored per the spec. `MCP::Client#cancel` (an equivalent that aborts the calling thread's synchronous wait) is deferred to a follow-up PR. Ref: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation ## How Has This Been Tested? `test/mcp/cancellation_test.rb` covers the `MCP::Cancellation` token contract. `test/mcp/server_cancellation_test.rb` covers end-to-end cancellation: - A handler spins on `cancelled?` in a background thread; the test sends `notifications/cancelled` and asserts the handler observed cancellation and the JSON-RPC response was suppressed. Each user-overridable handler type (tool, prompt template, resources/read, completion, custom method) has its own regression test. - `initialize` is not cancellable; unknown / duplicate / late-after-completion cancels are silently ignored. - The `reason` propagates into the `cancellation_reason` instrumentation field. - Custom transports implementing only the abstract `(method, params = nil)` contract keep working; the new kwargs (`session_id:`, `related_request_id:`, `parent_cancellation:`, `server_session:`) are silently dropped when the transport's signature does not declare them. `StreamableHTTPTransport` tests cover nested cancellation, hook deregistration after normal completion (so a late parent cancel does not emit a stray `notifications/cancelled`), and the first-writer-wins race when a real response and a cancel arrive concurrently. ## Breaking Change None. `MCP::ServerContext#initialize` gains an optional `cancellation:` keyword (defaults to `nil`), and `StreamableHTTPTransport#send_request` / `#send_notification` gain optional cancellation kwargs. The abstract `Transport` base class and `StdioTransport` keep their existing `(method, params = nil)` signatures, and custom transports following those signatures continue to work. `StreamableHTTPTransport` now dispatches client-originated notifications through `ServerSession#handle_json` before returning 202; previously these were accepted without dispatch, but the existing handlers for `notifications/initialized` and `notifications/progress` were already no-ops, so no user-visible effect is expected. Adding `server_context:` to a handler block is strictly opt-in.
72 lines
1.8 KiB
Ruby
72 lines
1.8 KiB
Ruby
# 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
|