docs: annotate Roots, Sampling, and Logging as deprecated per SEP-2577#429
Merged
koic merged 1 commit intoJun 27, 2026
Merged
Conversation
Split the advisory YARD @deprecated annotations out of modelcontextprotocol#406 so the documentation can land ahead of the 2026-07-28 protocol release. Per maintainer feedback, this drops the protocol-version-gated runtime Kernel.warn behavior and the new 2026-07-28 supported protocol version, leaving only the @deprecated notes for the Roots, Sampling, and Logging APIs deprecated by SEP-2577. Refs modelcontextprotocol#390 Co-authored-by: 🦞 Qlaw <noreply@qlaw.quick.shopify.io>
atesgoral
force-pushed
the
issue-390-deprecation-annotations
branch
from
82a6dba to
69bfe43
Compare
This was referenced Jun 27, 2026
koic
approved these changes
Jun 27, 2026
9 tasks
koic
added a commit
that referenced
this pull request
Jul 15, 2026
## Motivation and Context The MCP specification defines `sampling/createMessage` as a server-to-client request that lets a server ask the client to generate an LLM completion, so the server can leverage the client's model access without its own API keys. The Ruby SDK already supports the server side (sending the request) and, on the client side, the generic server-to-client request infrastructure introduced for elicitation (the standalone GET SSE listening stream and `on_server_request` dispatch). This adds the client-side `sampling/createMessage` handler on top of that infrastructure. ## Changes - Add `MCP::Client#on_sampling`, a thin wrapper that registers a `sampling/createMessage` handler via `transport.on_server_request`, mirroring `on_elicitation`. The handler receives the request params and returns a `CreateMessageResult`-shaped Hash sent back as the JSON-RPC result. - Document client-side sampling in the README, including the `sampling` (and `sampling.tools`) capability declaration and the human-in-the-loop guidance from the specification. ## How Has This Been Tested? - Unit tests for `on_sampling` covering handler registration on the transport and the error raised when the transport does not support server-to-client requests. - An HTTP transport test that dispatches a `sampling/createMessage` server request delivered on the SSE stream and returns a `CreateMessageResult`. ## Deprecation Note SEP-2577 deprecates sampling (along with roots and logging) starting with protocol version `2026-07-28`. The deprecation warnings are added in #406. Sampling remains fully supported under the current `2025-11-25` protocol version and stays available throughout the spec's deprecation window, so the client side is implemented here for parity with the server side and with the Python and TypeScript SDKs. `MCP::Client#on_sampling` carries the same `@deprecated` annotation as the server-side senders annotated in #429, tailored to the receiving side: the handler exists to interoperate with servers that still send sampling requests during the deprecation window. The README section carries the same note. Ref: https://modelcontextprotocol.io/specification/2025-11-25/client/sampling
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
Add advisory YARD
@deprecatedannotations for the Roots, Sampling, and Logging APIs deprecated by SEP-2577, without the protocol-version-gated runtime behavior change.Context
SEP-2577 deprecates Roots, Sampling, and Logging in the
2026-07-28protocol version. This PR splits the advisory annotations out of #406 per @koic's feedback, so the documentation can land now while the behavioral switch waits until the2026-07-28release is closer.Refs #390
Changes
@deprecatednotes to the server, server-context, and server-session APIs for roots (roots_list_changed_handler,list_roots), sampling (create_sampling_message), and logging (notify_log_message).Deliberately not included (deferred to a follow-up once
2026-07-28is closer to release):2026-07-28toSUPPORTED_STABLE_PROTOCOL_VERSIONS.Kernel.warnruntime warnings and theProtocolDeprecationshelper.Testing
Docs-only change (YARD comments + changelog). No behavior change; relies on CI for lint/test validation.