fix(core): preserve field descriptions in the zod <4.2 JSON Schema fallback

.changeset/zod-fallback-description-recovery.md

@@ -0,0 +1,8 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/server': patch
+---
+
+Recover `.describe()` descriptions when converting schemas from zod versions without `~standard.jsonSchema` (zod 4.0/4.1 and the zod@3.25.x `zod/v4` subpath). The bundled-converter fallback previously dropped all registry-held metadata, silently advertising tool schemas without
+any field documentation. The fallback warning can now be silenced with `MCP_SUPPRESS_ZOD_FALLBACK_WARNING=1` and mentions what is and isn't preserved.

docs/migration-SKILL.md

@@ -225,6 +225,14 @@ The variadic `.tool()`, `.prompt()`, `.resource()` methods are removed. Use the
 **IMPORTANT**: v2 requires schema objects implementing [Standard Schema](https://standardschema.dev/) — raw shapes like `{ name: z.string() }` are no longer supported. Wrap with `z.object()` (Zod v4), or use ArkType's `type({...})`, or Valibot. For raw JSON Schema, wrap with
 `fromJsonSchema(schema)` from `@modelcontextprotocol/server` (validator defaults automatically; pass an explicit validator for custom configurations). Applies to `inputSchema`, `outputSchema`, and `argsSchema`.
 
+**Zod version matrix** for `inputSchema`/`outputSchema`/`argsSchema` values:
+
+| Schema's zod lineage                       | Behavior in v2                                                                                                                                             |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| zod >=4.2 (`~standard.jsonSchema` present) | Native conversion, full fidelity                                                                                                                           |
+| zod 4.0 / 4.1, zod@3.25.x `zod/v4` subpath | Bundled-converter fallback + one-time warning (silence: `MCP_SUPPRESS_ZOD_FALLBACK_WARNING=1`); `.describe()` recovered best-effort, `.meta()` may be lost |
+| zod 3 classic (`zod` import from zod@3.x)  | Error at `tools/list` — upgrade to zod 4 or use `fromJsonSchema()`                                                                                         |
+
 ### Tools
 
 ```typescript

docs/migration.md

@@ -313,6 +313,34 @@ This applies to:
 | `SchemaInput<T>`                                                                     | `StandardSchemaWithJSON.InferInput<T>`                            |
 | `getSchemaShape`, `getSchemaDescription`, `isOptionalSchema`, `unwrapOptionalSchema` | No replacement — these are now internal Zod introspection helpers |
 
+#### Using zod 4.0 / 4.1 (or the zod@3.25.x `zod/v4` subpath)
+
+`~standard.jsonSchema` was added in zod 4.2.0. Older zod 4 lineages implement Standard Schema validation but not JSON Schema conversion, so the SDK falls back to converting your schema with its own bundled zod. Because zod stores `.describe()` text in a per-instance metadata
+registry, the bundled converter cannot see metadata attached through your zod instance — the SDK recovers `.describe()` descriptions on a best-effort basis (top level, object properties, array elements, and `.optional()`/`.nullable()`/`.default()` wrappers), but other registry
+metadata attached via `.meta()` may be lost.
+
+The fallback logs a one-time warning. Silence it with `MCP_SUPPRESS_ZOD_FALLBACK_WARNING=1`, or upgrade to zod >=4.2.0 for full fidelity. If upgrading isn't an option, you can supply the converter from your own zod instance, which preserves all metadata:
+
+```typescript
+import * as z from 'zod/v4'; // your zod, any 4.x lineage
+
+function withJsonSchema<T extends z.ZodType>(schema: T) {
+    return {
+        '~standard': {
+            ...schema['~standard'],
+            jsonSchema: {
+                input: () => z.toJSONSchema(schema, { target: 'draft-2020-12', io: 'input' }),
+                output: () => z.toJSONSchema(schema, { target: 'draft-2020-12', io: 'output' })
+            }
+        }
+    };
+}
+
+server.registerTool('greet', { inputSchema: withJsonSchema(z.object({ name: z.string().describe('who to greet') })) }, handler);
+```
+
+zod 3 schemas (the classic `zod` import from zod@3.x) cannot be converted at all and produce a clear error at `tools/list` time — upgrade to zod 4, or describe your input with `fromJsonSchema()` instead.
+
 ### Host header validation moved
 
 Express-specific middleware (`hostHeaderValidation()`, `localhostHostValidation()`) moved from the server package to `@modelcontextprotocol/express`. The server package now exports framework-agnostic functions instead: `validateHostHeader()`, `localhostAllowedHostnames()`,

packages/core/package.json

@@ -77,27 +77,28 @@
         }
     },
     "devDependencies": {
-        "@modelcontextprotocol/tsconfig": "workspace:^",
-        "@modelcontextprotocol/vitest-config": "workspace:^",
-        "@modelcontextprotocol/eslint-config": "workspace:^",
         "@cfworker/json-schema": "catalog:runtimeShared",
-        "ajv": "catalog:runtimeShared",
-        "ajv-formats": "catalog:runtimeShared",
         "@eslint/js": "catalog:devTools",
+        "@modelcontextprotocol/eslint-config": "workspace:^",
+        "@modelcontextprotocol/tsconfig": "workspace:^",
+        "@modelcontextprotocol/vitest-config": "workspace:^",
         "@types/content-type": "catalog:devTools",
         "@types/cors": "catalog:devTools",
         "@types/cross-spawn": "catalog:devTools",
         "@types/eventsource": "catalog:devTools",
         "@types/express": "catalog:devTools",
         "@types/express-serve-static-core": "catalog:devTools",
         "@typescript/native-preview": "catalog:devTools",
+        "ajv": "catalog:runtimeShared",
+        "ajv-formats": "catalog:runtimeShared",
         "eslint": "catalog:devTools",
         "eslint-config-prettier": "catalog:devTools",
         "eslint-plugin-n": "catalog:devTools",
         "prettier": "catalog:devTools",
         "tsx": "catalog:devTools",
         "typescript": "catalog:devTools",
         "typescript-eslint": "catalog:devTools",
-        "vitest": "catalog:devTools"
+        "vitest": "catalog:devTools",
+        "zod-v40": "npm:zod@4.0.17"
     }
 }

packages/core/src/util/standardSchema.ts

@@ -164,6 +164,131 @@
 
 let warnedZodFallback = false;
 
+function isZodFallbackWarningSuppressed(): boolean {
+    // Core must stay runtime-neutral (browser / Workers), so reach for `process` defensively.
+    try {
+        const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+        const value = env?.MCP_SUPPRESS_ZOD_FALLBACK_WARNING;
+        return value !== undefined && value !== '' && value !== '0' && value !== 'false';
+    } catch {
+        return false;
+    }
+}
+
+function readForeignDescription(node: unknown): string | undefined {
+    // `.description` is a getter that runs the schema's own zod code against its own
+    // metadata registry, so it works across zod instances where the bundled converter
+    // cannot. Foreign getters are untrusted: never let them break conversion.
+    try {
+        const description = (node as { description?: unknown }).description;
+        return typeof description === 'string' && description.length > 0 ? description : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+function unwrapForeignSchema(node: unknown): unknown {
+    // Wrappers like .optional()/.nullable()/.default() carry their own registry entry;
+    // a .describe() applied before wrapping lives on the inner schema instead.
+    try {
+        const def = (node as { _zod?: { def?: { innerType?: unknown } } })._zod?.def;
+        return def?.innerType;
+    } catch {
+        return undefined;
+    }
+}
+
+function readForeignDescriptionDeep(node: unknown): string | undefined {
+    let current: unknown = node;
+    for (let depth = 0; depth < 8 && current != null; depth++) {
+        const description = readForeignDescription(current);
+        if (description !== undefined) return description;
+        current = unwrapForeignSchema(current);
+    }
+    return undefined;
+}
+
+function foreignShape(node: unknown): Record<string, unknown> | undefined {
+    let current: unknown = node;
+    for (let depth = 0; depth < 8 && current != null; depth++) {
+        try {
+            const shape = (current as { shape?: unknown }).shape;
+            if (shape != null && typeof shape === 'object') return shape as Record<string, unknown>;
+        } catch {
+            return undefined;
+        }
+        current = unwrapForeignSchema(current);
+    }
+    return undefined;
+}
+
+function foreignElement(node: unknown): unknown {
+    let current: unknown = node;
+    for (let depth = 0; depth < 8 && current != null; depth++) {
+        try {
+            const element = (current as { element?: unknown }).element;
+            if (element != null) return element;
+        } catch {
+            return undefined;
+        }
+        current = unwrapForeignSchema(current);
+    }
+    return undefined;
+}
+
+/**
+ * Best-effort recovery of `.describe()` metadata after converting a foreign zod
+ * instance's schema with the SDK-bundled `z.toJSONSchema()`.
+ *
+ * Zod stores `.describe()` text in a per-instance metadata registry, so the bundled
+ * converter silently drops every description attached through a different zod instance
+ * (zod 4.0/4.1, or the zod@3.25.x `zod/v4` subpath). The schema's own `.description`
+ * getters still work, so walk the schema alongside the converted JSON Schema and fill
+ * in any descriptions the converter missed. Existing descriptions are never overwritten.
+ */
+function recoverForeignDescriptions(schema: unknown, jsonSchema: Record<string, unknown>, path = new WeakSet<object>(), depth = 0): void {
+    if (depth > 16 || schema == null || typeof schema !== 'object') return;
+    // Cycle detection is scoped to the current recursion path: a schema instance that is
+    // *reused* at several positions (sibling properties, nested objects) is converted to a
+    // distinct JSON Schema node per occurrence and must be recovered at every one of them.
+    // Only a true ancestor cycle stops the walk; the depth cap bounds everything else.
+    if (path.has(schema)) return;
+    path.add(schema);
+    try {
+        recoverNode(schema, jsonSchema, path, depth);
+    } finally {
+        path.delete(schema);
+    }
+}
+
+function recoverNode(schema: object, jsonSchema: Record<string, unknown>, path: WeakSet<object>, depth: number): void {
+    if (jsonSchema.description === undefined) {
+        const description = readForeignDescriptionDeep(schema);
+        if (description !== undefined) jsonSchema.description = description;
+    }
+
+    const properties = jsonSchema.properties;
+    if (properties != null && typeof properties === 'object') {
+        const shape = foreignShape(schema);
+        if (shape) {
+            for (const [key, fieldSchema] of Object.entries(shape)) {
+                const fieldJson = (properties as Record<string, unknown>)[key];
+                if (fieldJson != null && typeof fieldJson === 'object') {
+                    recoverForeignDescriptions(fieldSchema, fieldJson as Record<string, unknown>, path, depth + 1);
+                }
+            }
+        }
+    }
+
+    const items = jsonSchema.items;
+    if (items != null && typeof items === 'object' && !Array.isArray(items)) {
+        const element = foreignElement(schema);
+        if (element != null) {
+            recoverForeignDescriptions(element, items as Record<string, unknown>, path, depth + 1);
+        }
+    }
+}
+
 /**
  * Converts a StandardSchema to JSON Schema for use as an MCP tool/prompt schema.
  *
@@ -190,14 +315,17 @@
                     'Upgrade to zod >=4.2.0, or wrap your JSON Schema with fromJsonSchema().'
             );
         }
-        if (!warnedZodFallback) {
+        if (!warnedZodFallback && !isZodFallbackWarningSuppressed()) {
             warnedZodFallback = true;
             console.warn(
                 '[mcp-sdk] Your zod version does not implement `~standard.jsonSchema` (added in zod 4.2.0). ' +
-                    'Falling back to z.toJSONSchema(). Upgrade to zod >=4.2.0 to silence this warning.'
+                    'Falling back to the bundled converter; `.describe()` descriptions are recovered on a best-effort ' +
+                    'basis but other registry metadata (`.meta()`) may be lost. Upgrade to zod >=4.2.0 for full ' +
+                    'fidelity, or set MCP_SUPPRESS_ZOD_FALLBACK_WARNING=1 to silence this warning.'
             );
         }
         result = z.toJSONSchema(schema as unknown as z.ZodType, { target: 'draft-2020-12', io }) as Record<string, unknown>;
+        recoverForeignDescriptions(schema, result);
     } else {
         throw new Error(
             `Schema library "${std.vendor}" does not implement StandardJSONSchemaV1 (\`~standard.jsonSchema\`). ` +