fix: preserve tool schema metadata across pagination

Author: mattzcarey

docs/migration-SKILL.md

@@ -501,7 +501,8 @@ The 2025-11 task side-channel through `Protocol` is removed (was always `@experi
 
 `TaskStore` / `InMemoryTaskStore` / `CreateTaskOptions` / `isTerminal` (storage layer) are also removed; they will return with the SEP-2663 server-directed plugin.
 
-NOT removed (wire surface, kept for 2025-11-25 interop): task Zod schemas + inferred types (`Task`, `TaskStatus`, `TaskMetadata`, `RelatedTaskMetadata`, `CreateTaskResult`, `GetTask*`, `ListTasks*`, `CancelTask*`, `TaskStatusNotification*`, `TaskAugmentedRequestParams`), task members of the request/result/notification unions, the `tasks` capability key, `isTaskAugmentedRequestParams`, `RELATED_TASK_META_KEY`. Inbound `tasks/*` requests → `-32601`.
+NOT removed (wire surface, kept for 2025-11-25 interop): task Zod schemas + inferred types (`Task`, `TaskStatus`, `TaskMetadata`, `RelatedTaskMetadata`, `CreateTaskResult`, `GetTask*`, `ListTasks*`, `CancelTask*`, `TaskStatusNotification*`, `TaskAugmentedRequestParams`), task
+members of the request/result/notification unions, the `tasks` capability key, `isTaskAugmentedRequestParams`, `RELATED_TASK_META_KEY`. Inbound `tasks/*` requests → `-32601`.
 
 ## 13. Behavioral Changes
 
@@ -513,8 +514,10 @@ NOT removed (wire surface, kept for 2025-11-25 interop): task Zod schemas + infe
 
 No code changes required; these are wire-behavior notes:
 
-- Resumability behavior (SSE priming events, `closeSSEStream` / `closeStandaloneSSEStream` callbacks) is only enabled for protocol versions in the transport's supported-versions list that are `>= 2025-11-25`. Unknown future version strings in an `initialize` request body no longer enable it. Behavior for all currently supported protocol versions is unchanged.
-- Session-ID mismatch still responds `404 Not Found` with JSON-RPC error code `-32001` (`Session not found`), unchanged from v1. This `-32001` usage is an SDK convention, not a spec-assigned code, and may be re-derived as 2026 protocol revision error handling is adopted — migrated client code should key off the HTTP `404` status, not the `-32001` code.
+- Resumability behavior (SSE priming events, `closeSSEStream` / `closeStandaloneSSEStream` callbacks) is only enabled for protocol versions in the transport's supported-versions list that are `>= 2025-11-25`. Unknown future version strings in an `initialize` request body no
+  longer enable it. Behavior for all currently supported protocol versions is unchanged.
+- Session-ID mismatch still responds `404 Not Found` with JSON-RPC error code `-32001` (`Session not found`), unchanged from v1. This `-32001` usage is an SDK convention, not a spec-assigned code, and may be re-derived as 2026 protocol revision error handling is adopted —
+  migrated client code should key off the HTTP `404` status, not the `-32001` code.
 
 ## 14. Runtime-Specific JSON Schema Validators (Enhancement)
 
@@ -555,7 +558,7 @@ Tool schemas conform to full JSON Schema 2020-12, and `structuredContent` may be
 | ---------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `inputSchema` root                             | `type: "object"` + `properties`/`required` only          | `type: "object"` required, **plus** any 2020-12 keyword (`oneOf`/`anyOf`/`allOf`/`not`, `if`/`then`/`else`, `$ref`/`$defs`/`$anchor`) |
 | `outputSchema` root                            | `type: "object"` only                                    | **any** valid JSON Schema 2020-12 (object, array, primitive, composition)                                                             |
-| `Tool.inputSchema` / `Tool.outputSchema` types | object schema with typed `properties`/`required` members | broad JSON Schema records; narrow before reading keyword properties (**source-breaking**)                                             |
+| `Tool.inputSchema` / `Tool.outputSchema` types | object schema with typed `properties`/`required` members | broad JSON Schema records; narrow keyword field values before using them (**source-breaking**)                                        |
 | `CallToolResult.structuredContent` type        | `{ [key: string]: unknown }`                             | `unknown` (**source-breaking**)                                                                                                       |
 | `client.callTool(...)`                         | returns `structuredContent` as object                    | returns `structuredContent` as `unknown`; narrow it before property access                                                            |
 | `registerTool` handler return                  | `structuredContent` untyped                              | type-checked against the tool's `outputSchema` inferred output                                                                        |
@@ -570,20 +573,21 @@ const sc = result.structuredContent;
 const temp = typeof sc === 'object' && sc !== null && !Array.isArray(sc) ? (sc as Record<string, unknown>).temperature : undefined;
 ```
 
-Source-breaking fix — property access on `Tool.inputSchema` / `Tool.outputSchema` keyword fields also needs narrowing:
+Source-breaking fix — property access on `Tool.inputSchema` / `Tool.outputSchema` keyword field values also needs narrowing:
 
 ```typescript
-const schema = tool.inputSchema;
-const properties =
-    typeof schema === 'object' && schema !== null && !Array.isArray(schema)
-        ? (schema as Record<string, unknown>).properties
-        : undefined;
+const required = Array.isArray(tool.inputSchema.required) ? tool.inputSchema.required : [];
+const properties = tool.inputSchema.properties;
+if (typeof properties === 'object' && properties !== null && !Array.isArray(properties)) {
+    const propertyNames = Object.keys(properties);
+}
 ```
 
 Behavior notes:
 
 - A server returning array/primitive `structuredContent` automatically also emits a serialized `TextContent` block (old-client interop). No action required.
-- Built-in validators reject non-same-document `$ref`/`$dynamicRef` (SSRF) and over-budget schemas (composition DoS). Use a custom `jsonSchemaValidator` to change this.
+- Built-in validators reject non-same-document `$ref`/`$dynamicRef` (SSRF) and over-budget schemas (composition DoS). Use `resolveExternalSchemaRefs(schema, { allowlist })` to fetch and inline approved external refs before validation, or use a custom `jsonSchemaValidator` to
+  change validator behavior.
 
 ## 16. Migration Steps (apply in this order)
 

docs/migration.md

@@ -336,11 +336,11 @@ Note: the v2 signature takes a plain `string[]` instead of an options object.
 
 ### Resumability gating for unknown protocol versions (Streamable HTTP server)
 
-The server-side Streamable HTTP transport enables resumability behavior introduced with protocol version `2025-11-25` — SSE priming events and the `closeSSEStream` / `closeStandaloneSSEStream` callbacks — based on the client's protocol version. Previously this was an
-open-ended `protocolVersion >= '2025-11-25'` comparison, so an unrecognized future version string in an `initialize` request body (which, unlike the `MCP-Protocol-Version` header, is not validated against the supported-versions list) silently enabled the behavior.
+The server-side Streamable HTTP transport enables resumability behavior introduced with protocol version `2025-11-25` — SSE priming events and the `closeSSEStream` / `closeStandaloneSSEStream` callbacks — based on the client's protocol version. Previously this was an open-ended
+`protocolVersion >= '2025-11-25'` comparison, so an unrecognized future version string in an `initialize` request body (which, unlike the `MCP-Protocol-Version` header, is not validated against the supported-versions list) silently enabled the behavior.
 
-The check is now bounded: the version must be one of the transport's supported protocol versions (after `connect()`, the server's `supportedProtocolVersions`) **and** at least `2025-11-25`. Behavior for all currently supported protocol versions (`2024-10-07` through
-`2025-11-25`) is unchanged. Clients claiming an unknown future protocol version in the initialize body are now treated like clients without empty-SSE-data support: no priming event is sent and no early-close callbacks are provided.
+The check is now bounded: the version must be one of the transport's supported protocol versions (after `connect()`, the server's `supportedProtocolVersions`) **and** at least `2025-11-25`. Behavior for all currently supported protocol versions (`2024-10-07` through `2025-11-25`)
+is unchanged. Clients claiming an unknown future protocol version in the initialize body are now treated like clients without empty-SSE-data support: no priming event is sent and no early-close callbacks are provided.
 
 ### `setRequestHandler` and `setNotificationHandler` use method strings
 
@@ -902,7 +902,9 @@ The 2025-11 experimental tasks side-channel woven through `Protocol` has been re
 
 **Also removed:** the storage layer (`TaskStore`, `InMemoryTaskStore`, `CreateTaskOptions`, `isTerminal`). It will return as part of the SEP-2663 server-directed plugin in a follow-up.
 
-**Wire types remain.** The task wire surface defined by the 2025-11-25 protocol revision is still exported, for interoperability with peers on that revision: the task Zod schemas and their inferred types (`Task`, `TaskStatus`, `TaskMetadata`, `RelatedTaskMetadata`, `CreateTaskResult`, `GetTask*`, `GetTaskPayload*`, `ListTasks*`, `CancelTask*`, `TaskStatusNotification*`, `TaskAugmentedRequestParams`), the task members of the request/result/notification unions, the `tasks` capability key, the `isTaskAugmentedRequestParams` guard, and `RELATED_TASK_META_KEY`. Only the behavior is gone: servers built on this SDK do not advertise the `tasks` capability, and inbound `tasks/*` requests receive a standard `-32601` (method not found) error.
+**Wire types remain.** The task wire surface defined by the 2025-11-25 protocol revision is still exported, for interoperability with peers on that revision: the task Zod schemas and their inferred types (`Task`, `TaskStatus`, `TaskMetadata`, `RelatedTaskMetadata`,
+`CreateTaskResult`, `GetTask*`, `GetTaskPayload*`, `ListTasks*`, `CancelTask*`, `TaskStatusNotification*`, `TaskAugmentedRequestParams`), the task members of the request/result/notification unions, the `tasks` capability key, the `isTaskAugmentedRequestParams` guard, and
+`RELATED_TASK_META_KEY`. Only the behavior is gone: servers built on this SDK do not advertise the `tasks` capability, and inbound `tasks/*` requests receive a standard `-32601` (method not found) error.
 
 There is no migration path for the removed surface; it was always `@experimental`. Task support is planned to return as an opt-in extension plugin per SEP-2663.
 
@@ -1005,22 +1007,23 @@ if (typeof sc === 'object' && sc !== null && !Array.isArray(sc)) {
 }
 ```
 
-The generated `Tool.inputSchema` and `Tool.outputSchema` types also widened to reflect full JSON Schema 2020-12. `Tool.inputSchema.properties`, `Tool.inputSchema.required`, and analogous `outputSchema` fields are no longer statically present. Narrow the schema to an object record
-before reading keyword properties:
+The generated `Tool.inputSchema` and `Tool.outputSchema` types also widened to reflect full JSON Schema 2020-12. Keyword fields such as `properties`, `required`, and analogous `outputSchema` fields now have broad JSON values. Narrow the keyword field value before using it:
 
 ```typescript
-const schema = tool.inputSchema;
-const properties =
-    typeof schema === 'object' && schema !== null && !Array.isArray(schema)
-        ? (schema as Record<string, unknown>).properties
-        : undefined;
+const required = Array.isArray(tool.inputSchema.required) ? tool.inputSchema.required : [];
+const properties = tool.inputSchema.properties;
+if (typeof properties === 'object' && properties !== null && !Array.isArray(properties)) {
+    const propertyNames = Object.keys(properties);
+}
 ```
 
 **Stronger server-side typing.** When a tool declares an `outputSchema`, `registerTool` now type-checks the handler's returned `structuredContent` against the schema's inferred output type at compile time — a mismatch is a type error rather than a runtime-only failure.
 
-**Old-client interoperability.** A server that returns array or primitive `structuredContent` will automatically also emit a `TextContent` block containing the serialized JSON, so pre-SEP clients that only understand object-typed `structuredContent` can fall back to the text content. Object `structuredContent` (and results that already include a text block) are left unchanged.
+**Old-client interoperability.** A server that returns array or primitive `structuredContent` will automatically also emit a `TextContent` block containing the serialized JSON, so pre-SEP clients that only understand object-typed `structuredContent` can fall back to the text
+content. Object `structuredContent` (and results that already include a text block) are left unchanged.
 
-**Security.** The built-in validators never dereference non-same-document `$ref`/`$dynamicRef` (anything not beginning with `#`) — such schemas are rejected rather than fetched, preventing SSRF. Schemas exceeding a generous depth / subschema-count bound are also rejected to prevent composition-based validation DoS. Supply your own `jsonSchemaValidator` implementation if you need different behavior.
+**Security.** The built-in validators never dereference non-same-document `$ref`/`$dynamicRef` (anything not beginning with `#`) — such schemas are rejected rather than fetched, preventing SSRF. If you intentionally need external references, resolve and inline them before
+validation with `resolveExternalSchemaRefs(schema, { allowlist })`. Schemas exceeding a generous depth / subschema-count bound are also rejected to prevent composition-based validation DoS. Supply your own `jsonSchemaValidator` implementation if you need different behavior.
 
 ## Unchanged APIs
 
@@ -1034,9 +1037,9 @@ The following APIs are unchanged between v1 and v2 (only the import paths change
 - All Zod schemas and type definitions from `types.ts` (except the aliases listed above)
 - Tool, prompt, and resource callback return types
 
-**Session-ID mismatch responses**: when session management is enabled and a request carries an `Mcp-Session-Id` header that doesn't match the active session, the Streamable HTTP server transport responds `404 Not Found` with a JSON-RPC error body using code `-32001` and
-message `Session not found` — unchanged from v1. Note that this use of `-32001` is an SDK convention, not a spec-assigned error code, and it is expected to be re-derived as error handling for the 2026 protocol revision (`2026-07-28`) is adopted. Avoid hard-coding the
-`-32001` code in client logic; key off the HTTP `404` status instead.
+**Session-ID mismatch responses**: when session management is enabled and a request carries an `Mcp-Session-Id` header that doesn't match the active session, the Streamable HTTP server transport responds `404 Not Found` with a JSON-RPC error body using code `-32001` and message
+`Session not found` — unchanged from v1. Note that this use of `-32001` is an SDK convention, not a spec-assigned error code, and it is expected to be re-derived as error handling for the 2026 protocol revision (`2026-07-28`) is adopted. Avoid hard-coding the `-32001` code in
+client logic; key off the HTTP `404` status instead.
 
 ## Using an LLM to migrate your code
 

packages/client/src/client/client.ts

@@ -870,11 +870,16 @@ export class Client extends Protocol<ClientContext> {
      * Cache validators for tool output schemas.
      * Called after {@linkcode listTools | listTools()} to pre-compile validators for better performance.
      */
-    private cacheToolMetadata(tools: Tool[]): void {
-        this._cachedToolOutputValidators.clear();
-        this._toolOutputValidatorErrors.clear();
+    private cacheToolMetadata(tools: Tool[], reset: boolean): void {
+        if (reset) {
+            this._cachedToolOutputValidators.clear();
+            this._toolOutputValidatorErrors.clear();
+        }
 
         for (const tool of tools) {
+            this._cachedToolOutputValidators.delete(tool.name);
+            this._toolOutputValidatorErrors.delete(tool.name);
+
             // If the tool has an outputSchema, create and cache the validator. Compilation can throw
             // (invalid schema, or a SEP-2106 safety-guard rejection); scope that failure to the
             // offending tool rather than letting it reject the whole listTools() call.
@@ -926,8 +931,9 @@ export class Client extends Protocol<ClientContext> {
         }
         const result = await this._requestWithSchema({ method: 'tools/list', params }, ListToolsResultSchema, options);
 
-        // Cache the tools and their output schemas for future validation
-        this.cacheToolMetadata(result.tools);
+        // Cache the tools and their output schemas for future validation. Preserve entries across
+        // pagination so validators discovered on earlier pages remain active after the final page.
+        this.cacheToolMetadata(result.tools, params?.cursor === undefined);
 
         return result;
     }

packages/core/src/validators/externalRefResolver.ts

@@ -142,7 +142,8 @@ function assertHostAllowed(url: URL, options: ResolvedOptions): void {
     const host = url.hostname.toLowerCase();
 
     if (options.allowlist) {
-        if (!options.allowlist.includes(host)) {
+        const allowlist = new Set(options.allowlist.map(allowedHost => allowedHost.toLowerCase()));
+        if (!allowlist.has(host)) {
             throw new Error(`Refusing to dereference "${url.href}": host "${host}" is not in the allowlist.`);
         }
         return;

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

@@ -60,6 +60,20 @@ describe('resolveExternalSchemaRefs', () => {
         expect(() => assertSchemaSafeToCompile(resolved)).not.toThrow();
     });
 
+    it('matches allowlist hosts case-insensitively', async () => {
+        const schema: JsonSchemaType = { $ref: 'https://Schemas.Example.com/forecast.json' };
+        const fetchImpl = fetchStub({
+            'https://schemas.example.com/forecast.json': { type: 'array', items: { type: 'number' } }
+        });
+
+        const resolved = await resolveExternalSchemaRefs(schema, { allowlist: ['Schemas.Example.com'], fetch: fetchImpl });
+
+        expect(resolved).toEqual({
+            $ref: '#/$defs/__externalRef_0',
+            $defs: { __externalRef_0: { type: 'array', items: { type: 'number' } } }
+        });
+    });
+
     it.each([
         ['AJV', () => new AjvJsonSchemaValidator()],
         ['CfWorker', () => new CfWorkerJsonSchemaValidator()]