Add SEP-2549 caching hints (ttlMs and cacheScope) to cacheable results

[tarekgh]

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, and resources/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_changed and resources/updated notifications. A relevant notification still invalidates a cached response regardless of any remaining TTL.

What changed

Protocol (ModelContextProtocol.Core):

• New ICacheableResult interface exposing TimeSpan? TimeToLive (wire name ttlMs) and CacheScope? CacheScope (wire name cacheScope).
• New CacheScope enum with lowercase wire values public and private.
• The five cacheable result types implement the interface.
• CacheScope is 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:

• ttlMs values that are out of range, fractional, or that overflow (including positive and negative infinity) are clamped to TimeSpan.MinValue or TimeSpan.MaxValue rather than throwing. The shared TimeSpanMillisecondsConverter reads with the non-throwing TryGetDouble and 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).
• cacheScope values that are unknown or added by a future revision are tolerated and surfaced as null (which clients treat as the public default) instead of failing the whole result. Matching is case-insensitive on read so a mis-cased private, a security-relevant hint, is honored rather than silently downgraded to public. Output is always the exact lowercase spec value.

Tests

• Serialization, round-trip, omission, negative, and clamping edge cases for ttlMs.
• Unknown, partial-presence, and case-insensitive handling for cacheScope.
• Per-page independence of caching hints for paginated results.
• 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 a Native AOT publish of the AOT compatibility test app with no trimming or AOT warnings.

[Copilot]

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 + CacheScope and implements ttlMs/cacheScope on the five cacheable result DTOs.
• Hardens TimeSpanMillisecondsConverter to 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.