Merge remote-tracking branch 'origin/fweinberger/spec-type-predicates' into fweinberger/v2-bc-d1-base

# Conflicts:
#	docs/migration-SKILL.md
#	docs/migration.md
#	packages/core/src/exports/public/index.ts

Author: felixweinberger

.changeset/spec-type-schema.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+---
+
+Export `isSpecType` and `specTypeSchemas` records for runtime validation of any MCP spec type by name. `isSpecType.ContentBlock(value)` is a type predicate; `specTypeSchemas.ContentBlock` is a `StandardSchemaV1<ContentBlock>` validator. Guards are standalone functions, so `arr.filter(isSpecType.ContentBlock)` works. Also export the `StandardSchemaV1`, `SpecTypeName`, and `SpecTypes` types.

CLAUDE.md

@@ -38,7 +38,7 @@ Include what changed, why, and how to migrate. Search for related sections and g
 - **Files**: Lowercase with hyphens, test files with `.test.ts` suffix
 - **Imports**: ES module style, include `.js` extension, group imports logically
 - **Formatting**: 2-space indentation, semicolons required, single quotes preferred
-- **Testing**: Co-locate tests with source files, use descriptive test names
+- **Testing**: Place tests under each package's `test/` directory (vitest only includes `test/**/*.test.ts`), use descriptive test names
 - **Comments**: JSDoc for public APIs, inline comments for complex logic
 
 ### JSDoc `@example` Code Snippets

docs/migration-SKILL.md

@@ -59,7 +59,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 ```
 
-Note: `@modelcontextprotocol/client` and `@modelcontextprotocol/server` both re-export shared types from `@modelcontextprotocol/core`, so you can import types and error classes from whichever package you already depend on. Do not import from `@modelcontextprotocol/core` directly — it is an internal package.
+Note: `@modelcontextprotocol/client` and `@modelcontextprotocol/server` both re-export shared types from `@modelcontextprotocol/core`, so you can import types and error classes from whichever package you already depend on. Do not import from `@modelcontextprotocol/core` directly
+— it is an internal package.
 
 ### Dropped Node.js 18 and CommonJS
 
@@ -300,11 +301,11 @@ This applies to:
 
 **Removed Zod-specific helpers** from `@modelcontextprotocol/core` (use Standard Schema equivalents):
 
-| Removed | Replacement |
-|---|---|
-| `schemaToJson(schema)` | `standardSchemaToJsonSchema(schema)` |
-| `parseSchemaAsync(schema, data)` | `validateStandardSchema(schema, data)` |
-| `SchemaInput<T>` | `StandardSchemaWithJSON.InferInput<T>` |
+| Removed                                                                              | Replacement                                                       |
+| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| `schemaToJson(schema)`                                                               | `standardSchemaToJsonSchema(schema)`                              |
+| `parseSchemaAsync(schema, data)`                                                     | `validateStandardSchema(schema, data)`                            |
+| `SchemaInput<T>`                                                                     | `StandardSchemaWithJSON.InferInput<T>`                            |
 | `getSchemaShape`, `getSchemaDescription`, `isOptionalSchema`, `unwrapOptionalSchema` | No replacement — these are now internal Zod introspection helpers |
 
 ### Host header validation moved
@@ -492,18 +493,29 @@ The return type is now inferred from the method name via `ResultTypeMap`. For ex
 
 For **custom (non-spec)** methods, keep the result-schema argument — see [Sending custom-method requests](#sending-custom-method-requests). Only drop the schema when calling a spec method.
 
-If you were using `CallToolResultSchema` for **runtime validation** (not just in `request()`/`callTool()` calls), use the new `isCallToolResult` type guard instead:
+If you were using `CallToolResultSchema` (or any `*Schema` constant) for **runtime validation** (not just in `request()`/`callTool()` calls), use `isSpecType` or `specTypeSchemas`:
 
 ```typescript
 // v1: runtime validation with Zod schema
 import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
-if (CallToolResultSchema.safeParse(value).success) { /* ... */ }
+if (CallToolResultSchema.safeParse(value).success) {
+    /* ... */
+}
+
+// v2: keyed type predicate
+import { isSpecType } from '@modelcontextprotocol/client';
+if (isSpecType.CallToolResult(value)) {
+    /* ... */
+}
+const blocks = mixed.filter(isSpecType.ContentBlock);
 
-// v2: use the type guard
-import { isCallToolResult } from '@modelcontextprotocol/client';
-if (isCallToolResult(value)) { /* ... */ }
+// v2: or get the StandardSchemaV1 validator object directly
+import { specTypeSchemas } from '@modelcontextprotocol/client';
+const result = await specTypeSchemas.CallToolResult['~standard'].validate(value);
 ```
 
+`isSpecType` and `specTypeSchemas` are keyed by `SpecTypeName` — a literal union of every named type in the MCP spec — so you get autocomplete and a compile error on typos. `specTypeSchemas.X` is a `StandardSchemaV1<In, Out>`, which composes with any Standard-Schema-aware library. The pre-existing `isCallToolResult(value)` guard still works.
+
 ### Client list methods return empty results for missing capabilities
 
 `Client.listPrompts()`, `listResources()`, `listResourceTemplates()`, and `listTools()` now return empty results when the server didn't advertise the corresponding capability, instead of sending the request. This respects the MCP spec's capability negotiation.
@@ -537,20 +549,21 @@ import { InMemoryTransport } from '@modelcontextprotocol/client';
 
 The following deprecated type aliases have been removed from `@modelcontextprotocol/core`:
 
-| Removed                                  | Replacement                                      |
-| ---------------------------------------- | ------------------------------------------------ |
-| `JSONRPCError`                           | `JSONRPCErrorResponse`                           |
-| `JSONRPCErrorSchema`                     | `JSONRPCErrorResponseSchema`                     |
-| `isJSONRPCError`                         | `isJSONRPCErrorResponse`                         |
-| `isJSONRPCResponse`                      | `isJSONRPCResultResponse` (see note below)       |
-| `ResourceReferenceSchema`                | `ResourceTemplateReferenceSchema`                |
-| `ResourceReference`                      | `ResourceTemplateReference`                      |
-| `IsomorphicHeaders`                      | Use Web Standard `Headers`                       |
+| Removed                                  | Replacement                                                                                       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `JSONRPCError`                           | `JSONRPCErrorResponse`                                                                            |
+| `JSONRPCErrorSchema`                     | `JSONRPCErrorResponseSchema`                                                                      |
+| `isJSONRPCError`                         | `isJSONRPCErrorResponse`                                                                          |
+| `isJSONRPCResponse`                      | `isJSONRPCResultResponse` (see note below)                                                        |
+| `ResourceReferenceSchema`                | `ResourceTemplateReferenceSchema`                                                                 |
+| `ResourceReference`                      | `ResourceTemplateReference`                                                                       |
+| `IsomorphicHeaders`                      | Use Web Standard `Headers`                                                                        |
 | `AuthInfo` (from `server/auth/types.js`) | `AuthInfo` (now re-exported by `@modelcontextprotocol/client` and `@modelcontextprotocol/server`) |
 
 All other **type** symbols from `@modelcontextprotocol/sdk/types.js` retain their original names — import them from `@modelcontextprotocol/client` or `@modelcontextprotocol/server`. **Zod schemas** (e.g., `CallToolRequestSchema`) are not re-exported from the package roots; for runtime validation prefer the `isSpecType` / `specTypeSchemas` Records, or for v1 source compatibility import them from `@modelcontextprotocol/server/zod-schemas`.
 
-> **Note on `isJSONRPCResponse`:** v1's `isJSONRPCResponse` was a deprecated alias that only checked for *result* responses (it was equivalent to `isJSONRPCResultResponse`). v2 removes the deprecated alias and introduces a **new** `isJSONRPCResponse` with corrected semantics — it checks for *any* response (either result or error). If you are migrating v1 code that used `isJSONRPCResponse`, rename it to `isJSONRPCResultResponse` to preserve the original behavior. Use the new `isJSONRPCResponse` only when you want to match both result and error responses.
+> **Note on `isJSONRPCResponse`:** v1's `isJSONRPCResponse` was a deprecated alias that only checked for _result_ responses (it was equivalent to `isJSONRPCResultResponse`). v2 removes the deprecated alias and introduces a **new** `isJSONRPCResponse` with corrected semantics — it
+> checks for _any_ response (either result or error). If you are migrating v1 code that used `isJSONRPCResponse`, rename it to `isJSONRPCResultResponse` to preserve the original behavior. Use the new `isJSONRPCResponse` only when you want to match both result and error responses.
 
 **Before (v1):**
 
@@ -578,7 +591,7 @@ The `RequestHandlerExtra` type has been replaced with a structured context type
 | `extra.sendRequest(...)`                 | `ctx.mcpReq.send(...)`                                                 |
 | `extra.sendNotification(...)`            | `ctx.mcpReq.notify(...)`                                               |
 | `extra.authInfo`                         | `ctx.http?.authInfo`                                                   |
-| `extra.requestInfo`                      | `ctx.http?.req` (standard Web `Request`, only on `ServerContext`)     |
+| `extra.requestInfo`                      | `ctx.http?.req` (standard Web `Request`, only on `ServerContext`)      |
 | `extra.closeSSEStream`                   | `ctx.http?.closeSSE` (only on `ServerContext`)                         |
 | `extra.closeStandaloneSSEStream`         | `ctx.http?.closeStandaloneSSE` (only on `ServerContext`)               |
 | `extra.sessionId`                        | `ctx.sessionId`                                                        |
@@ -848,7 +861,8 @@ try {
 
 ### Experimental: `TaskCreationParams.ttl` no longer accepts `null`
 
-The `ttl` field in `TaskCreationParams` (used when requesting the server to create a task) no longer accepts `null`. Per the MCP spec, `null` TTL (meaning unlimited lifetime) is only valid in server responses (`Task.ttl`), not in client requests. Clients should omit `ttl` to let the server decide the lifetime.
+The `ttl` field in `TaskCreationParams` (used when requesting the server to create a task) no longer accepts `null`. Per the MCP spec, `null` TTL (meaning unlimited lifetime) is only valid in server responses (`Task.ttl`), not in client requests. Clients should omit `ttl` to let
+the server decide the lifetime.
 
 This also narrows the type of `requestedTtl` in `TaskContext`, `CreateTaskServerContext`, and `TaskServerContext` from `number | null | undefined` to `number | undefined`.
 

docs/migration.md

@@ -138,6 +138,8 @@ export { isTerminal } from '../../experimental/tasks/interfaces.js';
 export { InMemoryTaskMessageQueue, InMemoryTaskStore } from '../../experimental/tasks/stores/inMemory.js';
 
 // Validator types and classes
+export type { SpecTypeName, SpecTypes } from '../../types/specTypeSchema.js';
+export { isSpecType, specTypeSchemas } from '../../types/specTypeSchema.js';
 export type { StandardSchemaV1, StandardSchemaWithJSON } from '../../util/standardSchema.js';
 export { AjvJsonSchemaValidator } from '../../validators/ajvProvider.js';
 export type { CfWorkerSchemaDraft } from '../../validators/cfWorkerProvider.js';

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

@@ -5,4 +5,5 @@ export * from './enums.js';
 export * from './errors.js';
 export * from './guards.js';
 export * from './schemas.js';
+export * from './specTypeSchema.js';
 export * from './types.js';

packages/core/src/types/index.ts

@@ -12,11 +12,11 @@ import type {
     ResultTypeMap
 } from './types.js';
 
-export const JSONValueSchema: z.ZodType<JSONValue> = z.lazy(() =>
+export const JSONValueSchema: z.ZodType<JSONValue, JSONValue> = z.lazy(() =>
     z.union([z.string(), z.number(), z.boolean(), z.null(), z.record(z.string(), JSONValueSchema), z.array(JSONValueSchema)])
 );
-export const JSONObjectSchema: z.ZodType<JSONObject> = z.record(z.string(), JSONValueSchema);
-export const JSONArraySchema: z.ZodType<JSONArray> = z.array(JSONValueSchema);
+export const JSONObjectSchema: z.ZodType<JSONObject, JSONObject> = z.record(z.string(), JSONValueSchema);
+export const JSONArraySchema: z.ZodType<JSONArray, JSONArray> = z.array(JSONValueSchema);
 /**
  * A progress token, used to associate progress notifications with the original request.
  */

packages/core/src/types/schemas.ts

@@ -0,0 +1,40 @@
+/**
+ * Type-checked examples for `specTypeSchema.ts`.
+ *
+ * These examples are synced into JSDoc comments via the sync-snippets script.
+ * Each function's region markers define the code snippet that appears in the docs.
+ *
+ * @module
+ */
+
+import { isSpecType, specTypeSchemas } from './specTypeSchema.js';
+
+declare const untrusted: unknown;
+declare const value: unknown;
+declare const mixed: unknown[];
+
+async function specTypeSchemas_basicUsage() {
+    //#region specTypeSchemas_basicUsage
+    const result = await specTypeSchemas.CallToolResult['~standard'].validate(untrusted);
+    if (result.issues === undefined) {
+        // result.value is CallToolResult
+    }
+    //#endregion specTypeSchemas_basicUsage
+    void result;
+}
+
+function isSpecType_basicUsage() {
+    /* eslint-disable unicorn/no-array-callback-reference -- showcasing the guard-as-callback pattern */
+    //#region isSpecType_basicUsage
+    if (isSpecType.ContentBlock(value)) {
+        // value is ContentBlock
+    }
+
+    const blocks = mixed.filter(isSpecType.ContentBlock);
+    //#endregion isSpecType_basicUsage
+    /* eslint-enable unicorn/no-array-callback-reference */
+    void blocks;
+}
+
+void specTypeSchemas_basicUsage;
+void isSpecType_basicUsage;