fix(core-internal): harden the missing-key probe and cover enum-keyed records

- fieldAcceptsMissingKey no longer lets a throwing .transform()/.refine()
  escape the probe: depending on the zod build, ~standard.validate(undefined)
  either throws synchronously or returns a rejecting Promise whose unhandled
  rejection crashes the process during tools/list conversion. Both modes now
  conservatively keep the field required, and the Promise branch attaches a
  no-op catch so no rejection floats.
- Enum-keyed records (def.type === 'record') also emit a required list zod
  does not enforce when the shared value schema is defaulted or
  undefined-accepting; the override now drops it (all-or-nothing, since every
  key shares the one value schema).
- Move StandardSchemaToJsonSchemaOptions above the conversion function's
  JSDoc block so the doc comment re-attaches to the function it describes,
  and give the interface its own one-liner.
- Stop overclaiming in the changeset and JSDoc: BigInt values embedded as
  defaults or metadata (.default(0n), .meta({default: 1n})) still fail
  conversion inside zod's own processors, outside the override's reach.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: claude

.changeset/zod-tojsonschema-wire-truthful.md

@@ -3,12 +3,16 @@
 '@modelcontextprotocol/server': patch
 ---
 
-Make zod-to-JSON-Schema conversion wire-truthful for tool schemas. A `z.date()` (or any
-unrepresentable type) in a registered tool's schema no longer throws during conversion and
-fails the entire `tools/list` response — dates are advertised as `{type: 'string', format:
-'date-time'}` (the shape `JSON.stringify` actually produces), and other unrepresentable
-types degrade to an unconstrained schema. Output schemas no longer advertise constraints the
-server doesn't enforce on the raw `structuredContent` it ships: `.default()`-carrying fields
-are dropped from `required`, and `additionalProperties: false` is dropped for plain
-`z.object()` (kept for `z.strictObject()`), so validating clients no longer reject legitimate
-tool results.
+Make zod-to-JSON-Schema conversion wire-truthful for tool schemas. A `z.date()` (or another
+unrepresentable type such as `z.bigint()`) in a registered tool's schema no longer throws
+during conversion and fails the entire `tools/list` response — dates are advertised as
+`{type: 'string', format: 'date-time'}` (the shape `JSON.stringify` actually produces), and
+other unrepresentable types degrade to an unconstrained schema. (BigInt values embedded as
+defaults or metadata, e.g. `.default(0n)`, still fail conversion — JSON cannot carry them.)
+Output schemas no longer advertise constraints the server doesn't enforce on the raw
+`structuredContent` it ships: fields that may be legitimately absent (`.default()`,
+undefined-accepting types) are dropped from `required` — on objects and enum-keyed records —
+and `additionalProperties: false` is dropped for plain `z.object()` (kept for
+`z.strictObject()`), so validating clients no longer reject legitimate tool results.
+Elicitation is unaffected: `inputRequired.elicit()` keeps throwing on schemas its restricted
+form grammar cannot round-trip, including `z.date()`.

packages/core-internal/src/util/standardSchema.ts

@@ -180,13 +180,16 @@ export const JSON_SCHEMA_CONVERSION_TARGET = 'draft-2020-12';
  *
  * - `unrepresentable: 'any'`: a single unrepresentable type (e.g. `z.bigint()`) degrades
  *   to an unconstrained `{}` instead of throwing and failing the entire `tools/list`.
+ *   (BigInt *values* embedded as defaults or metadata — `.default(0n)`, `.meta({default: 1n})`
+ *   — still throw: zod JSON-round-trips them in its own processors, outside this hook's reach.)
  * - `z.date()` is rewritten to `{type: 'string', format: 'date-time'}` — the shape
  *   `JSON.stringify` actually produces for a `Date` (and what the zod 3 converter emitted).
  * - Output objects drop `additionalProperties: false` unless the object is strict:
  *   zod validation tolerates unknown keys on plain `z.object()`, and the raw payload
  *   ships them.
- * - Output objects drop `.default()`-carrying properties from `required`: zod fills
- *   defaults during validation, but the shipped payload may legitimately omit them.
+ * - Output objects and enum-keyed records drop properties that may be legitimately
+ *   absent from the shipped payload (`.default()`, undefined-accepting types) from
+ *   `required`: zod fills defaults during validation, but ships the raw object.
  */
 function zodConversionOptions(io: 'input' | 'output'): Pick<z.core.ToJSONSchemaParams, 'unrepresentable' | 'override'> {
     return {
@@ -200,7 +203,16 @@ function zodConversionOptions(io: 'input' | 'output'): Pick<z.core.ToJSONSchemaP
                 ctx.jsonSchema.format = 'date-time';
                 return;
             }
-            if (io !== 'output' || def.type !== 'object') return;
+            if (io !== 'output') return;
+            if (def.type === 'record') {
+                // Enum-keyed records emit a `required` list too. Every key shares the one
+                // value schema, so tolerance for missing keys is all-or-nothing.
+                if (Array.isArray(ctx.jsonSchema.required) && fieldAcceptsMissingKey(def.valueType)) {
+                    delete ctx.jsonSchema.required;
+                }
+                return;
+            }
+            if (def.type !== 'object') return;
             const isStrict = def.catchall?._zod.def.type === 'never';
             if (!isStrict && ctx.jsonSchema.additionalProperties === false) {
                 delete ctx.jsonSchema.additionalProperties;
@@ -225,26 +237,26 @@ function zodConversionOptions(io: 'input' | 'output'): Pick<z.core.ToJSONSchemaP
  * Whether a raw payload that omits this field still passes validation (zod treats a
  * missing key as `undefined` — true for `.default()`/`.prefault()`, `z.any()`,
  * `z.unknown()`, `z.undefined()`, and unions with them), so the wire schema must not
- * advertise the field as `required`. Async validation cannot be awaited here; such
- * fields conservatively stay required.
+ * advertise the field as `required`. A probe that throws, rejects, or goes async (a
+ * `.transform()` choking on `undefined` does all three depending on the zod version)
+ * cannot demonstrate tolerance, so such fields conservatively stay required.
  */
 function fieldAcceptsMissingKey(field: z.core.$ZodType | undefined): boolean {
     if (field === undefined) return false;
-    const result = field['~standard'].validate(undefined);
-    return !(result instanceof Promise) && result.issues === undefined;
+    try {
+        const result = field['~standard'].validate(undefined);
+        if (result instanceof Promise) {
+            // Never leave a floating rejection: an unhandled one crashes the process.
+            result.catch(() => {});
+            return false;
+        }
+        return result.issues === undefined;
+    } catch {
+        return false;
+    }
 }
 
-/**
- * Converts a StandardSchema to JSON Schema for use as an MCP tool/prompt schema.
- *
- * MCP requires `type: "object"` at the root of tool `inputSchema` and prompt
- * argument schemas; `outputSchema` may have any JSON Schema root (SEP-2106).
- * Zod's discriminated unions emit `{oneOf: [...]}` without a top-level `type`,
- * so for `io: 'input'` this function defaults `type` to `"object"` when absent
- * and throws on an explicit non-object `type` (e.g. `z.string()`). For
- * `io: 'output'` a non-object root is returned as-is; the `"object"` default is
- * applied only when the root is provably object-shaped.
- */
+/** Options for {@linkcode standardSchemaToJsonSchema}. */
 export interface StandardSchemaToJsonSchemaOptions {
     /**
      * How types JSON Schema cannot represent (`z.date()`, `z.bigint()`, …) are handled
@@ -262,6 +274,17 @@ export interface StandardSchemaToJsonSchemaOptions {
     unrepresentable?: 'wire' | 'throw';
 }
 
+/**
+ * Converts a StandardSchema to JSON Schema for use as an MCP tool/prompt schema.
+ *
+ * MCP requires `type: "object"` at the root of tool `inputSchema` and prompt
+ * argument schemas; `outputSchema` may have any JSON Schema root (SEP-2106).
+ * Zod's discriminated unions emit `{oneOf: [...]}` without a top-level `type`,
+ * so for `io: 'input'` this function defaults `type` to `"object"` when absent
+ * and throws on an explicit non-object `type` (e.g. `z.string()`). For
+ * `io: 'output'` a non-object root is returned as-is; the `"object"` default is
+ * applied only when the root is provably object-shaped.
+ */
 export function standardSchemaToJsonSchema(
     schema: StandardJSONSchemaV1,
     io: 'input' | 'output' = 'input',

packages/core-internal/test/util/standardSchema.test.ts

@@ -113,6 +113,37 @@ describe('zod conversion options (#2464)', () => {
         expect(result.required).toEqual(['name']);
     });
 
+    test('enum-keyed records with a defaulted value drop the emitted required list (output)', () => {
+        const schema = z.object({ tallies: z.record(z.enum(['likes', 'shares']), z.number().default(0)), name: z.string() });
+        const result = standardSchemaToJsonSchema(schema, 'output');
+
+        // zod fills record defaults during validation, so `{}` is a legitimate raw value
+        // for the record node — but the record field itself stays required on the parent.
+        const tallies = (result.properties as Record<string, Record<string, unknown>>).tallies!;
+        expect(tallies.required).toBeUndefined();
+        expect(result.required).toEqual(['tallies', 'name']);
+    });
+
+    test('enum-keyed records with a strict value keep the emitted required list (output)', () => {
+        const schema = z.record(z.enum(['likes', 'shares']), z.number());
+        const result = standardSchemaToJsonSchema(schema, 'output');
+
+        // Validation rejects a missing key here, so the required list is truthful.
+        expect(result.required).toEqual(['likes', 'shares']);
+    });
+
+    test('a required field whose transform throws on undefined stays required and does not crash', async () => {
+        const schema = z.object({ n: z.unknown().transform(v => (v as string).length), name: z.string() });
+        const result = standardSchemaToJsonSchema(schema, 'output');
+
+        // The missing-key probe cannot demonstrate tolerance (the transform throws on
+        // undefined; depending on the zod version the probe throws synchronously or
+        // returns a rejecting Promise) — the field conservatively stays required, and
+        // no unhandled rejection may escape (vitest fails the run on one).
+        expect(result.required).toEqual(['n', 'name']);
+        await new Promise(resolve => setTimeout(resolve, 10));
+    });
+
     test('plain z.object() output schemas do not advertise additionalProperties:false', () => {
         const result = standardSchemaToJsonSchema(z.object({ name: z.string() }), 'output');