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

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.

Author: Tarek Mahmoud Sayed

src/ModelContextProtocol.Core/McpJsonUtilities.cs

@@ -151,6 +151,7 @@ internal static bool IsValidMcpToolSchema(JsonElement element)
     [JsonSerializable(typeof(PingResult))]
     [JsonSerializable(typeof(ReadResourceRequestParams))]
     [JsonSerializable(typeof(ReadResourceResult))]
+    [JsonSerializable(typeof(CacheScope))]
     [JsonSerializable(typeof(SetLevelRequestParams))]
     [JsonSerializable(typeof(SubscribeRequestParams))]
     [JsonSerializable(typeof(UnsubscribeRequestParams))]

src/ModelContextProtocol.Core/Protocol/CacheScope.cs

@@ -0,0 +1,44 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Indicates the intended scope of a cached response, analogous to the HTTP
+/// <c>Cache-Control: public</c> and <c>Cache-Control: private</c> directives.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This is used by <see cref="ICacheableResult.CacheScope"/> to control who may cache a
+/// response returned by <c>tools/list</c>, <c>prompts/list</c>, <c>resources/list</c>,
+/// <c>resources/templates/list</c>, and <c>resources/read</c>.
+/// </para>
+/// <para>
+/// When the field is absent from a response, clients should treat it as <see cref="Public"/>.
+/// </para>
+/// </remarks>
+[JsonConverter(typeof(JsonStringEnumConverter<CacheScope>))]
+public enum CacheScope
+{
+    /// <summary>
+    /// The response does not contain user-specific data. Any client, shared gateway, or caching
+    /// proxy may store and serve the cached response to any user.
+    /// </summary>
+    /// <remarks>
+    /// This is appropriate for lists of tools, prompts, and resource templates that are identical
+    /// for all users.
+    /// </remarks>
+    [JsonStringEnumMemberName("public")]
+    Public,
+
+    /// <summary>
+    /// The response contains user-specific data. Only the requesting user's client may cache it.
+    /// Shared caches (for example, multi-tenant gateways) must not serve the cached response to a
+    /// different user.
+    /// </summary>
+    /// <remarks>
+    /// This is appropriate for <c>resources/read</c> results that depend on the authenticated user,
+    /// or for filtered list results that vary per user.
+    /// </remarks>
+    [JsonStringEnumMemberName("private")]
+    Private
+}

src/ModelContextProtocol.Core/Protocol/CacheScopeConverter.cs

@@ -0,0 +1,63 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Serializes <see cref="CacheScope"/> caching-scope hints, tolerating unknown or future values on read.
+/// </summary>
+/// <remarks>
+/// <para>
+/// SEP-2549 introduces <c>cacheScope</c> as a forward-looking caching hint. If a server sends an
+/// unrecognized scope string (for example, a value added in a later revision of the specification) or a
+/// non-string token, this converter maps it to <see langword="null"/> rather than throwing. This prevents
+/// a single unexpected hint from breaking deserialization of the entire result (for example, the whole
+/// tool list). A <see langword="null"/> result is the same as an absent field, which clients treat as
+/// <see cref="CacheScope.Public"/>.
+/// </para>
+/// <para>
+/// This converter is applied per-property on the cacheable result types. The <see cref="CacheScope"/>
+/// enum itself retains a standard string converter for any standalone serialization.
+/// </para>
+/// </remarks>
+internal sealed class CacheScopeConverter : JsonConverter<CacheScope?>
+{
+    public override CacheScope? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        if (reader.TokenType is JsonTokenType.String)
+        {
+            string? value = reader.GetString();
+
+            // Match case-insensitively so a non-conforming casing of "private" (a security-relevant hint)
+            // is honored rather than falling through to null, which clients would treat as "public" and
+            // could cache user-specific data in a shared cache. Genuinely unknown values still map to null.
+            if (string.Equals(value, "public", StringComparison.OrdinalIgnoreCase))
+            {
+                return CacheScope.Public;
+            }
+
+            if (string.Equals(value, "private", StringComparison.OrdinalIgnoreCase))
+            {
+                return CacheScope.Private;
+            }
+        }
+
+        return null;
+    }
+
+    public override void Write(Utf8JsonWriter writer, CacheScope? value, JsonSerializerOptions options)
+    {
+        if (value is null)
+        {
+            writer.WriteNullValue();
+            return;
+        }
+
+        writer.WriteStringValue(value switch
+        {
+            CacheScope.Public => "public",
+            CacheScope.Private => "private",
+            _ => throw new JsonException($"Unsupported {nameof(CacheScope)} value: {value}."),
+        });
+    }
+}

src/ModelContextProtocol.Core/Protocol/ICacheableResult.cs

@@ -0,0 +1,58 @@
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents a result that carries time-to-live (TTL) caching hints, allowing clients to cache
+/// the response for a period of time before re-fetching.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This interface corresponds to the <c>CacheableResult</c> type in the Model Context Protocol
+/// schema and is implemented by the results of <c>tools/list</c>, <c>prompts/list</c>,
+/// <c>resources/list</c>, <c>resources/templates/list</c>, and <c>resources/read</c>.
+/// </para>
+/// <para>
+/// The TTL is a freshness hint, not a guarantee. It supplements rather than replaces the existing
+/// <c>list_changed</c> and <c>resources/updated</c> notification mechanisms; both can coexist. A
+/// relevant notification invalidates a cached response regardless of any remaining TTL.
+/// </para>
+/// </remarks>
+public interface ICacheableResult
+{
+    /// <summary>
+    /// Gets or sets a hint indicating how long the client may cache this response before re-fetching.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The semantics are analogous to the HTTP <c>Cache-Control: max-age</c> directive. The value is
+    /// serialized as an integer number of milliseconds under the <c>ttlMs</c> JSON property.
+    /// </para>
+    /// <para>
+    /// A value of <see cref="TimeSpan.Zero"/> indicates the response should be considered immediately
+    /// stale; a positive value indicates the client should consider the response fresh for that
+    /// duration from the time it was received.
+    /// </para>
+    /// <para>
+    /// 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"/>.
+    /// </para>
+    /// </remarks>
+    TimeSpan? TimeToLive { get; set; }
+
+    /// <summary>
+    /// Gets or sets the intended scope of the cached response.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When this property is <see langword="null"/> (the field was absent from the response), clients
+    /// should treat the response as <see cref="Protocol.CacheScope.Public"/>.
+    /// </para>
+    /// <para>
+    /// An unrecognized or future scope value sent by a server (or a non-string value) is tolerated and
+    /// surfaced as <see langword="null"/> rather than causing deserialization of the whole result to
+    /// fail, so a single unexpected hint never prevents a client from reading the result.
+    /// </para>
+    /// </remarks>
+    CacheScope? CacheScope { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/ListPromptsResult.cs

@@ -18,11 +18,21 @@ namespace ModelContextProtocol.Protocol;
 /// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
 /// </para>
 /// </remarks>
-public sealed class ListPromptsResult : PaginatedResult
+public sealed class ListPromptsResult : PaginatedResult, ICacheableResult
 {
     /// <summary>
     /// Gets or sets a list of prompts or prompt templates that the server offers.
     /// </summary>
     [JsonPropertyName("prompts")]
     public IList<Prompt> Prompts { get; set; } = [];
+
+    /// <inheritdoc />
+    [JsonPropertyName("ttlMs")]
+    [JsonConverter(typeof(TimeSpanMillisecondsConverter))]
+    public TimeSpan? TimeToLive { get; set; }
+
+    /// <inheritdoc />
+    [JsonPropertyName("cacheScope")]
+    [JsonConverter(typeof(CacheScopeConverter))]
+    public CacheScope? CacheScope { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/ListResourceTemplatesResult.cs

@@ -20,7 +20,7 @@ namespace ModelContextProtocol.Protocol;
 /// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
 /// </para>
 /// </remarks>
-public sealed class ListResourceTemplatesResult : PaginatedResult
+public sealed class ListResourceTemplatesResult : PaginatedResult, ICacheableResult
 {
     /// <summary>
     /// Gets or sets a list of resource templates that the server offers.
@@ -32,4 +32,14 @@ public sealed class ListResourceTemplatesResult : PaginatedResult
     /// </remarks>
     [JsonPropertyName("resourceTemplates")]
     public IList<ResourceTemplate> ResourceTemplates { get; set; } = [];
+
+    /// <inheritdoc />
+    [JsonPropertyName("ttlMs")]
+    [JsonConverter(typeof(TimeSpanMillisecondsConverter))]
+    public TimeSpan? TimeToLive { get; set; }
+
+    /// <inheritdoc />
+    [JsonPropertyName("cacheScope")]
+    [JsonConverter(typeof(CacheScopeConverter))]
+    public CacheScope? CacheScope { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/ListResourcesResult.cs

@@ -18,11 +18,21 @@ namespace ModelContextProtocol.Protocol;
 /// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
 /// </para>
 /// </remarks>
-public sealed class ListResourcesResult : PaginatedResult
+public sealed class ListResourcesResult : PaginatedResult, ICacheableResult
 {
     /// <summary>
     /// Gets or sets a list of resources that the server offers.
     /// </summary>
     [JsonPropertyName("resources")]
     public IList<Resource> Resources { get; set; } = [];
+
+    /// <inheritdoc />
+    [JsonPropertyName("ttlMs")]
+    [JsonConverter(typeof(TimeSpanMillisecondsConverter))]
+    public TimeSpan? TimeToLive { get; set; }
+
+    /// <inheritdoc />
+    [JsonPropertyName("cacheScope")]
+    [JsonConverter(typeof(CacheScopeConverter))]
+    public CacheScope? CacheScope { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/ListToolsResult.cs

@@ -18,11 +18,21 @@ namespace ModelContextProtocol.Protocol;
 /// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
 /// </para>
 /// </remarks>
-public sealed class ListToolsResult : PaginatedResult
+public sealed class ListToolsResult : PaginatedResult, ICacheableResult
 {
     /// <summary>
     /// Gets or sets the server's response to a tools/list request from the client.
     /// </summary>
     [JsonPropertyName("tools")]
     public IList<Tool> Tools { get; set; } = [];
+
+    /// <inheritdoc />
+    [JsonPropertyName("ttlMs")]
+    [JsonConverter(typeof(TimeSpanMillisecondsConverter))]
+    public TimeSpan? TimeToLive { get; set; }
+
+    /// <inheritdoc />
+    [JsonPropertyName("cacheScope")]
+    [JsonConverter(typeof(CacheScopeConverter))]
+    public CacheScope? CacheScope { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/ReadResourceResult.cs

@@ -8,7 +8,7 @@ namespace ModelContextProtocol.Protocol;
 /// <remarks>
 /// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
 /// </remarks>
-public sealed class ReadResourceResult : Result
+public sealed class ReadResourceResult : Result, ICacheableResult
 {
     /// <summary>
     /// Gets or sets a list of <see cref="ResourceContents"/> objects that this resource contains.
@@ -20,4 +20,14 @@ public sealed class ReadResourceResult : Result
     /// </remarks>
     [JsonPropertyName("contents")]
     public IList<ResourceContents> Contents { get; set; } = [];
+
+    /// <inheritdoc />
+    [JsonPropertyName("ttlMs")]
+    [JsonConverter(typeof(TimeSpanMillisecondsConverter))]
+    public TimeSpan? TimeToLive { get; set; }
+
+    /// <inheritdoc />
+    [JsonPropertyName("cacheScope")]
+    [JsonConverter(typeof(CacheScopeConverter))]
+    public CacheScope? CacheScope { get; set; }
 }