Add SEP-2549 caching hints (ttlMs and cacheScope) to cacheable results#1623
Add SEP-2549 caching hints (ttlMs and cacheScope) to cacheable results#1623tarekgh wants to merge 3 commits into
Conversation
Implements SEP-2549 "TTL for List Results", which lets servers attach optional caching freshness hints to the five cacheable result types: tools/list, prompts/list, resources/list, resources/templates/list, and resources/read. Protocol changes: - Add ICacheableResult with TimeToLive (serialized as integer-millisecond ttlMs) and CacheScope (serialized as cacheScope). - Add the CacheScope enum (public, private) with lowercase wire values. - Implement the interface on the five cacheable result types. - Register CacheScope for source-generated serialization. Both fields are optional and omitted when unset, so the change is fully backward compatible and requires no capability negotiation. The SDK propagates the values without consuming them. Robustness and security: - ttlMs deserialization clamps out-of-range, fractional, and overflowing values (including positive and negative infinity) to TimeSpan.MinValue or MaxValue instead of throwing, so a malformed or hostile hint cannot break reading of the enclosing result. The shared TimeSpanMillisecondsConverter uses the non-throwing TryGetDouble and clamps by token sign, giving identical behavior on .NET and on .NET Framework (whose number parser reports failure on overflow rather than returning infinity). - cacheScope deserialization tolerates unknown or future values by mapping them to null (treated as the public default) instead of failing the whole result, and matches the known values case-insensitively so a mis-cased "private" is honored rather than silently downgraded to public. Tests: - Serialization, round-trip, omission, and clamping edge cases for ttlMs. - Unknown, partial, and case-insensitive cacheScope handling. - Per-page independence of caching hints for pagination. - End-to-end propagation of hints from server to client. - Regression coverage for the shared converter used by McpTask ttl and pollInterval. - Caching conformance scenario wiring, gated to the conformance build that provides it. Verified across net8.0, net9.0, net10.0, and net472, and under Native AOT publish with no trimming or AOT warnings.
There was a problem hiding this comment.
Pull request overview
Adds SEP-2549 caching hints to the C# MCP SDK protocol DTOs so servers can attach optional TTL (ttlMs) and cache scoping (cacheScope) metadata to cacheable results, with hardened deserialization and conformance wiring to validate behavior end-to-end.
Changes:
- Introduces
ICacheableResult+CacheScopeand implementsttlMs/cacheScopeon the five cacheable result DTOs. - Hardens
TimeSpanMillisecondsConverterto clamp out-of-range millisecond values instead of throwing, and adds broad regression/edge-case tests. - Extends the conformance server/tests infrastructure to support draft stateless lifecycle runs and a gated caching conformance scenario.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/ModelContextProtocol.Tests/Protocol/TimeSpanMillisecondsConverterSharedTests.cs | Regression tests ensuring hardened millisecond TimeSpan parsing still preserves existing McpTask behavior. |
| tests/ModelContextProtocol.Tests/Protocol/CacheableResultTests.cs | Unit tests covering serialization/omission/round-trip and hostile-input handling for ttlMs + cacheScope. |
| tests/ModelContextProtocol.Tests/Protocol/CacheableResultClientServerTests.cs | End-to-end client/server propagation tests for caching hints. |
| tests/ModelContextProtocol.ConformanceServer/Program.cs | Adds stateless server mode switch and applies caching hints via filters for conformance scenarios. |
| tests/ModelContextProtocol.AspNetCore.Tests/ServerConformanceTests.cs | Refactors server conformance runner invocation and adds stateless server usage for draft SEP-2243 scenarios. |
| tests/ModelContextProtocol.AspNetCore.Tests/ClientConformanceTests.cs | Updates skip messaging for SEP-2243 scenario availability. |
| tests/ModelContextProtocol.AspNetCore.Tests/CachingConformanceTests.cs | New gated conformance test + stateless server helper for the draft caching scenario. |
| tests/Common/Utils/NodeHelpers.cs | Enhances conformance runner plumbing and gates scenarios based on installed conformance package version. |
| src/ModelContextProtocol.Core/Protocol/TimeSpanMillisecondsConverter.cs | Clamps oversized/fractional millisecond inputs during deserialization to avoid throwing on hostile values. |
| src/ModelContextProtocol.Core/Protocol/ReadResourceResult.cs | Adds ttlMs/cacheScope properties and implements ICacheableResult. |
| src/ModelContextProtocol.Core/Protocol/ListToolsResult.cs | Adds ttlMs/cacheScope properties and implements ICacheableResult. |
| src/ModelContextProtocol.Core/Protocol/ListResourceTemplatesResult.cs | Adds ttlMs/cacheScope properties and implements ICacheableResult. |
| src/ModelContextProtocol.Core/Protocol/ListResourcesResult.cs | Adds ttlMs/cacheScope properties and implements ICacheableResult. |
| src/ModelContextProtocol.Core/Protocol/ListPromptsResult.cs | Adds ttlMs/cacheScope properties and implements ICacheableResult. |
| src/ModelContextProtocol.Core/Protocol/ICacheableResult.cs | New interface defining the cache hint surface area for cacheable results. |
| src/ModelContextProtocol.Core/Protocol/CacheScopeConverter.cs | New tolerant converter intended to map unknown cacheScope values to null. |
| src/ModelContextProtocol.Core/Protocol/CacheScope.cs | New enum for cache scoping with lowercase wire names. |
| src/ModelContextProtocol.Core/McpJsonUtilities.cs | Registers CacheScope for source-generated serialization. |
- CacheScopeConverter.Read now consumes non-string tokens with reader.Skip() before returning null. Previously an object or array value for cacheScope left the reader mispositioned and threw "read too much or not enough", breaking deserialization of the whole result. Added object and array cases to the tolerant-deserialization test. - GetInstalledConformanceVersion no longer calls EnsureNpmDependenciesInstalled. The version check backs Theory skip gates and must be side-effect-free; it now returns null when the conformance package is absent. The actual scenario run path still restores npm dependencies via ConformanceTestStartInfo.
halter73
left a comment
halter73
left a comment
There was a problem hiding this comment.
It might be nice to add some samples or conceptual docs showing how to configure ttlMs and cacheScope on the server and then consume it on the client.
docs/concepts/filters.md already has a caching example (server-side IMemoryCache). Adding a "Client-side caching hints (SEP-2549)" snippet that mirrors this filter pattern might be nice.
| /// <inheritdoc /> | ||
| [JsonPropertyName("ttlMs")] | ||
| [JsonConverter(typeof(TimeSpanMillisecondsConverter))] | ||
| public TimeSpan? TimeToLive { get; set; } |
There was a problem hiding this comment.
This and cacheScope are now required fields with the new protocol version. I assume we want to send defaults if this is unspecified with the draft protocol version selected. I imagine this would be ttlMs: 0 and cacheScope: "private" (immediately stale, not shareable), which preserves today's "don't cache" behavior.
Can we add the logic to send this instead of omitting the fields when they aren't customized? We currently use DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull for MCP DTOs in McpJsonUtilities, but that violates the spec.
And should we do something on the client if a server claiming to support the new protocol omits these fields? Maybe log a warning rather than throw to avoid breaking people unnecessarily when talking to non-conformant servers.
| /// </para> | ||
| /// </remarks> | ||
| public sealed class ListToolsResult : PaginatedResult | ||
| public sealed class ListToolsResult : PaginatedResult, ICacheableResult |
There was a problem hiding this comment.
The new TimeToLive/CacheScope properties are only reachable through the raw ListToolsAsync(ListToolsRequestParams, CancellationToken) overload. The auto-paginating ListToolsAsync(RequestOptions?, CancellationToken) overload (which is probably what most consumers reach for) returns IList<McpClientTool> and drops the per-page hints entirely. Same story for ListPromptsAsync, ListResourcesAsync, and ListResourceTemplatesAsync. ReadResourceAsync is fine since it isn't paginated.
Do we need any follow up issues for this? I can think of a couple things we might want to do. One would be to expose the TimeToLive/CacheScope to the auto-paginating overload. The second might be to take advantage of the caching opportunities in the client when given a non-zero ttol
In the meantime, adding a small <remarks> note on the convenience overloads pointing at the raw one probably makes sense.
| /// When this property is <see langword="null"/> (the field was absent from the response), clients | ||
| /// should assume a default of <see cref="TimeSpan.Zero"/> (immediately stale) and rely on their | ||
| /// own caching heuristics or notifications. A negative value should likewise be treated as | ||
| /// <see cref="TimeSpan.Zero"/>. |
There was a problem hiding this comment.
| /// <see cref="TimeSpan.Zero"/>. | |
| /// <see cref="TimeSpan.Zero"/>. The SDK preserves whatever value the server sent. |
Summary
Implements SEP-2549 "TTL for List Results".
The SEP lets a server attach optional caching hints to the responses that are expensive to recompute and are commonly re-fetched, so a client can keep using a recent response for a bounded period instead of requesting it again. Two hints are added to the five cacheable result types (
tools/list,prompts/list,resources/list,resources/templates/list, andresources/read):ttlMs: how long, in milliseconds, the client may treat the response as fresh.cacheScope: whether the response may be stored by shared caches (public) or only by the requesting user's own client (private).These hints supplement, and do not replace, the existing
list_changedandresources/updatednotifications. A relevant notification still invalidates a cached response regardless of any remaining TTL.What changed
Protocol (
ModelContextProtocol.Core):ICacheableResultinterface exposingTimeSpan? TimeToLive(wire namettlMs) andCacheScope? CacheScope(wire namecacheScope).CacheScopeenum with lowercase wire valuespublicandprivate.CacheScopeis registered for source-generated serialization.Both properties are optional and are omitted from the payload when unset, so the change is backward compatible and needs no capability negotiation. The SDK propagates the values end to end; it does not itself consume them to make caching decisions.
Reliability and security
The hints can come from any server, so deserialization is hardened to never let a malformed or hostile value break reading of the enclosing result:
ttlMsvalues that are out of range, fractional, or that overflow (including positive and negative infinity) are clamped toTimeSpan.MinValueorTimeSpan.MaxValuerather than throwing. The sharedTimeSpanMillisecondsConverterreads with the non-throwingTryGetDoubleand clamps by the sign of the raw token, so behavior is identical on modern .NET (where an out-of-range number parses to infinity) and on .NET Framework (where the parser reports failure on overflow).cacheScopevalues that are unknown or added by a future revision are tolerated and surfaced asnull(which clients treat as thepublicdefault) instead of failing the whole result. Matching is case-insensitive on read so a mis-casedprivate, a security-relevant hint, is honored rather than silently downgraded to public. Output is always the exact lowercase spec value.Tests
ttlMs.cacheScope.McpTaskttlandpollInterval.Verified across
net8.0,net9.0,net10.0, andnet472, and under a Native AOT publish of the AOT compatibility test app with no trimming or AOT warnings.