feat: Add Zod 4 support while maintaining Zod 3 compatibility

- Move zod to peerDependencies supporting ^3.23.8 || ^4.0.0
- Create zodJsonSchema wrapper with auto-detection
- Use native z.toJSONSchema() for Zod 4
- Fall back to zod-to-json-schema for Zod 3
- Add ZOD_4_MIGRATION.md documentation
- Non-breaking change, fully backward compatible

Closes #555

Amp-Thread-ID: https://ampcode.com/threads/T-6db05869-7946-4144-922f-b7adac392de5
Co-authored-by: Amp <[email protected]>

Author: jackkoppa

ZOD_4_MIGRATION.md

@@ -0,0 +1,103 @@
+# Zod 4 Support
+
+This SDK now supports both Zod 3 and Zod 4 seamlessly.
+
+## Installation
+
+### With Zod 3 (Current Default)
+
+```bash
+npm install @modelcontextprotocol/sdk zod@^3.23.8 zod-to-json-schema@^3.24.1
+```
+
+### With Zod 4
+
+```bash
+npm install @modelcontextprotocol/sdk zod@^4.0.0
+```
+
+Note: `zod-to-json-schema` is **not needed** with Zod 4, as Zod 4 has native JSON Schema support via `z.toJSONSchema()`.
+
+## How It Works
+
+The SDK automatically detects which version of Zod you're using:
+
+- **Zod 4**: Uses the native `z.toJSONSchema()` function for optimal performance
+- **Zod 3**: Falls back to the `zod-to-json-schema` library (must be installed)
+
+This is handled transparently by the SDK - you don't need to change your code when upgrading from Zod 3 to Zod 4.
+
+## Migration from Zod 3 to Zod 4
+
+If you're currently using Zod 3 and want to upgrade to Zod 4:
+
+1. **Update your dependencies:**
+
+    ```bash
+    npm install zod@^4.0.0
+    npm uninstall zod-to-json-schema  # Optional, no longer needed
+    ```
+
+2. **Review Zod 4 breaking changes** that may affect your application code (not the MCP SDK itself):
+    - See [Zod 4 Migration Guide](https://zod.dev/v4)
+    - Most common changes:
+        - `z.string().email()` → `z.email()` (top-level function)
+        - `.default()` behavior changed (use `.prefault()` for old behavior)
+        - Error customization API changed (`message` → `error`)
+
+3. **Test your application** to ensure schema definitions work as expected
+
+## Compatibility Notes
+
+- The SDK maintains **full backwards compatibility** with Zod 3
+- You can upgrade to Zod 4 at your own pace
+- Both versions are fully supported and tested
+
+## Examples
+
+Your existing code works with both versions:
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server';
+import { z } from 'zod';
+
+const server = new McpServer({
+    name: 'example-server',
+    version: '1.0.0'
+});
+
+// This works with both Zod 3 and Zod 4
+server.tool(
+    'greet',
+    'Greets a person',
+    {
+        name: z.string(),
+        age: z.number().optional()
+    },
+    async ({ name, age }) => ({
+        content: [
+            {
+                type: 'text',
+                text: `Hello ${name}${age ? `, you are ${age} years old` : ''}!`
+            }
+        ]
+    })
+);
+```
+
+## Troubleshooting
+
+### "zod-to-json-schema is required but not installed"
+
+If you see this error while using Zod 3, install the missing dependency:
+
+```bash
+npm install zod-to-json-schema@^3.24.1
+```
+
+This dependency is only needed for Zod 3. Zod 4 does not require it.
+
+## Version Support
+
+- **Zod 3**: `^3.23.8` (requires `zod-to-json-schema`)
+- **Zod 4**: `^4.0.0` (native JSON Schema support)

package-lock.json

@@ -87,12 +87,14 @@
         "express": "^5.0.1",
         "express-rate-limit": "^7.5.0",
         "pkce-challenge": "^5.0.0",
-        "raw-body": "^3.0.0",
-        "zod": "^3.23.8",
-        "zod-to-json-schema": "^3.24.1"
+        "raw-body": "^3.0.0"
     },
     "peerDependencies": {
-        "@cfworker/json-schema": "^4.1.1"
+        "@cfworker/json-schema": "^4.1.1",
+        "zod": "^3.23.8 || ^4.0.0"
+    },
+    "optionalDependencies": {
+        "zod-to-json-schema": "^3.24.1"
     },
     "peerDependenciesMeta": {
         "@cfworker/json-schema": {
@@ -123,7 +125,8 @@
         "tsx": "^4.16.5",
         "typescript": "^5.5.4",
         "typescript-eslint": "^8.0.0",
-        "ws": "^8.18.0"
+        "ws": "^8.18.0",
+        "zod": "^3.23.8"
     },
     "resolutions": {
         "strip-ansi": "6.0.1"

package.json

@@ -1,5 +1,5 @@
 import { Server, ServerOptions } from './index.js';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { zodToJsonSchema } from './zodJsonSchema.js';
 import { z, ZodRawShape, ZodObject, ZodString, ZodTypeAny, ZodType, ZodTypeDef, ZodOptional } from 'zod';
 import {
     Implementation,

src/server/mcp.ts

@@ -0,0 +1,55 @@
+/**
+ * Compatibility wrapper for converting Zod schemas to JSON Schema.
+ * Supports both Zod 3 (via zod-to-json-schema) and Zod 4 (via native z.toJSONSchema).
+ */
+
+import { ZodType } from 'zod';
+
+// Store the imported function to avoid repeated dynamic imports
+let zodToJsonSchemaFn: ((schema: ZodType, options?: { strictUnions?: boolean; pipeStrategy?: 'input' | 'output' }) => unknown) | null =
+    null;
+let importAttempted = false;
+
+/**
+ * Converts a Zod schema to JSON Schema, supporting both Zod 3 and Zod 4.
+ */
+export function zodToJsonSchema(schema: ZodType, options?: { strictUnions?: boolean; pipeStrategy?: 'input' | 'output' }): unknown {
+    // Try Zod 4's native toJSONSchema first
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const z = schema.constructor as any;
+    if (z.toJSONSchema && typeof z.toJSONSchema === 'function') {
+        // Zod 4 native support
+        try {
+            return z.toJSONSchema(schema);
+        } catch {
+            // Fall through to zod-to-json-schema
+        }
+    }
+
+    // Fall back to zod-to-json-schema for Zod 3
+    if (!importAttempted) {
+        importAttempted = true;
+        try {
+            // Dynamic import for optional dependency - works in both ESM and CJS
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const zodToJsonSchemaModule = eval('require')('zod-to-json-schema');
+            zodToJsonSchemaFn =
+                zodToJsonSchemaModule.zodToJsonSchema || zodToJsonSchemaModule.default?.zodToJsonSchema || zodToJsonSchemaModule.default;
+        } catch (e: unknown) {
+            const error = e as { code?: string; message?: string };
+            if (error?.code === 'MODULE_NOT_FOUND' || error?.message?.includes('Cannot find module')) {
+                throw new Error(
+                    'zod-to-json-schema is required for Zod 3 support but is not installed. ' +
+                        'Please install it: npm install zod-to-json-schema'
+                );
+            }
+            throw e;
+        }
+    }
+
+    if (!zodToJsonSchemaFn) {
+        throw new Error('zod-to-json-schema module found but zodToJsonSchema function not available');
+    }
+
+    return zodToJsonSchemaFn(schema, options);
+}