refactor(specTypeSchema): switch isSpecType/specTypeSchema to string-arg function form

Replaces the Record-of-predicates exports with two generic functions:
isSpecType('TypeName', value) and specTypeSchema('TypeName').

Drops the register() helper, the per-key closure creation (161 closures
at module init), the SchemaRecord/GuardRecord types, and both
Object.freeze(...) as unknown as casts. The single remaining cast is a
narrow Record<SpecTypeName, z.ZodType> at construction so indexing by
SpecTypeName is non-undefined under noUncheckedIndexedAccess.

Trade-off: arr.filter needs an arrow wrapper (mixed.filter(v =>
isSpecType('ContentBlock', v))). TypeScript's inferred type predicates
still narrow the result to ContentBlock[].

Author: felixweinberger

.changeset/spec-type-schema.md

@@ -3,4 +3,5 @@
 '@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.
+Export `isSpecType` and `specTypeSchema` for runtime validation of any MCP spec type by name. `isSpecType('ContentBlock', value)` is a type predicate; `specTypeSchema('ContentBlock')` returns a `StandardSchemaV1<ContentBlock>` validator. Also export the `StandardSchemaV1`,
+`SpecTypeName`, and `SpecTypes` types.

docs/migration-SKILL.md

@@ -99,7 +99,7 @@ Notes:
 | `WebSocketClientTransport`               | REMOVED (use `StreamableHTTPClientTransport` or `StdioClientTransport`)                                         |
 
 All other **type** symbols from `@modelcontextprotocol/sdk/types.js` retain their original names. **Zod schemas** (e.g., `CallToolResultSchema`, `ListToolsResultSchema`) are no longer part of the public API — they are internal to the SDK. For runtime validation, use
-`isSpecType.TypeName(value)` (e.g., `isSpecType.CallToolResult(v)`) or `specTypeSchemas.TypeName` for the `StandardSchemaV1` validator object. The keys are typed as `SpecTypeName`, a literal union of all spec type names.
+`isSpecType('TypeName', value)` (e.g., `isSpecType('CallToolResult', v)`) or `specTypeSchema('TypeName')` for the `StandardSchemaV1` validator object. The first argument is typed as `SpecTypeName`, a literal union of all spec type names.
 
 ### Error class changes
 
@@ -437,14 +437,14 @@ const tool = await client.callTool({ name: 'my-tool', arguments: {} });
 
 Remove unused schema imports: `CallToolResultSchema`, `CompatibilityCallToolResultSchema`, `ElicitResultSchema`, `CreateMessageResultSchema`, etc., when they were only used in `request()`/`send()`/`callTool()` calls.
 
-If a `*Schema` constant was used for **runtime validation** (not just as a `request()` argument), replace with `isSpecType` / `specTypeSchemas`:
+If a `*Schema` constant was used for **runtime validation** (not just as a `request()` argument), replace with `isSpecType` / `specTypeSchema`:
 
-| v1 pattern                                         | v2 replacement                                                                                      |
-| -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `CallToolResultSchema.safeParse(value).success`    | `isSpecType.CallToolResult(value)`                                                                  |
-| `<TypeName>Schema.safeParse(value).success`        | `isSpecType.<TypeName>(value)`                                                                      |
-| `<TypeName>Schema.parse(value)`                    | `await specTypeSchemas.<TypeName>['~standard'].validate(value)` (returns a `Result`, not the value) |
-| Passing `<TypeName>Schema` as a validator argument | `specTypeSchemas.<TypeName>` (a `StandardSchemaV1<In, Out>`)                                        |
+| v1 pattern                                         | v2 replacement                                                                                        |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `CallToolResultSchema.safeParse(value).success`    | `isSpecType('CallToolResult', value)`                                                                 |
+| `<TypeName>Schema.safeParse(value).success`        | `isSpecType('<TypeName>', value)`                                                                     |
+| `<TypeName>Schema.parse(value)`                    | `await specTypeSchema('<TypeName>')['~standard'].validate(value)` (returns a `Result`, not the value) |
+| Passing `<TypeName>Schema` as a validator argument | `specTypeSchema('<TypeName>')` (a `StandardSchemaV1<In, Out>`)                                        |
 
 `isCallToolResult(value)` still works, but `isSpecType` covers every spec type by name.
 

docs/migration.md

@@ -137,7 +137,8 @@ const transport = new StreamableHTTPClientTransport(new URL('http://localhost:30
 
 Resource Server helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `getOAuthProtectedResourceMetadataUrl`, `OAuthTokenVerifier`) are now first-class in `@modelcontextprotocol/express`.
 
-Authorization Server helpers (`mcpAuthRouter`, `OAuthServerProvider`, `ProxyOAuthServerProvider`, `authenticateClient`, `allowedMethods`, etc.) have been removed from the core SDK; new code should use a dedicated IdP/OAuth library. See the [examples](../examples/server/src/) for a working demo with `better-auth`.
+Authorization Server helpers (`mcpAuthRouter`, `OAuthServerProvider`, `ProxyOAuthServerProvider`, `authenticateClient`, `allowedMethods`, etc.) have been removed from the core SDK; new code should use a dedicated IdP/OAuth library. See the [examples](../examples/server/src/) for
+a working demo with `better-auth`.
 
 Note: `AuthInfo` has moved from `server/auth/types.ts` to the core types and is now re-exported by `@modelcontextprotocol/client` and `@modelcontextprotocol/server`.
 
@@ -445,7 +446,7 @@ const result = await client.callTool({ name: 'my-tool', arguments: {} });
 
 The return type is now inferred from the method name via `ResultTypeMap`. For example, `client.request({ method: 'tools/call', ... })` returns `Promise<CallToolResult | CreateTaskResult>`.
 
-If you were using `CallToolResultSchema` (or any `*Schema` constant) for **runtime validation** (not just in `request()`/`callTool()` calls), use `isSpecType` or `specTypeSchemas`:
+If you were using `CallToolResultSchema` (or any `*Schema` constant) for **runtime validation** (not just in `request()`/`callTool()` calls), use `isSpecType` or `specTypeSchema`:
 
 ```typescript
 // v1: runtime validation with Zod schema
@@ -454,19 +455,20 @@ if (CallToolResultSchema.safeParse(value).success) {
     /* ... */
 }
 
-// v2: keyed type predicate
+// v2: type predicate by name
 import { isSpecType } from '@modelcontextprotocol/client';
-if (isSpecType.CallToolResult(value)) {
+if (isSpecType('CallToolResult', value)) {
     /* ... */
 }
-const blocks = mixed.filter(isSpecType.ContentBlock);
+const blocks = mixed.filter(v => isSpecType('ContentBlock', v));
 
 // v2: or get the StandardSchemaV1 validator object directly
-import { specTypeSchemas } from '@modelcontextprotocol/client';
-const result = await specTypeSchemas.CallToolResult['~standard'].validate(value);
+import { specTypeSchema } from '@modelcontextprotocol/client';
+const result = await specTypeSchema('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.
+The first argument to `isSpecType` and `specTypeSchema` is a `SpecTypeName` — a literal union of every named type in the MCP spec — so you get autocomplete and a compile error on typos. `specTypeSchema(name)` returns 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
 

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

@@ -138,7 +138,7 @@ export { InMemoryTaskMessageQueue, InMemoryTaskStore } from '../../experimental/
 
 // Validator types and classes
 export type { SpecTypeName, SpecTypes } from '../../types/specTypeSchema.js';
-export { isSpecType, specTypeSchemas } from '../../types/specTypeSchema.js';
+export { isSpecType, specTypeSchema } 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/types/specTypeSchema.examples.ts

@@ -7,34 +7,32 @@
  * @module
  */
 
-import { isSpecType, specTypeSchemas } from './specTypeSchema.js';
+import { isSpecType, specTypeSchema } 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);
+async function specTypeSchema_basicUsage() {
+    //#region specTypeSchema_basicUsage
+    const result = await specTypeSchema('CallToolResult')['~standard'].validate(untrusted);
     if (result.issues === undefined) {
         // result.value is CallToolResult
     }
-    //#endregion specTypeSchemas_basicUsage
+    //#endregion specTypeSchema_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)) {
+    if (isSpecType('ContentBlock', value)) {
         // value is ContentBlock
     }
 
-    const blocks = mixed.filter(isSpecType.ContentBlock);
+    const blocks = mixed.filter(v => isSpecType('ContentBlock', v));
     //#endregion isSpecType_basicUsage
-    /* eslint-enable unicorn/no-array-callback-reference */
     void blocks;
 }
 
-void specTypeSchemas_basicUsage;
+void specTypeSchema_basicUsage;
 void isSpecType_basicUsage;

packages/core/src/types/specTypeSchema.ts

@@ -235,62 +235,59 @@ type SpecTypeInputs = {
     [K in SchemaKey as StripSchemaSuffix<K>]: SchemaFor<K> extends z.ZodType ? z.input<SchemaFor<K>> : never;
 };
 
-type SchemaRecord = { readonly [K in SpecTypeName]: StandardSchemaV1<SpecTypeInputs[K], SpecTypes[K]> };
-type GuardRecord = { readonly [K in SpecTypeName]: (value: unknown) => value is SpecTypeInputs[K] };
-
-const _specTypeSchemas: Record<string, z.ZodTypeAny> = {};
-const _isSpecType: Record<string, (value: unknown) => boolean> = {};
-function register(key: string, schema: z.ZodTypeAny): void {
-    const name = key.slice(0, -'Schema'.length);
-    _specTypeSchemas[name] = schema;
-    _isSpecType[name] = (v: unknown) => schema.safeParse(v).success;
-}
+// Populated for every SpecTypeName by the loops below; the cast lets `allSchemas[name]` be
+// non-undefined under `noUncheckedIndexedAccess` when `name` is a SpecTypeName.
+const allSchemas = {} as Record<SpecTypeName, z.ZodType>;
 for (const key of SPEC_SCHEMA_KEYS) {
     // eslint-disable-next-line import/namespace -- key is constrained to keyof typeof schemas via the satisfies clause above
-    register(key, schemas[key]);
+    allSchemas[key.slice(0, -'Schema'.length) as SpecTypeName] = schemas[key];
 }
 for (const [key, schema] of Object.entries(authSchemas)) {
-    register(key, schema);
+    allSchemas[key.slice(0, -'Schema'.length) as SpecTypeName] = schema;
 }
 
 /**
- * Runtime validators for every MCP spec type, keyed by type name.
+ * Returns the runtime validator for the named MCP spec type.
  *
  * Use this when you need to validate a spec-defined shape at a boundary the SDK does not own, for
  * example an extension's custom-method payload that embeds a `CallToolResult`, or a value read from
  * storage that should be a `Tool`.
  *
- * Each entry implements the Standard Schema interface, so it composes with any
+ * The returned validator implements the Standard Schema interface, so it composes with any
  * Standard-Schema-aware library. For a simple boolean check, use {@linkcode isSpecType} instead.
  *
  * @example
- * ```ts source="./specTypeSchema.examples.ts#specTypeSchemas_basicUsage"
- * const result = await specTypeSchemas.CallToolResult['~standard'].validate(untrusted);
+ * ```ts source="./specTypeSchema.examples.ts#specTypeSchema_basicUsage"
+ * const result = await specTypeSchema('CallToolResult')['~standard'].validate(untrusted);
  * if (result.issues === undefined) {
  *     // result.value is CallToolResult
  * }
  * ```
  */
-export const specTypeSchemas: SchemaRecord = Object.freeze(_specTypeSchemas) as unknown as SchemaRecord;
+export function specTypeSchema<K extends SpecTypeName>(name: K): StandardSchemaV1<SpecTypeInputs[K], SpecTypes[K]>;
+export function specTypeSchema(name: SpecTypeName): StandardSchemaV1 {
+    return allSchemas[name];
+}
 
 /**
- * Type predicates for every MCP spec type, keyed by type name.
+ * Type predicate for the named MCP spec type.
  *
  * Returns `true` if the value satisfies the schema's input type (`z.input<>`, before defaults and
  * transforms are applied), and narrows to that input type. For schemas with `.default()` or
  * `.preprocess()`, this may accept values that do not structurally match the named output type;
- * for example `isSpecType.CallToolResult({})` is `true` because `content` has a default. Use
- * `specTypeSchemas.X['~standard'].validate(value)` when you need the validated output value.
- *
- * Each guard is a standalone function, so it can be passed directly as a callback.
+ * for example `isSpecType('CallToolResult', {})` is `true` because `content` has a default. Use
+ * `specTypeSchema(name)['~standard'].validate(value)` when you need the validated output value.
  *
  * @example
  * ```ts source="./specTypeSchema.examples.ts#isSpecType_basicUsage"
- * if (isSpecType.ContentBlock(value)) {
+ * if (isSpecType('ContentBlock', value)) {
  *     // value is ContentBlock
  * }
  *
- * const blocks = mixed.filter(isSpecType.ContentBlock);
+ * const blocks = mixed.filter(v => isSpecType('ContentBlock', v));
  * ```
  */
-export const isSpecType: GuardRecord = Object.freeze(_isSpecType) as unknown as GuardRecord;
+export function isSpecType<K extends SpecTypeName>(name: K, value: unknown): value is SpecTypeInputs[K];
+export function isSpecType(name: SpecTypeName, value: unknown): boolean {
+    return allSchemas[name].safeParse(value).success;
+}