fix(validators): honor declared draft-07/06 JSON Schema dialects

The default validator rejected any schema declaring a non-2020-12
$schema, so tools from servers emitting zod-to-json-schema's default
draft-07 output (e.g. the Filesystem reference server) failed pre-wire
with InvalidParams before a request was ever sent.

Dispatch on the declared dialect instead, via a classifier shared by
both providers: no $schema or 2020-12 keeps the 2020-12 engine,
draft-07/06 validate with a draft-07 engine (Ajv classic on Node,
draft '7' on the cfworker provider), and unknown dialects still throw
the typed error, now listing the supported dialects. Caller-supplied
engines and explicit { draft } continue to bypass the dispatch.

Author: felixweinberger

.changeset/validator-dialect-dispatch.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/server': patch
+'@modelcontextprotocol/client': patch
+---
+
+The default validator now honors declared draft-07/06 dialects instead of rejecting them: a schema stamped `"$schema": "http://json-schema.org/draft-07/schema#"` (zod-to-json-schema's default output) validates with draft-07 semantics on both the Ajv and Cloudflare Workers providers. Schemas with no `$schema` still validate as 2020-12, and unknown dialects still produce the typed error (now listing the supported dialects).

docs/migration/upgrade-to-v2.md

@@ -707,10 +707,9 @@ the host side and register the result with `fromJsonSchema()`: zod-4 input via z
 own `z.toJSONSchema(z.object(shape), { io: 'input', target: 'draft-2020-12' })` (the
 conversion is runtime-structural, so a zod ≥4.2 in the host handles schemas built by a
 different zod-4 copy), zod-3 input via the
-[`zod-to-json-schema`](https://www.npmjs.com/package/zod-to-json-schema) package. Strip
-the `$schema` member from the converted output before passing it to `fromJsonSchema()`
-— `zod-to-json-schema` stamps a draft-07 `$schema` by default, and the default
-validator [accepts 2020-12 only](#json-schema-2020-12-posture-sep-1613-sep-2106).
+[`zod-to-json-schema`](https://www.npmjs.com/package/zod-to-json-schema) package. Its
+default draft-07 `$schema` stamp is fine as-is — the default validator
+[honors declared draft-07/06 dialects](#json-schema-2020-12-posture-sep-1613-sep-2106).
 
 How a too-old zod surfaces depends on which entry point your code imports. With
 main-entry `import { z } from 'zod'` on a zod-3 range, the project **typechecks cleanly
@@ -1455,9 +1454,11 @@ classes — import it from one package consistently within a process.
 
 #### JSON Schema 2020-12 posture (SEP-1613, SEP-2106)
 
-The default validator supports **JSON Schema 2020-12 only**. On Node it is now `Ajv2020`
-instead of draft-07 `Ajv`; the Cloudflare Workers default was already 2020-12. Schemas
-declaring a different `$schema` are rejected with `Error("…unsupported dialect…")`.
+The default validator dispatches on the schema's declared `$schema`: absent or 2020-12
+validates as **JSON Schema 2020-12** — on Node via `Ajv2020` instead of v1's draft-07
+`Ajv` (the Cloudflare Workers default was already 2020-12) — and a declared draft-07 or
+draft-06 `$schema` validates with draft-07 semantics. Schemas declaring any other
+`$schema` are rejected with `Error("…unsupported dialect…")`.
 
 `CallToolResult.structuredContent` is widened from `{ [k: string]: unknown }` to
 `unknown` (SEP-2106 lifts the `type:"object"` root restriction). The presence check is
@@ -1469,8 +1470,8 @@ surfaced per-tool on `callTool`).
 | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `result.structuredContent.<key>` / `result.structuredContent?.<k>` | narrow first: `const sc = result.structuredContent; if (typeof sc === 'object' && sc !== null && '<k>' in sc) { sc.<k> }`                                                                              |
 | `if (!result.structuredContent)`                                   | `if (result.structuredContent === undefined)`                                                                                                                                                          |
-| relying on default `Ajv` being draft-07                            | `new AjvJsonSchemaValidator(new Ajv({ strict: false, validateFormats: true, validateSchema: false, allErrors: true }))` (import `Ajv`, `addFormats`, `AjvJsonSchemaValidator` from `…/validators/ajv`) |
-| draft-07 idioms via `fromJsonSchema(schema)`                       | `fromJsonSchema(schema, new AjvJsonSchemaValidator(ajv))` — the `McpServer`/`Client` `jsonSchemaValidator` option does **not** reach `fromJsonSchema`-authored schemas                                 |
+| draft-07 idioms **without** a declared `$schema` (a declared draft-07/06 `$schema` dispatches automatically) | `new AjvJsonSchemaValidator(new Ajv({ strict: false, validateFormats: true, validateSchema: false, allErrors: true }))` (import `Ajv`, `addFormats`, `AjvJsonSchemaValidator` from `…/validators/ajv`) |
+| undeclared draft-07 idioms via `fromJsonSchema(schema)`            | `fromJsonSchema(schema, new AjvJsonSchemaValidator(ajv))` — the `McpServer`/`Client` `jsonSchemaValidator` option does **not** reach `fromJsonSchema`-authored schemas                                 |
 | `outputSchema` / `inputSchema` with absolute-URI `$ref`            | inline under `$defs` and reference with `#/$defs/Name`                                                                                                                                                 |
 
 A tool may now register an `outputSchema` whose root is `type:"array"`, `type:"string"`,

packages/core-internal/src/validators/ajvProvider.ts

@@ -6,18 +6,9 @@ import { Ajv as Draft7Ajv } from 'ajv';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import _addFormats from 'ajv-formats';
 
+import { declaredDialect } from './dialects';
 import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './types';
 
-/**
- * Canonical 2020-12 `$schema` URIs (http + https variants, trailing-`#` stripped). When a schema
- * declares anything else, the default provider throws a plain `Error` with a clear message rather
- * than letting the engine crash on an opaque internal error or silently mis-validate.
- */
-const DRAFT_2020_12_URIS: ReadonlySet<string> = new Set([
-    'https://json-schema.org/draft/2020-12/schema',
-    'http://json-schema.org/draft/2020-12/schema'
-]);
-
 /** Structural subset of the AJV interface used by {@link AjvJsonSchemaValidator}. */
 interface AjvLike {
     compile: (schema: unknown) => AjvValidateFunction;
@@ -35,8 +26,8 @@ interface AjvValidateFunction {
 /** `ajv-formats` default export, normalised through the CJS/ESM interop wrapper. */
 const addFormats = _addFormats as unknown as typeof _addFormats.default;
 
-function createDefaultAjvInstance(): AjvLike {
-    const ajv = new Ajv2020({
+function createDefaultAjvInstance(engineClass: typeof Ajv2020 | typeof Draft7Ajv): AjvLike {
+    const ajv = new engineClass({
         strict: false,
         validateFormats: true,
         validateSchema: false,
@@ -50,8 +41,10 @@ function createDefaultAjvInstance(): AjvLike {
  * AJV-backed JSON Schema validator. See `@modelcontextprotocol/{client,server}/validators/ajv`
  * for the customisation entry point (re-exports `Ajv` and `addFormats` from the bundled copy).
  *
- * Default validates as **JSON Schema 2020-12** (SEP-1613). Schemas declaring a different
- * `$schema` are rejected with a plain `Error`; pass a pre-configured Ajv instance to validate
+ * Default dispatches on the schema's declared dialect: no `$schema` or 2020-12 → `Ajv2020`
+ * (SEP-1613); draft-07 or draft-06 → the classic draft-07 `Ajv` class (draft-07's changes over
+ * draft-06 are additive, so one engine covers both). Schemas declaring any other `$schema` are
+ * rejected with a plain `Error`; pass a pre-configured Ajv instance to validate
  * other dialects. The SDK bundles ajv internally but does not re-export `Ajv2020` (its type
  * graph tips downstream declaration bundling — see #2339). To construct a custom 2020-12
  * instance, add `ajv` to your own dependencies (matching the SDK's pinned version) and
@@ -80,15 +73,18 @@ function createDefaultAjvInstance(): AjvLike {
  */
 export class AjvJsonSchemaValidator implements jsonSchemaValidator {
     private _ajv: AjvLike | undefined;
-    /** True iff the constructor received a caller-supplied engine; the `$schema` check is skipped. */
+    /** Lazy classic (draft-07) engine, built on the first draft-07/draft-06-declared schema. */
+    private _ajvDraft7: AjvLike | undefined;
+    /** True iff the constructor received a caller-supplied engine; the `$schema` dispatch is skipped. */
     private readonly _userAjv: boolean;
 
     /**
      * @param ajv - Optional pre-configured AJV-compatible instance. When supplied, this instance is
      * used for **every** schema regardless of its declared `$schema` (the caller owns dialect
-     * choice). When omitted, the provider constructs a single `Ajv2020` instance with
+     * choice). When omitted, the provider constructs per-dialect engines (`Ajv2020`, and the
+     * classic draft-07 `Ajv` for draft-07/06-declared schemas) with
      * `strict: false`, `validateFormats: true`, `validateSchema: false`, `allErrors: true`, and
-     * `ajv-formats` registered — **lazily, on the first {@linkcode getValidator} call**, so
+     * `ajv-formats` registered — **lazily, on the first {@linkcode getValidator} call needing each**, so
      * constructing the provider (e.g. as the default validator of a `Client`/`Server` that never
      * validates a JSON Schema) does not pay the ajv + ajv-formats instantiation cost. The parameter
      * is typed structurally so consumers who don't pass an instance need not have `ajv` installed.
@@ -98,29 +94,30 @@ export class AjvJsonSchemaValidator implements jsonSchemaValidator {
         this._ajv = ajv;
     }
 
-    /** The underlying engine — the default instance is created on first use. */
+    /** The underlying 2020-12 engine — the default instance is created on first use. */
     private get ajv(): AjvLike {
-        return (this._ajv ??= createDefaultAjvInstance());
+        return (this._ajv ??= createDefaultAjvInstance(Ajv2020));
     }
 
-    getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
-        // Caller supplied a specific engine — do not second-guess by `$schema`
-        // (bring-your-own-validator means bring-your-own-dialect).
-        if (
-            !this._userAjv &&
-            '$schema' in schema &&
-            typeof schema.$schema === 'string' &&
-            !DRAFT_2020_12_URIS.has(schema.$schema.replace(/#$/, ''))
-        ) {
-            const declared = schema.$schema.slice(0, 200);
-            throw new Error(
-                `JSON Schema declares an unsupported dialect ("$schema": "${declared}"). ` +
-                    `The default validator supports JSON Schema 2020-12 only; pass a pre-configured ` +
-                    `Ajv instance to AjvJsonSchemaValidator(ajv) to validate other dialects.`
-            );
+    /**
+     * Pick the engine for a schema's declared dialect. A caller-supplied engine is used for
+     * every schema — do not second-guess by `$schema` (bring-your-own-validator means
+     * bring-your-own-dialect). Otherwise: no `$schema` or 2020-12 → `Ajv2020`; draft-07 or
+     * draft-06 → classic `Ajv`; anything else → `Error`.
+     */
+    private _engineFor(schema: JsonSchemaType): AjvLike {
+        if (this._userAjv) {
+            return this.ajv;
         }
+        const dialect = declaredDialect(
+            schema,
+            'pass a pre-configured Ajv instance to AjvJsonSchemaValidator(ajv) to validate other dialects.'
+        );
+        return dialect === '2020-12' ? this.ajv : (this._ajvDraft7 ??= createDefaultAjvInstance(Draft7Ajv));
+    }
 
-        const engine = this.ajv;
+    getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
+        const engine = this._engineFor(schema);
         const ajvValidator =
             '$id' in schema && typeof schema.$id === 'string'
                 ? (engine.getSchema(schema.$id) ?? engine.compile(schema))

packages/core-internal/src/validators/cfWorkerProvider.ts

@@ -10,28 +10,21 @@
 
 import { Validator } from '@cfworker/json-schema';
 
+import { declaredDialect } from './dialects';
 import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './types';
 
 /**
  * JSON Schema draft version supported by `@cfworker/json-schema`.
  */
 export type CfWorkerSchemaDraft = '4' | '7' | '2019-09' | '2020-12';
 
-/**
- * Canonical 2020-12 `$schema` URIs (http + https variants, trailing-`#` stripped). When a schema
- * declares anything else and no `{draft}` is forced, the provider throws a plain `Error`.
- */
-const DRAFT_2020_12_URIS: ReadonlySet<string> = new Set([
-    'https://json-schema.org/draft/2020-12/schema',
-    'http://json-schema.org/draft/2020-12/schema'
-]);
-
 /**
  * `@cfworker/json-schema`-backed JSON Schema validator. See
  * `@modelcontextprotocol/{client,server}/validators/cf-worker` for the customisation entry point.
  *
- * Default validates as **JSON Schema 2020-12** (SEP-1613). Schemas declaring a different
- * `$schema` are rejected with a plain `Error`. Passing an explicit `draft` to the constructor
+ * Default dispatches on the schema's declared dialect: no `$schema` or 2020-12 → `'2020-12'`
+ * (SEP-1613); draft-07 or draft-06 → `'7'`. Schemas declaring any other `$schema` are rejected
+ * with a plain `Error`. Passing an explicit `draft` to the constructor
  * overrides this — that draft is used for every schema regardless of `$schema`.
  *
  * @example Use with default configuration (2020-12, shortcircuit on)
@@ -58,14 +51,24 @@ export class CfWorkerJsonSchemaValidator implements jsonSchemaValidator {
      * @param options - Configuration options
      * @param options.shortcircuit - If `true`, stop validation after first error (default: `true`)
      * @param options.draft - JSON Schema draft version to force for every schema. When set, the
-     * `$schema` check is skipped. When omitted, the provider validates as 2020-12 and rejects
-     * schemas declaring a different `$schema`.
+     * `$schema` dispatch is skipped. When omitted, the provider dispatches on each schema's
+     * declared `$schema` (2020-12, draft-07, draft-06; absent means 2020-12) and rejects others.
      */
     constructor(options?: { shortcircuit?: boolean; draft?: CfWorkerSchemaDraft }) {
         this.shortcircuit = options?.shortcircuit ?? true;
         this.draft = options?.draft;
     }
 
+    /**
+     * Pick the engine draft for a schema's declared dialect (a caller-forced `{draft}` bypasses
+     * this — do not second-guess by `$schema`). No `$schema` or 2020-12 → `'2020-12'`; draft-07
+     * or draft-06 → `'7'`; anything else → `Error`.
+     */
+    private _draftFor(schema: JsonSchemaType): CfWorkerSchemaDraft {
+        const dialect = declaredDialect(schema, 'pass an explicit { draft } to CfWorkerJsonSchemaValidator to validate other dialects.');
+        return dialect === '2020-12' ? '2020-12' : '7';
+    }
+
     /**
      * Create a validator for the given JSON Schema
      *
@@ -75,22 +78,7 @@ export class CfWorkerJsonSchemaValidator implements jsonSchemaValidator {
      * @returns A validator function that validates input data
      */
     getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
-        // Caller forced a draft — use it for everything; do not second-guess by `$schema`.
-        if (
-            this.draft === undefined &&
-            '$schema' in schema &&
-            typeof schema.$schema === 'string' &&
-            !DRAFT_2020_12_URIS.has(schema.$schema.replace(/#$/, ''))
-        ) {
-            const declared = schema.$schema.slice(0, 200);
-            throw new Error(
-                `JSON Schema declares an unsupported dialect ("$schema": "${declared}"). ` +
-                    `The default validator supports JSON Schema 2020-12 only; pass an explicit ` +
-                    `{ draft } to CfWorkerJsonSchemaValidator to validate other dialects.`
-            );
-        }
-
-        const draft = this.draft ?? '2020-12';
+        const draft = this.draft ?? this._draftFor(schema);
         // Cast to the cfworker Schema type - our JsonSchemaType is structurally compatible
         const validator = new Validator(schema as ConstructorParameters<typeof Validator>[0], draft, this.shortcircuit);
 

packages/core-internal/src/validators/dialects.ts

@@ -0,0 +1,45 @@
+/**
+ * Declared-dialect classification shared by the default validator providers.
+ */
+
+import type { JsonSchemaType } from './types';
+
+/**
+ * Canonical `$schema` URIs per supported dialect (http + https variants, trailing-`#` stripped).
+ */
+const DRAFT_2020_12_URIS: ReadonlySet<string> = new Set([
+    'https://json-schema.org/draft/2020-12/schema',
+    'http://json-schema.org/draft/2020-12/schema'
+]);
+const DRAFT_07_URIS: ReadonlySet<string> = new Set(['https://json-schema.org/draft-07/schema', 'http://json-schema.org/draft-07/schema']);
+const DRAFT_06_URIS: ReadonlySet<string> = new Set(['https://json-schema.org/draft-06/schema', 'http://json-schema.org/draft-06/schema']);
+
+/**
+ * Dialects the default providers dispatch on. draft-06 maps to `'draft-7'`: draft-07 only adds
+ * keywords over draft-06 (`if`/`then`/`else`), and enforcing them on a draft-06 schema is the
+ * accepted downlevel.
+ */
+export type DeclaredDialect = '2020-12' | 'draft-7';
+
+/**
+ * Classify a schema's declared `$schema` dialect. No `$schema` (or a non-string one) means
+ * 2020-12. Any other dialect throws a plain `Error` with a clear message rather than letting the
+ * engine crash on an opaque internal error or silently mis-validate; `remedy` names the calling
+ * provider's escape hatch in that message.
+ */
+export function declaredDialect(schema: JsonSchemaType, remedy: string): DeclaredDialect {
+    if (!('$schema' in schema) || typeof schema.$schema !== 'string') {
+        return '2020-12';
+    }
+    const declared = schema.$schema.replace(/#$/, '');
+    if (DRAFT_2020_12_URIS.has(declared)) {
+        return '2020-12';
+    }
+    if (DRAFT_07_URIS.has(declared) || DRAFT_06_URIS.has(declared)) {
+        return 'draft-7';
+    }
+    throw new Error(
+        `JSON Schema declares an unsupported dialect ("$schema": "${schema.$schema.slice(0, 200)}"). ` +
+            `The default validator supports JSON Schema 2020-12, draft-07, and draft-06; ${remedy}`
+    );
+}

packages/core-internal/src/wire/rev2025-11-25/legacyWrap.ts

@@ -69,10 +69,12 @@ const REF_REWRITE_NAME_MAP_KEYS: ReadonlySet<string> = new Set([
  */
 export function wrapOutputSchemaForLegacy(natural: Readonly<Record<string, unknown>>): Record<string, unknown> {
     // A root `$schema` is hoisted to the wrapper root: it's a document-level
-    // dialect declaration and the SEP-1613 dialect checks (both built-in
-    // providers) only inspect the root, so leaving it under `properties.result`
-    // would make a non-2020-12 schema pass the dialect check on the 2025
-    // projection while the same tool is rejected on the 2026 era.
+    // dialect declaration and the built-in providers' dialect dispatch only
+    // inspects the root, so leaving it under `properties.result` would make
+    // the wrapper validate under the default 2020-12 engine (e.g. draft-07
+    // tuple-form `items` silently ignored) while the same tool dispatches to
+    // the declared dialect on the 2026 era — and hide an unsupported dialect
+    // from the graceful rejection.
     const $schema = typeof natural['$schema'] === 'string' ? natural['$schema'] : undefined;
     // `$id` at the natural root: every same-document `#/…` ref inside resolves
     // against that base URI, not against the wrapper root — skip the rewrite.