feat(core): per-revision spec reference types and the 2026-07-28 wire contract surface (#2252)

Author: felixweinberger

.changeset/spec-reference-types-2026-07-28.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/codemod': patch
+---
+
+Add per-revision spec reference types (2025-11-25 and 2026-07-28) with split comparison tests, and the 2026-07-28 wire contract surface: request-meta key constants, `RequestMetaEnvelopeSchema`, `server/discover` shapes, the typed `-32004` error, the `-32003` code constant, and a `resultType` passthrough on the base result. Types and constants only — no behavior changes.

.github/workflows/update-spec-types.yml

@@ -34,16 +34,16 @@ jobs:
               run: pnpm install
 
             - name: Fetch latest spec types
-              run: pnpm run fetch:spec-types
+              run: pnpm run fetch:spec-types 2026-07-28
 
             - name: Check for changes
               id: check_changes
               run: |
-                  if git diff --quiet packages/core/src/types/spec.types.ts; then
+                  if git diff --quiet packages/core/src/types/spec.types.2026-07-28.ts; then
                     echo "has_changes=false" >> $GITHUB_OUTPUT
                   else
                     echo "has_changes=true" >> $GITHUB_OUTPUT
-                    LATEST_SHA=$(grep "Last updated from commit:" packages/core/src/types/spec.types.ts | cut -d: -f2 | tr -d ' ')
+                    LATEST_SHA=$(grep "Last updated from commit:" packages/core/src/types/spec.types.2026-07-28.ts | cut -d: -f2 | tr -d ' ')
                     echo "sha=$LATEST_SHA" >> $GITHUB_OUTPUT
                   fi
 
@@ -59,12 +59,12 @@ jobs:
                   git config user.email "github-actions[bot]@users.noreply.github.com"
 
                   git checkout -B update-spec-types
-                  git add packages/core/src/types/spec.types.ts
-                  git commit -m "chore: update spec.types.ts from upstream"
+                  git add packages/core/src/types/spec.types.2026-07-28.ts
+                  git commit -m "chore: update spec.types.2026-07-28.ts from upstream"
                   git push -f --no-verify origin update-spec-types
 
                   # Create PR if it doesn't exist, or update if it does
-                  PR_BODY="This PR updates \`packages/core/src/types/spec.types.ts\` from the Model Context Protocol specification.
+                  PR_BODY="This PR updates \`packages/core/src/types/spec.types.2026-07-28.ts\` from the Model Context Protocol specification.
 
                   Source file: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/${{ steps.check_changes.outputs.sha }}/schema/draft/schema.ts
 
@@ -77,7 +77,7 @@ jobs:
                     gh pr edit "$EXISTING_PR" --body "$PR_BODY"
                   else
                     gh pr create \
-                      --title "chore: update spec.types.ts from upstream" \
+                      --title "chore: update spec.types.2026-07-28.ts from upstream" \
                       --body "$PR_BODY" \
                       --base main \
                       --head update-spec-types

.prettierignore

@@ -10,7 +10,8 @@ node_modules
 pnpm-lock.yaml
 
 # Ignore generated files
-src/spec.types.ts
+**/src/types/spec.types.2025-11-25.ts
+**/src/types/spec.types.2026-07-28.ts
 
 # Batch test cloned repos and results
 packages/codemod/batch-test/repos

REVIEW.md

@@ -75,7 +75,7 @@ When verifying spec compliance, consult the spec directly rather than relying on
 
 ### Schema Compliance
 
-- When editing Zod protocol schemas in `schemas.ts`, verify unknown-key handling matches the spec `schema.ts`: if the spec type has no `additionalProperties: false`, the SDK schema must use `z.looseObject()` / `.catchall(z.unknown())` rather than implicit strict — over-strict Zod (incl. `z.literal('object')` on `type`) rejects spec-valid payloads from other SDKs. Also confirm `spec.types.test.ts` still passes bidirectionally. (#1768, #1849, #1169)
+- When editing Zod protocol schemas in `schemas.ts`, verify unknown-key handling matches the spec `schema.ts`: if the spec type has no `additionalProperties: false`, the SDK schema must use `z.looseObject()` / `.catchall(z.unknown())` rather than implicit strict — over-strict Zod (incl. `z.literal('object')` on `type`) rejects spec-valid payloads from other SDKs. Also confirm the `spec.types.*.test.ts` comparisons still pass bidirectionally. (#1768, #1849, #1169)
 
 ### Async / Lifecycle
 

common/eslint-config/eslint.config.mjs

@@ -96,7 +96,7 @@ export default defineConfig(
     },
     {
         // Ignore generated protocol types everywhere
-        ignores: ['**/spec.types.ts']
+        ignores: ['**/spec.types.2025-11-25.ts', '**/spec.types.2026-07-28.ts']
     },
     {
         files: ['packages/client/**/*.ts', 'packages/server/**/*.ts'],

packages/codemod/src/generated/specSchemaMap.ts

@@ -27,6 +27,8 @@ export const SPEC_SCHEMA_NAMES: ReadonlySet<string> = new Set([
     'CreateMessageResultWithToolsSchema',
     'CreateTaskResultSchema',
     'CursorSchema',
+    'DiscoverRequestSchema',
+    'DiscoverResultSchema',
     'ElicitRequestFormParamsSchema',
     'ElicitRequestParamsSchema',
     'ElicitRequestSchema',
@@ -112,6 +114,7 @@ export const SPEC_SCHEMA_NAMES: ReadonlySet<string> = new Set([
     'ReadResourceResultSchema',
     'RelatedTaskMetadataSchema',
     'RequestIdSchema',
+    'RequestMetaEnvelopeSchema',
     'RequestMetaSchema',
     'RequestSchema',
     'ResourceContentsSchema',

packages/core/src/exports/public/index.ts

@@ -71,14 +71,18 @@ export * from '../../types/types.js';
 
 // Constants
 export {
+    CLIENT_CAPABILITIES_META_KEY,
+    CLIENT_INFO_META_KEY,
     DEFAULT_NEGOTIATED_PROTOCOL_VERSION,
     INTERNAL_ERROR,
     INVALID_PARAMS,
     INVALID_REQUEST,
     JSONRPC_VERSION,
     LATEST_PROTOCOL_VERSION,
+    LOG_LEVEL_META_KEY,
     METHOD_NOT_FOUND,
     PARSE_ERROR,
+    PROTOCOL_VERSION_META_KEY,
     RELATED_TASK_META_KEY,
     SUPPORTED_PROTOCOL_VERSIONS
 } from '../../types/constants.js';
@@ -87,7 +91,7 @@ export {
 export { ProtocolErrorCode } from '../../types/enums.js';
 
 // Error classes
-export { ProtocolError, UrlElicitationRequiredError } from '../../types/errors.js';
+export { ProtocolError, UnsupportedProtocolVersionError, UrlElicitationRequiredError } from '../../types/errors.js';
 
 // Type guards and message parsing
 export {

packages/core/src/types/constants.ts

@@ -4,6 +4,39 @@ export const SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION, '2025-06-18
 
 export const RELATED_TASK_META_KEY = 'io.modelcontextprotocol/related-task';
 
+/* Reserved `_meta` keys for the per-request envelope (protocol revision 2026-07-28) */
+
+/**
+ * `_meta` key carrying the MCP protocol version governing a request.
+ *
+ * For the HTTP transport, the value must match the `MCP-Protocol-Version` header.
+ */
+export const PROTOCOL_VERSION_META_KEY = 'io.modelcontextprotocol/protocolVersion';
+
+/**
+ * `_meta` key identifying the client software making a request.
+ */
+export const CLIENT_INFO_META_KEY = 'io.modelcontextprotocol/clientInfo';
+
+/**
+ * `_meta` key carrying the client's capabilities for a request.
+ *
+ * Capabilities are declared per request rather than once at initialization;
+ * servers must not infer capabilities from prior requests.
+ */
+export const CLIENT_CAPABILITIES_META_KEY = 'io.modelcontextprotocol/clientCapabilities';
+
+/**
+ * `_meta` key carrying the desired log level for a request.
+ *
+ * When absent, the server must not send `notifications/message` notifications
+ * for the request.
+ *
+ * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577); remains
+ * in the specification for at least twelve months.
+ */
+export const LOG_LEVEL_META_KEY = 'io.modelcontextprotocol/logLevel';
+
 /* JSON-RPC types */
 export const JSONRPC_VERSION = '2.0';
 

packages/core/src/types/enums.ts

@@ -12,5 +12,15 @@ export enum ProtocolErrorCode {
 
     // MCP-specific error codes
     ResourceNotFound = -32_002,
+    /**
+     * Processing the request requires a capability the client did not declare
+     * in the request's `clientCapabilities` (protocol revision 2026-07-28).
+     */
+    MissingRequiredClientCapability = -32_003,
+    /**
+     * The request's protocol version is unknown to the server or unsupported
+     * by it (protocol revision 2026-07-28).
+     */
+    UnsupportedProtocolVersion = -32_004,
     UrlElicitationRequired = -32_042
 }

packages/core/src/types/errors.ts

@@ -1,5 +1,5 @@
 import { ProtocolErrorCode } from './enums.js';
-import type { ElicitRequestURLParams } from './types.js';
+import type { ElicitRequestURLParams, UnsupportedProtocolVersionErrorData } from './types.js';
 
 /**
  * Protocol errors are JSON-RPC errors that cross the wire as error responses.
@@ -27,6 +27,13 @@ export class ProtocolError extends Error {
             }
         }
 
+        if (code === ProtocolErrorCode.UnsupportedProtocolVersion && data) {
+            const errorData = data as Partial<UnsupportedProtocolVersionErrorData>;
+            if (Array.isArray(errorData.supported) && typeof errorData.requested === 'string') {
+                return new UnsupportedProtocolVersionError({ supported: errorData.supported, requested: errorData.requested }, message);
+            }
+        }
+
         // Default to generic ProtocolError
         return new ProtocolError(code, message, data);
     }
@@ -47,3 +54,32 @@ export class UrlElicitationRequiredError extends ProtocolError {
         return (this.data as { elicitations: ElicitRequestURLParams[] })?.elicitations ?? [];
     }
 }
+
+/**
+ * Error type for the `-32004` UnsupportedProtocolVersion protocol error (protocol
+ * revision 2026-07-28): the request's protocol version is unknown to the server or
+ * unsupported by it.
+ *
+ * The error data lists the protocol versions the receiver supports (`supported`),
+ * so the sender can choose a mutually supported version and retry, and echoes the
+ * version that was requested (`requested`).
+ */
+export class UnsupportedProtocolVersionError extends ProtocolError {
+    constructor(data: UnsupportedProtocolVersionErrorData, message: string = `Unsupported protocol version: ${data.requested}`) {
+        super(ProtocolErrorCode.UnsupportedProtocolVersion, message, data);
+    }
+
+    /**
+     * Protocol versions the receiver supports.
+     */
+    get supported(): string[] {
+        return (this.data as UnsupportedProtocolVersionErrorData).supported;
+    }
+
+    /**
+     * The protocol version that was requested.
+     */
+    get requested(): string {
+        return (this.data as UnsupportedProtocolVersionErrorData).requested;
+    }
+}