Align draft schema with spec docs (subscriptionId, HeaderMismatch, notification directions)#2889
Open
pja-ant wants to merge 2 commits into
Open
Align draft schema with spec docs (subscriptionId, HeaderMismatch, notification directions)#2889pja-ant wants to merge 2 commits into
pja-ant wants to merge 2 commits into
Conversation
- Declare the reserved io.modelcontextprotocol/subscriptionId _meta key via a new NotificationMetaObject type, including the rule for deriving the value from the subscriptions/listen request's JSON-RPC ID - Rewrite the three list_changed notification doc comments to reflect the opt-in subscriptions model instead of unsolicited delivery - Add the HEADER_MISMATCH (-32001) error code and HeaderMismatchError type required by the Streamable HTTP transport's header validation - Update cacheScope JSDoc to the authorization-context caching model used by the caching utility doc - Make CancelledNotificationParams.requestId required - Describe cancellation as client-initiated, with one server-side use: on stdio a server sends notifications/cancelled solely to terminate a subscriptions/listen stream - Give ListRootsRequest a minimal params shape instead of RequestParams, matching other server-initiated input requests - Remove ProgressNotification from ClientNotification: only clients issue requests, so only servers report progress Regenerated schema.json and schema.mdx.
- Cancellation: describe cancellation as client-to-server, with the server-side exception for subscriptions/listen stream teardown on stdio - Progress: describe progress notifications as server-to-client only, and use Client/Server in the sequence diagram - Subscriptions: state how io.modelcontextprotocol/subscriptionId is derived from the subscriptions/listen request's JSON-RPC ID (decimal string for numeric IDs, verbatim for string IDs)
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
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.
What this does
Fixes a set of inconsistencies between
schema/draft/schema.ts(the source of truth) and the draft specification prose, found during a pre-release consistency review.Why now
The draft is heading to release; each of these is a place where an implementer reading the schema and one reading the prose would build incompatible behavior.
Changes
io.modelcontextprotocol/subscriptionId_metakey in a newNotificationMetaObjecttype, and specify the derivation rule (decimal string of a numeric JSON-RPC ID, verbatim for a string ID). Previously the key existed only in prose and one example, and the docs showed numeric id1acknowledged as string"1"with no conversion rule — a strict comparison silently drops all subscription notifications on stdio.*ListChangedNotificationdoc comments that still said notifications "may be issued by servers without any previous subscription", contradicting the opt-in subscriptions model (servers MUST NOT send unrequested types).HEADER_MISMATCH = -32001and aHeaderMismatchErrorinterface. The transport requires servers to emit this code, but the schema had no definition, so generated SDKs could not recognize it.cacheScope: "private"doc comment with caching.mdx's authorization-context model (the two previously described different cache-sharing rules — a security boundary).CancelledNotificationParams.requestIdrequired (the optionality was a leftover from removed task cancellation, and an id-less cancellation has no defined meaning).ListRootsRequestminimal params instead ofRequestParams, which forced servers to fabricate client-identifying_metaon a server-initiated input request.ProgressNotificationfromClientNotification(clients no longer receive requests, so they have nothing to report progress on).CancelledNotificationstays inServerNotificationbut is now scoped: servers send it solely to terminate asubscriptions/listenstream on stdio, matching the teardown rule from (chore): sep-to-spec consistency pass #2863. cancellation.mdx and progress.mdx are rewritten to match the directional model.Verification
npm run generate:schemaartifacts committed;npm run prepandnpm run checkpass clean.