From 792b5342dd34e9476ec2911d8511bfec37f3812a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 21 Aug 2026 04:26:45 +0000 Subject: [PATCH] chore: update spec.types.2026-07-28.ts from upstream --- .../core/src/types/spec.types.2026-07-28.ts | 252 ++++++++++++++---- 1 file changed, 197 insertions(+), 55 deletions(-) diff --git a/packages/core/src/types/spec.types.2026-07-28.ts b/packages/core/src/types/spec.types.2026-07-28.ts index 7305df0462..0b8d1eaf5d 100644 --- a/packages/core/src/types/spec.types.2026-07-28.ts +++ b/packages/core/src/types/spec.types.2026-07-28.ts @@ -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: 9d700ed62dcf86cb77475c9b81930611a9182f46 + * Last updated from commit: f7e99af6417ec978233d8e27e1ac878b12106542 * * 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 @@ -82,12 +82,19 @@ export interface RequestMetaObject extends MetaObject { */ '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; /** * The client's capabilities for this specific request. Required. * @@ -110,6 +117,53 @@ 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; +} + +/** + * 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. * @@ -147,7 +201,7 @@ export interface Request { * @category Common Types */ export interface NotificationParams { - _meta?: MetaObject; + _meta?: NotificationMetaObject; } /** @internal */ @@ -174,7 +228,7 @@ export type ResultType = 'complete' | 'input_required' | string; * @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. @@ -298,7 +352,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} (`-32003`). + * 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,13 +411,42 @@ 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). + */ + +/** + * 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 = -32003; +export const MISSING_REQUIRED_CLIENT_CAPABILITY = -32021; /** * Error code returned when the request's protocol version is not supported @@ -371,7 +454,24 @@ export const MISSING_REQUIRED_CLIENT_CAPABILITY = -32003; * * @category Errors */ -export const UNSUPPORTED_PROTOCOL_VERSION = -32004; +export const UNSUPPORTED_PROTOCOL_VERSION = -32022; + +/** + * 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 { + error: Error & { + code: typeof HEADER_MISMATCH; + }; +} /** * Returned when the request's protocol version is unknown to the server or @@ -517,9 +617,9 @@ export interface CancelledNotificationParams extends NotificationParams { /** * The ID of the request to cancel. * - * This MUST correspond to the ID of a request previously issued in the same direction. + * This MUST correspond to the ID of a request the client previously issued. */ - requestId?: RequestId; + requestId: RequestId; /** * An optional string describing the reason for the cancellation. This MAY be logged or presented to the user. @@ -528,7 +628,9 @@ export interface CancelledNotificationParams extends NotificationParams { } /** - * This notification can be sent by either side to indicate that it is cancelling a previously-issued request. + * 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. * * 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 +671,7 @@ export interface DiscoverRequest extends JSONRPCRequest { * * @category `server/discover` */ -export interface DiscoverResult extends Result { +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. @@ -579,10 +681,6 @@ export interface DiscoverResult extends Result { * The capabilities of the server. */ capabilities: ServerCapabilities; - /** - * Information about the server software implementation. - */ - serverInfo: Implementation; /** * Natural-language guidance describing the server and its features. * @@ -674,6 +772,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 +869,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 +1093,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"`: Any client or intermediary (e.g., shared gateway, proxy) - * MAY cache the response and serve it to any user. - * - `"private"`: Only the requesting user's client MAY cache the response. - * Shared caches (e.g., multi-tenant gateways) MUST NOT serve a cached - * copy to a different user. + * - `"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 +1240,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 may be issued by servers without any previous subscription from the client. + * 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} @@ -1204,6 +1310,53 @@ export interface SubscriptionsListenRequest extends JSONRPCRequest { params: SubscriptionsListenRequestParams; } +/** + * 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 SubscriptionsListenResultMetaObject extends ResultMetaObject { + /** + * Identifies the subscription stream this response closes, so the client can + * correlate it with the originating subscription — mirroring the same key on + * the stream's notifications. The value is the JSON-RPC ID of the + * `subscriptions/listen` request that opened the stream (and equals this + * response's `id`). + */ + 'io.modelcontextprotocol/subscriptionId': RequestId; +} + +/** + * The response to a {@link SubscriptionsListenRequest | subscriptions/listen} + * request, signalling that the subscription has ended gracefully (for example, + * during server shutdown). Because the listen stream is long-lived, this result + * is sent only when the server tears the subscription down; an abrupt transport + * close carries no response. The result body is otherwise empty. + * + * @example Subscription closed gracefully + * {@includeCode ./examples/SubscriptionsListenResult/listen-closed.json} + * + * @category `subscriptions/listen` + */ +export interface SubscriptionsListenResult extends Result { + _meta: SubscriptionsListenResultMetaObject; +} + +/** + * A successful response from the server for a {@link SubscriptionsListenRequest | subscriptions/listen} + * request, sent when the server tears the subscription down gracefully. + * + * @example Subscription closed gracefully response + * {@includeCode ./examples/SubscriptionsListenResultResponse/listen-closed-response.json} + * + * @category `subscriptions/listen` + */ +export interface SubscriptionsListenResultResponse extends JSONRPCResultResponse { + result: SubscriptionsListenResult; +} + /** * Parameters for a {@link SubscriptionsAcknowledgedNotification | notifications/subscriptions/acknowledged} notification. * @@ -1220,10 +1373,16 @@ export interface SubscriptionsAcknowledgedNotificationParams extends Notificatio } /** - * 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 + * 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} @@ -1578,7 +1737,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 may be issued by servers without any previous subscription from the client. + * 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 +1879,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 may be issued by servers without any previous subscription from the client. + * 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 +1981,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. */ inputSchema: { $schema?: string; type: 'object'; [key: string]: unknown }; @@ -2533,7 +2697,9 @@ export interface PromptReference extends BaseMetadata { */ export interface ListRootsRequest { method: 'roots/list'; - params?: RequestParams; + params?: { + _meta?: MetaObject; + }; } /** @@ -2643,12 +2809,6 @@ export interface ElicitRequestURLParams { */ message: string; - /** - * The ID of the elicitation, which must be unique within the context of the server. - * The client MUST treat this ID as an opaque value. - */ - elicitationId: string; - /** * The URL that the user should navigate to. * @@ -2963,24 +3123,6 @@ export interface ElicitResult { content?: { [key: string]: string | number | boolean | string[] }; } -/** - * An optional notification from the server to the client, informing it of a completion of a out-of-band elicitation request. - * - * @example Elicitation complete - * {@includeCode ./examples/ElicitationCompleteNotification/elicitation-complete.json} - * - * @category `notifications/elicitation/complete` - */ -export interface ElicitationCompleteNotification extends JSONRPCNotification { - method: 'notifications/elicitation/complete'; - params: { - /** - * The ID of the elicitation that completed. - */ - elicitationId: string; - }; -} - /* Client messages */ /** @internal */ export type ClientRequest = @@ -2996,7 +3138,7 @@ export type ClientRequest = | ListToolsRequest; /** @internal */ -export type ClientNotification = CancelledNotification | ProgressNotification; +export type ClientNotification = CancelledNotification; /** @internal */ export type ClientResult = EmptyResult; @@ -3012,7 +3154,6 @@ export type ServerNotification = | ResourceListChangedNotification | ToolListChangedNotification | PromptListChangedNotification - | ElicitationCompleteNotification | SubscriptionsAcknowledgedNotification; /** @internal */ @@ -3025,6 +3166,7 @@ export type ServerResult = | ListResourceTemplatesResult | ListResourcesResult | ReadResourceResult + | SubscriptionsListenResult | CallToolResult | ListToolsResult | InputRequiredResult;