feat: zod v4 with backwards compatibility for v3.25+

[dclark27]

Motivation and Context

Add transparent Zod v3/v4 compatibility to the MCP TypeScript SDK, allowing users to install and use either version without any code changes or configuration. This addresses the need for the SDK to support multiple major versions of Zod in user applications.

The SDK exports v4 schemas by default, but the compatibility layer detects the Zod version at runtime and routes all schema operations (parsing, JSON Schema conversion, schema construction) to the appropriate implementation.

Borrowed openai's idea to vendor zod-to-json-schema locally, can be removed if the lib author ever merges their PR.

How Has This Been Tested?

Install the published version and test in your own app:

npm i @socotra/modelcontextprotocol-sdk
# or
pnpm i @socotra/modelcontextprotocol-sdk

Comprehensive Test Coverage

• 49 Test Suites | 1090 Tests (all passing)

• User-facing APIs tested with both v3 and v4:

  • Client core functionality (v3 + v4)
  • Server core functionality (v3 + v4)
  • MCP protocol handling (v3 + v4)
  • All major transports: SSE, HTTP, stdio (v3 + v4)
  • Completable schemas (v3 + v4)
  • Client authentication (v3 + v4)
  • Integration tests: task resumability, state management (v3 + v4)

• Internal utilities tested with v4 only:

  • OAuth schemas and utilities (internal SDK infrastructure)
  • Shared protocol utilities

Test Files Created

• 10+ .v3.test.ts files demonstrating real Zod v3 usage patterns
• Tests import SDK schemas directly from types.js
• Tests define custom schemas using their Zod version
• Identical test logic between v3 and v4 versions

Breaking Changes

None. This is purely additive:

• All v4 (default) behavior unchanged
• No API modifications
• No configuration required
• v3 users benefit automatically through the compat layer

Types of changes

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally (1090/1090 passing)
• I have added appropriate error handling (compat layer includes runtime guards)
• I have added or updated documentation as needed (updated README.md)

Additional context

Implementation Architecture

Compatibility Layer (src/server/zod-compat.ts)

• Runtime schema detection: isZ4Schema(), isZ4Object(), isZ3Object()
• Unified parsing: safeParse(), safeParseAsync()
• Schema construction: objectFromShape(), normalizeObjectSchema()
• Type inference helpers: SchemaOutput<S>, SchemaInput<S>

JSON Schema Routing (src/server/zod-json-schema-compat.ts)

• Detects schema version and routes to appropriate converter
• Maps v3 to vendored converter, v4 to Mini converter
• Transparent option mapping between versions

Design Decisions

1. User-facing tests have both v3 and v4 coverage - Proves users get identical behavior
2. Internal utilities tested with v4 only - No version difference in internal code
3. No hidden test infrastructure - V3 tests import SDK schemas directly, demonstrating real usage
4. Schemas work transparently - Users don't write version-specific code

[dclark27]

Update:

Merge conflicts resolved. 1.20.2-next.0 published under @socotra/modelcontextprotocol-sdk

Update 10/31:

Updated to 1.21.0 and released under @socotra/modelcontextprotocol-sdk

[wladyslawczyzewski]

any info when we should expect this PR to merge? 🤔

[punkpeye]

This PR cannot land soon enough.

[colinhacks]

cc @StefanTerdell

publishing a 3.25.x for zod-to-json-schema would go a long way here.