feat(core): add specTypeSchema() for runtime validation of any spec type

Adds specTypeSchema(name) returning a StandardSchemaV1 validator for any
named MCP spec type, and isSpecType(name, value) as a boolean predicate.
The SpecTypeName union and SpecTypes map are derived from the internal
Zod schemas, so they cover every spec type with no curation.

Replaces the earlier curated-5-predicates approach with a single keyed
entrypoint that does not require a new export each time an extension
embeds a different spec type.

Also: moves guards.test.ts to test/ (vitest include is test/**/*.test.ts;
the file was previously dead) and corrects CLAUDE.md test-location guidance.

Author: felixweinberger

.changeset/spec-type-schema.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/client': patch
+'@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.

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

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

@@ -136,7 +136,9 @@ export { isTerminal } from '../../experimental/tasks/interfaces.js';
 export { InMemoryTaskMessageQueue, InMemoryTaskStore } from '../../experimental/tasks/stores/inMemory.js';
 
 // Validator types and classes
-export type { StandardSchemaWithJSON } from '../../util/standardSchema.js';
+export type { StandardSchemaV1, StandardSchemaWithJSON } from '../../util/standardSchema.js';
+export type { SpecTypeName, SpecTypes } from '../../types/specTypeSchema.js';
+export { isSpecType, specTypeSchema } from '../../types/specTypeSchema.js';
 export { AjvJsonSchemaValidator } from '../../validators/ajvProvider.js';
 export type { CfWorkerSchemaDraft } from '../../validators/cfWorkerProvider.js';
 // fromJsonSchema is intentionally NOT exported here — the server and client packages

packages/core/src/types/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/specTypeSchema.ts

@@ -0,0 +1,84 @@
+import type * as z from 'zod/v4';
+
+import type { StandardSchemaV1 } from '../util/standardSchema.js';
+import * as schemas from './schemas.js';
+
+type SchemaModule = typeof schemas;
+
+type StripSchemaSuffix<K> = K extends `${infer N}Schema` ? N : never;
+
+/** Keys of `schemas.ts` that end in `Schema` and hold a Standard Schema value. */
+type SchemaKey = {
+    [K in keyof SchemaModule]: K extends `${string}Schema`
+        ? SchemaModule[K] extends { readonly '~standard': unknown }
+            ? K
+            : never
+        : never;
+}[keyof SchemaModule];
+
+/**
+ * Union of every named type in the MCP spec schema (e.g. `'CallToolResult'`, `'ContentBlock'`,
+ * `'Tool'`). Derived from the SDK's internal Zod schemas, so it stays in sync with the spec.
+ */
+export type SpecTypeName = StripSchemaSuffix<SchemaKey>;
+
+/**
+ * Maps each {@linkcode SpecTypeName} to its TypeScript type.
+ *
+ * `SpecTypes['CallToolResult']` is equivalent to importing the `CallToolResult` type directly.
+ */
+export type SpecTypes = {
+    [K in SchemaKey as StripSchemaSuffix<K>]: SchemaModule[K] extends z.ZodType<infer T> ? T : never;
+};
+
+const specTypeSchemas: Record<string, z.ZodTypeAny> = {};
+for (const [key, value] of Object.entries(schemas)) {
+    if (key.endsWith('Schema') && value !== null && typeof value === 'object') {
+        specTypeSchemas[key.slice(0, -'Schema'.length)] = value as z.ZodTypeAny;
+    }
+}
+
+/**
+ * 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`.
+ *
+ * The returned object implements the Standard Schema interface
+ * (`schema['~standard'].validate(value)`), so it composes with any Standard-Schema-aware library.
+ *
+ * @throws {TypeError} if `name` is not a known spec type.
+ *
+ * @example
+ * ```ts
+ * const schema = specTypeSchema('CallToolResult');
+ * const result = schema['~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]>;
+}
+
+/**
+ * Type predicate: returns `true` if `value` structurally matches the named MCP spec type.
+ *
+ * Convenience wrapper over {@linkcode specTypeSchema} for boolean checks.
+ *
+ * @example
+ * ```ts
+ * if (isSpecType('ContentBlock', value)) {
+ *     // value is ContentBlock
+ * }
+ * ```
+ */
+export function isSpecType<K extends SpecTypeName>(name: K, value: unknown): value is SpecTypes[K] {
+    return specTypeSchemas[name]?.safeParse(value).success ?? false;
+}

packages/core/src/types/guards.test.ts packages/core/test/types/guards.test.tspackages/core/src/types/guards.test.ts renamed to packages/core/test/types/guards.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { JSONRPC_VERSION } from './constants.js';
-import { isCallToolResult, isJSONRPCErrorResponse, isJSONRPCResponse, isJSONRPCResultResponse } from './guards.js';
+import { JSONRPC_VERSION } from '../../src/types/constants.js';
+import { isCallToolResult, isJSONRPCErrorResponse, isJSONRPCResponse, isJSONRPCResultResponse } from '../../src/types/guards.js';
 
 describe('isJSONRPCResponse', () => {
     it('returns true for a valid result response', () => {

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

@@ -0,0 +1,77 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import type { SpecTypeName, SpecTypes } from '../../src/types/specTypeSchema.js';
+import { isSpecType, specTypeSchema } from '../../src/types/specTypeSchema.js';
+import type { CallToolResult, ContentBlock, Implementation, JSONRPCRequest, Tool } from '../../src/types/types.js';
+
+describe('specTypeSchema()', () => {
+    it('returns a StandardSchemaV1 validator that accepts valid values', () => {
+        const schema = specTypeSchema('Implementation');
+        const result = schema['~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' });
+        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('covers JSON-RPC envelope types', () => {
+        const ok = specTypeSchema('JSONRPCRequest')['~standard'].validate({ jsonrpc: '2.0', id: 1, method: 'ping' });
+        expect((ok as { issues?: unknown }).issues).toBeUndefined();
+    });
+});
+
+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);
+    });
+
+    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);
+    });
+
+    it('Tool — accepts valid, rejects missing inputSchema', () => {
+        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('narrows the value type', () => {
+        const v: unknown = { name: 'x', version: '1.0.0' };
+        if (isSpecType('Implementation', v)) {
+            expectTypeOf(v).toEqualTypeOf<SpecTypes['Implementation']>();
+        }
+    });
+});
+
+describe('SpecTypeName / SpecTypes (type-level)', () => {
+    it('SpecTypeName includes representative names', () => {
+        expectTypeOf<'CallToolResult'>().toMatchTypeOf<SpecTypeName>();
+        expectTypeOf<'ContentBlock'>().toMatchTypeOf<SpecTypeName>();
+        expectTypeOf<'Tool'>().toMatchTypeOf<SpecTypeName>();
+        expectTypeOf<'Implementation'>().toMatchTypeOf<SpecTypeName>();
+        expectTypeOf<'JSONRPCRequest'>().toMatchTypeOf<SpecTypeName>();
+    });
+
+    it('SpecTypes[K] matches the named export type', () => {
+        expectTypeOf<SpecTypes['CallToolResult']>().toEqualTypeOf<CallToolResult>();
+        expectTypeOf<SpecTypes['ContentBlock']>().toEqualTypeOf<ContentBlock>();
+        expectTypeOf<SpecTypes['Tool']>().toEqualTypeOf<Tool>();
+        expectTypeOf<SpecTypes['Implementation']>().toEqualTypeOf<Implementation>();
+        expectTypeOf<SpecTypes['JSONRPCRequest']>().toEqualTypeOf<JSONRPCRequest>();
+    });
+});