feat: deprecate roots, sampling, and logging runtime APIs (SEP-2577)#2268
Open
mattzcarey wants to merge 2 commits into
Open
feat: deprecate roots, sampling, and logging runtime APIs (SEP-2577)#2268mattzcarey wants to merge 2 commits into
mattzcarey wants to merge 2 commits into
Conversation
Adds @deprecated JSDoc annotations to the runtime public API surface for roots, sampling, and logging, deprecated as of protocol version 2026-07-28 per SEP-2577. Reference spec types were already annotated in #2252; this covers the Server/Client/McpServer methods, ServerContext helpers, runtime capability schema fields, and the server/client guides. No behavior changes.
🦋 Changeset detectedLatest commit: 59741a8 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
@modelcontextprotocol/client
@modelcontextprotocol/codemod
@modelcontextprotocol/server
@modelcontextprotocol/server-legacy
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
typedoc treats the resolved-but-undocumented {@linkcode *CapabilitiesSchema}
links as warnings, failing docs:check in CI.
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
1 participant
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.
Summary
Implements the runtime-API portion of SEP-2577 (Deprecate Roots, Sampling, and Logging). Per the draft spec (
docs/specification/draft/deprecated.mdxregistry, plus the banners onclient/roots.mdx,client/sampling.mdx, andserver/utilities/logging.mdx), roots, sampling, and logging are deprecated as of protocol revision 2026-07-28, remain fully functional for at least twelve months, and are eligible for removal no earlier than the first revision on/after 2027-07-28.The reference spec types in
spec.types.2026-07-28.ts(plusLOG_LEVEL_META_KEYand the_metalog-level schema annotation) were already annotated in #2252. This PR completes the picture by annotating the runtime public API with matching@deprecatedJSDoc, and adding deprecation callouts to the guides.What's annotated
@modelcontextprotocol/serverServer.createMessage()(all three overloads)Server.listRoots()Server.sendLoggingMessage()and the internallogging/setLevelhandler registrationMcpServer.sendLoggingMessage()buildContext'sctx.mcpReq.log/ctx.mcpReq.requestSamplingwiring (comment)@modelcontextprotocol/clientClient.setLoggingLevel()Client.sendRootsListChanged()roots/listandsampling/createMessagehandler surfaces, plus comments on the corresponding capability assertions@modelcontextprotocol/coreServerContext.mcpReq.log/requestSamplinghelper types (shared/protocol.ts)ClientCapabilitiesSchema.roots/.samplingandServerCapabilitiesSchema.loggingfield JSDoc (types/schemas.ts), surfaced on the inferredClientCapabilities/ServerCapabilitiestypes (types/types.ts)Docs: deprecation callouts on the Logging, Sampling, and Roots sections of
docs/server.mdanddocs/client.md, each with the spec's migration guidance (roots → tool parameters / resource URIs / configuration; sampling → direct LLM provider APIs; logging → stderr / OpenTelemetry).Wording matches the #2252 annotations (
Deprecated as of protocol version 2026-07-28 (SEP-2577), twelve-month window, deprecated features registry).No behavior change
JSDoc and docs only. No removals, no runtime changes — all three features keep working exactly as before for the full deprecation window.
Validation
pnpm build:all✅pnpm typecheck:all✅pnpm lint:all(incl.sync:snippets --check) ✅Downstream impact
createMessage,listRoots, orsetLoggingLevel, so no migration is needed there.@typescript-eslintdeprecation plugins) will see new warnings on these surfaces — this is the expected outcome of the SEP and signals where migration is needed.Closes #2195