`registerTool` type error with zod 4.4.x — `ZodString` not assignable to `AnySchema`

[quotentiroler]

Description

When using @modelcontextprotocol/sdk@1.29.0 with zod@4.4.x (tested with 4.4.1), TypeScript reports type errors on registerTool calls. The AnySchema type defined in zod-compat.d.ts fails to structurally match zod 4.4's schema types (ZodString, ZodOptional<ZodNumber>, etc.).

This is a compile-time issue — the code works at runtime but doesn't type-check.

Reproduction

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import * as z from 'zod' // zod@4.4.1

const server = new McpServer({ name: 'test', version: '1.0.0' })

server.registerTool('example', {
  description: 'test tool',
  inputSchema: { name: z.string(), age: z.number().optional() },
}, async ({ name, age }) => {
  return { content: [{ type: 'text', text: `${name} ${age}` }] }
})

Error:

error TS2322: Type 'ZodString' is not assignable to type 'AnySchema'.
  Type 'ZodString' is not assignable to type '$ZodType<unknown, unknown>'.
    Types of property '_zpiInput' are incompatible.

Analysis

The SDK defines:

// zod-compat.d.ts
type AnySchema = z3.ZodTypeAny | z4.$ZodType
type ZodRawShapeCompat = Record<string, AnySchema>

With zod@4.3.6, ZodString satisfies z4.$ZodType through the type chain ZodString → _ZodString → _ZodType → ZodType → $ZodType. Starting with zod@4.4.x, this structural match breaks — likely due to internal type refactoring in zod.

Key observations:

• Direct assignment const s: $ZodType = z.string() (importing $ZodType from zod/v4/core) works in isolation
• The same assignment via the SDK's re-exported AnySchema type fails
• This suggests a module identity / declaration merging issue where TypeScript resolves two different $ZodType declarations from the SDK's internal zod dependency vs the project's zod

Workaround

Pin zod to 4.3.6 — this satisfies both the SDK's peer dep (^3.25 || ^4.0) and the AI SDK's peer dep (^3.25.76 || ^4.1.8).

Environment

• @modelcontextprotocol/sdk: 1.29.0
• zod: 4.4.1 (fails) / 4.3.6 (works)
• TypeScript: 5.8.3
• Runtime: Bun 1.2.x
• OS: Windows 11

[quotentiroler]

The SDK correctly declares zod: "^3.25 || ^4.0" as a peer dependency, but bun installs a nested zod@3.25.76 inside node_modules/@modelcontextprotocol/sdk/node_modules/zod (satisfying the ^3.25 half) while the project uses zod@4.4.2 at the top level. TypeScript then sees two incompatible type hierarchies.

Workaround: "overrides": { "zod": "4.4.2" } in package.json to force deduplication. Not an SDK bug.