Merge pull request #425 from koic/feature_cancellation_for_client

Support client-side `notifications/cancelled` per MCP specification

Author: koic

README.md

@@ -41,7 +41,7 @@ It implements the Model Context Protocol specification, handling model context r
 - 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)
+- Supports cancellation of in-flight requests on both server and client (notifications/cancelled)
 
 ### Supported Methods
 
@@ -1205,12 +1205,7 @@ 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.
+Client-initiated cancellation is also supported: see [Client-Side: Cancelling an In-Flight Request](#client-side-cancelling-an-in-flight-request) below.
 
 #### Server-Side: Handlers that Check for Cancellation
 
@@ -1319,6 +1314,60 @@ Nested cancellation propagation is supported on `StreamableHTTPTransport` only.
 the parent `tools/call` is cancelled. The parent tool itself still observes cancellation
 via `server_context.cancelled?` between nested calls.
 
+#### Client-Side: Cancelling an In-Flight Request
+
+`MCP::Client` lets the caller cancel a request it has already issued. The recommended pattern is to pass
+an `MCP::Cancellation` token into the request method, run the request on a worker thread, and call
+`cancellation.cancel(reason:)` from another thread. The cancelling thread sends `notifications/cancelled` to
+the server, and the calling thread is woken up with `MCP::CancelledError`:
+
+```ruby
+client = MCP::Client.new(transport: transport)
+cancellation = MCP::Cancellation.new
+
+Thread.new do
+  client.call_tool(name: "slow_tool", arguments: {}, cancellation: cancellation)
+rescue MCP::CancelledError
+  # cleanup
+end
+
+# Later, from another thread:
+cancellation.cancel(reason: "user pressed cancel")
+```
+
+All request methods (`tools`, `list_tools`, `resources`, `list_resources`, `resource_templates`, `list_resource_templates`,
+`prompts`, `list_prompts`, `call_tool`, `read_resource`, `get_prompt`, `complete`, `ping`) accept the `cancellation:` keyword.
+Request ids are managed internally, so the token is the only thing a caller needs to cancel a request.
+
+> [!NOTE]
+> When a cancel wins the race, the SDK's worker thread that is blocked on the underlying I/O is *not* force-killed;
+> it stays blocked until the transport actually returns (or the user closes the transport). This matches the server-side
+> `StreamableHTTPTransport#send_request` trade-off. For `StreamableHTTPTransport#send_request` trade-off. For `Client::HTTP`
+> the leak resolves as soon as the server sends any response; for `Client::Stdio` you may need to call `client.transport.close`
+> to free the thread if the server stops responding entirely. The cancel-dispatch thread waits for the worker's send-boundary signal
+> (`&on_sent` from `send_request`) before issuing `notifications/cancelled`, so the cancel is held until the worker has at
+> least committed to writing the request; while the worker is wedged the cancel notification is deferred along with it.
+
+##### Wire-order guarantees
+
+`Client::Stdio` serializes the request write and any subsequent `notifications/cancelled` write through a single `@write_mutex`,
+so the server is guaranteed to read the request line before the cancel line.
+
+`Client::HTTP` cannot offer the same wire-arrival guarantee. Faraday's synchronous `post` does not expose a post-write / pre-response hook,
+so the SDK yields just before the request POST is dispatched. After the yield, the cancel-dispatch thread issues a separate `notifications/cancelled` POST
+on its own connection, and the two POSTs may overlap on the network. The spec is satisfied either way: the sender has already issued the request and
+still believes it to be in-progress when issuing the cancel ([MCP cancellation spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation)),
+and on the receiver side, "receivers MAY ignore a cancellation notification whose `requestId` is unknown" covers the case where the cancel POST
+happens to arrive first. The calling thread raises `MCP::CancelledError` regardless of network ordering.
+
+##### Custom transports
+
+Custom transports that want to support `cancellation:` must implement `send_notification(notification:)` so `notifications/cancelled` can be delivered.
+They should also accept the optional block passed to `send_request(request:, &on_sent)` and call it once the request bytes have been handed off to the wire
+(under a write-side mutex for stdio-style transports, immediately before the synchronous round-trip for HTTP-style transports).
+The cancel-dispatch thread waits on this signal before sending `notifications/cancelled`. Transports that do not invoke the block fall back to waiting for
+the worker thread to terminate, which preserves wire-order at the cost of delaying the cancel notification until the request has fully completed.
+
 ### Ping
 
 The MCP Ruby SDK supports the