Cacheable, stably-ordered tools/list (#108) - #124
Merged
Conversation
SEP-2549 adds ttlMs and cacheScope to the list-shaped results so a client can cache instead of poll. tools/list is the only one of the five we expose, and it is the one worth caching: 29 tool descriptors is a lot of prompt to re-send. Both values are safe here because the registry is built once at start-up and cannot change without a restart - which is exactly what the listChanged:false we already advertise says. An hour, and "private" (see CacheableResult from #105 for why: single user by construction, and the one case where an intermediary could cache at all is the tunnelled HTTP transport, where you would not want it to). Sent only to a client on the revision that defines them, like resultType: an older client implements no caching, so it gains nothing from the fields and might validate strictly against a schema without them. Ordering was already right - the registry walks its registration order - but untested and undocumented, so the SHOULD held by accident. Now there is a regression guard on the real registry: if a tool moves, a test says so, because every clients cached copy and prompt cache turns over when it does. 6 tests.
12 tasks
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
1 participant
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.
Closes #108.
SEP-2549 adds
ttlMsandcacheScopeto the list-shaped results so a client can cache instead of poll.tools/listis the only one of the five we expose, and the one worth caching — 29 tool descriptors is a lot of prompt to re-send.Change
tools/listreturnsttlMs(one hour) andcacheScope: "private", reusing theCacheableResulthelper from MCP 2026-07-28: implement the requiredserver/discoverRPC #105.resultType: an older client implements no caching, gains nothing from the fields, and might validate strictly against a schema without them.listChanged: falsewe already advertise says. A test asserts those two statements agree, so if tools ever become dynamic both have to change together.Ordering
Already correct — the registry walks its registration order — but untested and undocumented, so the SHOULD held by accident. Now pinned: one test on a synthetic registry proves the order is registration order and not sorted, another pins the real server's list. If a tool is added or moved, a test says so and whoever moved it has to mean it: every client's cached copy and every prompt cache turns over when it does.
Verification
_meta; two calls byte-identical; registration order preserved; the real registry's order pinned with no duplicate names; cache hints consistent withlistChanged: false.README: "Protocol revisions" covers the caching and the ordering guarantee.