Support client-side notifications/cancelled per MCP specification

[koic]

Motivation and Context

The server-side half of MCP notifications/cancelled shipped earlier and lets handlers observe cancellation via server_context.cancelled? / raise_if_cancelled!. This PR delivers the client-side equivalent that was deferred at the time: an MCP::Client user can now cancel a request they have already issued and have the calling thread wake up, matching the Python SDK (anyio.CancelScope) and TypeScript SDK (AbortSignal) ergonomics.

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:

cancellation = MCP::Cancellation.new
Thread.new do
  client.call_tool(name: "slow_tool", arguments: {}, cancellation: cancellation)
rescue MCP::CancelledError
  # cleanup
end
cancellation.cancel(reason: "user pressed cancel")

For low-level use, Client#cancel(request_id:, reason:) sends the notification without managing the calling thread, and Client#generate_request_id lets callers pre-allocate an id before kicking off a request on another thread. The request_id: and cancellation: keywords are accepted by every request method (tools, list_tools, resources, list_resources, resource_templates, list_resource_templates, prompts, list_prompts, call_tool, read_resource, get_prompt, complete, ping).

When cancellation: is supplied, the actual blocking transport.send_request runs on a worker thread; the calling thread waits on a Queue woken either by the response or by the cancel signal (whichever arrives first - the same race contract as the server-side StreamableHTTPTransport#cancel_pending_request). On a normal completion the on_cancel hook is deregistered so a late cancel does not emit a stray notifications/cancelled. The worker thread is not force-killed when a cancel wins the race; it stays blocked on the underlying I/O until the transport actually returns (or the user closes it). For Client::HTTP the leak resolves as soon as the server sends any response; for Client::Stdio the user may need to call client.transport.close if the server stops responding entirely.

Client::Stdio and Client::HTTP gain send_notification(notification:) so Client#cancel can deliver the JSON-RPC notification through the existing transport plumbing. Custom transports that do not implement send_notification cause Client#cancel to raise NoMethodError.

Ref: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation

How Has This Been Tested?

test/mcp/client_test.rb covers Client#cancel payload (with and without reason), Client#generate_request_id returning distinct UUIDs, every request method threading request_id: through, and the full cancellation: flow:

• Returns the response when no cancel happens (no behaviour regression for callers that do not pass a token).
• Pre-cancelled token raises MCP::CancelledError immediately and never reaches the transport (no stray request, no stray notification).
• Mid-flight cancel raises MCP::CancelledError carrying the supplied reason and sends notifications/cancelled through the transport.
• Late cancel after a normal completion does not emit a stray notification (the on_cancel hook is deregistered in the ensure block).

test/mcp/client/stdio_test.rb covers send_notification writing the JSON line through the spawned process and returning nil without waiting for a response.

test/mcp/client/http_test.rb covers send_notification POSTing the body, tolerating HTTP 202 Accepted, and surfacing Faraday errors as RequestHandlerError.

Breaking Change

None. All new keywords (request_id:, cancellation:) on request methods are optional and default to nil. Existing callers that do not pass them get the original synchronous behaviour. Custom transports that already implement send_request(request:) continue to work; only callers of Client#cancel need a transport that responds to send_notification, and the failure mode is a clear NoMethodError rather than silent breakage.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed