fix(core,server): #2337 review-4 — Tool outputSchema type widen, module-level warn-once, recursive object-shape check, Ajv2020 customization docs

Author: felixweinberger

packages/client/src/validators/ajv.ts

@@ -1,14 +1,16 @@
 /**
- * Customisation entry point for the AJV validator. Re-exports `Ajv` + `addFormats` from the
- * SDK's bundled copy, so customising the validator needs no extra installs.
+ * Customisation entry point for the AJV validator. Re-exports `Ajv2020`, `Ajv`, and `addFormats`
+ * from the SDK's bundled copy, so customising the validator needs no extra installs. Use `Ajv2020`
+ * for a custom instance — `Ajv` is the draft-07 class (kept for opting back to the pre-SEP-1613
+ * default) and would silently downgrade dialect.
  *
  * @example
  * ```ts
- * import { Ajv, addFormats, AjvJsonSchemaValidator } from '@modelcontextprotocol/client/validators/ajv';
+ * import { Ajv2020, addFormats, AjvJsonSchemaValidator } from '@modelcontextprotocol/client/validators/ajv';
  *
- * const ajv = new Ajv({ strict: true, allErrors: true });
+ * const ajv = new Ajv2020({ strict: false, validateSchema: false, allErrors: true });
  * addFormats(ajv);
  * const validator = new AjvJsonSchemaValidator(ajv);
  * ```
  */
-export { addFormats, Ajv, AjvJsonSchemaValidator } from '@modelcontextprotocol/core/validators/ajv';
+export { addFormats, Ajv, Ajv2020, AjvJsonSchemaValidator } from '@modelcontextprotocol/core/validators/ajv';

packages/core/src/types/specTypeSchema.ts

@@ -238,14 +238,21 @@ type GuardRecord = { readonly [K in SpecTypeName]: (value: unknown) => value is
 
 /**
  * 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`.
+ * `structuredContent` to `unknown`, and the public `Tool` / `ListToolsResult` types widen
+ * `outputSchema` to a loose JSON Schema document; the era-neutral runtime schema in `schemas.ts`
+ * keeps the 2025 record / `type:'object'` shapes 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 PublicToolSchema = schemas.ToolSchema.extend({
+    outputSchema: z.object({ $schema: z.string().optional() }).catchall(z.unknown()).optional()
+});
 const SCHEMA_OVERRIDES: Partial<Record<ProtocolSchemaKey, z.ZodType>> = {
     CallToolResultSchema: PublicCallToolResultSchema,
-    CompatibilityCallToolResultSchema: PublicCallToolResultSchema.or(schemas.ResultSchema.extend({ toolResult: z.unknown() }))
+    CompatibilityCallToolResultSchema: PublicCallToolResultSchema.or(schemas.ResultSchema.extend({ toolResult: z.unknown() })),
+    ToolSchema: PublicToolSchema,
+    ListToolsResultSchema: schemas.ListToolsResultSchema.extend({ tools: z.array(PublicToolSchema) })
 };
 
 const _specTypeSchemas: Record<string, StandardSchemaV1> = {};

packages/core/src/types/types.ts

@@ -220,6 +220,20 @@ type StripWireOnly<T> = T extends unknown ? { [K in keyof T as K extends WireOnl
  */
 type WidenStructuredContent<T> = T extends unknown ? { [K in keyof T]: K extends 'structuredContent' ? unknown : T[K] } : never;
 
+/**
+ * SEP-2106: re-types `outputSchema` on the schema-inferred `Tool` to the loose JSON Schema 2020-12
+ * shape (any JSON Schema document, not just `type:'object'`). The era-neutral runtime schema in
+ * `schemas.ts` keeps the 2025 `type:'object'` constraint for wire-parse byte-identity (Q10-L2); only
+ * the public TypeScript type widens. `Omit<T,'outputSchema'> & {…}` cannot be used here because
+ * `Omit` over an index-signatured type erases the known keys.
+ */
+type Sep2106OutputSchema = { $schema?: string; [k: string]: unknown };
+type WidenToolOutputSchema<T> = T extends unknown
+    ? { [K in keyof T]: K extends 'outputSchema' ? Sep2106OutputSchema | undefined : T[K] }
+    : never;
+/** Re-maps a schema-inferred type's `tools` member to the public (widened) {@linkcode Tool}`[]`. */
+type WithPublicTools<T> = T extends unknown ? { [K in keyof T]: K extends 'tools' ? Tool[] : T[K] } : never;
+
 /* JSON-RPC types */
 export type ProgressToken = Infer<typeof ProgressTokenSchema>;
 export type Cursor = Infer<typeof CursorSchema>;
@@ -404,9 +418,14 @@ export type PromptListChangedNotification = Infer<typeof PromptListChangedNotifi
 /* Tools */
 export type ToolAnnotations = Infer<typeof ToolAnnotationsSchema>;
 export type ToolExecution = Infer<typeof ToolExecutionSchema>;
-export type Tool = Infer<typeof ToolSchema>;
+/**
+ * `outputSchema` is widened to the loose SEP-2106 shape (any JSON Schema 2020-12 document, not just
+ * `type:'object'`). The 2025-era wire parse retains the `type:'object'` runtime constraint; only the
+ * public TypeScript type widens. {@linkcode ListToolsResult}`.tools` carries the same widened shape.
+ */
+export type Tool = WidenToolOutputSchema<Infer<typeof ToolSchema>>;
 export type ListToolsRequest = Infer<typeof ListToolsRequestSchema>;
-export type ListToolsResult = StripWireOnly<Infer<typeof ListToolsResultSchema>>;
+export type ListToolsResult = WithPublicTools<StripWireOnly<Infer<typeof ListToolsResultSchema>>>;
 export type CallToolRequestParams = Infer<typeof CallToolRequestParamsSchema>;
 /**
  * `structuredContent` is widened to `unknown` per SEP-2106 (the 2026-07-28 protocol revision allows
@@ -925,13 +944,16 @@ export type CreateMessageRequestParamsBase = Omit<CreateMessageRequestParams, 't
 
 /**
  * {@linkcode CreateMessageRequestParams} with required tools - for tool-enabled overload.
+ * `tools` keeps the schema-derived (2025-era, `type:'object'` outputSchema) shape: this overload is
+ * the deprecated 2025-only push-sampling path, and the 2025 wire cannot carry a non-object
+ * outputSchema regardless.
  *
  * @deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577); remains
  * in the specification for at least twelve months. Migrate to calling LLM
  * provider APIs directly.
  */
 export interface CreateMessageRequestParamsWithTools extends CreateMessageRequestParams {
-    tools: Tool[];
+    tools: NonNullable<CreateMessageRequestParams['tools']>;
 }
 
 export type CompleteRequestResourceTemplate = ExpandRecursively<

packages/core/src/util/standardSchema.ts

@@ -230,7 +230,8 @@ export function standardSchemaToJsonSchema(schema: StandardJSONSchemaV1, io: 'in
 /**
  * A typeless JSON Schema root is "provably object-shaped" when either it carries object keywords
  * directly (`properties`/`patternProperties`/`additionalProperties`/`required`), or it is a
- * composition (`oneOf`/`anyOf`/`allOf`) whose every member is itself `type:'object'`. Used to
+ * composition (`oneOf`/`anyOf`/`allOf`) whose every member is itself `type:'object'` or recursively
+ * provably object-shaped (e.g. a nested `discriminatedUnion`). `$ref` is not followed. Used to
  * decide whether stamping `type:'object'` is safe (redundant-but-valid) versus self-contradictory.
  */
 function isProvablyObjectShapedRoot(schema: Record<string, unknown>): boolean {
@@ -240,7 +241,12 @@ function isProvablyObjectShapedRoot(schema: Record<string, unknown>): boolean {
     for (const key of ['oneOf', 'anyOf', 'allOf'] as const) {
         const members = schema[key];
         if (Array.isArray(members) && members.length > 0) {
-            return members.every(m => m !== null && typeof m === 'object' && (m as Record<string, unknown>).type === 'object');
+            return members.every(
+                m =>
+                    m !== null &&
+                    typeof m === 'object' &&
+                    ((m as Record<string, unknown>).type === 'object' || isProvablyObjectShapedRoot(m as Record<string, unknown>))
+            );
         }
     }
     return false;

packages/core/src/validators/ajvProvider.examples.ts

@@ -7,7 +7,7 @@
  * @module
  */
 
-import { addFormats, Ajv, AjvJsonSchemaValidator } from './ajvProvider.js';
+import { addFormats, Ajv2020, AjvJsonSchemaValidator } from './ajvProvider.js';
 
 /**
  * Example: Default AJV instance.
@@ -21,10 +21,13 @@ function AjvJsonSchemaValidator_default() {
 
 /**
  * Example: Custom AJV instance.
+ *
+ * Use the re-exported `Ajv2020` class so the custom instance keeps validating JSON Schema 2020-12
+ * (SEP-1613). Passing `new Ajv(...)` (the draft-07 class) would silently downgrade dialect.
  */
 function AjvJsonSchemaValidator_customInstance() {
     //#region AjvJsonSchemaValidator_customInstance
-    const ajv = new Ajv({ strict: true, allErrors: true });
+    const ajv = new Ajv2020({ strict: false, validateSchema: false, allErrors: true });
     const validator = new AjvJsonSchemaValidator(ajv);
     //#endregion AjvJsonSchemaValidator_customInstance
     return validator;
@@ -33,12 +36,12 @@ function AjvJsonSchemaValidator_customInstance() {
 /**
  * Example: Custom AJV instance with formats registered.
  *
- * `Ajv` and `addFormats` are re-exported from this module so customising the validator
+ * `Ajv2020` and `addFormats` are re-exported from this module so customising the validator
  * requires no extra `package.json` dependencies — both come from the SDK's bundled copy.
  */
 function AjvJsonSchemaValidator_withFormats() {
     //#region AjvJsonSchemaValidator_withFormats
-    const ajv = new Ajv({ strict: true, allErrors: true });
+    const ajv = new Ajv2020({ strict: false, validateSchema: false, allErrors: true });
     addFormats(ajv);
     const validator = new AjvJsonSchemaValidator(ajv);
     //#endregion AjvJsonSchemaValidator_withFormats

packages/core/src/validators/ajvProvider.ts

@@ -47,11 +47,14 @@ 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).
+ * for the customisation entry point (re-exports `Ajv2020`, `Ajv`, and `addFormats` from the
+ * bundled copy).
  *
  * Default validates as **JSON Schema 2020-12** (SEP-1613). Schemas declaring a different
  * `$schema` are rejected with `SchemaCompileError{kind:'unsupported-dialect'}`; pass a
- * pre-configured Ajv instance to validate other dialects.
+ * pre-configured Ajv instance to validate other dialects. When passing a custom instance, use the
+ * re-exported `Ajv2020` class — `new Ajv(...)` is the draft-07 class and would silently downgrade
+ * dialect.
  *
  * @example Use with default configuration
  * ```ts source="./ajvProvider.examples.ts#AjvJsonSchemaValidator_default"
@@ -60,13 +63,13 @@ function createDefaultAjvInstance(): AjvLike {
  *
  * @example Use with a custom AJV instance
  * ```ts source="./ajvProvider.examples.ts#AjvJsonSchemaValidator_customInstance"
- * const ajv = new Ajv({ strict: true, allErrors: true });
+ * const ajv = new Ajv2020({ strict: false, validateSchema: false, allErrors: true });
  * const validator = new AjvJsonSchemaValidator(ajv);
  * ```
  *
  * @example Register ajv-formats
  * ```ts source="./ajvProvider.examples.ts#AjvJsonSchemaValidator_withFormats"
- * const ajv = new Ajv({ strict: true, allErrors: true });
+ * const ajv = new Ajv2020({ strict: false, validateSchema: false, allErrors: true });
  * addFormats(ajv);
  * const validator = new AjvJsonSchemaValidator(ajv);
  * ```
@@ -149,5 +152,10 @@ export class AjvJsonSchemaValidator implements jsonSchemaValidator {
  * (`new AjvJsonSchemaValidator(new Ajv({ strict: false }))`).
  */
 export { Ajv } from 'ajv';
+/**
+ * 2020-12 AJV class — the dialect the default provider uses (SEP-1613). Re-exported so a custom
+ * instance can be passed without an extra `ajv` install and without silently downgrading to draft-07.
+ */
+export { Ajv2020 } from 'ajv/dist/2020.js';
 /** `ajv-formats` default export, normalised through the CJS/ESM interop wrapper. */
 export { addFormats };

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

@@ -69,6 +69,19 @@ describe('isSpecType', () => {
         expect(isSpecType.Tool({ name: 'echo' })).toBe(false);
     });
 
+    it('Tool — SEP-2106 widened outputSchema (override applied)', () => {
+        const arrayOut = { name: 'nums', inputSchema: { type: 'object' }, outputSchema: { type: 'array', items: { type: 'number' } } };
+        expect(isSpecType.Tool(arrayOut)).toBe(true);
+        expect(isSpecType.ListToolsResult({ tools: [arrayOut] })).toBe(true);
+        // type-level: the public Tool['outputSchema'] is the loose SEP-2106 shape, not pinned to type:'object'.
+        const t: Tool = {
+            name: 'nums',
+            inputSchema: { type: 'object' },
+            outputSchema: { type: 'array', items: { type: 'number' } }
+        };
+        void t;
+    });
+
     it('ResourceTemplate — accepts valid, rejects missing uriTemplate', () => {
         expect(isSpecType.ResourceTemplate({ name: 'r', uriTemplate: 'file:///{path}' })).toBe(true);
         expect(isSpecType.ResourceTemplate({ name: 'r' })).toBe(false);
@@ -162,7 +175,11 @@ describe('SpecTypeName / SpecTypes (type-level)', () => {
         type DeclaresResultType = 'resultType' extends KnownKeys<SpecTypes['CallToolResult']> ? true : false;
         expectTypeOf<DeclaresResultType>().toEqualTypeOf<false>();
         expectTypeOf<SpecTypes['ContentBlock']>().toEqualTypeOf<ContentBlock>();
-        expectTypeOf<SpecTypes['Tool']>().toEqualTypeOf<Tool>();
+        // SEP-2106: the public `Tool` widens `outputSchema` to a loose JSON Schema document (the
+        // 2025 runtime schema retains `type:'object'`). Same bidirectional pin as CallToolResult —
+        // spec→public holds directly; public→spec holds once outputSchema is re-narrowed.
+        expectTypeOf<SpecTypes['Tool']>().toMatchTypeOf<Tool>();
+        expectTypeOf<Tool & { outputSchema?: { type: 'object' } }>().toMatchTypeOf<SpecTypes['Tool']>();
         expectTypeOf<SpecTypes['Implementation']>().toEqualTypeOf<Implementation>();
         expectTypeOf<SpecTypes['JSONRPCRequest']>().toEqualTypeOf<JSONRPCRequest>();
         expectTypeOf<SpecTypes['OAuthTokens']>().toEqualTypeOf<OAuthTokens>();

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

@@ -77,6 +77,14 @@ describe('standardSchemaToJsonSchema', () => {
             expect(result.type).toBe('object');
         });
 
+        test('union of discriminatedUnions (typeless anyOf of typeless oneOf-of-objects) is stamped type:object', () => {
+            // Members are themselves typeless object-shaped compositions; the check recurses.
+            const a = z.discriminatedUnion('kind', [z.object({ kind: z.literal('a'), x: z.number() }), z.object({ kind: z.literal('b') })]);
+            const b = z.discriminatedUnion('kind', [z.object({ kind: z.literal('c'), y: z.string() }), z.object({ kind: z.literal('d') })]);
+            const result = standardSchemaToJsonSchema(z.union([a, b]), 'output');
+            expect(result.type).toBe('object');
+        });
+
         test('mixed union (object + primitive) is NOT stamped', () => {
             const schema = z.union([z.object({ a: z.number() }), z.string()]);
             const result = standardSchemaToJsonSchema(schema, 'output');

packages/server/src/server/mcp.ts

@@ -50,6 +50,13 @@ import { getCompleter, isCompletable } from './completable.js';
 import type { ServerOptions } from './server.js';
 import { Server } from './server.js';
 
+/**
+ * Tool names whose non-object `outputSchema` has already been warned about. Module-level so the
+ * warn-once dedup survives across the per-request `createMcpHandler` factory model (which builds a
+ * fresh `McpServer` per request).
+ */
+const warnedNonObjectOutput: Set<string> = new Set();
+
 /**
  * High-level MCP server that provides a simpler API for working with resources, tools, and prompts.
  * For advanced usage (like sending notifications or setting custom request handlers), use the underlying
@@ -82,8 +89,6 @@ export class McpServer {
      * per-request-factory `createMcpHandler` model.
      */
     private _toolInputSchemaJson: { [name: string]: Record<string, unknown> } = {};
-    /** Tool names whose non-object `outputSchema` has already been warned about (warn-once per tool). */
-    private _warnedNonObjectOutput: Set<string> = new Set();
 
     /** Whether the negotiated protocol revision is the modern (≥ 2026-07-28) era. */
     private _isModernEra(): boolean {
@@ -92,8 +97,11 @@ export class McpServer {
     }
 
     private _warnNonObjectOutputSchemaOnce(name: string): void {
-        if (this._warnedNonObjectOutput.has(name)) return;
-        this._warnedNonObjectOutput.add(name);
+        // Module-level dedup: under the per-request `createMcpHandler` factory model a fresh
+        // McpServer is constructed per request, so an instance-level Set would re-warn on every
+        // request. The dedup key is the tool name — process-global, mirrors `warnedZodFallback`.
+        if (warnedNonObjectOutput.has(name)) return;
+        warnedNonObjectOutput.add(name);
         console.warn(
             `[mcp-sdk] tool '${name}' has a non-object outputSchema (SEP-2106). This is dropped from the ` +
                 `legacy (≤ 2025-11-25) tools/list projection so 2025 clients can still call the tool; ` +
@@ -221,7 +229,7 @@ export class McpServer {
                             if (isNonObjectJsonSchemaRoot(json) && !this._isModernEra()) {
                                 this._warnNonObjectOutputSchemaOnce(name);
                             } else {
-                                toolDefinition.outputSchema = json as Tool['outputSchema'];
+                                toolDefinition.outputSchema = json;
                             }
                         }
 

packages/server/src/validators/ajv.ts

@@ -1,14 +1,16 @@
 /**
- * Customisation entry point for the AJV validator. Re-exports `Ajv` + `addFormats` from the
- * SDK's bundled copy, so customising the validator needs no extra installs.
+ * Customisation entry point for the AJV validator. Re-exports `Ajv2020`, `Ajv`, and `addFormats`
+ * from the SDK's bundled copy, so customising the validator needs no extra installs. Use `Ajv2020`
+ * for a custom instance — `Ajv` is the draft-07 class (kept for opting back to the pre-SEP-1613
+ * default) and would silently downgrade dialect.
  *
  * @example
  * ```ts
- * import { Ajv, addFormats, AjvJsonSchemaValidator } from '@modelcontextprotocol/server/validators/ajv';
+ * import { Ajv2020, addFormats, AjvJsonSchemaValidator } from '@modelcontextprotocol/server/validators/ajv';
  *
- * const ajv = new Ajv({ strict: true, allErrors: true });
+ * const ajv = new Ajv2020({ strict: false, validateSchema: false, allErrors: true });
  * addFormats(ajv);
  * const validator = new AjvJsonSchemaValidator(ajv);
  * ```
  */
-export { addFormats, Ajv, AjvJsonSchemaValidator } from '@modelcontextprotocol/core/validators/ajv';
+export { addFormats, Ajv, Ajv2020, AjvJsonSchemaValidator } from '@modelcontextprotocol/core/validators/ajv';