-
Notifications
You must be signed in to change notification settings - Fork 2k
chore: update spec.types.ts from upstream #2027
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,7 +3,7 @@ | |
| * | ||
| * Source: https://github.com/modelcontextprotocol/modelcontextprotocol | ||
| * Pulled from: https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/main/schema/draft/schema.ts | ||
| * Last updated from commit: f68d864a813754e188c6df52dcc5772a12f96c63 | ||
| * Last updated from commit: 71e306956a4959c9655e5036be215d41986596e6 | ||
| * | ||
| * DO NOT EDIT THIS FILE MANUALLY. Changes will be overwritten by automated updates. | ||
| * To update this file, run: pnpm run fetch:spec-types 2026-07-28 | ||
|
|
@@ -81,13 +81,20 @@ | |
| * {@link UnsupportedProtocolVersionError}. | ||
| */ | ||
| 'io.modelcontextprotocol/protocolVersion': string; | ||
| /** | ||
| * Identifies the client software making the request. Required. | ||
| * Identifies the client software making the request. Clients SHOULD | ||
| * include this field on every request unless specifically configured not | ||
| * to do so. | ||
| * | ||
| * The {@link Implementation} schema requires `name` and `version`; other | ||
| * fields are optional. | ||
| * | ||
| * The value is self-reported by the client and is not verified by the | ||
| * protocol. It is intended for display, logging, and debugging. Servers | ||
| * SHOULD NOT use it to change their behavior, and SHOULD NOT rely on it for | ||
| * security decisions. | ||
| */ | ||
| 'io.modelcontextprotocol/clientInfo': Implementation; | ||
| 'io.modelcontextprotocol/clientInfo'?: Implementation; | ||
|
Check failure on line 97 in packages/core-internal/src/types/spec.types.2026-07-28.ts
|
||
| /** | ||
| * The client's capabilities for this specific request. Required. | ||
| * | ||
|
|
@@ -133,6 +140,30 @@ | |
| 'io.modelcontextprotocol/subscriptionId'?: RequestId; | ||
| } | ||
|
|
||
| /** | ||
| * Extends {@link MetaObject} with additional result-specific fields. All key naming rules from `MetaObject` apply. | ||
| * | ||
| * @see {@link MetaObject} for key naming rules and reserved prefixes. | ||
| * @see [General fields: `_meta`](/specification/draft/basic/index#meta) for more details. | ||
| * @category Common Types | ||
| */ | ||
| export interface ResultMetaObject extends MetaObject { | ||
| /** | ||
| * Identifies the server software producing the response. Servers SHOULD | ||
| * include this field on every response unless specifically configured not | ||
| * to do so. | ||
| * | ||
| * The {@link Implementation} schema requires `name` and `version`; other | ||
| * fields are optional. | ||
| * | ||
| * The value is self-reported by the server and is not verified by the | ||
| * protocol. It is intended for display, logging, and debugging. Clients | ||
| * SHOULD NOT use it to change their behavior, and SHOULD NOT rely on it for | ||
| * security decisions. | ||
| */ | ||
| 'io.modelcontextprotocol/serverInfo'?: Implementation; | ||
| } | ||
|
|
||
| /** | ||
| * A progress token, used to associate progress notifications with the original request. | ||
| * | ||
|
|
@@ -197,7 +228,7 @@ | |
| * @category Common Types | ||
| */ | ||
| export interface Result { | ||
| _meta?: MetaObject; | ||
| _meta?: ResultMetaObject; | ||
| /** | ||
| * Indicates the type of the result, which allows the client to determine | ||
| * how to parse the result object. | ||
|
|
@@ -647,16 +678,12 @@ | |
| */ | ||
| supportedVersions: string[]; | ||
| /** | ||
| * The capabilities of the server. | ||
| */ | ||
| capabilities: ServerCapabilities; | ||
| /** | ||
| * Information about the server software implementation. | ||
| */ | ||
| serverInfo: Implementation; | ||
| /** | ||
| * Natural-language guidance describing the server and its features. | ||
| * | ||
|
Check failure on line 686 in packages/core-internal/src/types/spec.types.2026-07-28.ts
|
||
|
Comment on lines
681
to
686
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🔴 This re-pull relocates Extended reasoning...What the bug isThis spec re-pull (commit
The anchor file exists precisely so that drift like this trips CI, and it does — twice over — but the PR ships only the anchor, leaving the tree red and the SDK spec-divergent. Deterministic CI failures (verified empirically by three independent runs each)Typecheck — Vitest drift guard —
Runtime/interop divergence if forced throughClient rejects spec-compliant servers. The 2026 wire schemas still require body Client identity plumbing reads a field the spec deleted. Server never stamps the new key. Why existing code doesn't prevent itThe drift-guard test is designed to catch exactly this — and it does, which is why the tree cannot go green without the companion work. The Zod side stays permissive for the new key ( Step-by-step proof
How to fixLand the companion port in the same PR (or hold this sync until it exists):
Six independent verifiers confirmed every layer of this finding empirically (tsc and vitest runs reproduce the exact errors above); none refuted it. |
||
| * This can be used by clients to improve an LLM's understanding of | ||
| * available tools (e.g., by including it in a system prompt). It should | ||
| * focus on information that helps the model use the server effectively | ||
|
|
@@ -1284,13 +1311,13 @@ | |
| } | ||
|
|
||
| /** | ||
| * Extends {@link MetaObject} with the subscription-stream identifier carried by a | ||
| * Extends {@link ResultMetaObject} with the subscription-stream identifier carried by a | ||
| * {@link SubscriptionsListenResult}. All key naming rules from `MetaObject` apply. | ||
| * | ||
| * @see {@link MetaObject} for key naming rules and reserved prefixes. | ||
| * @category `subscriptions/listen` | ||
| */ | ||
| export interface SubscriptionsListenResultMeta extends MetaObject { | ||
| export interface SubscriptionsListenResultMeta extends ResultMetaObject { | ||
| /** | ||
| * Identifies the subscription stream this response closes, so the client can | ||
| * correlate it with the originating subscription — mirroring the same key on | ||
|
|
@@ -1333,10 +1360,16 @@ | |
| } | ||
|
|
||
| /** | ||
| * Sent by the server as the first message on a | ||
| * {@link SubscriptionsListenRequest | subscriptions/listen} stream to acknowledge | ||
| * that the subscription has been established and to report which notification | ||
| * types it agreed to honor. | ||
| * Sent by the server to acknowledge that a | ||
| * {@link SubscriptionsListenRequest | subscriptions/listen} subscription has been | ||
| * established and to report which notification types it agreed to honor. | ||
| * | ||
| * This notification MUST be the first message the server sends carrying the | ||
| * subscription's ID in `io.modelcontextprotocol/subscriptionId`. The server MUST | ||
| * NOT send any notification on the subscription before acknowledging it. On | ||
| * stdio, where every subscription shares one channel, this ordering is defined | ||
|
Comment on lines
+1363
to
+1370
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 The SDK's published JSDoc for Extended reasoning...What the bug isThis sync's only content change rewrites the spec JSDoc for Two SDK doc surfaces copied the superseded wording and become stale the moment this sync lands:
Why it matters
Step-by-step proof
Why nothing catches itNeither How to fixCompanion doc-only edit: update the |
||
| * per subscription ID and not per channel: messages belonging to other | ||
| * subscriptions MAY be interleaved before it. | ||
| * | ||
| * @example Listen acknowledged | ||
| * {@includeCode ./examples/SubscriptionsAcknowledgedNotification/listen-acknowledged.json} | ||
|
Comment on lines
+1363
to
1375
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Upstream spec-internal inconsistency introduced by this exact hunk's new MUST prose, to batch with the other schema.ts feedback: (1) the ack is required by prose to carry the subscription ID in Extended reasoning...What the new prose saysThis re-pull rewrites the Inconsistency 1 — the ack is not type-required to carry the ID it is defined byThe MUST presupposes the ack carries the subscription ID — that is the only thing that makes the per-subscription-ID ordering on stdio well-defined at all. But Inconsistency 2 — pre-ack graceful close makes the result the first ID-carrying messageThe MUST says first message, not notification — and the word choice is not accidental redundancy, because the very next sentence covers notifications separately ('MUST NOT send any notification on the subscription before acknowledging it'). So the first sentence's broader scope sweeps in JSON-RPC responses. But the spec REQUIRES the subscription ID on exactly one other message: Step-by-step proof
Why this is concrete, not hypotheticalThe shipped SDK client already encodes the lenient reading of inconsistency 2: the How to fixNo change to this automated sync itself (the file is DO-NOT-EDIT). Batch with the upstream schema.ts feedback already collected on this PR: (a) give the ack params a dedicated required-key meta interface (the |
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🔴 This spec sync makes
_meta['io.modelcontextprotocol/clientInfo']optional on requests ("Clients SHOULD include this field... unless specifically configured not to do so"), but the SDK's 2026-07-28 wire layer still hard-requires it —RequestMetaEnvelopeSchema(packages/core-internal/src/wire/rev2026-07-28/buildSchemas.ts:670) andREQUIRED_ENVELOPE_KEYS(codec.ts:60) — socheckInboundEnveloperejects every request from a spec-compliant client configured not to send clientInfo. As filed the PR also breakspnpm typecheck: the bidirectional drift-guard attest/spec.types.2026-07-28.test.ts:179fails with TS2322 because the SDK'sRequestMetaEnvelopetype still requires the key. A companion SDK update (optional key in the envelope schema/type, drop it fromREQUIRED_ENVELOPE_KEYS) is needed before merge.Extended reasoning...
What the bug is
This upstream sync changes
RequestMetaObject['io.modelcontextprotocol/clientInfo']from required to optional (this diff,spec.types.2026-07-28.ts:84-97), with new prose explicitly permitting clients to omit it: "Clients SHOULD include this field on every request unless specifically configured not to do so." The PR updates only the spec anchor file — no companion change to the SDK's 2026-07-28 wire layer, which still hard-requires the key in three places:packages/core-internal/src/wire/rev2026-07-28/buildSchemas.ts:670—RequestMetaEnvelopeSchemadeclares[CLIENT_INFO_META_KEY]: ImplementationSchema(non-optional) inside thez.looseObjectat line 657.packages/core-internal/src/wire/rev2026-07-28/codec.ts:60—REQUIRED_ENVELOPE_KEYSlistsCLIENT_INFO_META_KEY;checkInboundEnvelope(codec.ts:266-278)safeParses every inbound request envelope againstRequestMetaEnvelopeSchemaand returns an "Invalid_metaenvelope for protocol revision 2026-07-28" error naming clientInfo as required.packages/core-internal/src/types/types.ts:247-252— the SDK's neutralRequestMetaEnvelopetype also still requires the key.Failure 1 — CI goes red: the drift guard no longer compiles
The drift-guard test at
packages/core-internal/test/spec.types.2026-07-28.test.ts:178-181does a bidirectional assignment between the SDK envelope type and the spec type:With spec clientInfo now
Implementation | undefinedand the SDK envelope still requiringImplementation,sdk = specfails. This was empirically reproduced by three independent verifiers:tsc --noEmitonpackages/core-internalat the PR head exits non-zero withTS2322attest/spec.types.2026-07-28.test.ts(179,9)("Type 'undefined' is not assignable to type '{ name: string; version: string; ... }'"), plus ~10 cascading errors for every request type embedding the envelope (tools/call, prompts/get, resources/read, subscriptions/listen, etc., around lines 548 and 623-647). So merging as filed breakspnpm typecheck— and per this PR's own review history, CI never runs on the bot's GITHUB_TOKEN-pushed refresh branch, so the break would land on main silently.Failure 2 — spec-valid requests rejected at runtime
Step-by-step:
tools/callwith_metacarryingprotocolVersionandclientCapabilitiesbut noio.modelcontextprotocol/clientInfo.checkInboundEnvelope(codec.ts:266-278) runsRequestMetaEnvelopeSchema.safeParseon the envelope; the non-optional[CLIENT_INFO_META_KEY]atbuildSchemas.ts:670makes the parse fail._metaenvelope" error. Every request from that client is rejected, on every method, over both stdio and Streamable HTTP.This is exactly the repository's Schema Compliance recurring catch (REVIEW.md: over-strict Zod "rejects spec-valid payloads from other SDKs. Also confirm the
spec.types.*.test.tscomparisons still pass bidirectionally" — #1768, #1849, #1169). Both prongs of that catch fire here.Why nothing prevents it
The nightly cron regenerates only the anchor file; nothing in the automation touches the wire schemas, codec, or SDK types, and the drift-guard test that exists precisely to catch this divergence catches it only as a compile error — which never runs on this bot-pushed branch. The requiredness semantics changed upstream, and the SDK's companion update is genuine manual work this PR lacks.
How to fix
Companion SDK change in the same merge:
[CLIENT_INFO_META_KEY]optional inRequestMetaEnvelopeSchema(buildSchemas.ts:670) and in theRequestMetaEnvelopetype (types.ts:247-252).CLIENT_INFO_META_KEYfromREQUIRED_ENVELOPE_KEYS(codec.ts:60) and adjust any error-message text that names it.codec.ts:127outbound path is fine as-is — SHOULD-include remains the default behavior); only inbound validation and the type need loosening.pnpm typecheckto confirm the bidirectional drift guard is green again.Note: the separate
serverInfo/ResultMetaObjectaddition and theDiscoverResult.serverInforemoval in this same sync are distinct findings with their own companion work — this comment covers only the request-side clientInfo requiredness.