feat(core,server): default to Ajv2020 dialect + close SEP-2106 test gaps

- ajvProvider: use Ajv2020 so the default Node validator honors the 2020-12
  dialect (prefixItems etc.); previously new Ajv() ran draft-07 and silently
  ignored 2020-12 keywords (R-2106-1/2).
- add MCP_DEFAULT_SCHEMA_DIALECT='2020-12' as the single source of truth;
  cfWorker provider defaults through it.
- refactor the server structuredContent text-fallback from in-place mutation to
  a pure withStructuredContentTextFallback() so the tools/call path is
  side-effect-free.
- tests: Ajv2020 prefixItems regression (both validators); standardSchema
  io:'output' branch; spec.types<->schemas field-level mirror; registerTool
  compile-time Output typing; falsy structuredContent round-trip (false/""/null);
  schema-safety guards surfacing cleanly via fromJsonSchema.
- changeset: note the Ajv2020 default-dialect fix.

Author: mattzcarey

.changeset/sep-2106-json-schema-2020-12.md

@@ -13,3 +13,4 @@ Implement SEP-2106: tool `inputSchema`/`outputSchema` conform to JSON Schema 202
 - `McpServer.registerTool` type-checks a handler's returned `structuredContent` against the tool's `outputSchema` inferred output.
 - Servers returning array or primitive `structuredContent` automatically also emit a serialized `TextContent` block, so pre-SEP clients can fall back to the text content.
 - Built-in validators refuse to dereference non-same-document `$ref`/`$dynamicRef` (SSRF guard) and reject schemas exceeding depth / subschema-count bounds (composition-DoS guard).
+- The default Node validator now uses `Ajv2020`, so the 2020-12 dialect is honored by default (previously `new Ajv()` ran draft-07 semantics and silently ignored keywords such as `prefixItems`). Both built-in validators now default to the `2020-12` dialect (`MCP_DEFAULT_SCHEMA_DIALECT`).

packages/core/src/index.ts

@@ -20,3 +20,4 @@ export type { AjvJsonSchemaValidator } from './validators/ajvProvider.js';
 export type { CfWorkerJsonSchemaValidator, CfWorkerSchemaDraft } from './validators/cfWorkerProvider.js';
 export * from './validators/fromJsonSchema.js';
 export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './validators/types.js';
+export { MCP_DEFAULT_SCHEMA_DIALECT } from './validators/types.js';

packages/core/src/validators/ajvProvider.ts

@@ -2,7 +2,8 @@
  * AJV-based JSON Schema validator provider
  */
 
-import { Ajv } from 'ajv';
+import type { Ajv } from 'ajv';
+import { Ajv2020 } from 'ajv/dist/2020.js';
 import _addFormats from 'ajv-formats';
 
 import { assertSchemaSafeToCompile } from './schemaBounds.js';
@@ -23,7 +24,13 @@ interface AjvValidateFunction {
 }
 
 function createDefaultAjvInstance(): Ajv {
-    const ajv = new Ajv({
+    // SEP-2106: MCP tool schemas default to the JSON Schema 2020-12 dialect when no `$schema` is
+    // declared. Plain `Ajv` is draft-07 and *silently ignores* 2020-12 keywords such as
+    // `prefixItems` (e.g. it would accept `[1, "a"]` for a `[string, number]` tuple), which would
+    // make validation disagree with the declared schema. `Ajv2020` runs the 2020-12 meta-schema and
+    // vocabulary, matching the cfworker default (`draft: '2020-12'`) used in the browser/workerd
+    // builds.
+    const ajv = new Ajv2020({
         strict: false,
         validateFormats: true,
         validateSchema: false,

packages/core/src/validators/cfWorkerProvider.ts

@@ -12,6 +12,7 @@ import { Validator } from '@cfworker/json-schema';
 
 import { assertSchemaSafeToCompile } from './schemaBounds.js';
 import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './types.js';
+import { MCP_DEFAULT_SCHEMA_DIALECT } from './types.js';
 
 /**
  * JSON Schema draft version supported by `@cfworker/json-schema`.
@@ -48,7 +49,8 @@ export class CfWorkerJsonSchemaValidator implements jsonSchemaValidator {
      */
     constructor(options?: { shortcircuit?: boolean; draft?: CfWorkerSchemaDraft }) {
         this.shortcircuit = options?.shortcircuit ?? true;
-        this.draft = options?.draft ?? '2020-12';
+        // SEP-2106: default to the MCP-wide dialect (2020-12) when the caller does not pin one.
+        this.draft = options?.draft ?? MCP_DEFAULT_SCHEMA_DIALECT;
     }
 
     /**

packages/core/src/validators/types.ts

@@ -13,6 +13,17 @@ import type { JSONSchema } from 'json-schema-typed';
  */
 export type JsonSchemaType = JSONSchema.Interface;
 
+/**
+ * The JSON Schema dialect MCP tool `inputSchema`/`outputSchema` default to when no explicit
+ * `$schema` is declared (SEP-2106).
+ *
+ * Both built-in validators are configured to this dialect — `AjvJsonSchemaValidator` via `Ajv2020`
+ * and `CfWorkerJsonSchemaValidator` via its `draft: '2020-12'` default — so the answer to "what
+ * dialect does MCP assume?" lives in exactly one place rather than being an implicit per-provider
+ * default. Custom `jsonSchemaValidator` implementations SHOULD also default to this dialect.
+ */
+export const MCP_DEFAULT_SCHEMA_DIALECT = '2020-12' as const;
+
 /**
  * Result of a JSON Schema validation operation
  */

packages/core/test/types/specTypeSchema.test.ts

@@ -12,7 +12,8 @@ import type {
     JSONRPCRequest,
     JSONValue,
     ResourceTemplateType,
-    Tool
+    Tool,
+    ToolResultContent
 } from '../../src/types/types.js';
 
 describe('specTypeSchemas', () => {
@@ -148,6 +149,38 @@ describe('SpecTypeName / SpecTypes (type-level)', () => {
     });
 });
 
+// SEP-2106 / R-2106-6/7/8: the hand-written interfaces in spec.types.ts and the runtime Zod schemas
+// in schemas.ts must describe the same shape. The whole-type assertions above already enforce this
+// for `Tool`/`CallToolResult`, but these field-level checks make the mirror an explicit, enforced
+// invariant: a future change that widens one file's `inputSchema`/`outputSchema`/`structuredContent`
+// without mirroring the other fails *here*, pointing straight at the offending field.
+describe('SEP-2106 spec.types ↔ schemas mirror (type-level)', () => {
+    it('Tool.inputSchema keeps a required root type:"object" but is otherwise open', () => {
+        expectTypeOf<Tool['inputSchema']['type']>().toEqualTypeOf<'object'>();
+        // Open-ended: arbitrary 2020-12 keywords are accepted alongside `type`.
+        expectTypeOf<Tool['inputSchema']['oneOf']>().toEqualTypeOf<unknown>();
+        expectTypeOf<Tool['inputSchema']['$schema']>().toEqualTypeOf<string | undefined>();
+    });
+
+    it('Tool.outputSchema drops the root type:"object" requirement', () => {
+        // No required `type` member: indexing `type` resolves through the `[key: string]: unknown`
+        // index signature, not a `'object'` literal.
+        expectTypeOf<NonNullable<Tool['outputSchema']>['type']>().toEqualTypeOf<unknown>();
+        expectTypeOf<NonNullable<Tool['outputSchema']>['$schema']>().toEqualTypeOf<string | undefined>();
+    });
+
+    it('CallToolResult.structuredContent and ToolResultContent.structuredContent are any JSON value (unknown)', () => {
+        expectTypeOf<CallToolResult['structuredContent']>().toEqualTypeOf<unknown>();
+        expectTypeOf<ToolResultContent['structuredContent']>().toEqualTypeOf<unknown>();
+    });
+
+    it('the inferred (schemas.ts) types equal the hand-written (spec.types.ts) types end to end', () => {
+        expectTypeOf<SpecTypes['Tool']>().toEqualTypeOf<Tool>();
+        expectTypeOf<SpecTypes['CallToolResult']>().toEqualTypeOf<CallToolResult>();
+        expectTypeOf<SpecTypes['ToolResultContent']>().toEqualTypeOf<ToolResultContent>();
+    });
+});
+
 describe('SPEC_SCHEMA_KEYS allowlist', () => {
     // Mirrors the exclusion comment in specTypeSchema.ts. If this list grows, confirm the new
     // entry has no public type in types.ts before adding it here; otherwise add it to the allowlist.

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

@@ -39,4 +39,35 @@ describe('standardSchemaToJsonSchema', () => {
         expect(keys.filter(k => k === 'type')).toHaveLength(1);
         expect(result.type).toBe('object');
     });
+
+    // SEP-2106 / R-2106-7: a tool's `outputSchema` may be any valid JSON Schema 2020-12 — arrays,
+    // primitives, or compositions — so the `io: 'output'` branch must return the converted schema
+    // unchanged, never forcing (or rejecting based on) a root `type: 'object'`.
+    describe("io: 'output' (SEP-2106 outputSchema)", () => {
+        test('returns a non-object root unchanged (array)', () => {
+            const result = standardSchemaToJsonSchema(z.array(z.number()), 'output');
+
+            expect(result.type).toBe('array');
+            expect(result.items).toBeDefined();
+        });
+
+        test('returns a primitive root unchanged (number)', () => {
+            const result = standardSchemaToJsonSchema(z.number(), 'output');
+
+            expect(result.type).toBe('number');
+        });
+
+        test('does not force type:object onto an object output schema', () => {
+            const result = standardSchemaToJsonSchema(z.object({ x: z.string() }), 'output');
+
+            const keys = Object.keys(result);
+            expect(keys.filter(k => k === 'type')).toHaveLength(1);
+            expect(result.type).toBe('object');
+        });
+
+        test('does not throw for a non-object type (unlike input)', () => {
+            expect(() => standardSchemaToJsonSchema(z.string(), 'output')).not.toThrow();
+            expect(() => standardSchemaToJsonSchema(z.array(z.string()), 'output')).not.toThrow();
+        });
+    });
 });

packages/core/test/validators/validators.test.ts

@@ -391,6 +391,22 @@ describe('JSON Schema Validators', () => {
                 expect(validator('specific-value').valid).toBe(true);
                 expect(validator('other-value').valid).toBe(false);
             });
+
+            // SEP-2106 / R-2106-2: the default validators MUST run the 2020-12 dialect, not draft-07.
+            // `prefixItems` is a 2020-12 keyword; draft-07 silently ignores it (accepting any tuple),
+            // so this is the canonical guard that the default dialect is wired correctly. A plain
+            // draft-07 `new Ajv()` would let `[1, 'a']` validate against a `[string, number]` tuple.
+            it('honors prefixItems (2020-12 tuple) on the default dialect', () => {
+                const schema: JsonSchemaType = {
+                    type: 'array',
+                    prefixItems: [{ type: 'string' }, { type: 'number' }]
+                };
+                const validator = provider.getValidator(schema);
+
+                expect(validator(['a', 1]).valid).toBe(true);
+                // draft-07 would (incorrectly) accept this because it ignores prefixItems.
+                expect(validator([1, 'a']).valid).toBe(false);
+            });
         });
 
         describe('Complex real-world schemas', () => {

packages/server/src/server/mcp.ts

@@ -177,10 +177,7 @@ export class McpServer {
                 // Per SEP-2106, a server returning array or primitive structuredContent MUST also emit a
                 // TextContent block with the serialized JSON, so pre-SEP clients that only understand
                 // object-typed structuredContent can fall back to the text content.
-                if (isCallToolResult(result)) {
-                    ensureStructuredContentTextFallback(result);
-                }
-                return result;
+                return isCallToolResult(result) ? withStructuredContentTextFallback(result) : result;
             } catch (error) {
                 if (error instanceof ProtocolError && error.code === ProtocolErrorCode.UrlElicitationRequired) {
                     throw error; // Return the error to the caller without wrapping in CallToolResult
@@ -1169,27 +1166,35 @@ export type RegisteredTool = {
 };
 
 /**
- * Ensures backward compatibility for non-object `structuredContent` (SEP-2106).
+ * Returns a {@link CallToolResult} with a backward-compatibility text block added when required by
+ * SEP-2106, without mutating the input.
  *
  * Servers that return array or primitive `structuredContent` MUST also include a {@link TextContent}
  * block with the serialized JSON, so pre-SEP clients that only understand object-typed
- * `structuredContent` can fall back to the text content. Object `structuredContent` (the only shape
- * pre-SEP clients accept) needs no fallback, and a result that already carries a text block is left
- * untouched — the handler is assumed to have provided its own representation.
+ * `structuredContent` can fall back to the text content. The original result is returned unchanged
+ * (same reference) when no fallback is needed:
+ *
+ * - no `structuredContent` present, or
+ * - `structuredContent` is a plain object (the only shape pre-SEP clients accept), or
+ * - the result already carries a text block — the handler is assumed to have provided its own
+ *   representation.
+ *
+ * Otherwise a new result is returned with a serialized text block appended; the input is left
+ * untouched so the request handler stays a side-effect-free pipeline.
  */
-function ensureStructuredContentTextFallback(result: CallToolResult): void {
+function withStructuredContentTextFallback(result: CallToolResult): CallToolResult {
     const structuredContent = result.structuredContent;
     if (structuredContent === undefined) {
-        return;
+        return result;
     }
     const isPlainObject = structuredContent !== null && typeof structuredContent === 'object' && !Array.isArray(structuredContent);
     if (isPlainObject) {
-        return;
+        return result;
     }
     if (result.content.some(block => block.type === 'text')) {
-        return;
+        return result;
     }
-    result.content = [...result.content, { type: 'text', text: JSON.stringify(structuredContent) }];
+    return { ...result, content: [...result.content, { type: 'text', text: JSON.stringify(structuredContent) }] };
 }
 
 /**

packages/server/test/server/mcp.compat.test.ts

@@ -127,3 +127,61 @@ describe('InferRawShape', () => {
         expectTypeOf<S>().toEqualTypeOf<{ a: string; b?: string | undefined }>();
     });
 });
+
+// SEP-2106 / R-2106-3: when a tool declares an `outputSchema`, `registerTool` infers it as the
+// `Output` type param so the handler's returned `structuredContent` is checked against the schema's
+// inferred output at compile time. These cases pin that contract: correct shapes compile, wrong
+// shapes fail to type-check (guarded by @ts-expect-error so a regression that loosens the typing
+// turns these into compile errors). Type-only — registration side effects are covered above.
+describe('registerTool compile-time outputSchema typing (SEP-2106)', () => {
+    it('accepts structuredContent matching a Standard Schema outputSchema', () => {
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        server.registerTool('bmi', { outputSchema: z.object({ bmi: z.number() }) }, async () => ({
+            content: [{ type: 'text' as const, text: '22.9' }],
+            structuredContent: { bmi: 22.9 }
+        }));
+    });
+
+    it('rejects structuredContent that does not match the outputSchema', () => {
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        // The return-type mismatch surfaces at the registerTool call (the handler's return type is
+        // contextually checked against ToolResultFor<Output>), so the directive sits on this line.
+        // @ts-expect-error - bmi must be a number, not a string
+        server.registerTool('bmi', { outputSchema: z.object({ bmi: z.number() }) }, async () => ({
+            content: [{ type: 'text' as const, text: 'x' }],
+            structuredContent: { bmi: 'not-a-number' }
+        }));
+    });
+
+    it('allows omitting structuredContent at compile time (the MUST-return rule is runtime-enforced)', () => {
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        // CallToolResultWithStructuredContent<T> types structuredContent as optional (`?: T`), so a
+        // handler that omits it still compiles. The "outputSchema implies structuredContent" rule is
+        // enforced at runtime by validateToolOutput (covered in client/server runtime tests), not by
+        // the type system — this documents and pins that boundary.
+        server.registerTool('bmi', { outputSchema: z.object({ bmi: z.number() }) }, async () => ({
+            content: [{ type: 'text' as const, text: 'x' }]
+        }));
+    });
+
+    it('supports a non-object (array) outputSchema per SEP-2106', () => {
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        server.registerTool('forecast', { outputSchema: z.array(z.object({ temp: z.number() })) }, async () => ({
+            content: [{ type: 'text' as const, text: '[]' }],
+            structuredContent: [{ temp: 1 }]
+        }));
+    });
+
+    it('allows any JSON value in structuredContent when no outputSchema is declared', () => {
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        server.registerTool('free', {}, async () => ({
+            content: [{ type: 'text' as const, text: '42' }],
+            structuredContent: 42
+        }));
+    });
+});