docs(examples): caching story asserts client-side honouring; README adds cacheMode + custom-store sections

The client now calls listTools() and readResource() twice each and asserts the
second of each pair is cache-served — the server's resource handler counts how
many times it ran and exposes that via a read-count tool, so the example
verifies (server-side) that the cache hit never reached the wire. Demonstrates
cacheMode:'refresh' and the post-refresh return to cache-serving.

README drops the follow-up note (honouring is shipped), adds a §cacheMode
section, and adds a §Custom store section showing the four-method
ResponseCacheStore interface shape with the cachePartition guidance for shared
stores.

Author: felixweinberger

examples/caching/README.md

@@ -1,10 +1,52 @@
 # caching
 
 `CacheableResult` freshness hints (protocol revision 2026-07-28). The server declares hints at two layers — a per-registration `cacheHint` on the resource and server-level `ServerOptions.cacheHints` — and the SDK resolves most-specific-author-first (handler-return fields would
-take precedence over both) and stamps `ttlMs`/`cacheScope` on the wire toward modern clients only. The client reads the stamped values back.
-
-> Full client-side cache **honouring** (re-using a still-fresh result instead of re-requesting) is a follow-up; this example reads what the server emits today.
+take precedence over both) and stamps `ttlMs`/`cacheScope` on the wire toward modern clients only. The client honours the stamped values: a still-fresh held entry is served without a round trip.
 
 ```bash
 pnpm tsx examples/caching/client.ts
 ```
+
+The client calls `listTools()` and `readResource()` twice each; the second of each pair is served from the response cache. The server exposes a `request-count` tool (how many `tools/list` requests reached it) and a `read-count` tool (how many times the resource handler ran), so the example asserts each counter is unchanged after the cache-served call and increments after `cacheMode: 'refresh'`.
+
+## `cacheMode`
+
+Per-call control on the cacheable verbs (`listTools()` / `listPrompts()` / `listResources()` / `listResourceTemplates()` / `readResource()`):
+
+```ts
+await client.readResource({ uri: 'config://app' }); // 'use' (default): serve from cache if fresh
+await client.readResource({ uri: 'config://app' }, { cacheMode: 'refresh' }); // always fetch, then re-store
+await client.readResource({ uri: 'config://app' }, { cacheMode: 'bypass' }); // fetch; do not read or write the cache
+```
+
+A `list_changed` notification still evicts immediately regardless of TTL.
+
+## Custom store
+
+The default per-client `InMemoryResponseCacheStore` (bounded at 512 entries by default) is enough for most hosts. To back the cache with something persistent (Redis, KV, IndexedDB), implement the five-method `ResponseCacheStore` interface — the store is a dumb keyed-value carrier; freshness and partitioning are the client's job:
+
+```ts
+import type { CacheEntry, CacheKey, CacheScope, ResponseCacheStore } from '@modelcontextprotocol/client';
+
+class MyStore implements ResponseCacheStore {
+    async get(key: CacheKey): Promise<CacheEntry | undefined> {
+        /* read {value, stamp, expiresAt, scope} from your backend */
+    }
+    async set(key: CacheKey, entry: { value: unknown; expiresAt?: number; scope?: CacheScope }): Promise<number> {
+        /* write entry under key; return a monotonically-increasing stamp */
+    }
+    async delete(key: CacheKey): Promise<void> {
+        /* drop the single entry under key (no-op if absent) */
+    }
+    async evict(method: string): Promise<void> {
+        /* drop every entry whose key.method === method (across every partition) */
+    }
+    async clear(): Promise<void> {
+        /* drop everything */
+    }
+}
+
+const client = new Client({ name: 'host', version: '1.0.0' }, { responseCacheStore: new MyStore(), cachePartition: principalId });
+```
+
+The SDK scopes every entry by the connected server's identity automatically — you do not encode server identity into `cachePartition` or the store key yourself. When one store backs several principals against the same server, set `ClientOptions.cachePartition` to a stable identity of the authorization context (e.g. the auth subject) so `'private'`-scoped entries are isolated per principal; `'public'`-scoped entries are shared within the connected server's namespace automatically. Note `serverInfo` is self-reported, so a server that deliberately impersonates another's `name`/`version` shares its `'public'` slot; the per-principal isolation holds regardless.

examples/caching/client.ts

@@ -1,8 +1,7 @@
 /**
  * Reads the cache hints emitted on cacheable results (2026-07-28 connections
- * only) and asserts the configured values reached the wire. Full client-side
- * cache *honouring* (re-using a fresh result instead of re-requesting) is a
- * follow-up — see the SDK's tracking issue for client cache support.
+ * only) and asserts the client honours them: a still-fresh cached entry is
+ * served without a round trip.
  */
 import { check, connectFromArgs, runClient } from '../harness.js';
 
@@ -11,22 +10,60 @@ interface Cacheable {
     cacheScope?: 'public' | 'private';
 }
 
+async function callCount(client: Awaited<ReturnType<typeof connectFromArgs>>, name: 'read-count' | 'request-count'): Promise<number> {
+    const r = await client.callTool({ name });
+    return Number((r.content[0] as { text: string }).text);
+}
+
 runClient('caching', async () => {
     // connectFromArgs picks transport (default: spawn ./server.ts over stdio; --http <url>) and era (--legacy) from argv. Your code would construct a Client and connect over your chosen transport directly.
     const client = await connectFromArgs(import.meta.dirname);
     check.equal(client.getNegotiatedProtocolVersion(), '2026-07-28');
 
+    // The server stamps `tools/list` with `ttlMs: 30_000, cacheScope: 'public'`.
     const tools = (await client.listTools()) as Cacheable & Awaited<ReturnType<typeof client.listTools>>;
     check.equal(tools.ttlMs, 30_000);
     check.equal(tools.cacheScope, 'public');
+    // `request-count` proves the wire was reached exactly once.
+    check.equal(await callCount(client, 'request-count'), 1);
+
+    // The second call is served from the response cache: the server-side
+    // `tools/list` counter is unchanged, and the result is a fresh copy of the
+    // held entry (so mutating it cannot reach the cache).
+    const toolsAgain = await client.listTools();
+    check.deepEqual(
+        toolsAgain.tools.map(t => t.name),
+        tools.tools.map(t => t.name)
+    );
+    check.equal(await callCount(client, 'request-count'), 1);
+
+    // `cacheMode: 'refresh'` always fetches and re-stores: the counter moves.
+    await client.listTools(undefined, { cacheMode: 'refresh' });
+    check.equal(await callCount(client, 'request-count'), 2);
 
     const resources = (await client.listResources()) as Cacheable & Awaited<ReturnType<typeof client.listResources>>;
     check.equal(resources.ttlMs, 5000);
     check.equal(resources.cacheScope, 'public');
 
+    // `readResource`: the resource handler counts how many times it ran, and
+    // the `read-count` tool exposes that counter.
     const read = (await client.readResource({ uri: 'config://app' })) as Cacheable & Awaited<ReturnType<typeof client.readResource>>;
     check.equal(read.ttlMs, 60_000);
     check.equal(read.cacheScope, 'private');
+    check.equal(await callCount(client, 'read-count'), 1);
+
+    // Within TTL, default `cacheMode: 'use'` → served from cache; the server
+    // handler does not run.
+    await client.readResource({ uri: 'config://app' });
+    check.equal(await callCount(client, 'read-count'), 1);
+
+    // `cacheMode: 'refresh'` always fetches and re-stores.
+    await client.readResource({ uri: 'config://app' }, { cacheMode: 'refresh' });
+    check.equal(await callCount(client, 'read-count'), 2);
+
+    // After the refresh the entry is fresh again — back to cache-served.
+    await client.readResource({ uri: 'config://app' });
+    check.equal(await callCount(client, 'read-count'), 2);
 
     await client.close();
 });

examples/caching/server.ts

@@ -17,6 +17,13 @@ import { McpServer } from '@modelcontextprotocol/server';
 
 import { runServerFromArgs } from '../harness.js';
 
+// Module-level (process-wide) counters so the values survive the harness's
+// stateless HTTP leg (fresh `buildServer()` per request) as well as stdio's
+// single per-connection instance. The client asserts against these to prove a
+// cache-served call never reached the server.
+let readCount = 0;
+let listCount = 0;
+
 function buildServer(): McpServer {
     const server = new McpServer(
         { name: 'caching-example', version: '1.0.0' },
@@ -40,12 +47,42 @@ function buildServer(): McpServer {
             description: 'Static application config (rarely changes)',
             cacheHint: { ttlMs: 60_000, cacheScope: 'private' }
         },
-        async uri => ({ contents: [{ uri: uri.href, mimeType: 'application/json', text: '{"feature":true}' }] })
+        async uri => {
+            readCount++;
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: '{"feature":true}' }] };
+        }
     );
 
     // A tool, so tools/list has something to cache.
     server.registerTool('noop', { description: 'no-op' }, async () => ({ content: [{ type: 'text', text: 'ok' }] }));
 
+    // Exposes the server-side `resources/read` invocation count so the client
+    // can assert that a cache-served call did not reach the wire.
+    server.registerTool('read-count', { description: 'Number of resources/read calls that reached this server' }, async () => ({
+        content: [{ type: 'text', text: String(readCount) }]
+    }));
+
+    // Exposes the server-side `tools/list` invocation count.
+    server.registerTool('request-count', { description: 'Number of tools/list requests that reached this server' }, async () => ({
+        content: [{ type: 'text', text: String(listCount) }]
+    }));
+
+    // Wrap the auto-generated `tools/list` handler so the example can prove a
+    // cache-served `listTools()` never reached the wire. `McpServer` registers
+    // the handler lazily on the first `registerTool()`; we re-seat it here so
+    // every dispatch increments `listCount` before delegating to the original.
+    // (Reaches the underlying request-handler map directly — there is no public
+    // wrapper hook; acceptable for an instrumentation example.)
+    const handlers = (server.server as unknown as { _requestHandlers: Map<string, (...a: unknown[]) => Promise<unknown>> })
+        ._requestHandlers;
+    const original = handlers.get('tools/list');
+    if (original) {
+        handlers.set('tools/list', (...a) => {
+            listCount++;
+            return original(...a);
+        });
+    }
+
     return server;
 }