feat(mcp): add ttlMs + cacheScope to ReadResource contents (SEP-2549)

[JayDS22]

Summary

Annotate every ReadResource response with the per-entry caching hints proposed in SEP-2549 ("CacheableResult") so the wire shape matches the MCP 2026-07-28 RC ahead of SDK support:

https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate

Per-resource defaults are picked by mutability:

URI	ttlMs	cacheScope	Reason
apap://templates	60_000	private	list, per-client view
apap://templates/{id}	300_000	public	hash-immutable single row
apap://agreements	30_000	private	list, mutates on trigger
apap://agreements/{id}	30_000	private	single agreement, mutable
apap://schema/protocol.cto	86_400_000	public	bundled .cto, ships with build (entry for when the schema resource lands; cf. #185)

The fields are emitted alongside uri/mimeType/text. The SDK's ReadResourceResult type does not yet declare them, but the SDK's response path is pass-through (no schema-strip), so caching proxies see them today as forward-compatible hints. Once SEP-2549 lands in the SDK the spread becomes a plain field assignment with no behavioural change.

Mirrors the POC change at JayDS22/apap-mcp-poc#4.

Test plan

• npm test -- --testPathPattern='mcp\\.test' (7/7 pass)
• npm test full suite (71/71 pass)
• npx tsc --noEmit -p . clean
• Manual: hit POST /mcp with resources/read for apap://agreements, confirm ttlMs/cacheScope present in JSON-RPC response

Notes

• The new server/handlers/mcp.test.ts is the first jest file for mcp.ts; it pins the cache defaults so future edits cannot silently change a per-resource TTL or scope.
• No DB schema change. No public REST API change. Only the MCP resources/read payload gains two optional fields.

[JayDS22]

Moving to draft pending audit follow-ups: replacing the as unknown as Array<...> per-callsite cast with one module-augmentation declare module '@modelcontextprotocol/sdk/types.js' { interface TextResourceContents { ttlMs?: number; cacheScope?: 'public' | 'private' } }, dropping the dead CACHE_HINTS.schema key until #199 lands (or rebasing this branch on top of #199), and broadening the integration test coverage past just apap://agreements. Will re-mark ready once those land.

[niallroche]

The CACHE_HINTS design and TTL values look well-reasoned, and the pass-through behaviour of the current SDK makes this forward-compatible. Two things needed before this can land:

parse-endpoint.js and parse.js in the repo root look like debugging scripts from exploring the OpenAPI spec. Please remove them from this branch — they shouldn't be committed.
This creates server/handlers/mcp.test.ts, which will conflict with #196, #200, and #199 (all creating the same file). The intended merge order is #196 → #200 → #199 → #201. After #196 merges, @JayDS22 please rebase this branch and append the SEP-2549 test block to the existing file rather than creating a new one.

[JayDS22]

Pushed b7e6c8f addressing the two audit items, @niallroche:

1. Module augmentation in place of per-callsite casts. Added server/types/mcp-augmentation.d.ts that declares ttlMs?: number and cacheScope?: 'public' | 'private' on both TextResourceContents and BlobResourceContents. The spread sites in mcp.ts stay clean and the SEP-2549 fields are documented as intentional forward-compatible extensions rather than relying on the type-checker not noticing.
2. Dropped the dead schema key from CACHE_HINTS. apap://schema/protocol.cto only exists on jay/feat/mcp-concerto-context (PR feat(mcp): Concerto typed-context hint + protocol.cto schema resource #199), not on main, so the entry was unreachable. Test that pinned it is retired too. A TODO comment in mcp.ts records that the key gets re-added ({ ttlMs: 86_400_000, cacheScope: 'public' }) in a one-line follow-up once feat(mcp): Concerto typed-context hint + protocol.cto schema resource #199 merges and the schema resource lands here.

No wire-format change for the four resource URIs already covered; ttlMs and cacheScope still land on every contents[] entry.

Verification: npm test 70/70 pass, mcp.test alone 6/6, npx tsc --noEmit -p . clean.

Marked ready for review.

[niallroche]

Some suggestions:

1. remove the TODO after [feat(mcp): Concerto typed-context hint + protocol.cto schema resource #199]is merged.

2. this test doesn't assert anything meaningful:
   it('exports the same CACHE_HINTS reference for both list and item resources', () => {
   expect(CACHE_HINTS.agreementList.ttlMs).toBe(CACHE_HINTS.agreementItem.ttlMs);
   expect(CACHE_HINTS.agreementList).not.toBe(CACHE_HINTS.agreementItem); // trivially true
   });
   The second assertion — that agreementList and agreementItem are different object references — is always true for distinct keys on any object. It's not testing anything. Should either be removed or replaced with something that actually catches a regression (e.g. asserting both have cacheScope: 'private').

3. there is an edge case for templateItem: { ttlMs: 300_000, cacheScope: 'public' } when the template will serve the old version

[niallroche]

good to go

[github-actions]

🎉 Thank you for your contribution! 🎉

Dear @JayDS22,

Your pull request has been successfully merged into the project! We greatly appreciate your efforts and the time you've dedicated to improving our repository.

What happens next?

• Your changes will be included in the next release
• Your name will be added to our contributors list
• Feel free to take on another issue or suggest new features

Once again, thank you for being part of our community!

Best regards,
The APAP Team