chore: update spec.types.ts from upstream #2027
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: e3f281c7243b7dfe4c0dca450230fe3d7de3cf8b | ||
| * | ||
| * 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 | ||
|
|
@@ -110,6 +110,29 @@ export interface RequestMetaObject extends MetaObject { | |
| 'io.modelcontextprotocol/logLevel'?: LoggingLevel; | ||
| } | ||
|
|
||
| /** | ||
| * Extends {@link MetaObject} with additional notification-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 NotificationMetaObject extends MetaObject { | ||
| /** | ||
| * Identifies the subscription stream a notification was delivered on. The | ||
| * server MUST include this key on every notification delivered via a | ||
| * {@link SubscriptionsListenRequest | subscriptions/listen} stream, so the | ||
| * client can correlate the notification with the originating subscription. | ||
| * The key is absent on notifications not delivered via a subscription | ||
| * stream (e.g. progress notifications for an in-flight request), which is | ||
| * why it is optional here. | ||
| * | ||
| * The value is the JSON-RPC ID of the `subscriptions/listen` request that | ||
| * opened the stream. | ||
| */ | ||
| 'io.modelcontextprotocol/subscriptionId'?: RequestId; | ||
| } | ||
|
|
||
| /** | ||
| * A progress token, used to associate progress notifications with the original request. | ||
| * | ||
|
|
@@ -147,7 +170,7 @@ export interface Request { | |
| * @category Common Types | ||
| */ | ||
| export interface NotificationParams { | ||
| _meta?: NotificationMetaObject; | ||
| } | ||
|
|
||
| /** @internal */ | ||
|
|
@@ -298,7 +321,7 @@ export interface InvalidRequestError extends Error { | |
| * | ||
| * In MCP, a server returns this error when a client invokes a method the server does not implement — either a genuinely unknown method, or one gated behind a server capability the server did not advertise (e.g., calling `prompts/list` when the `prompts` capability was not advertised). | ||
| * | ||
| * A request that requires a client capability the client did not declare is signalled instead by {@link MissingRequiredClientCapabilityError} (`-32021`). | ||
| * | ||
| * @see {@link https://www.jsonrpc.org/specification#error_object | JSON-RPC 2.0 Error Object} | ||
| * | ||
|
|
@@ -357,21 +380,67 @@ export interface InternalError extends Error { | |
| code: typeof INTERNAL_ERROR; | ||
| } | ||
|
|
||
| /* | ||
| * MCP error codes. | ||
| * | ||
| * JSON-RPC 2.0 reserves `-32000` to `-32099` for implementation-defined | ||
| * server errors. MCP partitions that range: | ||
| * | ||
| * - `-32000` to `-32019`: implementation-defined. Existing SDKs and | ||
| * implementations use codes here for their own purposes; the specification | ||
| * will never define codes in this sub-range, and receivers must not assign | ||
| * cross-implementation semantics to them. | ||
| * - `-32020` to `-32099`: reserved for error codes defined by the MCP | ||
| * specification. Every code allocated here is recorded in this file. | ||
| * Codes are allocated sequentially starting at `-32020` and proceeding | ||
| * toward `-32099`. | ||
| * | ||
| * Codes defined by earlier protocol versions remain reserved and are never | ||
| * reused: `-32002` (resource not found, 2025-11-25 and earlier; replaced by | ||
| * `-32602`) and `-32042` (URL elicitation required, 2025-11-25 only). | ||
|
Comment on lines
+396
to
+400
There was a problem hiding this comment. 🟡 Companion-work item: this sync's new error-code partition prose (spec.types.2026-07-28.ts:398-400) retires Extended reasoning...What changed in the specThis sync adds the new error-code partition comment (spec.types.2026-07-28.ts:396-400), which states that codes defined by earlier protocol versions remain reserved and are never reused, explicitly listing What the SDK still ships
Why nothing in CI surfaces itNeither Step-by-step proof
Why this is not an immediate defectThe SDK currently targets 2025-11-25 ( How to fix (companion-work scope)
|
||
| */ | ||
|
|
||
| /** | ||
| * Error code returned when the HTTP headers of a request do not match the | ||
| * corresponding values in the request body, or required headers are | ||
| * missing or malformed. | ||
| * | ||
| * @category Errors | ||
| */ | ||
| export const HEADER_MISMATCH = -32020; | ||
|
|
||
| /** | ||
| * Error code returned when a server requires a client capability that was | ||
| * not declared in the request's `clientCapabilities`. | ||
| * | ||
| * @category Errors | ||
| */ | ||
| export const MISSING_REQUIRED_CLIENT_CAPABILITY = -32021; | ||
|
|
||
| /** | ||
| * Error code returned when the request's protocol version is not supported | ||
| * by the server. | ||
| * | ||
| * @category Errors | ||
| */ | ||
| export const UNSUPPORTED_PROTOCOL_VERSION = -32022; | ||
|
Comment on lines
+405
to
+426
There was a problem hiding this comment. 🔴 This re-pull repartitions the MCP error-code range (-32000..-32019 implementation-defined, -32020..-32099 spec-reserved) and renumbers the spec constants — HEADER_MISMATCH is now -32020, MISSING_REQUIRED_CLIENT_CAPABILITY moves -32003 → -32021, and UNSUPPORTED_PROTOCOL_VERSION moves -32004 → -32022 — so the SDK's ProtocolErrorCode.MissingRequiredClientCapability/UnsupportedProtocolVersion members (enums.ts:19/24) and the public UnsupportedProtocolVersionError class (errors.ts) now carry the wrong wire values for the 2026-07-28 revision they document, and the spec.types.2026-07-28.test.ts assertions pinning -32003/-32004 fail. The new partition also makes prior comment #3433435413 partially stale: the transport's -32000/-32001 codes (e.g. the 404/-32001 'Session not found' response) now sit in the implementation-defined sub-range and no longer collide with HeaderMismatchError, so any ProtocolErrorCode.HeaderMismatch member added by the companion work must use -32_020, not -32_001. The remaining HeaderMismatchError gap (no SDK schema/types/specTypeSchema registration, no sdkTypeChecks or allowlist entry, and the snapshot now exporting 151 types vs the hardcoded toHaveLength(150)) still stands and keeps the 2026-07-28 drift guard red. Extended reasoning...What changedThis re-pull introduces an explicit partition of the JSON-RPC implementation-defined error range (spec.types.2026-07-28.ts:383-401): SDK surface that is now staleThe SDK recently added (per the 2026-06-17 status update) Prior -32001 guidance is now staleInline comment #3433435413 was written against the previous revision where What remains valid from the prior commentThe missing SDK surface for Step-by-step proof
How to fix (companion work)Renumber |
||
|
|
||
| /** | ||
| * Returned when a server rejects a request because the values in the HTTP | ||
| * headers do not match the corresponding values in the request body, or | ||
| * because required headers are missing or malformed. For HTTP, the response | ||
| * status code MUST be `400 Bad Request`. | ||
| * | ||
| * @example Header mismatch | ||
| * {@includeCode ./examples/HeaderMismatchError/header-mismatch.json} | ||
| * | ||
| * @category Errors | ||
| */ | ||
| export interface HeaderMismatchError extends Omit<JSONRPCErrorResponse, 'error'> { | ||
| error: Error & { | ||
| code: typeof HEADER_MISMATCH; | ||
| }; | ||
|
Comment on lines
425
to
+442
There was a problem hiding this comment. 🔴 The spec now reserves Extended reasoning...What changed in the specThis sync adds a dedicated error code and envelope for header/body mismatches on the Streamable HTTP transport (spec.types.2026-07-28.ts:390 and ~408-422): export const HEADER_MISMATCH = -32001;
export interface HeaderMismatchError extends Omit<JSONRPCErrorResponse, 'error'> {
error: Error & {
code: typeof HEADER_MISMATCH;
};
}The JSDoc is normative: it is returned "when a server rejects a request because the values in the HTTP headers do not match the corresponding values in the request body, or because required headers are missing or malformed", and "For HTTP, the response status code MUST be Gap 1 — wire-code collision with the SDK's existing
|
||
| } | ||
|
|
||
| /** | ||
| * Returned when the request's protocol version is unknown to the server or | ||
|
|
@@ -517,9 +586,9 @@ export interface CancelledNotificationParams extends NotificationParams { | |
| /** | ||
| * The ID of the request to cancel. | ||
| * | ||
| * This MUST correspond to the ID of a request the client previously issued. | ||
| */ | ||
| requestId: RequestId; | ||
|
Comment on lines
586
to
+591
There was a problem hiding this comment. 🔴 This sync makes Extended reasoning...What changed in the specThis re-pull (91b403f8) changes What the SDK still ships
How the drift guard breaks
Step-by-step proof:
Why the existing porting checklist points away from thisPrior comment #3368827092 (2026-06-07) examined this exact field while both sides were optional and explicitly concluded: 'the bidirectional ImpactCI for the 2026-07-28 drift guard goes red on these two entries (on top of the other documented breakage on this held sync). More importantly, the companion work has a genuine wire-compatibility decision to make that no existing comment records: the 2025-11-25 snapshot (and the deliberately retained 2025-11-25 wire surface from #2248) still permits How to fix (companion work)Pick one of:
Either way, also update the stale 'previously issued in the same direction' JSDoc at schemas.ts:213 to the new client-direction wording (plus the stdio |
||
|
|
||
| /** | ||
| * An optional string describing the reason for the cancellation. This MAY be logged or presented to the user. | ||
|
|
@@ -528,7 +597,9 @@ export interface CancelledNotificationParams extends NotificationParams { | |
| } | ||
|
|
||
| /** | ||
| * This notification is sent by the client to indicate that it is cancelling a request it previously issued. | ||
| * | ||
| * On stdio, the server also sends this notification, solely to terminate a {@link SubscriptionsListenRequest | subscriptions/listen} stream: it references the ID of the `subscriptions/listen` request that opened the stream. Servers MUST NOT use this notification to cancel any other request. | ||
| * | ||
|
Comment on lines
597
to
603
There was a problem hiding this comment. 🟡 Companion-work scoping note: the rewritten Extended reasoning...What changed in the specThis re-pull rewrites the What the SDK does today
Step-by-step proof (once the companion subscriptions/listen work lands)
Why nothing in CI surfaces it and why existing comments don't cover it
ImpactUntil addressed, the only spec-defined way to end a How to fix (companion work, not this automated sync)When implementing |
||
| * The request SHOULD still be in-flight, but due to communication latency, it is always possible that this notification MAY arrive after the request has already finished. | ||
| * | ||
|
|
@@ -569,7 +640,7 @@ export interface DiscoverRequest extends JSONRPCRequest { | |
| * | ||
| * @category `server/discover` | ||
| */ | ||
| export interface DiscoverResult extends CacheableResult { | ||
| /** | ||
| * MCP Protocol Versions this server supports. The client should choose a | ||
| * version from this list for use in subsequent requests. | ||
|
|
@@ -674,6 +745,9 @@ export interface ClientCapabilities { | |
| * (e.g., "io.modelcontextprotocol/oauth-client-credentials"), and values are | ||
| * per-extension settings objects. An empty object indicates support with no settings. | ||
| * | ||
| * Keys MUST follow the {@link MetaObject | `_meta` key naming rules}, with a | ||
| * mandatory prefix. | ||
| * | ||
| * @example Extensions — MCP Apps (UI) extension with MIME type support | ||
| * {@includeCode ./examples/ClientCapabilities/extensions-ui-mime-types.json} | ||
| */ | ||
|
|
@@ -768,6 +842,9 @@ export interface ServerCapabilities { | |
| * (e.g., "io.modelcontextprotocol/tasks"), and values are per-extension settings | ||
| * objects. An empty object indicates support with no settings. | ||
| * | ||
| * Keys MUST follow the {@link MetaObject | `_meta` key naming rules}, with a | ||
| * mandatory prefix. | ||
| * | ||
| * @example Extensions — Tasks extension support | ||
| * {@includeCode ./examples/ServerCapabilities/extensions-tasks.json} | ||
| */ | ||
|
|
@@ -989,11 +1066,13 @@ export interface CacheableResult extends Result { | |
| * Indicates the intended scope of the cached response, analogous to HTTP | ||
| * `Cache-Control: public` vs `Cache-Control: private`. | ||
| * | ||
| * - `"public"`: The response does not contain user-specific data. Any | ||
| * client or intermediary (e.g., shared gateway, caching proxy) MAY cache | ||
| * the response and serve it across authorization contexts. | ||
| * - `"private"`: The response MAY be cached and reused only within the | ||
| * same authorization context. Caches MUST NOT be shared across | ||
| * authorization contexts (e.g., a different access token requires a | ||
| * different cache). | ||
| * | ||
| */ | ||
| cacheScope: 'public' | 'private'; | ||
|
|
@@ -1134,7 +1213,7 @@ export interface ReadResourceResultResponse extends JSONRPCResultResponse { | |
| } | ||
|
|
||
| /** | ||
| * An optional notification from the server to the client, informing it that the list of resources it can read from has changed. This is only delivered on a {@link SubscriptionsListenRequest | subscriptions/listen} stream when the client requested it via the `resourcesListChanged` filter field. | ||
| * | ||
| * @example Resources list changed | ||
| * {@includeCode ./examples/ResourceListChangedNotification/resources-list-changed.json} | ||
|
|
@@ -1578,7 +1657,7 @@ export interface EmbeddedResource { | |
| _meta?: MetaObject; | ||
| } | ||
| /** | ||
| * An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This is only delivered on a {@link SubscriptionsListenRequest | subscriptions/listen} stream when the client requested it via the `promptsListChanged` filter field. | ||
| * | ||
| * @example Prompts list changed | ||
| * {@includeCode ./examples/PromptListChangedNotification/prompts-list-changed.json} | ||
|
|
@@ -1720,7 +1799,7 @@ export interface CallToolRequest extends JSONRPCRequest { | |
| } | ||
|
|
||
| /** | ||
| * An optional notification from the server to the client, informing it that the list of tools it offers has changed. This is only delivered on a {@link SubscriptionsListenRequest | subscriptions/listen} stream when the client requested it via the `toolsListChanged` filter field. | ||
| * | ||
| * @example Tools list changed | ||
| * {@includeCode ./examples/ToolListChangedNotification/tools-list-changed.json} | ||
|
|
@@ -1822,6 +1901,11 @@ export interface Tool extends BaseMetadata, Icons { | |
| * (`if`/`then`/`else`), reference keywords (`$ref`, `$defs`, `$anchor`), and any other | ||
| * standard validation or annotation keywords. | ||
| * | ||
| * Property schemas may carry an `x-mcp-header` annotation to mirror the | ||
| * argument value into an HTTP header on the Streamable HTTP transport. See | ||
| * the Streamable HTTP transport specification for the validity and | ||
| * extraction rules. | ||
| * | ||
| * Defaults to JSON Schema 2020-12 when no explicit `$schema` is provided. | ||
|
Comment on lines
+1904
to
1909
There was a problem hiding this comment. 🟡 Companion-work scoping: this revision adds JSDoc to Extended reasoning...What changed in the specThis sync adds new JSDoc prose to Why neither transport supports itA grep for Why this is silent and not covered by the existing checklistThis is the same silent-transport-divergence class already accepted repeatedly on this PR (#3239359153 GET→ Step-by-step proof
Impact and how to fixThis is not a defect introduced by this automated sync — the PR is already held pending the companion 2026-07-28 redesign — but it is a transport-level feature the existing companion-work comments do not enumerate. The companion port should: (a) on the client transport, when sending |
||
| */ | ||
| inputSchema: { $schema?: string; type: 'object'; [key: string]: unknown }; | ||
|
|
@@ -2533,7 +2617,9 @@ export interface PromptReference extends BaseMetadata { | |
| */ | ||
| export interface ListRootsRequest { | ||
| method: 'roots/list'; | ||
| params?: { | ||
| _meta?: MetaObject; | ||
| }; | ||
| } | ||
|
|
||
| /** | ||
|
|
@@ -2643,12 +2729,6 @@ export interface ElicitRequestURLParams { | |
| */ | ||
| message: string; | ||
|
|
||
| /** | ||
| * The URL that the user should navigate to. | ||
| * | ||
|
Comment on lines
2729
to
2734
There was a problem hiding this comment. 🔴 This spec sync deletes the entire URL-elicitation completion surface — the required Extended reasoning...What changed in the specThis re-pull (91b403f) removes the correlation/completion machinery for URL-mode elicitation in two coordinated deletions:
These are two halves of one surface: What the SDK still ships
How it breaks the drift guard
(One nuance: Step-by-step proof
Why this isn't covered by existing commentsPrior comment #3239359156 flagged the delivery-channel gap for How to fix (companion work)
Comment on lines
2729
to
2734
There was a problem hiding this comment. 🟡 This sync deletes the URL-elicitation completion flow from the 2026-07-28 revision ( Extended reasoning...What changed in the specThis re-pull (e3f281c7) removes the URL-elicitation completion machinery from the 2026-07-28 revision: the required What the SDK still ships at runtime (not covered by the existing schema/test comment)Inline comment #3433435404 already covers the schema/test surface for this deletion (
Why this is silentserver.ts and the example apps have no compile-time link to Step-by-step scenario
How to fix (companion-work scope)The SDK's wire surface deliberately targets 2025-11-25 (where this flow still exists), so removal is not the ask — version-scoping/deprecation is, mirroring how the SEP-2577 tier and the -32042 mechanism (#3440492937) were handled:
Filed as a nit in the same companion-work-scoping tier as the other accepted silent-divergence findings on this held PR; it does not independently break CI. |
||
|
|
@@ -2963,24 +3043,6 @@ export interface ElicitResult { | |
| content?: { [key: string]: string | number | boolean | string[] }; | ||
| } | ||
|
|
||
| /* Client messages */ | ||
| /** @internal */ | ||
| export type ClientRequest = | ||
|
|
@@ -2996,7 +3058,7 @@ export type ClientRequest = | |
| | ListToolsRequest; | ||
|
|
||
| /** @internal */ | ||
| export type ClientNotification = CancelledNotification; | ||
|
|
||
| /** @internal */ | ||
| export type ClientResult = EmptyResult; | ||
|
|
@@ -3012,7 +3074,6 @@ export type ServerNotification = | |
| | ResourceListChangedNotification | ||
| | ToolListChangedNotification | ||
| | PromptListChangedNotification | ||
| | SubscriptionsAcknowledgedNotification; | ||
|
|
||
| /** @internal */ | ||
|
|
||
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 sync adds a new exported
NotificationMetaObjectinterface (carrying the reservedio.modelcontextprotocol/subscriptionIdmeta key) and changesNotificationParams._metafromMetaObjectto it, but the SDK has noNotificationMetaObjectSchemaand the drift-guard test has neither ansdkTypeChecksentry nor aMISSING_SDK_TYPES_2026_07_28allowlist entry for the new name — so the coverage check and the hardcoded export-count assertion inspec.types.2026-07-28.test.tsboth fail. The companion port also needs to note that notifications now require their own meta shape (distinct from both request and result meta), which extends the two-wayRequestMetaSchema/MetaObjectSchemasplit prescribed in #3278874070 into a three-way split, and that the eventualsubscriptions/listenserver implementation MUST stampsubscriptionIdon every stream-delivered notification.Extended reasoning...
What changed
This re-pull adds
export interface NotificationMetaObject extends MetaObjectatpackages/core/src/types/spec.types.2026-07-28.ts:120, defining the reserved key'io.modelcontextprotocol/subscriptionId'?: RequestId— the JSON-RPC ID of thesubscriptions/listenrequest that opened the stream, which the server MUST include on every notification delivered via that stream (and omit on notifications not delivered via a subscription stream, e.g. progress notifications for an in-flight request). The same hunk changesNotificationParams._metafromMetaObjecttoNotificationMetaObject(spec.types.2026-07-28.ts:173).Why the drift guard goes red on this name
packages/core/test/spec.types.2026-07-28.test.tsextracts everyexport interface|class|typename from the snapshot and asserts each one not inMISSING_SDK_TYPES_2026_07_28(lines 381-491) has ansdkTypeChecksentry; it also hardcodesexpect(specTypes).toHaveLength(150)at line 521.NotificationMetaObjectappears nowhere in the test file (grep: 0 matches), so:should have comprehensive compatibility testsfails withNotificationMetaObjectinmissingTests(line 539'stoHaveLength(0)).grep -cE '^export (interface|class|type) '= 151), so thetoHaveLength(150)assertion at line 521 fails.Step-by-step: (1)
extractExportedTypespicks up'NotificationMetaObject'from line 120; (2) the allowlist at lines 381-491 does not contain it; (3)sdkTypeChecks['NotificationMetaObject']isundefined→ the name lands inmissingTests→ assertion fails; (4) independently, 151 ≠ 150 fails the count check. None of the existing porting checklists on this PR (#3223937253's additive batch, #3206453749, #3252228073, or the later corrections) enumerate this export, so a porter working through them would still have a red coverage check on this one name.Why the SDK side is also a real gap, not just a test-file addition
A grep across
packages/core/srcfindsNotificationMetaObjectandio.modelcontextprotocol/subscriptionIdonly in the spec snapshot — there is noNotificationMetaObjectSchemainschemas.ts, notypes.tsalias, and noSUBSCRIPTION_ID_META_KEYconstant.NotificationsParamsSchema._metacurrently reusesRequestMetaSchema(schemas.ts:110), and the test file does have ansdkTypeChecks.NotificationParamsbidirectional entry (test line 77), so the spec-side change ofNotificationParams._metamakes that check relevant: the notification meta shape now carries an optionalRequestId-typed reserved key the SDK schema does not model.This also invalidates the prescription in #3278874070, which directed the companion port to split the shared
RequestMetaSchematwo ways — a request-directionRequestMetaSchemaforBaseRequestParamsSchemaand a bareMetaObjectSchemaforResultSchemaandNotificationsParamsSchema. After this revision, notifications need their own meta shape (bareMetaObjectplus the optionalsubscriptionIdkey), distinct from both the request meta and the bare result meta — i.e. a three-way split (RequestMetaSchema/NotificationMetaObjectSchema/MetaObjectSchema), not the two-way one the existing comment prescribes. A porter following #3278874070 verbatim would wireNotificationsParamsSchema._metato the bareMetaObjectSchemaand the bidirectional/exact-keys checks would still need the subscriptionId-bearing shape.Companion-work scoping (server side)
The MUST-include rule is a server-side delivery requirement: when the eventual
subscriptions/listenimplementation lands (per the existing transport-layer comments #3239359153/#3246176899), every notification routed onto a subscription stream must be stamped with_meta['io.modelcontextprotocol/subscriptionId'] = <id of the listen request>. No notification-emit path inpackages/serverstamps any subscription correlation key today, and no existing porting checklist names this requirement.How to fix
In the companion PR (this automated sync is already held for that work): add
NotificationMetaObjectSchematoschemas.ts(bare loose meta object plus optional'io.modelcontextprotocol/subscriptionId': RequestIdSchema), pointNotificationsParamsSchema._metaat it (adjusting the #3278874070 split to three-way), export theSUBSCRIPTION_ID_META_KEYconstant, add thesdkTypeChecks.NotificationMetaObjectentry (or an allowlist entry if the SDK chooses not to model it), bump thetoHaveLengthcount once all deltas are reconciled, and include the stamp-subscriptionId-on-stream-delivery requirement in thesubscriptions/listenserver implementation's scope.