Stamp a real freshness hint on cacheable results (#523)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: alistair3149

CHANGELOG.md

@@ -20,6 +20,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ### Changed
 
+- Cacheable results (tool and resource lists, wiki resource reads, discovery) now carry a 60-second freshness hint instead of `ttlMs: 0`, so clients on the 2026-07-28 revision can cache them between polls. Change notifications are unaffected.
 - The hosted OAuth sign-in's approval page is shorter and now names the address you will be returned to, including for a local application, where it previously said only "an application on this device". It no longer promises a permissions step the wiki does not always show.
 - The HTTP transport's own `401`, `503` and `413` replies carry new JSON-RPC error codes. Clients read the HTTP status for these conditions, so no change is expected; anything matching on the old codes `-32001` and `-32000` needs updating.
 

src/server.ts

@@ -39,6 +39,14 @@ export interface CreateServerOptions {
 	publisher?: ChangePublisher;
 }
 
+// Everything cacheable here changes only when a reconcile pass runs (a wiki is
+// added or removed, or an extension probe flips), and subscribed clients learn
+// of that through listChanged events — the TTL only bounds staleness for
+// clients that poll instead. Private scope: tool and resource lists reflect
+// this deployment's wiki configuration, so a shared cache must not serve one
+// deployment's lists to another behind the same intermediary.
+const CACHE_HINT = { ttlMs: 60_000, cacheScope: 'private' } as const;
+
 export const createServer = async (
 	ctx: ToolContext,
 	reqCtx?: Pick<McpRequestContext, 'era'>,
@@ -62,6 +70,13 @@ export const createServer = async (
 				logging: {},
 			},
 			instructions: SERVER_INSTRUCTIONS,
+			cacheHints: {
+				'tools/list': CACHE_HINT,
+				'resources/list': CACHE_HINT,
+				'resources/templates/list': CACHE_HINT,
+				'resources/read': CACHE_HINT,
+				'server/discover': CACHE_HINT,
+			},
 		},
 	);
 

tests/transport/modernEra.test.ts

@@ -85,6 +85,33 @@ describe('2026-07-28 era over Streamable HTTP (in-memory)', () => {
 		expect(result.isError ?? false).toBe(false);
 	});
 
+	it('stamps the configured cache hints on cacheable modern-era results', async () => {
+		const { handler } = buildHandler();
+		cleanups.push(() => handler.close());
+
+		const client = new Client(
+			{ name: 'cache-hint-test', version: '0.0.0' },
+			{ versionNegotiation: { mode: { pin: '2026-07-28' } } },
+		);
+		cleanups.push(() => client.close());
+		await client.connect(clientTransport(handler));
+
+		const tools = await client.listTools();
+		expect(tools.ttlMs).toBe(60_000);
+		expect(tools.cacheScope).toBe('private');
+
+		const resources = await client.listResources();
+		expect(resources.ttlMs).toBe(60_000);
+		expect(resources.cacheScope).toBe('private');
+
+		// resources/read is the one operation with a competing precedence path
+		// (a per-registration cacheHint would override field by field), so pin
+		// that the per-operation hint reaches an actual read result.
+		const read = await client.readResource({ uri: 'mcp://wikis/test-wiki' });
+		expect(read.ttlMs).toBe(60_000);
+		expect(read.cacheScope).toBe('private');
+	});
+
 	it('falls back to a legacy handshake through the same handler when negotiation is off', async () => {
 		const { handler } = buildHandler();
 		cleanups.push(() => handler.close());
@@ -95,6 +122,10 @@ describe('2026-07-28 era over Streamable HTTP (in-memory)', () => {
 
 		const tools = await client.listTools();
 		expect(tools.tools.length).toBeGreaterThan(0);
+		// Cache hints are a 2026-07-28 wire feature; a legacy-era response must
+		// not carry them.
+		expect(tools.ttlMs).toBeUndefined();
+		expect(tools.cacheScope).toBeUndefined();
 	});
 
 	it('delivers toolsChanged to a modern listen subscriber when a management tool reconciles', async () => {