fix(core,docs): #2337 review-5 + CI — drop Ajv2020 re-export (tsdown ceiling), ToolResultContent widen, migration prose alignment

Author: felixweinberger

.changeset/client-response-cache-substrate.md

@@ -4,4 +4,4 @@
 
 `Client.listTools()` / `listPrompts()` / `listResources()` / `listResourceTemplates()` now **auto-aggregate every page** when called without a `cursor` and return the complete result with `nextCursor: undefined` (matching the C#, Java, and mcp.d SDKs). Pass an explicit `{ cursor }` string to fetch a single page; the per-page path is unchanged. Existing manual pagination loops keep working — the first iteration returns everything and the loop exits — but can be deleted. The aggregated result is written to the new pluggable `ResponseCacheStore` (default: a fresh per-instance `InMemoryResponseCacheStore`); a `ClientResponseCache` collaborator owns the eviction-generation guard and the derived `tools/list` index that `callTool`'s output validation and SEP-2243 `Mcp-Param-*` mirroring read. New exports: `ResponseCacheStore`, `CacheKey`, `CacheEntry`, `CacheScope`, `MaybePromise`, `InMemoryResponseCacheStore`; new `ClientOptions.responseCacheStore` / `ClientOptions.listMaxPages` (caps the auto-aggregate walk at 64 pages by default; throws `SdkError` with `SdkErrorCode.ListPaginationExceeded` on overrun so a partial aggregate is never cached). The store interface is async-ready (`MaybePromise<…>`); the in-memory default stays synchronous. Entries are automatically scoped by the connected server's identity and (when set) the consumer-supplied `cachePartition`, so a shared store does not collide across servers or principals; evictions are likewise scoped to the connected server's partitions.
 
-**Behavior change (every era):** output-schema validator compilation is now lazy — validators are compiled on the first `callTool()` against the cached `tools/list` entry, not eagerly inside `listTools()` — and non-throwing: an uncompilable `outputSchema` is `console.warn`-ed and validation is skipped for that tool only (previously `listTools()` threw). A pluggable `jsonSchemaValidator` provider therefore observes compilation at `callTool` time, not `listTools` time. The legacy-era `listTools()` path is unchanged at the wire level but is observably different at the validator-lifecycle level.
+**Behavior change (every era):** output-schema validator compilation is now lazy — validators are compiled on the first `callTool()` against the cached `tools/list` entry, not eagerly inside `listTools()`. `listTools()` no longer throws on an uncompilable `outputSchema` (every tool stays listed; the compile failure is captured per-tool); calling `callTool()` on the affected tool throws `ProtocolError(InvalidParams, "Tool 'X' has an invalid outputSchema: …")` with `data.reason` set to the structured kind, before the request is sent — output-schema validation is never silently skipped. A pluggable `jsonSchemaValidator` provider therefore observes compilation at `callTool` time, not `listTools` time. The legacy-era `listTools()` path is unchanged at the wire level but is observably different at the validator-lifecycle level.

docs/migration-SKILL.md

@@ -574,7 +574,7 @@ side: auto-fulfilment is on by default (`ClientOptions.inputRequired`, `maxRound
 
 `Client.listTools()` / `listPrompts()` / `listResources()` / `listResourceTemplates()` / `readResource()` now honour the server-stamped SEP-2549 `ttlMs`/`cacheScope`: a still-fresh cached entry is returned without a round trip. Opt-in by server hint — a server that sends `ttlMs: 0` (the SDK's default stamp) sees no behaviour change. Per-call override: pass `{ cacheMode: 'refresh' }` (always fetch and re-store) or `{ cacheMode: 'bypass' }` (fetch without touching the cache). Server `ttlMs` is clamped at 24 h (`MAX_CACHE_TTL_MS`). Entries are automatically scoped by connected-server identity; new `ClientOptions.cachePartition` (per-principal slot for `'private'`-scoped entries on a shared `responseCacheStore`; default `''`) and `ClientOptions.defaultCacheTtlMs` (TTL when the result lacks one, e.g. legacy-era responses; default `0`). `ResponseCacheStore` gained `delete(key)` (driven by `notifications/resources/updated`); `InMemoryResponseCacheStore` is now bounded (`{ maxEntries }`, default 512).
 
-Output-schema validator compilation is now lazy (first `callTool()` against the cached `tools/list` entry) and non-throwing (an uncompilable `outputSchema` is `console.warn`-ed and validation is skipped for that tool only); `listTools()` no longer throws on an uncompilable `outputSchema`. Applies on every era — the legacy-era `listTools()` path is unchanged at the wire level only.
+Output-schema validator compilation is now lazy (first `callTool()` against the cached `tools/list` entry); `listTools()` no longer throws on an uncompilable `outputSchema` — every tool stays listed and the compile failure is captured per-tool. Calling `callTool()` on the affected tool throws `ProtocolError(InvalidParams)` with `data.reason` set to the structured kind, before the request is sent (validation is never silently skipped). Applies on every era — the legacy-era `listTools()` path is unchanged at the wire level only.
 
 No code changes required; wire-behavior note: on a 2026-07-28 Streamable HTTP connection, aborting an in-flight client request (caller `signal` / timeout) closes that request's SSE response stream as the spec cancellation signal — `notifications/cancelled` is no longer POSTed
 there. 2025-era connections and stdio at any era still send `notifications/cancelled`. Custom `Transport` implementations that open one underlying request per outbound message and honor `TransportSendOptions.requestSignal` may declare `readonly hasPerRequestStream = true` to opt
@@ -670,6 +670,7 @@ JSON Schema 2020-12 posture (SEP-1613 / SEP-2106): the default validator support
 | `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`) |
+| draft-07 idioms via `fromJsonSchema(schema)`                       | `fromJsonSchema(schema, new AjvJsonSchemaValidator(ajv))` — the `McpServer`/`Client` `jsonSchemaValidator` option does **not** reach `fromJsonSchema`-authored schemas                                         |
 | `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

@@ -594,9 +594,10 @@ New `ClientOptions`:
 
 The `ResponseCacheStore` interface gained `delete(key)` (the per-URI invalidation `notifications/resources/updated` drives) — custom stores written against the alpha substrate need to add it. The default `InMemoryResponseCacheStore` is now bounded (default 512 entries, oldest-first eviction; configurable via `{ maxEntries }`).
 
-**Output-schema validator lifecycle (every era):** validator compilation is now lazy — validators are compiled on the first `callTool()` against the cached `tools/list` entry, not eagerly inside `listTools()` — and non-throwing: an uncompilable `outputSchema` is `console.warn`-ed
-and validation is skipped for that tool only. In v1, `listTools()` threw on an uncompilable `outputSchema`; now it succeeds, and a pluggable `jsonSchemaValidator` provider observes compilation at `callTool` time, not `listTools` time. The legacy-era `listTools()` path is
-unchanged at the wire level but is observably different at the validator-lifecycle level.
+**Output-schema validator lifecycle (every era):** validator compilation is now lazy — validators are compiled on the first `callTool()` against the cached `tools/list` entry, not eagerly inside `listTools()`. In v1, `listTools()` threw on an uncompilable `outputSchema`; now
+`listTools()` succeeds (every tool stays listed) and the compile failure is captured per-tool. Calling `callTool()` on the affected tool then throws `ProtocolError(InvalidParams, "Tool 'X' has an invalid outputSchema: …")` with `data.reason` set to the structured kind, **before
+the request is sent** — output-schema validation is never silently skipped. A pluggable `jsonSchemaValidator` provider observes compilation at `callTool` time, not `listTools` time. The legacy-era `listTools()` path is unchanged at the wire level but is observably different at
+the validator-lifecycle level.
 
 ### `InMemoryTransport` moved
 
@@ -1454,7 +1455,7 @@ The default validator supports **JSON Schema 2020-12 only** (the spec's only MUS
 
 - **You declared 2020-12 keywords (`$defs`, `prefixItems`, `unevaluatedProperties`, `dependentRequired`) in a server schema and they were silently ignored.** They are now enforced. If a previously "passing" tool input or output starts failing validation, the schema was always
   wrong on the wire — fix the schema or the data.
-- **You authored draft-07 idioms via `fromJsonSchema()`** (e.g. tuple `items: [...]` instead of `prefixItems`, draft-07 `definitions`). Port to 2020-12 spelling, or pass a draft-07 Ajv instance per the opt-back below.
+- **You authored draft-07 idioms via `fromJsonSchema()`** (e.g. tuple `items: [...]` instead of `prefixItems`, draft-07 `definitions`). Port to 2020-12 spelling, or pass a draft-07 Ajv instance **as the second argument** — `fromJsonSchema(schema, new AjvJsonSchemaValidator(ajv))` — built per the opt-back recipe below. The `McpServer`/`Client` `jsonSchemaValidator` option does **not** reach `fromJsonSchema()`-authored schemas (`fromJsonSchema()` compiles eagerly with the package-level default unless a validator is passed directly).
 - **You imported `Ajv` from the SDK's validator subpath and relied on the re-export being the draft-07 class.** It still is — `Ajv` remains the draft-07 class (re-exported for the opt-back), but it is **no longer** what the SDK uses by default.
 
 To validate other dialects, pass a pre-configured Ajv instance:

packages/client/src/validators/ajv.ts

@@ -1,16 +1,19 @@
 /**
- * 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.
+ * Customisation entry point for the AJV validator. Re-exports `Ajv` and `addFormats` from the
+ * SDK's bundled copy. For a custom 2020-12 instance, import `Ajv2020` directly from
+ * `'ajv/dist/2020.js'` (`ajv` is a peer dependency of this subpath; `Ajv2020` is not re-exported
+ * here because its type graph tips downstream declaration bundling — tracked in #2339). The
+ * re-exported `Ajv` is the **draft-07** class, kept for opting back to the pre-SEP-1613 default,
+ * and would silently downgrade dialect if used for routine customisation.
  *
  * @example
  * ```ts
- * import { Ajv2020, addFormats, AjvJsonSchemaValidator } from '@modelcontextprotocol/client/validators/ajv';
+ * import { Ajv2020 } from 'ajv/dist/2020.js';
+ * import { addFormats, AjvJsonSchemaValidator } from '@modelcontextprotocol/client/validators/ajv';
  *
  * const ajv = new Ajv2020({ strict: false, validateSchema: false, allErrors: true });
  * addFormats(ajv);
  * const validator = new AjvJsonSchemaValidator(ajv);
  * ```
  */
-export { addFormats, Ajv, Ajv2020, AjvJsonSchemaValidator } from '@modelcontextprotocol/core/validators/ajv';
+export { addFormats, Ajv, AjvJsonSchemaValidator } from '@modelcontextprotocol/core/validators/ajv';

packages/core/src/types/specTypeSchema.ts

@@ -237,8 +237,8 @@ type SchemaRecord = { readonly [K in SpecTypeName]: StandardSchemaV1Sync<SpecTyp
 type GuardRecord = { readonly [K in SpecTypeName]: (value: unknown) => value is SpecTypeInputs[K] };
 
 /**
- * SEP-2106: the public `CallToolResult` / `CompatibilityCallToolResult` types widen
- * `structuredContent` to `unknown`, and the public `Tool` / `ListToolsResult` types widen
+ * SEP-2106: the public `CallToolResult` / `CompatibilityCallToolResult` / `ToolResultContent` types
+ * widen `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
@@ -251,6 +251,7 @@ const PublicToolSchema = schemas.ToolSchema.extend({
 const SCHEMA_OVERRIDES: Partial<Record<ProtocolSchemaKey, z.ZodType>> = {
     CallToolResultSchema: PublicCallToolResultSchema,
     CompatibilityCallToolResultSchema: PublicCallToolResultSchema.or(schemas.ResultSchema.extend({ toolResult: z.unknown() })),
+    ToolResultContentSchema: schemas.ToolResultContentSchema.extend({ structuredContent: z.unknown().optional() }),
     ToolSchema: PublicToolSchema,
     ListToolsResultSchema: schemas.ListToolsResultSchema.extend({ tools: z.array(PublicToolSchema) })
 };

packages/core/src/types/types.ts

@@ -407,7 +407,7 @@ export type ToolUseContent = Infer<typeof ToolUseContentSchema>;
  * in the specification for at least twelve months. Migrate to calling LLM
  * provider APIs directly.
  */
-export type ToolResultContent = Infer<typeof ToolResultContentSchema>;
+export type ToolResultContent = WidenStructuredContent<Infer<typeof ToolResultContentSchema>>;
 export type EmbeddedResource = Infer<typeof EmbeddedResourceSchema>;
 export type ResourceLink = Infer<typeof ResourceLinkSchema>;
 export type ContentBlock = Infer<typeof ContentBlockSchema>;

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

@@ -7,7 +7,9 @@
  * @module
  */
 
-import { addFormats, Ajv2020, AjvJsonSchemaValidator } from './ajvProvider.js';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+
+import { addFormats, AjvJsonSchemaValidator } from './ajvProvider.js';
 
 /**
  * Example: Default AJV instance.
@@ -22,11 +24,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.
+ * Import `Ajv2020` directly from `'ajv/dist/2020.js'` (`ajv` is a peer dependency of this subpath)
+ * 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
+    // import { Ajv2020 } from 'ajv/dist/2020.js';
     const ajv = new Ajv2020({ strict: false, validateSchema: false, allErrors: true });
     const validator = new AjvJsonSchemaValidator(ajv);
     //#endregion AjvJsonSchemaValidator_customInstance
@@ -36,11 +40,13 @@ function AjvJsonSchemaValidator_customInstance() {
 /**
  * Example: Custom AJV instance with formats registered.
  *
- * `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.
+ * `addFormats` is re-exported from this module; `Ajv2020` is imported directly from
+ * `'ajv/dist/2020.js'` (peer dependency — its type graph tips downstream declaration bundling so
+ * it is not re-exported; tracked in #2339).
  */
 function AjvJsonSchemaValidator_withFormats() {
     //#region AjvJsonSchemaValidator_withFormats
+    // import { Ajv2020 } from 'ajv/dist/2020.js';
     const ajv = new Ajv2020({ strict: false, validateSchema: false, allErrors: true });
     addFormats(ajv);
     const validator = new AjvJsonSchemaValidator(ajv);

packages/core/src/validators/ajvProvider.ts

@@ -47,14 +47,13 @@ function createDefaultAjvInstance(): AjvLike {
 
 /**
  * AJV-backed JSON Schema validator. See `@modelcontextprotocol/{client,server}/validators/ajv`
- * for the customisation entry point (re-exports `Ajv2020`, `Ajv`, and `addFormats` from the
- * bundled copy).
+ * 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 `SchemaCompileError{kind:'unsupported-dialect'}`; pass a
- * 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.
+ * pre-configured Ajv instance to validate other dialects. When passing a custom instance, import
+ * `Ajv2020` directly from `'ajv/dist/2020.js'` (`ajv` is a peer dependency of this subpath) —
+ * `new Ajv(...)` is the draft-07 class and would silently downgrade dialect.
  *
  * @example Use with default configuration
  * ```ts source="./ajvProvider.examples.ts#AjvJsonSchemaValidator_default"
@@ -63,12 +62,14 @@ function createDefaultAjvInstance(): AjvLike {
  *
  * @example Use with a custom AJV instance
  * ```ts source="./ajvProvider.examples.ts#AjvJsonSchemaValidator_customInstance"
+ * // import { Ajv2020 } from 'ajv/dist/2020.js';
  * 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"
+ * // import { Ajv2020 } from 'ajv/dist/2020.js';
  * const ajv = new Ajv2020({ strict: false, validateSchema: false, allErrors: true });
  * addFormats(ajv);
  * const validator = new AjvJsonSchemaValidator(ajv);
@@ -148,14 +149,23 @@ export class AjvJsonSchemaValidator implements jsonSchemaValidator {
 }
 
 /**
- * Draft-07 AJV class, re-exported for consumers who need to opt back to the pre-SEP-1613 default
- * (`new AjvJsonSchemaValidator(new Ajv({ strict: false }))`).
+ * Draft-07 AJV class, re-exported for consumers who need to opt back to the pre-SEP-1613 default.
+ * The full v1-equivalent construction is:
+ *
+ * ```ts
+ * const ajv = new Ajv({ strict: false, validateFormats: true, validateSchema: false, allErrors: true });
+ * addFormats(ajv);
+ * new AjvJsonSchemaValidator(ajv);
+ * ```
+ *
+ * (omitting `validateSchema: false` makes a 2020-12-stamped `$schema` fail with an opaque
+ * "no schema with key or ref …" engine error; omitting `addFormats` silently drops `format`
+ * validation that the v1 default had).
+ *
+ * `Ajv2020` is **not** re-exported here (its type graph tips downstream declaration bundling;
+ * tracked in #2339); import it directly from `'ajv/dist/2020.js'` — `ajv` is a peer dependency
+ * of this subpath.
  */
 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/spec.types.2025-11-25.test.ts

@@ -569,7 +569,10 @@ const sdkTypeChecks = {
     },
     ToolResultContent: (sdk: SDKTypes.ToolResultContent, spec: SpecTypes.ToolResultContent) => {
         sdk = spec;
-        spec = sdk;
+        // SEP-2106: the public SDK type widens `structuredContent` to `unknown`; the 2025 spec
+        // type pins it at `{ [key: string]: unknown }`. spec→sdk holds (record ⊂ unknown); the
+        // reverse intentionally does not.
+        spec = sdk as typeof sdk & { structuredContent?: { [key: string]: unknown } };
     },
     SamplingMessageContentBlock: (sdk: SDKTypes.SamplingMessageContentBlock, spec: SpecTypes.SamplingMessageContentBlock) => {
         sdk = spec;