Add ttlMs and cacheScope to cacheable result records (SEP-2549) - #1062
Open
aboullaite wants to merge 4 commits into
Open
Add ttlMs and cacheScope to cacheable result records (SEP-2549)#1062aboullaite wants to merge 4 commits into
aboullaite wants to merge 4 commits into
Conversation
Copy link
Copy Markdown
Sorry, something went wrong.
The draft spec introduces TTL caching hints on list and read results. This adds the optional ttlMs (Integer) and cacheScope (CacheScope enum) fields to ListToolsResult, ListPromptsResult, ListResourcesResult, ListResourceTemplatesResult, and ReadResourceResult, following the wire-record evolution rules in CONTRIBUTING.md. Purely additive, schema-layer only: no server or client behavior changes. Server-side TTL configuration hooks are deferred to modelcontextprotocol#578.
The draft spec requires cacheable results to carry ttlMs and cacheScope on the wire. Other SDKs (Go, Python, TypeScript) all stamp defaults after handlers return: ttlMs=0 (immediately stale) and cacheScope=public. This adds the same default stamping in McpAsyncServer and McpStatelessAsyncServer for all five cacheable result types. For list results the defaults are set at the build site. For ReadResourceResult, which is built by user handlers, a withCacheDefaults helper stamps missing fields while preserving any values the handler set explicitly.
Two fixes from review: 1. Widen ttlMs from Integer to Long across all five cacheable result records. The spec defines ttlMs as a non-negative integer with no upper bound, and Jackson rejects values exceeding Integer.MAX_VALUE. Long handles any realistic TTL without interop failures. 2. Default cacheScope to PRIVATE (not PUBLIC) for resources/read in both server classes. The spec's caching guidance says resources/read results that depend on the authenticated user should be private. List results keep the PUBLIC default since they are not user-specific.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add ttlMs and cacheScope to cacheable result records (SEP-2549)
Motivation and Context
SEP-2549 introduces TTL caching hints so clients and intermediaries (gateways, proxies) can cache list and read results without re-fetching on every request. The draft spec adds two fields to cacheable result types:
This PR adds the schema fields and server-side default stamping. The server now emits ttlMs=0 (immediately stale) and cacheScope="public" on all cacheable responses. Server-side configuration hooks for user-defined TTLs are intentionally left out following @Kehrlann's note that those belong with the repositories refactor in #578 (and the related #1034).
Towards #1009
How Has This Been Tested?
UT + IT
Breaking Changes
None. Both fields are optional (nullable), existing constructors are preserved as @Deprecated overloads.
Types of changes
Checklist
Additional context
Remaining work for full #1009 coverage (follow-up PRs):