Add ttlMs and cacheScope to DiscoverResult per spec PR #2855

SEP-2549 (PR #1623 cherry-picked in 51571c6) added the ICacheableResult
contract with 	tlMs and cacheScope to the five list/read results, but the
spec was subsequently amended by spec PR #2855 to also require both fields on
server/discover responses. Implement that on DiscoverResult and emit safe
defaults from the built-in handler so existing servers keep their "do not
cache" behavior while remaining wire-compliant under draft.

Changes:

- `DiscoverResult` now implements `ICacheableResult` and carries
  `TimeToLive`/`CacheScope` properties with the same wire shape as the
  list/read results.
- `ICacheableResult` xmldoc updated to mention `server/discover` alongside
  the existing list/read implementers.
- `McpServerImpl.ConfigureDiscover` emits `ttlMs: 0` +
  `cacheScope: "private"` (immediately stale, not shareable) on the built-in
  handler. The values match halter73's design call on PR #1623: the safest
  defaults preserve today's behavior without requiring server authors to
  opt-in to caching, while still satisfying the wire requirement under draft.
- `RawHttpConformanceTests.ServerDiscover_RawPost_ReturnsDiscoverResult` and
  `RawStreamConformanceTests.ServerDiscover_ReturnsSupportedVersionsIncludingDraft`
  now assert the fields are emitted with the expected values.
- New `DiscoverResultCacheableTests` exercises the round-trip on
  `DiscoverResult` (the existing parameterized `CacheableResultTests` cannot
  cover it because `DiscoverResult` has required CLR properties that block
  reflection-based `Activator.CreateInstance`).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: halter73

src/ModelContextProtocol.Core/Protocol/DiscoverResult.cs

@@ -11,7 +11,7 @@ namespace ModelContextProtocol.Protocol;
 /// to learn what a server supports without performing the legacy <c>initialize</c> handshake.
 /// </para>
 /// </remarks>
-public sealed class DiscoverResult : Result
+public sealed class DiscoverResult : Result, ICacheableResult
 {
     /// <summary>
     /// Gets or sets the list of MCP protocol version strings that the server supports.
@@ -43,4 +43,25 @@ public sealed class DiscoverResult : Result
     /// </remarks>
     [JsonPropertyName("instructions")]
     public string? Instructions { get; set; }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// Spec PR #2855 makes <c>ttlMs</c> a required field on <see cref="DiscoverResult"/>. The
+    /// server emits a safe default (<see cref="TimeSpan.Zero"/>, i.e. immediately stale) on
+    /// draft sessions when the application has not set an explicit value, preserving today's
+    /// "do not cache" behavior while satisfying the wire requirement.
+    /// </remarks>
+    [JsonPropertyName("ttlMs")]
+    [JsonConverter(typeof(TimeSpanMillisecondsConverter))]
+    public TimeSpan? TimeToLive { get; set; }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// Spec PR #2855 makes <c>cacheScope</c> a required field on <see cref="DiscoverResult"/>. The
+    /// server emits a safe default (<see cref="Protocol.CacheScope.Private"/>) on draft sessions
+    /// when the application has not set an explicit value.
+    /// </remarks>
+    [JsonPropertyName("cacheScope")]
+    [JsonConverter(typeof(CacheScopeConverter))]
+    public CacheScope? CacheScope { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/ICacheableResult.cs

@@ -7,8 +7,9 @@ namespace ModelContextProtocol.Protocol;
 /// <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>.
+/// schema and is implemented by the results of <c>server/discover</c>, <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

src/ModelContextProtocol.Core/Server/McpServerImpl.cs

@@ -444,6 +444,11 @@ private void ConfigureDiscover(McpServerOptions options)
                     Capabilities = ServerCapabilities ?? new(),
                     ServerInfo = options.ServerInfo ?? DefaultImplementation,
                     Instructions = options.ServerInstructions,
+                    // Spec PR #2855 makes ttlMs and cacheScope required on DiscoverResult. Default to
+                    // the safest values (immediately stale, not shareable) so existing servers keep
+                    // their "do not cache" behavior while satisfying the wire requirement.
+                    TimeToLive = TimeSpan.Zero,
+                    CacheScope = CacheScope.Private,
                 });
             },
             McpJsonUtilities.JsonContext.Default.DiscoverRequestParams,

tests/ModelContextProtocol.AspNetCore.Tests/RawHttpConformanceTests.cs

@@ -6,6 +6,7 @@
 using ModelContextProtocol.Tests.Utils;
 using System.Net;
 using System.Text;
+using System.Text.Json;
 using System.Text.Json.Nodes;
 
 namespace ModelContextProtocol.AspNetCore.Tests;
@@ -126,6 +127,12 @@ public async Task ServerDiscover_RawPost_ReturnsDiscoverResult()
         var json = await ReadJsonResponseAsync(response, TestContext.Current.CancellationToken);
         var supported = json["result"]!["supportedVersions"]!.AsArray().Select(n => n!.GetValue<string>()).ToList();
         Assert.Contains(DraftVersion, supported);
+
+        // Spec PR #2855 makes ttlMs and cacheScope required on DiscoverResult; the server emits the
+        // safest defaults (immediately stale, not shareable) when the application hasn't customized.
+        Assert.Equal(JsonValueKind.Number, json["result"]!["ttlMs"]!.GetValueKind());
+        Assert.Equal(0, json["result"]!["ttlMs"]!.GetValue<long>());
+        Assert.Equal("private", json["result"]!["cacheScope"]!.GetValue<string>());
     }
 
     [Fact]

tests/ModelContextProtocol.Tests/Protocol/DiscoverResultCacheableTests.cs

@@ -0,0 +1,125 @@
+using ModelContextProtocol.Protocol;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace ModelContextProtocol.Tests.Protocol;
+
+/// <summary>
+/// Targeted tests for the SEP-2549 caching hints (<c>ttlMs</c> and <c>cacheScope</c>) on
+/// <see cref="DiscoverResult"/>. Spec PR #2855 promotes both fields to required on the discover
+/// response. <see cref="DiscoverResult"/> has <c>required</c> CLR properties for
+/// <see cref="DiscoverResult.SupportedVersions"/>, <see cref="DiscoverResult.Capabilities"/>, and
+/// <see cref="DiscoverResult.ServerInfo"/>, which prevents reuse of the parameterized
+/// <see cref="CacheableResultTests"/> helper (it instantiates via reflection). This file covers the
+/// same property-shape assertions for <see cref="DiscoverResult"/>.
+/// </summary>
+public static class DiscoverResultCacheableTests
+{
+    private static DiscoverResult NewDiscoverResult() => new()
+    {
+        SupportedVersions = ["2025-11-25", McpSession.DraftProtocolVersion],
+        Capabilities = new ServerCapabilities(),
+        ServerInfo = new Implementation { Name = "test-server", Version = "1.0" },
+    };
+
+    [Fact]
+    public static void DiscoverResult_SerializesTtlMsAsIntegerMilliseconds()
+    {
+        var result = NewDiscoverResult();
+        result.TimeToLive = TimeSpan.FromMilliseconds(300_000);
+        result.CacheScope = CacheScope.Public;
+
+        string json = JsonSerializer.Serialize(result, McpJsonUtilities.DefaultOptions);
+        var node = JsonNode.Parse(json)!.AsObject();
+
+        Assert.True(node.ContainsKey("ttlMs"));
+        Assert.Equal(JsonValueKind.Number, node["ttlMs"]!.GetValueKind());
+        Assert.Equal(300_000, node["ttlMs"]!.GetValue<long>());
+        Assert.Equal("public", node["cacheScope"]!.GetValue<string>());
+
+        var deserialized = JsonSerializer.Deserialize<DiscoverResult>(json, McpJsonUtilities.DefaultOptions)!;
+        Assert.Equal(TimeSpan.FromMilliseconds(300_000), deserialized.TimeToLive);
+        Assert.Equal(CacheScope.Public, deserialized.CacheScope);
+    }
+
+    [Fact]
+    public static void DiscoverResult_PrivateScope_RoundTrips()
+    {
+        var result = NewDiscoverResult();
+        result.TimeToLive = TimeSpan.Zero;
+        result.CacheScope = CacheScope.Private;
+
+        string json = JsonSerializer.Serialize(result, McpJsonUtilities.DefaultOptions);
+        var node = JsonNode.Parse(json)!.AsObject();
+
+        Assert.True(node.ContainsKey("ttlMs"));
+        Assert.Equal(0, node["ttlMs"]!.GetValue<long>());
+        Assert.Equal("private", node["cacheScope"]!.GetValue<string>());
+
+        var deserialized = JsonSerializer.Deserialize<DiscoverResult>(json, McpJsonUtilities.DefaultOptions)!;
+        Assert.Equal(TimeSpan.Zero, deserialized.TimeToLive);
+        Assert.Equal(CacheScope.Private, deserialized.CacheScope);
+    }
+
+    [Fact]
+    public static void DiscoverResult_OmitsCachingHints_WhenUnset()
+    {
+        var result = NewDiscoverResult();
+
+        string json = JsonSerializer.Serialize(result, McpJsonUtilities.DefaultOptions);
+        var node = JsonNode.Parse(json)!.AsObject();
+
+        // Backward compatibility: servers that do not set the hints must not emit them.
+        Assert.False(node.ContainsKey("ttlMs"));
+        Assert.False(node.ContainsKey("cacheScope"));
+
+        var deserialized = JsonSerializer.Deserialize<DiscoverResult>(json, McpJsonUtilities.DefaultOptions)!;
+        Assert.Null(deserialized.TimeToLive);
+        Assert.Null(deserialized.CacheScope);
+    }
+
+    [Fact]
+    public static void DiscoverResult_DeserializesMissingHints_AsNull()
+    {
+        // A response from a pre-PR-#2855 server may omit both fields. Deserialization must succeed
+        // and surface them as null so callers can apply their own defaults.
+        string json =
+            """
+            {
+              "supportedVersions": ["2025-11-25"],
+              "capabilities": {},
+              "serverInfo": {"name": "x", "version": "1"}
+            }
+            """;
+
+        var deserialized = JsonSerializer.Deserialize<DiscoverResult>(json, McpJsonUtilities.DefaultOptions)!;
+        Assert.Null(deserialized.TimeToLive);
+        Assert.Null(deserialized.CacheScope);
+    }
+
+    [Fact]
+    public static void DiscoverResult_DeserializesUnknownCacheScope_AsNull()
+    {
+        // A future or unknown cacheScope string must not break deserialization of the entire result.
+        string json =
+            """
+            {
+              "supportedVersions": ["2025-11-25"],
+              "capabilities": {},
+              "serverInfo": {"name": "x", "version": "1"},
+              "cacheScope": "shared"
+            }
+            """;
+
+        var deserialized = JsonSerializer.Deserialize<DiscoverResult>(json, McpJsonUtilities.DefaultOptions)!;
+        Assert.Null(deserialized.CacheScope);
+    }
+
+    [Fact]
+    public static void DiscoverResult_ImplementsICacheableResult()
+    {
+        // Compile-time assertion that DiscoverResult participates in the shared cacheability surface
+        // alongside the list/read result types.
+        Assert.IsAssignableFrom<ICacheableResult>(NewDiscoverResult());
+    }
+}

tests/ModelContextProtocol.Tests/Server/RawStreamConformanceTests.cs

@@ -5,6 +5,7 @@
 using ModelContextProtocol.Tests.Utils;
 using System.IO.Pipelines;
 using System.Text;
+using System.Text.Json;
 using System.Text.Json.Nodes;
 
 namespace ModelContextProtocol.Tests.Server;
@@ -101,6 +102,12 @@ public async Task ServerDiscover_ReturnsSupportedVersionsIncludingDraft()
         Assert.NotNull(result["capabilities"]);
         Assert.NotNull(result["serverInfo"]);
         Assert.Equal("raw-conformance-server", result["serverInfo"]!["name"]!.GetValue<string>());
+
+        // Spec PR #2855 makes ttlMs and cacheScope required on DiscoverResult; the server emits the
+        // safest defaults (immediately stale, not shareable) when the application hasn't customized.
+        Assert.Equal(JsonValueKind.Number, result["ttlMs"]!.GetValueKind());
+        Assert.Equal(0, result["ttlMs"]!.GetValue<long>());
+        Assert.Equal("private", result["cacheScope"]!.GetValue<string>());
     }
 
     [Fact]