fix(client,core,docs): #2337 review-3 — recovery-path validator re-resolve, isCallToolResult widening, isError skip, opt-back snippet

Author: felixweinberger

.changeset/sep-2106-dialect-posture.md

@@ -4,4 +4,4 @@
 '@modelcontextprotocol/server': patch
 ---
 
-SEP-1613 / SEP-2106 (JSON Schema 2020-12 posture): the Node default JSON Schema validator is now `Ajv2020` (true draft 2020-12) instead of the draft-07 `Ajv` class — `$defs`/`prefixItems`/`unevaluatedProperties`/`dependentRequired` are now enforced where they were previously silently ignored; pass `new AjvJsonSchemaValidator(new Ajv({ strict: false }))` to opt back. `outputSchema` may now have a non-object root and `CallToolResult.structuredContent` is widened to `unknown` (a deliberate source-level break for typed consumers — see the migration guide for the narrowing pattern). McpServer drops a non-object `outputSchema` from the legacy (≤ 2025-11-25) `tools/list` projection with a warn-once, and auto-appends a `TextContent` JSON serialisation when a handler returns non-object `structuredContent` without its own text block. The `structuredContent` presence check is `!== undefined` (not falsy) on both sides. Thanks @mattzcarey (#2249).
+SEP-1613 / SEP-2106 (JSON Schema 2020-12 posture): the Node default JSON Schema validator is now `Ajv2020` (true draft 2020-12) instead of the draft-07 `Ajv` class — `$defs`/`prefixItems`/`unevaluatedProperties`/`dependentRequired` are now enforced where they were previously silently ignored; to opt back, construct the draft-07 instance with the v1 defaults — `const ajv = new Ajv({ strict: false, validateFormats: true, validateSchema: false, allErrors: true }); addFormats(ajv);` — and pass `new AjvJsonSchemaValidator(ajv)`. `outputSchema` may now have a non-object root and `CallToolResult.structuredContent` is widened to `unknown` (a deliberate source-level break for typed consumers — see the migration guide for the narrowing pattern). McpServer drops a non-object `outputSchema` from the legacy (≤ 2025-11-25) `tools/list` projection with a warn-once, and auto-appends a `TextContent` JSON serialisation when a handler returns non-object `structuredContent` without its own text block. The `structuredContent` presence check is `!== undefined` (not falsy) on both sides. Thanks @mattzcarey (#2249).

docs/migration-SKILL.md

@@ -665,12 +665,12 @@ JSON Schema 2020-12 posture (SEP-1613 / SEP-2106): the default validator support
 `SchemaCompileError{kind:'unsupported-dialect'}`; to validate other dialects, pass a pre-configured Ajv instance: `new AjvJsonSchemaValidator(new Ajv({...}))`. `CallToolResult.structuredContent` is typed `unknown` (was `{ [k: string]: unknown }`). The presence check is
 `!== undefined`, not falsy. Non-same-document `$ref`/`$dynamicRef` is rejected at compile time with `SchemaCompileError`.
 
-| v1 pattern                                                         | Mechanical fix                                                                                                                   |
-| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
-| `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 }))` (import `Ajv` from `…/validators/ajv`)                                  |
-| `outputSchema` or `inputSchema` with absolute-URI `$ref`           | inline under `$defs` and reference with `#/$defs/Name`                                                                           |
+| v1 pattern                                                         | Mechanical fix                                                                                                                                                                                                 |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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                            | `const ajv = new Ajv({ strict: false, validateFormats: true, validateSchema: false, allErrors: true }); addFormats(ajv); new AjvJsonSchemaValidator(ajv)` (import `Ajv`, `addFormats` from `…/validators/ajv`) |
+| `outputSchema` or `inputSchema` with absolute-URI `$ref`           | inline under `$defs` and reference with `#/$defs/Name`                                                                                                                                                         |
 
 ## 15. Migration Steps (apply in this order)
 

docs/migration.md

@@ -1460,10 +1460,12 @@ The default validator supports **JSON Schema 2020-12 only** (the spec's only MUS
 To validate other dialects, pass a pre-configured Ajv instance:
 
 ```typescript
-import { Ajv, AjvJsonSchemaValidator } from '@modelcontextprotocol/server/validators/ajv';
+import { Ajv, addFormats, AjvJsonSchemaValidator } from '@modelcontextprotocol/server/validators/ajv';
 
 // Opt back to the v1 (draft-07) default — accepted structurally; the $schema check is skipped.
-const server = new McpServer({ name: 'my-server', version: '1.0.0' }, { jsonSchemaValidator: new AjvJsonSchemaValidator(new Ajv({ strict: false })) });
+const ajv = new Ajv({ strict: false, validateFormats: true, validateSchema: false, allErrors: true });
+addFormats(ajv);
+const server = new McpServer({ name: 'my-server', version: '1.0.0' }, { jsonSchemaValidator: new AjvJsonSchemaValidator(ajv) });
 ```
 
 #### Non-same-document `$ref` is rejected — use `#/$defs/…` or `#anchor`

packages/client/src/client/client.ts

@@ -2182,20 +2182,21 @@ export class Client extends Protocol<ClientContext> {
         // must agree — and is compiled in isolation (never written to the cache). The cache read
         // is guarded: a custom store whose `get()` rejects routes to `onerror` and degrades to
         // skipping validation (same outcome as a cold cache).
-        const compiled =
+        let compiled =
             options?.toolDefinition === undefined
                 ? await this._cache
                       .outputValidator(params.name, tool => this._compileOutputValidator(tool))
                       .catch(error => void this._reportStoreError(error))
                 : this._compileOutputValidator(options.toolDefinition);
-        if (compiled !== undefined && !compiled.ok) {
+        const assertCompiled = (): void => {
+            if (compiled === undefined || compiled.ok) return;
             const compileError = compiled.compileError;
             const message = (compileError instanceof Error ? compileError.message : String(compileError)).slice(0, 200);
             throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Tool '${params.name}' has an invalid outputSchema: ${message}`, {
                 reason: compileError instanceof SchemaCompileError ? compileError.reason.kind : 'invalid-schema'
             });
-        }
-        const validator = compiled?.validator;
+        };
+        assertCompiled();
 
         // The method-keyed request() path validates the era registry's plain
         // CallToolResult schema — with the result map aligned to the typed
@@ -2235,9 +2236,19 @@ export class Client extends Protocol<ClientContext> {
             // `HEADER_MISMATCH` — the refetch failure is observable only
             // through `onerror`.
             await this.listTools(undefined, refreshOptions).catch(error_ => this._reportStoreError(error_));
+            // Re-resolve the output validator against the freshly-fetched entry — the pre-flight
+            // `compiled` was resolved from the now-evicted cache and may be stale (different
+            // outputSchema) or absent (cold cache on the first attempt). The recovery path is only
+            // entered when `options.toolDefinition` is undefined, so the cache is the sole source.
+            // Re-run the same fail-fast compile-error check before issuing the retry.
+            compiled = await this._cache
+                .outputValidator(params.name, tool => this._compileOutputValidator(tool))
+                .catch(error_ => void this._reportStoreError(error_));
+            assertCompiled();
             result = await this.request({ method: 'tools/call', params }, await buildSendOptions());
         }
 
+        const validator = compiled !== undefined && compiled.ok ? compiled.validator : undefined;
         if (validator) {
             // If tool has outputSchema, it MUST return structuredContent (unless it's an error).
             // SEP-2106: presence is `=== undefined`, not falsy — `null`/`0`/`false`/`""` are legal
@@ -2251,7 +2262,7 @@ export class Client extends Protocol<ClientContext> {
             }
 
             // Only validate structured content if present (not when there's an error)
-            if (result.structuredContent !== undefined) {
+            if (result.structuredContent !== undefined && !result.isError) {
                 try {
                     // Validate the structured content against the schema
                     const validationResult = validator(result.structuredContent);

packages/core/src/types/guards.ts

@@ -1,3 +1,5 @@
+import * as z from 'zod/v4';
+
 import {
     CallToolResultSchema,
     InitializedNotificationSchema,
@@ -71,6 +73,13 @@ export const isJSONRPCErrorResponse = (value: unknown): value is JSONRPCErrorRes
  */
 export const isJSONRPCResponse = (value: unknown): value is JSONRPCResponse => JSONRPCResponseSchema.safeParse(value).success;
 
+/**
+ * Narrows to the public {@linkcode CallToolResult} type (`structuredContent: unknown` per
+ * SEP-2106); the underlying era-neutral runtime schema keeps the 2025 record shape for
+ * wire-parse byte-identity (Q10-L2), so we widen locally rather than touch `schemas.ts`.
+ */
+const PublicCallToolResultSchema = CallToolResultSchema.extend({ structuredContent: z.unknown().optional() });
+
 /**
  * Checks if a value is a valid {@linkcode CallToolResult}.
  *
@@ -79,13 +88,17 @@ export const isJSONRPCResponse = (value: unknown): value is JSONRPCResponse => J
  * (e.g. `resultType`) still passes through the loose index signature. Use a
  * transport-level parse to validate raw wire traffic.
  *
+ * Narrows to the public {@linkcode CallToolResult} type (`structuredContent: unknown` per
+ * SEP-2106); the underlying era-neutral runtime schema keeps the 2025 record shape for
+ * wire-parse byte-identity.
+ *
  * @param value - The value to check.
  *
  * @returns True if the value is a valid {@linkcode CallToolResult}, false otherwise.
  */
 export const isCallToolResult = (value: unknown): value is CallToolResult => {
     if (typeof value !== 'object' || value === null || !('content' in value)) return false;
-    return CallToolResultSchema.safeParse(value).success;
+    return PublicCallToolResultSchema.safeParse(value).success;
 };
 
 /**

packages/core/src/types/specTypeSchema.ts

@@ -1,4 +1,4 @@
-import type * as z from 'zod/v4';
+import * as z from 'zod/v4';
 
 import {
     OAuthClientInformationFullSchema,
@@ -236,6 +236,18 @@ type SpecTypeInputs = {
 type SchemaRecord = { readonly [K in SpecTypeName]: StandardSchemaV1Sync<SpecTypeInputs[K], SpecTypes[K]> };
 type GuardRecord = { readonly [K in SpecTypeName]: (value: unknown) => value is SpecTypeInputs[K] };
 
+/**
+ * SEP-2106: the public `CallToolResult` / `CompatibilityCallToolResult` types widen
+ * `structuredContent` to `unknown`; the era-neutral runtime schema in `schemas.ts` keeps the 2025
+ * record shape for wire-parse byte-identity (Q10-L2). Override the registered runtime validators
+ * here so `specTypeSchemas` / `isSpecType` accept the public shape without touching `schemas.ts`.
+ */
+const PublicCallToolResultSchema = schemas.CallToolResultSchema.extend({ structuredContent: z.unknown().optional() });
+const SCHEMA_OVERRIDES: Partial<Record<ProtocolSchemaKey, z.ZodType>> = {
+    CallToolResultSchema: PublicCallToolResultSchema,
+    CompatibilityCallToolResultSchema: PublicCallToolResultSchema.or(schemas.ResultSchema.extend({ toolResult: z.unknown() }))
+};
+
 const _specTypeSchemas: Record<string, StandardSchemaV1> = {};
 const _isSpecType: Record<string, (value: unknown) => boolean> = {};
 function register(key: string, schema: z.ZodType): void {
@@ -245,7 +257,7 @@ function register(key: string, schema: z.ZodType): void {
 }
 for (const key of SPEC_SCHEMA_KEYS) {
     // eslint-disable-next-line import/namespace -- key is constrained to keyof typeof schemas via the satisfies clause above
-    register(key, schemas[key]);
+    register(key, SCHEMA_OVERRIDES[key] ?? schemas[key]);
 }
 for (const [key, schema] of Object.entries(authSchemas)) {
     register(key, schema);

packages/core/test/types/guards.test.ts

@@ -107,6 +107,13 @@ describe('isCallToolResult', () => {
         ).toBe(true);
     });
 
+    it('SEP-2106: accepts widened structuredContent (arrays / primitives)', () => {
+        expect(isCallToolResult({ content: [], structuredContent: [1, 2, 3] })).toBe(true);
+        expect(isCallToolResult({ content: [], structuredContent: 0 })).toBe(true);
+        expect(isCallToolResult({ content: [], structuredContent: 'x' })).toBe(true);
+        expect(isCallToolResult({ content: [], structuredContent: null })).toBe(true);
+    });
+
     it('returns false for non-objects', () => {
         expect(isCallToolResult(null)).toBe(false);
         expect(isCallToolResult(42)).toBe(false);

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

@@ -52,6 +52,12 @@ describe('isSpecType', () => {
         expect(isSpecType.CallToolResult('string')).toBe(false);
     });
 
+    it('CallToolResult — SEP-2106 widened structuredContent (override applied)', () => {
+        expect(isSpecType.CallToolResult({ content: [], structuredContent: [1, 2, 3] })).toBe(true);
+        expect(isSpecType.CallToolResult({ content: [], structuredContent: 0 })).toBe(true);
+        expect(isSpecType.CompatibilityCallToolResult({ content: [], structuredContent: 'x' })).toBe(true);
+    });
+
     it('ContentBlock — accepts text block, rejects wrong shape', () => {
         expect(isSpecType.ContentBlock({ type: 'text', text: 'hi' })).toBe(true);
         expect(isSpecType.ContentBlock({ type: 'text' })).toBe(false);