feat!: drop Zod v3 support

[mattzcarey]

Summary

This PR removes Zod v3 support from the SDK. Users must now use Zod v4.0 or later.

Key changes:

• Remove all Zod v3 compatibility code (zodCompat.ts, zodJsonSchemaCompat.ts)
• Add new simplified schema.ts utilities using native Zod v4 APIs
• Remove zod-to-json-schema dependency (Zod v4 has built-in z.toJSONSchema())
• Require full Zod schemas instead of raw shapes for inputSchema/argsSchema
• Simplify internal tool/prompt handler execution with closure-based factories

Breaking Changes

1. Zod v4 required

Users must upgrade to Zod v4.0 or later and import from zod/v4:

// Before
import { z } from 'zod';

// After
import * as z from 'zod/v4';

2. Raw shapes no longer supported

Tool inputSchema and prompt argsSchema must now be full Zod schemas:

// Before (v1) - raw shape worked
server.tool('greet', { name: z.string() }, async ({ name }) => { ... });

// After (v2) - must use z.object()
server.registerTool('greet', {
  inputSchema: z.object({ name: z.string() })
}, async ({ name }) => { ... });

// For tools with no parameters
server.registerTool('ping', {
  inputSchema: z.object({})
}, async () => { ... });

3. Removed deprecated exports

• completable() function removed from @modelcontextprotocol/server (use Completable.string() etc.)

Internal Changes

Replaced zodCompat.ts with schema.ts

The 275-line compatibility layer was replaced with a ~95-line utility file using native Zod v4 APIs:

• AnySchema = z.core.$ZodType
• AnyObjectSchema = z.core.$ZodObject
• schemaToJson() wraps z.toJSONSchema()
• parseSchema() / parseSchemaAsync() wrap z.safeParse() / z.safeParseAsync()
• getSchemaShape(), isOptionalSchema(), unwrapOptionalSchema() for schema introspection

Simplified tool/prompt execution

• Added createToolExecutor() closure factory that captures schema types at registration time
• Added createPromptHandler() closure factory for prompts
• Removed runtime type casts from handler execution paths
• executeToolHandler() reduced from ~30 lines to a single tool.executor(args, extra) call

Removed dependencies

• zod-to-json-schema removed (Zod v4 has built-in JSON Schema conversion)
• Removed zod/v3 from workspace dependencies

Files Changed

• Deleted: packages/core/src/util/zodCompat.ts (275 lines)
• Deleted: packages/core/src/util/zodJsonSchemaCompat.ts (53 lines)
• Deleted: test/helpers/src/fixtures/zodTestMatrix.ts (v3/v4 test matrix)
• Added: packages/core/src/util/schema.ts (94 lines)
• Modified: packages/server/src/server/mcp.ts (major refactor)
• Modified: All examples and tests to use zod/v4 imports

Test Plan

• pnpm check:all passes (typecheck + lint)
• pnpm test:all passes (485+ tests)
• Conformance tests pass

---

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: d05b6bf

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/server

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

@modelcontextprotocol/express

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: d05b6bf