feat(client): minimal response-cache substrate; list* auto-paginate and write one cached entry

ResponseCacheStore / InMemoryResponseCacheStore (new file responseCache.ts)
back the Client's derived views: a no-argument listTools / listPrompts /
listResources / listResourceTemplates call walks every page and writes ONE
aggregated entry; explicit-cursor calls still pass through. list_changed
notifications evict the matching method (no refetch); _resetConnectionState
clears the store. _toolDefinition(name) is the derived name->Tool view over
the cached tools/list entry, memoized against the entry's stamp (mcp.d's
cachedTool pattern).

New ClientOptions: responseCacheStore (defaults to a fresh per-instance
InMemoryResponseCacheStore — a store MUST NOT be shared across clients with
different auth contexts; entries are keyed by method only) and listMaxPages
(auto-pagination cap, default 64).

The e2e *:list:pagination 'raw server' bodies and pagination:client:
cursor-handling are rewritten to assert the aggregated result and the
verbatim wire-level cursor walk; the 'mcpserver' bodies are unchanged (still
knownFailure — McpServer does not paginate server-side).

Author: felixweinberger

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

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': minor
+---
+
+Response-cache substrate. `Client` now holds a pluggable `ResponseCacheStore` (default: a fresh per-instance `InMemoryResponseCacheStore`) that the four `list*` verbs write their aggregated result to and that `*/list_changed` notifications evict. A no-argument `listTools()` / `listPrompts()` / `listResources()` / `listResourceTemplates()` call now walks every page internally and returns the aggregated list (`nextCursor: undefined`); explicit-cursor calls still return one page. The cached `tools/list` entry is the single source for the existing output-schema validators and (on a 2026-07-28 connection) SEP-2243 `Mcp-Param-*` mirroring. New exports: `ResponseCacheStore`, `CacheKey`, `CacheEntry`, `CacheScope`, `MaybePromise`, `InMemoryResponseCacheStore`; new `ClientOptions.responseCacheStore` / `ClientOptions.listMaxPages`. The store interface is async-ready (`MaybePromise<…>`); the in-memory default stays synchronous. **A store instance must not be shared across `Client` instances at all in v2.0.x** — entries are keyed by method only (server-identity confusion + `clear()`/`evict()` cross-talk); per-principal partitioning that enables safe sharing arrives with the full caching engine.

docs/migration.md

@@ -538,6 +538,14 @@ const result = specTypeSchemas.CallToolResult['~standard'].validate(value);
 `isSpecType` and `specTypeSchemas` are keyed by `SpecTypeName` — a literal union of every named type in the MCP spec — so you get autocomplete and a compile error on typos. `specTypeSchemas.X` is a `StandardSchemaV1Sync<In, Out>` — `validate()` returns the result synchronously,
 so you can access `.issues` / `.value` without `await`. It composes with any Standard-Schema-aware library. The pre-existing `isCallToolResult(value)` guard still works.
 
+### Client list methods auto-paginate and feed the response cache
+
+A no-argument `Client.listTools()` / `listPrompts()` / `listResources()` / `listResourceTemplates()` call now walks every page internally and returns the aggregated list (`nextCursor` is `undefined`). Explicit-cursor calls (`listTools({ cursor })`) still return one page, so the
+documented cursor loop continues to work — it just iterates once. The aggregated result is written to a per-client response cache (`ResponseCacheStore`, default `InMemoryResponseCacheStore`); a `*/list_changed` notification evicts the matching entry, and a reconnect clears the
+per-instance default store (a user-supplied store is left untouched). The cached `tools/list` entry is what `callTool`'s output validation and (on a 2026-07-28 connection) SEP-2243 `Mcp-Param-*` mirroring read. Pass `ClientOptions.responseCacheStore` to supply your own store —
+**do not share one store across `Client` instances at all in v2.0.x** (server-identity confusion + `clear()`/`evict()` cross-talk; per-principal partitioning that enables safe sharing arrives with the full caching engine). `ClientOptions.listMaxPages` (default `64`) bounds the
+auto-pagination loop.
+
 ### Client list methods return empty results for missing capabilities
 
 `Client.listPrompts()`, `listResources()`, `listResourceTemplates()`, and `listTools()` now return empty results when the server didn't advertise the corresponding capability, instead of sending the request. This respects the MCP spec's capability negotiation.

packages/client/src/client/client.ts

@@ -78,6 +78,8 @@ import {
     SubscriptionFilterSchema
 } from '@modelcontextprotocol/core';
 
+import type { ResponseCacheStore } from './responseCache.js';
+import { InMemoryResponseCacheStore } from './responseCache.js';
 import type { ResolvedVersionNegotiation, VersionNegotiationOptions } from './versionNegotiation.js';
 import { detectProbeEnvironment, detectProbeTransportKind, negotiateEra, resolveVersionNegotiation } from './versionNegotiation.js';
 
@@ -255,8 +257,43 @@ export type ClientOptions = ProtocolOptions & {
      * ```
      */
     listChanged?: ListChangedHandlers;
+
+    /**
+     * Cap on the number of pages a no-argument `list*` call walks before
+     * throwing (a defence against a server whose `nextCursor` never
+     * converges). `0` disables the cap. Default: `64`.
+     */
+    listMaxPages?: number;
+
+    /**
+     * The response-cache store backing the client's derived views (the cached
+     * `tools/list` result that {@linkcode Client.callTool | callTool}'s output
+     * validation and SEP-2243 header mirroring read). Defaults to a fresh
+     * {@linkcode InMemoryResponseCacheStore} per client.
+     *
+     * **Do not share one store across clients at all in v2.0.x** — entries
+     * are keyed by method + params only, so two clients connected to
+     * different servers (even under the same credential) collide on
+     * `tools/list`, and one client's `list_changed` evicts every co-tenant's
+     * entry. Supply your own only as a single-client backing store.
+     * Per-principal partitioning that enables safe sharing is #39.
+     */
+    responseCacheStore?: ResponseCacheStore;
 };
 
+/**
+ * `list_changed` notification → response-cache method(s) to evict. `resources`
+ * covers both list verbs (the spec's "relevant notification ⇒ immediately
+ * stale").
+ */
+const LIST_CHANGED_EVICTIONS: Readonly<Record<string, readonly string[]>> = {
+    'notifications/tools/list_changed': ['tools/list'],
+    'notifications/prompts/list_changed': ['prompts/list'],
+    'notifications/resources/list_changed': ['resources/list', 'resources/templates/list']
+};
+
+const DEFAULT_LIST_MAX_PAGES = 64;
+
 /**
  * A handle to an open `subscriptions/listen` stream (protocol revision
  * 2026-07-28). Change notifications delivered on the stream dispatch to the
@@ -340,6 +377,33 @@ export class Client extends Protocol<ClientContext> {
     private _instructions?: string;
     private _jsonSchemaValidator: jsonSchemaValidator;
     private _cachedToolOutputValidators: Map<string, JsonSchemaValidator<unknown>> = new Map();
+    /**
+     * The response-cache substrate. The four list verbs write their aggregated
+     * result here; `_toolDefinition` and the output-validator map are derived
+     * views over the `tools/list` entry. `list_changed` evicts the matching
+     * method; `_resetConnectionState` clears the lot.
+     */
+    private readonly _responseCache: ResponseCacheStore;
+    /**
+     * `name → Tool` index derived from the cached `tools/list` entry, memoized
+     * against the entry's `stamp` so it re-derives only when the backing entry
+     * changes (mcp.d's `cachedTool` pattern).
+     */
+    private _toolIndex?: { stamp: number; byName: Map<string, Tool> };
+    /**
+     * Per-method eviction-generation counter. `_onnotification`'s
+     * `list_changed` evict bumps it; `_listAllPages` captures it before page 1
+     * and `_cacheListResult` skips the write if it moved — so a `list_changed`
+     * arriving mid-walk is not overwritten by the walk's stale aggregate.
+     */
+    private readonly _evictionGeneration = new Map<string, number>();
+    /**
+     * Whether `_responseCache` is the per-instance default the constructor
+     * allocated. A user-supplied store is never `clear()`ed by
+     * `_resetConnectionState` (defeats the only reason to supply one).
+     */
+    private readonly _responseCacheIsDefault: boolean;
+    private readonly _listMaxPages: number;
     private _listChangedDebounceTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
     /**
      * The constructor `listChanged` configuration. Durable across reconnects:
@@ -397,6 +461,13 @@ export class Client extends Protocol<ClientContext> {
         }
         this._listChangedDebounceTimers.clear();
         this._cachedToolOutputValidators.clear();
+        // A user-supplied store is NOT cleared on reconnect/close — that would
+        // defeat the only reason to supply one. The per-instance default IS
+        // cleared (it is connection-scoped); the default impl is synchronous,
+        // so the MaybePromise<void> return is a plain void here.
+        if (this._responseCacheIsDefault) void this._responseCache.clear();
+        this._toolIndex = undefined;
+        this._evictionGeneration.clear();
     }
 
     override async close(): Promise<void> {
@@ -426,6 +497,12 @@ export class Client extends Protocol<ClientContext> {
         // Multi-round-trip auto-fulfilment driver (2026-07-28): on by default,
         // configurable via ClientOptions.inputRequired.
         this._inputRequiredDriverConfig = resolveInputRequiredDriverConfig(options?.inputRequired);
+        // Response-cache substrate. A fresh in-memory store is allocated when
+        // the caller does not supply one — never share a default across
+        // instances (see ClientOptions.responseCacheStore).
+        this._responseCacheIsDefault = options?.responseCacheStore === undefined;
+        this._responseCache = options?.responseCacheStore ?? new InMemoryResponseCacheStore();
+        this._listMaxPages = options?.listMaxPages ?? DEFAULT_LIST_MAX_PAGES;
 
         // Store list changed config for setup after connection (when we know server capabilities)
         if (options?.listChanged) {
@@ -1254,7 +1331,12 @@ export class Client extends Protocol<ClientContext> {
             console.debug('Client.listPrompts() called but server does not advertise prompts capability - returning empty list');
             return { prompts: [] };
         }
-        return this.request({ method: 'prompts/list', params }, options);
+        if (params?.cursor !== undefined) return this.request({ method: 'prompts/list', params }, options);
+        const { result, generation } = await this._listAllPages<ListPromptsResult>('prompts/list', params, options, (acc, page) =>
+            acc.prompts.push(...page.prompts)
+        );
+        await this._cacheListResult('prompts/list', result, generation);
+        return result;
     }
 
     /**
@@ -1285,7 +1367,12 @@ export class Client extends Protocol<ClientContext> {
             console.debug('Client.listResources() called but server does not advertise resources capability - returning empty list');
             return { resources: [] };
         }
-        return this.request({ method: 'resources/list', params }, options);
+        if (params?.cursor !== undefined) return this.request({ method: 'resources/list', params }, options);
+        const { result, generation } = await this._listAllPages<ListResourcesResult>('resources/list', params, options, (acc, page) =>
+            acc.resources.push(...page.resources)
+        );
+        await this._cacheListResult('resources/list', result, generation);
+        return result;
     }
 
     /**
@@ -1305,7 +1392,96 @@ export class Client extends Protocol<ClientContext> {
             );
             return { resourceTemplates: [] };
         }
-        return this.request({ method: 'resources/templates/list', params }, options);
+        if (params?.cursor !== undefined) return this.request({ method: 'resources/templates/list', params }, options);
+        const { result, generation } = await this._listAllPages<ListResourceTemplatesResult>(
+            'resources/templates/list',
+            params,
+            options,
+            (acc, page) => acc.resourceTemplates.push(...page.resourceTemplates)
+        );
+        await this._cacheListResult('resources/templates/list', result, generation);
+        return result;
+    }
+
+    /**
+     * Walk every page of a paginated list verb and return the aggregated
+     * result. Page 1's result object is mutated in place (its items array is
+     * extended; `nextCursor` is cleared); page-1 metadata (`ttlMs`,
+     * `cacheScope`, `_meta`) is preserved. A `nextCursor` that repeats stops
+     * the walk (defence against a non-converging server, mcp.d's
+     * `drainList` guard); `listMaxPages` is a hard cap — hitting it throws
+     * (the caller's `_cacheListResult` is never reached, so a partial
+     * aggregate is never cached).
+     */
+    private async _listAllPages<R extends { nextCursor?: string }>(
+        method: RequestMethod,
+        params: Record<string, unknown> | undefined,
+        options: RequestOptions | undefined,
+        append: (acc: R, page: R) => void
+    ): Promise<{ result: R; generation: number }> {
+        // Capture the eviction generation BEFORE page 1: a `list_changed` that
+        // lands mid-walk bumps the counter, and `_cacheListResult` skips the
+        // write when it observes the bump (the result still returns to the
+        // caller — it just is not cached).
+        const generation = this._evictionGeneration.get(method) ?? 0;
+        const acc = (await this.request({ method, params }, options)) as R;
+        let cursor = acc.nextCursor;
+        const seen = new Set<string>();
+        let pages = 1;
+        while (cursor !== undefined && !seen.has(cursor)) {
+            if (this._listMaxPages !== 0 && pages >= this._listMaxPages) {
+                throw new Error(`${method}: exceeded listMaxPages (${this._listMaxPages}); server pagination did not terminate`);
+            }
+            seen.add(cursor);
+            const page = (await this.request({ method, params: { ...params, cursor } }, options)) as R;
+            append(acc, page);
+            cursor = page.nextCursor;
+            pages++;
+        }
+        acc.nextCursor = undefined;
+        return { result: acc, generation };
+    }
+
+    /**
+     * Write an aggregated list result to the response-cache substrate (the
+     * store generates and owns the stamp). Skips the write when the
+     * per-method eviction generation moved while the walk was in flight — a
+     * `list_changed` that landed mid-walk has already invalidated the result
+     * the caller is about to write, and overwriting the eviction with the
+     * stale aggregate would lose the invalidation.
+     */
+    private async _cacheListResult(method: string, value: unknown, generation: number): Promise<void> {
+        if ((this._evictionGeneration.get(method) ?? 0) !== generation) return;
+        await this._responseCache.set({ method }, { value });
+    }
+
+    /** Route a custom-store failure to `onerror` without aborting the surrounding dispatch. */
+    private _reportStoreError(e: unknown): void {
+        this.onerror?.(e instanceof Error ? e : new Error(String(e)));
+    }
+
+    /**
+     * The descriptor for tool `name` taken from the cached `tools/list` entry —
+     * the single source for output-schema validation and SEP-2243
+     * `x-mcp-header` mirroring. The `name → Tool` index is memoized against
+     * the entry's `stamp` and re-derived only when the backing entry changes
+     * (mcp.d's `cachedTool`). Returns `undefined` only when no `tools/list`
+     * response is held at all, or the held list does not contain `name`.
+     *
+     * @internal
+     */
+    private async _toolDefinition(name: string): Promise<Tool | undefined> {
+        const entry = await this._responseCache.get({ method: 'tools/list' });
+        if (entry === undefined) {
+            this._toolIndex = undefined;
+            return undefined;
+        }
+        if (this._toolIndex?.stamp !== entry.stamp) {
+            const byName = new Map<string, Tool>();
+            for (const tool of (entry.value as ListToolsResult).tools) byName.set(tool.name, tool);
+            this._toolIndex = { stamp: entry.stamp, byName };
+        }
+        return this._toolIndex.byName.get(name);
     }
 
     /** Reads the contents of a resource by URI. */
@@ -1542,6 +1718,34 @@ export class Client extends Protocol<ClientContext> {
      * being silently swallowed.
      */
     protected override _onnotification(raw: JSONRPCNotification, extra?: MessageExtraInfo): void {
+        // Response-cache invalidation: a `list_changed` notification means the
+        // matching cached list result is stale. Evict (do NOT refetch) before
+        // dispatch so a `listChanged.onChanged` handler that calls `listTools()`
+        // observes the cleared entry. Runs regardless of whether the user
+        // configured `listChanged` — derived views (`_toolDefinition`, output
+        // validators) must drop the stale entry either way. `raw.method` is
+        // server-controlled; guard with `Object.hasOwn` so an inherited
+        // `Object.prototype` member name (`constructor`, `toString`, …) does
+        // not reach the iteration as a non-iterable function.
+        const evicted = Object.hasOwn(LIST_CHANGED_EVICTIONS, raw.method) ? LIST_CHANGED_EVICTIONS[raw.method] : undefined;
+        if (evicted !== undefined) {
+            for (const method of evicted) {
+                // Bump the generation FIRST and unconditionally: the
+                // `_cacheListResult` race guard relies on the bump, not on
+                // the store's evict completing.
+                this._evictionGeneration.set(method, (this._evictionGeneration.get(method) ?? 0) + 1);
+                // A custom store's `evict()` may throw or reject; route to
+                // `onerror` and proceed so dispatch (and the user's
+                // `listChanged` handler) runs regardless. The store interface
+                // is async-ready; an async evict is fire-and-forget here —
+                // dispatch must not block on it.
+                try {
+                    void Promise.resolve(this._responseCache.evict(method)).catch(error => this._reportStoreError(error));
+                } catch (error) {
+                    this._reportStoreError(error);
+                }
+            }
+        }
         if (raw.method === 'notifications/subscriptions/acknowledged') {
             const params = raw.params as { _meta?: Record<string, unknown>; notifications?: unknown } | undefined;
             const subscriptionId = params?._meta?.[SUBSCRIPTION_ID_META_KEY];
@@ -1753,11 +1957,16 @@ export class Client extends Protocol<ClientContext> {
             console.debug('Client.listTools() called but server does not advertise tools capability - returning empty list');
             return { tools: [] };
         }
-        const result = await this.request({ method: 'tools/list', params }, options);
-
+        // Explicit-cursor calls pass through (one page, no caching) so existing
+        // cursor loops keep working; the no-argument call walks every page and
+        // writes ONE aggregated entry — `_toolDefinition` reads that entry.
+        if (params?.cursor !== undefined) return this.request({ method: 'tools/list', params }, options);
+        const { result, generation } = await this._listAllPages<ListToolsResult>('tools/list', params, options, (acc, page) =>
+            acc.tools.push(...page.tools)
+        );
+        await this._cacheListResult('tools/list', result, generation);
         // Cache the tools and their output schemas for future validation
         this.cacheToolMetadata(result.tools);
-
         return result;
     }