refactor(core): Record-form isSpecType/specTypeSchemas instead of specTypeSchema()/isSpecType()

Author: felixweinberger

.changeset/spec-type-schema.md

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

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 `specTypeSchema('TypeName')` for the `StandardSchemaV1` validator object. The `'TypeName'` argument is typed as `SpecTypeName`, a literal union of all spec type names.
+`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.
 
 ### 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()` / `specTypeSchema()`:
+If a `*Schema` constant was used for **runtime validation** (not just as a `request()` argument), replace with `isSpecType` / `specTypeSchemas`:
 
-| v1 pattern                                         | v2 replacement                                                 |
-| -------------------------------------------------- | -------------------------------------------------------------- |
-| `CallToolResultSchema.safeParse(value).success`    | `isSpecType('CallToolResult', value)`                          |
-| `<TypeName>Schema.safeParse(value).success`        | `isSpecType('<TypeName>', value)`                              |
-| `<TypeName>Schema.parse(value)`                    | `specTypeSchema('<TypeName>')['~standard'].validate(value)`    |
-| Passing `<TypeName>Schema` as a validator argument | `specTypeSchema('<TypeName>')` (returns `StandardSchemaV1<T>`) |
+| v1 pattern                                         | v2 replacement                                               |
+| -------------------------------------------------- | ------------------------------------------------------------ |
+| `CallToolResultSchema.safeParse(value).success`    | `isSpecType.CallToolResult(value)`                           |
+| `<TypeName>Schema.safeParse(value).success`        | `isSpecType.<TypeName>(value)`                               |
+| `<TypeName>Schema.parse(value)`                    | `specTypeSchemas.<TypeName>['~standard'].validate(value)`    |
+| Passing `<TypeName>Schema` as a validator argument | `specTypeSchemas.<TypeName>` (returns `StandardSchemaV1<T>`) |
 
 `isCallToolResult(value)` still works, but `isSpecType` covers every spec type by name.
 

docs/migration.md

@@ -443,7 +443,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 `specTypeSchema()`:
+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
@@ -454,17 +454,17 @@ if (CallToolResultSchema.safeParse(value).success) {
 
 // v2: keyed type predicate
 import { isSpecType } from '@modelcontextprotocol/client';
-if (isSpecType('CallToolResult', value)) {
+if (isSpecType.CallToolResult(value)) {
     /* ... */
 }
+const blocks = mixed.filter(isSpecType.ContentBlock);
 
 // v2: or get the StandardSchemaV1 validator object directly
-import { specTypeSchema } from '@modelcontextprotocol/client';
-const schema = specTypeSchema('CallToolResult');
-const result = schema['~standard'].validate(value);
+import { specTypeSchemas } from '@modelcontextprotocol/client';
+const result = specTypeSchemas.CallToolResult['~standard'].validate(value);
 ```
 
-The `name` argument is typed as `SpecTypeName` — a literal union of every named type in the MCP spec — so you get autocomplete and a compile error on typos. `specTypeSchema()` returns a `StandardSchemaV1<T>`, which composes with any Standard-Schema-aware library and is accepted
+`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<T>`, which composes with any Standard-Schema-aware library and is accepted
 by `setCustomRequestHandler`/`sendCustomRequest`. 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, specTypeSchema } 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/types/specTypeSchema.ts

@@ -33,56 +33,55 @@ export type SpecTypes = {
     [K in SchemaKey as StripSchemaSuffix<K>]: SchemaModule[K] extends z.ZodType<infer T> ? T : never;
 };
 
-const specTypeSchemas: Record<string, z.ZodTypeAny> = {};
+type SchemaRecord = { readonly [K in SpecTypeName]: StandardSchemaV1<SpecTypes[K]> };
+type GuardRecord = { readonly [K in SpecTypeName]: (value: unknown) => value is SpecTypes[K] };
+
+const _specTypeSchemas: Record<string, z.ZodTypeAny> = {};
+const _isSpecType: Record<string, (value: unknown) => boolean> = {};
 for (const source of [schemas, authSchemas]) {
     for (const [key, value] of Object.entries(source)) {
         if (key.endsWith('Schema') && value !== null && typeof value === 'object') {
-            specTypeSchemas[key.slice(0, -'Schema'.length)] = value as z.ZodTypeAny;
+            const name = key.slice(0, -'Schema'.length);
+            const schema = value as z.ZodTypeAny;
+            _specTypeSchemas[name] = schema;
+            _isSpecType[name] = (v: unknown) => schema.safeParse(v).success;
         }
     }
 }
 
 /**
- * Returns a {@linkcode StandardSchemaV1} 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`.
+ * Runtime validators for every MCP spec type, keyed by type name.
  *
- * The returned object implements the Standard Schema interface
- * (`schema['~standard'].validate(value)`), so it composes with any Standard-Schema-aware library.
+ * 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`.
  *
- * @throws {TypeError} if `name` is not a known spec type.
+ * Each entry implements the Standard Schema interface (`schema['~standard'].validate(value)`), so it
+ * composes with any Standard-Schema-aware library.
  *
  * @example
  * ```ts
- * const schema = specTypeSchema('CallToolResult');
- * const result = schema['~standard'].validate(untrusted);
+ * const result = specTypeSchemas.CallToolResult['~standard'].validate(untrusted);
  * if (result.issues === undefined) {
  *     // result.value is CallToolResult
  * }
  * ```
  */
-export function specTypeSchema<K extends SpecTypeName>(name: K): StandardSchemaV1<SpecTypes[K]> {
-    const schema = specTypeSchemas[name];
-    if (schema === undefined) {
-        throw new TypeError(`Unknown MCP spec type: "${name}"`);
-    }
-    return schema as unknown as StandardSchemaV1<SpecTypes[K]>;
-}
+export const specTypeSchemas: SchemaRecord = Object.freeze(_specTypeSchemas) as unknown as SchemaRecord;
 
 /**
- * Type predicate: returns `true` if `value` structurally matches the named MCP spec type.
+ * Type predicates for every MCP spec type, keyed by type name.
  *
- * Convenience wrapper over {@linkcode specTypeSchema} for boolean checks.
+ * Returns `true` if the value structurally matches the named spec type. Each guard is a standalone
+ * function, so it can be passed directly as a callback.
  *
  * @example
  * ```ts
- * if (isSpecType('ContentBlock', value)) {
+ * if (isSpecType.ContentBlock(value)) {
  *     // value is ContentBlock
  * }
+ *
+ * const blocks = mixed.filter(isSpecType.ContentBlock);
  * ```
  */
-export function isSpecType<K extends SpecTypeName>(name: K, value: unknown): value is SpecTypes[K] {
-    return specTypeSchemas[name]?.safeParse(value).success ?? false;
-}
+export const isSpecType: GuardRecord = Object.freeze(_isSpecType) as unknown as GuardRecord;

packages/core/test/types/specTypeSchema.test.ts

@@ -2,68 +2,75 @@ import { describe, expect, expectTypeOf, it } from 'vitest';
 
 import type { OAuthMetadata, OAuthTokens } from '../../src/shared/auth.js';
 import type { SpecTypeName, SpecTypes } from '../../src/types/specTypeSchema.js';
-import { isSpecType, specTypeSchema } from '../../src/types/specTypeSchema.js';
+import { isSpecType, specTypeSchemas } from '../../src/types/specTypeSchema.js';
 import type { CallToolResult, ContentBlock, Implementation, JSONRPCRequest, Tool } from '../../src/types/types.js';
 
-describe('specTypeSchema()', () => {
+describe('specTypeSchemas', () => {
     it('returns a StandardSchemaV1 validator that accepts valid values', () => {
-        const schema = specTypeSchema('Implementation');
-        const result = schema['~standard'].validate({ name: 'x', version: '1.0.0' });
+        const result = specTypeSchemas.Implementation['~standard'].validate({ name: 'x', version: '1.0.0' });
         expect((result as { issues?: unknown }).issues).toBeUndefined();
     });
 
     it('returns a validator that rejects invalid values with issues', () => {
-        const schema = specTypeSchema('Implementation');
-        const result = schema['~standard'].validate({ name: 'x' });
+        const result = specTypeSchemas.Implementation['~standard'].validate({ name: 'x' });
         expect((result as { issues?: readonly unknown[] }).issues?.length).toBeGreaterThan(0);
     });
 
-    it('throws TypeError for an unknown name', () => {
-        expect(() => specTypeSchema('NotASpecType' as SpecTypeName)).toThrow(TypeError);
+    it('rejects unknown names at compile time and is undefined at runtime', () => {
+        // @ts-expect-error - 'NotASpecType' is not a SpecTypeName
+        expect(specTypeSchemas['NotASpecType']).toBeUndefined();
     });
 
     it('covers JSON-RPC envelope types', () => {
-        const ok = specTypeSchema('JSONRPCRequest')['~standard'].validate({ jsonrpc: '2.0', id: 1, method: 'ping' });
+        const ok = specTypeSchemas.JSONRPCRequest['~standard'].validate({ jsonrpc: '2.0', id: 1, method: 'ping' });
         expect((ok as { issues?: unknown }).issues).toBeUndefined();
     });
 
     it('covers OAuth types from shared/auth.ts', () => {
-        const ok = specTypeSchema('OAuthTokens')['~standard'].validate({ access_token: 'x', token_type: 'Bearer' });
+        const ok = specTypeSchemas.OAuthTokens['~standard'].validate({ access_token: 'x', token_type: 'Bearer' });
         expect((ok as { issues?: unknown }).issues).toBeUndefined();
-        const bad = specTypeSchema('OAuthTokens')['~standard'].validate({ token_type: 'Bearer' });
+        const bad = specTypeSchemas.OAuthTokens['~standard'].validate({ token_type: 'Bearer' });
         expect((bad as { issues?: readonly unknown[] }).issues?.length).toBeGreaterThan(0);
     });
 });
 
-describe('isSpecType()', () => {
+describe('isSpecType', () => {
     it('CallToolResult — accepts valid, rejects invalid/null/primitive', () => {
-        expect(isSpecType('CallToolResult', { content: [{ type: 'text', text: 'hi' }] })).toBe(true);
-        expect(isSpecType('CallToolResult', { content: 'not-an-array' })).toBe(false);
-        expect(isSpecType('CallToolResult', null)).toBe(false);
-        expect(isSpecType('CallToolResult', 'string')).toBe(false);
+        expect(isSpecType.CallToolResult({ content: [{ type: 'text', text: 'hi' }] })).toBe(true);
+        expect(isSpecType.CallToolResult({ content: 'not-an-array' })).toBe(false);
+        expect(isSpecType.CallToolResult(null)).toBe(false);
+        expect(isSpecType.CallToolResult('string')).toBe(false);
     });
 
     it('ContentBlock — accepts text block, rejects wrong shape', () => {
-        expect(isSpecType('ContentBlock', { type: 'text', text: 'hi' })).toBe(true);
-        expect(isSpecType('ContentBlock', { type: 'text' })).toBe(false);
-        expect(isSpecType('ContentBlock', {})).toBe(false);
+        expect(isSpecType.ContentBlock({ type: 'text', text: 'hi' })).toBe(true);
+        expect(isSpecType.ContentBlock({ type: 'text' })).toBe(false);
+        expect(isSpecType.ContentBlock({})).toBe(false);
     });
 
     it('Tool — accepts valid, rejects missing inputSchema', () => {
-        expect(isSpecType('Tool', { name: 'echo', inputSchema: { type: 'object' } })).toBe(true);
-        expect(isSpecType('Tool', { name: 'echo' })).toBe(false);
+        expect(isSpecType.Tool({ name: 'echo', inputSchema: { type: 'object' } })).toBe(true);
+        expect(isSpecType.Tool({ name: 'echo' })).toBe(false);
     });
 
-    it('returns false (not throw) for unknown name', () => {
-        expect(isSpecType('NotASpecType' as SpecTypeName, {})).toBe(false);
+    it('rejects unknown names at compile time and is undefined at runtime', () => {
+        // @ts-expect-error - 'NotASpecType' is not a SpecTypeName
+        expect(isSpecType['NotASpecType']).toBeUndefined();
     });
 
     it('narrows the value type', () => {
         const v: unknown = { name: 'x', version: '1.0.0' };
-        if (isSpecType('Implementation', v)) {
+        if (isSpecType.Implementation(v)) {
             expectTypeOf(v).toEqualTypeOf<SpecTypes['Implementation']>();
         }
     });
+
+    it('guards work as filter callbacks and narrow the element type', () => {
+        const mixed: unknown[] = [{ type: 'text', text: 'hi' }, 42, { type: 'text' }];
+        const blocks = mixed.filter(isSpecType.ContentBlock);
+        expect(blocks).toHaveLength(1);
+        expectTypeOf(blocks).toEqualTypeOf<ContentBlock[]>();
+    });
 });
 
 describe('SpecTypeName / SpecTypes (type-level)', () => {