feat: generate schemas from types, improve type definitions

[ochafik]

Summary

This PR adds auto-generated Zod schemas and types from spec.types.ts using ts-to-zod + AST-based refactorings (for complete backwards compatibility), plus discriminated union types (McpRequest, McpNotification, McpResult) for better TypeScript type narrowing.

See Reviewer Verification section below for scripts to compare exports between branches.

Key Features

1. Schema Generation Pipeline

spec.types.ts (from MCP spec repo) ↓ preProcessTypes() [AST transforms] sdk.types.ts (SDK-compatible types + union types) ↓ ts-to-zod library ↓ postProcess() [AST transforms] sdk.schemas.ts (Zod schemas) 

2. Discriminated Union Types for Type Narrowing

// New union types enable TypeScript narrowing on 'method' fieldtypeMcpRequest=InitializeRequest|PingRequest|CallToolRequest| ... functionhandleRequest(request: McpRequest){if(request.method==='tools/call'){// TypeScript knows this is CallToolRequestconsole.log(request.params.name);// ✓ typed as string}}

3. Naming Scheme

Type	Name	Description
Base interface	Request, Notification, Result	Backwards-compatible base types
Union type	McpRequest, McpNotification, McpResult	Discriminated unions for narrowing

4. Client/Server Use Union Types by Default

Client and Server now default to union types for better type narrowing out of the box:

// Before: Client<Request, Notification, Result>// After: Client<McpRequest, McpNotification, McpResult>constclient=newClient({name: "my-client",version: "1.0"});// Users get type narrowing automatically// Custom types still work (must extend base types)constclient=newClient<MyRequest,MyNotification,MyResult>(...);

Note: This is technically a breaking change if you explicitly annotated variables with the old defaults (e.g., Client<Request, Notification, Result>), but this is unlikely since those were the defaults and writing them explicitly would be redundant.

Schema Post-Processing

The script applies several transforms for SDK compatibility:

Transform	Purpose
Zod v4 import	"zod" → "zod/v4"
Index signatures	z.record().and(z.object()) → z.looseObject()
Integer refinements	Add .int() to ProgressTokenSchema, RequestIdSchema
Content defaults	Add .default([]) to content arrays for backwards compat
Passthrough	Add .passthrough() to ToolSchema.outputSchema
Union ordering	Reorder so specific schemas match first (EnumSchema before StringSchema)
Discriminated unions	Convert tagged unions for better performance
Field validation	Add datetime, startsWith, base64 validation

Configuration-Driven Transforms

Transforms are declaratively configured:

// Schemas needing .default([]) on content fieldconstARRAY_DEFAULT_FIELDS={'CallToolResultSchema': ['content'],'ToolResultContentSchema': ['content'],};// Union member ordering (more specific schemas first)constUNION_MEMBER_ORDER={'PrimitiveSchemaDefinitionSchema': ['EnumSchemaSchema','BooleanSchemaSchema', ...],'EnumSchemaSchema': ['LegacyTitledEnumSchemaSchema', ...],};

Generated Files

File	Description
sdk.types.ts	Pre-processed types with base interfaces + union types
sdk.schemas.ts	Zod schemas with all post-processing applied
sdk.schemas.zod.test.ts	Integration tests for schema/type alignment

types.ts: Now a Thin Re-export Layer

src/types.ts is now primarily a re-export layer from the generated files:

// ~130 types re-exported from generated fileexporttype{Request,Notification,Result,McpRequest,McpNotification,McpResult, ... }from'./generated/sdk.types.js';// ~120 schemas re-exported from generated fileexport{JSONRPCMessageSchema,CallToolResultSchema, ... }from'./generated/sdk.schemas.js';// Only a few SDK-specific items still defined locally:// - JSONRPCResponseSchema (union of result + error)// - ProgressSchema (derived from ProgressNotificationParamsSchema)// - Type guards (isJSONRPCRequest, etc.)// - ErrorCode enum

Test Results

• ✅ Typecheck: 0 errors
• ✅ Tests: 1583 passed
• ✅ All union types work correctly for narrowing
• ✅ Export comparison: 329 → 334 symbols (5 additions, 0 removals)

---

Reviewer Verification

export-symbols.ts

#!/usr/bin/env npx tsx /** * List all exported symbols from src/types.ts using TypeScript compiler API. * Usage: npx tsx export-symbols.ts [--json] */import*astsfrom'typescript';import*aspathfrom'path';consttypesPath=path.resolve(import.meta.dirname,'src/types.ts');constjsonOutput=process.argv.includes('--json');constprogram=ts.createProgram([typesPath],{target: ts.ScriptTarget.ESNext,module: ts.ModuleKind.ESNext,moduleResolution: ts.ModuleResolutionKind.NodeNext,strict: true,skipLibCheck: true,});constchecker=program.getTypeChecker();constsourceFile=program.getSourceFile(typesPath);if(!sourceFile){console.error('Could not find:',typesPath);process.exit(1);}interfaceExportInfo{name: string;kind: string;isType: boolean;}constexports: ExportInfo[]=[];constmoduleSymbol=checker.getSymbolAtLocation(sourceFile);if(moduleSymbol){for(constsymbolofchecker.getExportsOfModule(moduleSymbol)){constname=symbol.getName();constdeclarations=symbol.getDeclarations();letkind='unknown',isType=false;if(declarations?.length){constdecl=declarations[0];if(ts.isTypeAliasDeclaration(decl)){kind='type';isType=true;}elseif(ts.isInterfaceDeclaration(decl)){kind='interface';isType=true;}elseif(ts.isVariableDeclaration(decl)){kind='const';}elseif(ts.isEnumDeclaration(decl)){kind='enum';}elseif(ts.isFunctionDeclaration(decl)){kind='function';}elseif(ts.isExportSpecifier(decl)){constorig=checker.getAliasedSymbol(symbol).getDeclarations()?.[0];if(orig){if(ts.isTypeAliasDeclaration(orig)){kind='type';isType=true;}elseif(ts.isInterfaceDeclaration(orig)){kind='interface';isType=true;}elseif(ts.isVariableDeclaration(orig)){kind='const';}elseif(ts.isEnumDeclaration(orig)){kind='enum';}}}}exports.push({ name, kind, isType });}}exports.sort((a,b)=>a.name.localeCompare(b.name));if(jsonOutput){console.log(JSON.stringify(exports,null,2));}else{exports.forEach(e=>console.log(`${e.kind}\t${e.name}`));}

# Compare exported symbols between branches npx tsx export-symbols.ts --json > pr-symbols.json git stash && git checkout main npx tsx export-symbols.ts --json > main-symbols.json git checkout - && git stash pop diff <(jq -r '.[].name' main-symbols.json | sort)<(jq -r '.[].name' pr-symbols.json | sort)

Expected: Only additions (5 new exports), no removals:

• McpRequest, McpNotification, McpResult - new union types for type narrowing
• ElicitationCapabilitySchema, ErrorSchema - new schemas

export-schemas-to-json.ts

#!/usr/bin/env npx tsx /** * Export all Zod schemas to JSON Schema format. * Usage: npm run build && npx tsx export-schemas-to-json.ts */import{toJSONSchema}from'zod/v4-mini';importtype{$ZodType}from'zod/v4/core';import*astypesfrom'./dist/esm/types.js';constschemaExports: Record<string,unknown>={};for(const[name,value]ofObject.entries(types)){if(name.endsWith('Schema')&&value&&typeofvalue==='object'&&'_zod'invalue){try{schemaExports[name]=toJSONSchema(valueas$ZodType,{target: 'draft-7'});}catch(e){schemaExports[name]={error: String(e)};}}}constsorted: Record<string,unknown>={};for(constnameofObject.keys(schemaExports).sort()){sorted[name]=schemaExports[name];}console.log(JSON.stringify(sorted,null,2));

# Compare JSON Schema output between branches npm run build && npx tsx export-schemas-to-json.ts > pr-schemas.json git stash && git checkout main npm run build && npx tsx export-schemas-to-json.ts > main-schemas.json git checkout - && git stash pop diff <(jq -r 'keys[]' main-schemas.json | sort)<(jq -r 'keys[]' pr-schemas.json | sort)

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/sdk@1292 

commit: 1ebf506