Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/shared-cache-after-private-expiry.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@modelcontextprotocol/client': patch
---

Use a held public cache entry after a private entry expires, so shared-store clients can reuse its response and tool metadata without an unnecessary request. Fresh private entries still take precedence, and stale private metadata remains available when no public entry is held.
16 changes: 9 additions & 7 deletions packages/client/src/client/responseCache.ts
Original file line number Diff line number Diff line change
Expand Up @@ -377,8 +377,10 @@ export class ClientResponseCache {
}

/**
* Two-probe lookup: this client's own (private) partition first, then the
* connected server's shared (public) partition. The shared probe is gated
* Two-probe lookup: this client's fresh private entry first, then the
* connected server's shared (public) partition. A stale private entry is
* retained for derived metadata only when no public entry is held.
* The shared probe is gated
* on `entry.scope === 'public'` — a co-tenant client that omits
* `cachePartition` writes its `'private'`-scoped entries at the public
* partition, and serving those to a correctly-partitioned client would
Expand All @@ -391,11 +393,11 @@ export class ClientResponseCache {
const key = { method, params: params ?? '' };
const ownPartition = this._partitionFor('private');
const own = await this._store.get({ ...key, partition: ownPartition });
if (own !== undefined) return own;
if (own?.expiresAt !== undefined && own.expiresAt > this.now()) return own;
const sharedPartition = this._partitionFor('public');
if (sharedPartition === ownPartition) return undefined;
if (sharedPartition === ownPartition) return own;
const shared = await this._store.get({ ...key, partition: sharedPartition });
return shared?.scope === 'public' ? shared : undefined;
return shared?.scope === 'public' ? shared : own;
}

/**
Expand Down Expand Up @@ -553,8 +555,8 @@ export class ClientResponseCache {

/**
* Serve the fresh cached result for `{method, params}`, or `undefined`.
* Lookup is the two-probe order (own-partition then this server's shared
* partition, gated on `scope === 'public'`); freshness is
* Lookup prefers a fresh private entry, then this server's shared
* partition, gated on `scope === 'public'`; freshness is
* `entry.expiresAt > now()` (a missing `expiresAt` is never fresh),
* checked BEFORE decoding so stale entries cost no parse. Every hit is
* freshly parsed, so the caller owns the value outright. An entry whose
Expand Down
73 changes: 73 additions & 0 deletions packages/client/test/client/responseCache.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,39 @@ describe('InMemoryResponseCacheStore', () => {
});

describe('ClientResponseCache', () => {
it('keeps the single-partition lookup to one probe when its entry is stale', async () => {
const store = new InMemoryResponseCacheStore();
const get = store.get.bind(store);
let probes = 0;
store.get = key => {
probes++;
return get(key);
};
const cache = new ClientResponseCache(store, true);
await cache.write('tools/list', { tools: [TOOL_A] }, cache.captureGeneration('tools/list'));
expect((await cache.toolDefinition('a'))?.name).toBe('a');
expect(probes).toBe(1);
});

it.each([undefined, 'private'] as const)('retains stale private metadata when the shared entry has scope %s', async sharedScope => {
const store = new InMemoryResponseCacheStore();
const cache = new ClientResponseCache(store, true, undefined, 'alice', () => 10);
cache.setServerIdentity('srv');
store.set(
{ method: 'tools/list', partition: part('alice', 'srv') },
{ value: JSON.stringify({ tools: [TOOL_A] }), expiresAt: 10, scope: 'private' }
);
if (sharedScope !== undefined) {
store.set(
{ method: 'tools/list', partition: part('', 'srv') },
{ value: JSON.stringify({ tools: [TOOL_B] }), expiresAt: 20, scope: sharedScope }
);
}
expect(await cache.read('tools/list')).toBeUndefined();
expect((await cache.toolDefinition('a'))?.name).toBe('a');
expect(await cache.outputValidator('a', tool => tool.name)).toBe('a');
});

it('write skips when the captured generation moved (list_changed-during-walk guard)', async () => {
const store = new InMemoryResponseCacheStore();
const cache = new ClientResponseCache(store, false);
Expand Down Expand Up @@ -842,6 +875,46 @@ describe('Client honours cacheHints (SEP-2549)', () => {
}
});

it('an expired private entry falls back to a fresh public entry and its tool metadata', async () => {
const store = new InMemoryResponseCacheStore();
const a = await scriptedModernServer([[TOOL_A]], { listHint: { ttlMs: 10, cacheScope: 'private' } });
const alice = modernClient(store, { cachePartition: 'alice' });
await alice.connect(a.clientTx);
setNow(alice, 1_000_000);
await alice.listTools();
expect((await toolDef(alice, 'a'))?.name).toBe('a');
const compile = (tool: Tool): string => tool.name;
expect(await cacheOf(alice).outputValidator('a', compile)).toBe('a');

const b = await scriptedModernServer([[TOOL_B]], { listHint: { ttlMs: 60_000, cacheScope: 'public' } });
const bob = modernClient(store, { cachePartition: 'bob' });
await bob.connect(b.clientTx);
setNow(bob, 1_000_005);
await bob.listTools();
expect(b.listCount()).toBe(1);

setNow(alice, 1_000_005);
expect((await alice.listTools()).tools.map(t => t.name)).toEqual(['a']);
expect((await toolDef(alice, 'a'))?.name).toBe('a');
expect(a.listCount()).toBe(1);

setNow(alice, 1_000_010);
expect((await alice.listTools()).tools.map(t => t.name)).toEqual(['b']);
expect(a.listCount()).toBe(1);
expect((await toolDef(alice, 'b'))?.name).toBe('b');
expect(await toolDef(alice, 'a')).toBeUndefined();
expect(await cacheOf(alice).outputValidator('b', compile)).toBe('b');
expect(await cacheOf(alice).outputValidator('a', compile)).toBeUndefined();
expect(store.get({ method: 'tools/list', partition: part('alice') })).toBeDefined();

setNow(alice, 1_100_000);
expect(await cacheOf(alice).read('tools/list')).toBeUndefined();
expect((await toolDef(alice, 'b'))?.name).toBe('b');
expect(await cacheOf(alice).outputValidator('b', compile)).toBe('b');
await alice.close();
await bob.close();
});

it("different serverIdentity on a shared store: no cross-talk even for 'public' entries", async () => {
const store = new InMemoryResponseCacheStore();
// Server X stamps public; client x writes under [x@1.0.0, ''].
Expand Down
Loading