Fix keyset pagination with monotonic UUIDv7-like task IDs

src/Common/Polyfills/System/GuidPolyfills.cs

@@ -0,0 +1,83 @@
+namespace System;
+
+/// <summary>
+/// Provides polyfills for GUID generation methods not available in older .NET versions.
+/// </summary>
+internal static class GuidPolyfills
+{
+    private static long s_lastTimestamp;
+    private static long s_counter;
+    private static readonly object s_lock = new();
+
+    /// <summary>
+    /// Creates a monotonically increasing GUID using UUID v7 format with the specified timestamp.
+    /// Uses a counter for intra-millisecond ordering to ensure strict monotonicity.
+    /// </summary>
+    /// <param name="timestamp">The Unix timestamp in milliseconds to embed in the GUID.</param>
+    /// <returns>A new monotonically increasing GUID.</returns>
+    public static Guid CreateMonotonicUuid(long timestamp)
+    {
+        // UUID v7 format (RFC 9562):
+        // - 48 bits: Unix timestamp in milliseconds (big-endian)
+        // - 4 bits: version (0111 = 7)
+        // - 12 bits: counter/sequence (for intra-millisecond ordering)
+        // - 2 bits: variant (10)
+        // - 62 bits: random
+
+        long counter;
+
+        lock (s_lock)
+        {
+            if (timestamp == s_lastTimestamp)
+            {
+                // Same millisecond - increment counter
+                s_counter++;
+            }
+            else
+            {
+                // New millisecond - reset counter
+                s_lastTimestamp = timestamp;
+                s_counter = 0;
+            }
+
+            counter = s_counter;
+        }
+
+        byte[] bytes = new byte[16];
+
+        // Fill lower random bits (last 8 bytes) with random data
+#if NETSTANDARD2_0
+        using (var rng = Security.Cryptography.RandomNumberGenerator.Create())
+        {
+            rng.GetBytes(bytes, 8, 8);
+        }
+#else
+        Security.Cryptography.RandomNumberGenerator.Fill(bytes.AsSpan(8, 8));
+#endif
+
+        // Set timestamp (48 bits, big-endian) in first 6 bytes
+        bytes[0] = (byte)(timestamp >> 40);
+        bytes[1] = (byte)(timestamp >> 32);
+        bytes[2] = (byte)(timestamp >> 24);
+        bytes[3] = (byte)(timestamp >> 16);
+        bytes[4] = (byte)(timestamp >> 8);
+        bytes[5] = (byte)timestamp;
+
+        // Set version 7 (0111) in high nibble of byte 6, and high 4 bits of counter in low nibble
+        bytes[6] = (byte)(0x70 | ((counter >> 8) & 0x0F));
+
+        // Set remaining 8 bits of counter in byte 7
+        bytes[7] = (byte)(counter & 0xFF);
+
+        // Set variant (10) in high 2 bits of byte 8
+        bytes[8] = (byte)((bytes[8] & 0x3F) | 0x80);
+
+        // Convert from big-endian byte array to Guid
+        return new Guid(
+            (int)(bytes[0] << 24 | bytes[1] << 16 | bytes[2] << 8 | bytes[3]),
+            (short)(bytes[4] << 8 | bytes[5]),
+            (short)(bytes[6] << 8 | bytes[7]),
+            bytes[8], bytes[9], bytes[10], bytes[11],
+            bytes[12], bytes[13], bytes[14], bytes[15]);
+    }
+}

src/ModelContextProtocol.Core/Server/InMemoryMcpTaskStore.cs

@@ -3,7 +3,11 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json;
 
+#if MCP_TEST_TIME_PROVIDER
+namespace ModelContextProtocol.Tests.Internal;
+#else
 namespace ModelContextProtocol;
+#endif
 
 /// <summary>
 /// Provides an in-memory implementation of <see cref="IMcpTaskStore"/> for development and testing.
@@ -35,6 +39,9 @@ public sealed class InMemoryMcpTaskStore : IMcpTaskStore, IDisposable
     private readonly int _pageSize;
     private readonly int? _maxTasks;
     private readonly int? _maxTasksPerSession;
+#if MCP_TEST_TIME_PROVIDER
+    private readonly TimeProvider _timeProvider;
+#endif
 
     /// <summary>
     /// Initializes a new instance of the <see cref="InMemoryMcpTaskStore"/> class.
@@ -120,6 +127,9 @@ public InMemoryMcpTaskStore(
         _pageSize = pageSize;
         _maxTasks = maxTasks;
         _maxTasksPerSession = maxTasksPerSession;
+#if MCP_TEST_TIME_PROVIDER
+        _timeProvider = TimeProvider.System;
+#endif
 
         cleanupInterval ??= TimeSpan.FromMinutes(1);
         if (cleanupInterval.Value != Timeout.InfiniteTimeSpan)
@@ -128,6 +138,26 @@ public InMemoryMcpTaskStore(
         }
     }
 
+#if MCP_TEST_TIME_PROVIDER
+    /// <summary>
+    /// Initializes a new instance of the <see cref="InMemoryMcpTaskStore"/> class with a custom time provider.
+    /// This constructor is only available for testing purposes.
+    /// </summary>
+    internal InMemoryMcpTaskStore(
+        TimeSpan? defaultTtl,
+        TimeSpan? maxTtl,
+        TimeSpan? pollInterval,
+        TimeSpan? cleanupInterval,
+        int pageSize,
+        int? maxTasks,
+        int? maxTasksPerSession,
+        TimeProvider timeProvider)
+        : this(defaultTtl, maxTtl, pollInterval, cleanupInterval, pageSize, maxTasks, maxTasksPerSession)
+    {
+        _timeProvider = timeProvider ?? TimeProvider.System;
+    }
+#endif
+
     /// <inheritdoc/>
     public Task<McpTask> CreateTaskAsync(
         McpTaskMetadata taskParams,
@@ -155,7 +185,7 @@ public Task<McpTask> CreateTaskAsync(
         }
 
         var taskId = GenerateTaskId();
-        var now = DateTimeOffset.UtcNow;
+        var now = GetUtcNow();
 
         // Determine TTL: use requested, fall back to default, respect max limit
         var ttl = taskParams.TimeToLive ?? _defaultTtl;
@@ -242,7 +272,7 @@ public Task<McpTask> StoreTaskResultAsync(
             var updatedEntry = new TaskEntry(entry)
             {
                 Status = status,
-                LastUpdatedAt = DateTimeOffset.UtcNow,
+                LastUpdatedAt = GetUtcNow(),
                 StoredResult = result
             };
 
@@ -303,7 +333,7 @@ public Task<McpTask> UpdateTaskStatusAsync(
             {
                 Status = status,
                 StatusMessage = statusMessage,
-                LastUpdatedAt = DateTimeOffset.UtcNow,
+                LastUpdatedAt = GetUtcNow(),
             };
 
             if (_tasks.TryUpdate(taskId, updatedEntry, entry))
@@ -397,7 +427,7 @@ public Task<McpTask> CancelTaskAsync(string taskId, string? sessionId = null, Ca
             var updatedEntry = new TaskEntry(entry)
             {
                 Status = McpTaskStatus.Cancelled,
-                LastUpdatedAt = DateTimeOffset.UtcNow,
+                LastUpdatedAt = GetUtcNow(),
             };
 
             if (_tasks.TryUpdate(taskId, updatedEntry, entry))
@@ -417,20 +447,31 @@ public void Dispose()
         _cleanupTimer?.Dispose();
     }
 
-    private static string GenerateTaskId() => Guid.NewGuid().ToString("N");
+    private string GenerateTaskId() =>
+        GuidPolyfills.CreateMonotonicUuid(GetUtcNow().ToUnixTimeMilliseconds()).ToString("N");
 
     private static bool IsTerminalStatus(McpTaskStatus status) =>
         status is McpTaskStatus.Completed or McpTaskStatus.Failed or McpTaskStatus.Cancelled;
 
+#if MCP_TEST_TIME_PROVIDER
+    private DateTimeOffset GetUtcNow() => _timeProvider.GetUtcNow();
+#else
+    private static DateTimeOffset GetUtcNow() => DateTimeOffset.UtcNow;
+#endif
+
+#if MCP_TEST_TIME_PROVIDER
+    private bool IsExpired(TaskEntry entry)
+#else
     private static bool IsExpired(TaskEntry entry)
+#endif
     {
         if (entry.TimeToLive == null)
         {
             return false; // Unlimited lifetime
         }
 
         var expirationTime = entry.CreatedAt + entry.TimeToLive.Value;
-        return DateTimeOffset.UtcNow >= expirationTime;
+        return GetUtcNow() >= expirationTime;
     }
 
     private void CleanupExpiredTasks(object? state)

tests/ModelContextProtocol.Tests/ModelContextProtocol.Tests.csproj

@@ -11,6 +11,8 @@
     <RootNamespace>ModelContextProtocol.Tests</RootNamespace>
     <!-- https://github.com/dotnet/sdk/issues/51060 -->
     <NoWarn>$(NoWarn);NU1903;NU1902</NoWarn>
+    <!-- Define for conditional TimeProvider support in InMemoryMcpTaskStore -->
+    <DefineConstants>$(DefineConstants);MCP_TEST_TIME_PROVIDER</DefineConstants>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(TargetFramework)' == 'net9.0'">
@@ -27,6 +29,11 @@
 
   <ItemGroup>
     <Compile Include="..\Common\**\*.cs" />
+    <!-- Link InMemoryMcpTaskStore.cs for testing with TimeProvider support -->
+    <Compile Include="..\..\src\ModelContextProtocol.Core\Server\InMemoryMcpTaskStore.cs" Link="Server\InMemoryMcpTaskStore.cs" />
+    <!-- Include dependencies for the linked InMemoryMcpTaskStore.cs -->
+    <Compile Include="..\..\src\Common\Experimentals.cs" Link="Experimentals.cs" />
+    <Compile Include="..\..\src\Common\Polyfills\System\GuidPolyfills.cs" Link="Polyfills\GuidPolyfills.cs" />
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' == 'net472'">
@@ -43,6 +50,7 @@
     <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
     <PackageReference Include="Microsoft.Extensions.Logging" />
     <PackageReference Include="Microsoft.Extensions.Logging.Console" />
+    <PackageReference Include="Microsoft.Extensions.TimeProvider.Testing" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" />
     <PackageReference Include="Moq" />
     <PackageReference Include="OpenTelemetry" />

tests/ModelContextProtocol.Tests/Server/InMemoryMcpTaskStoreTests.cs

@@ -1,7 +1,9 @@
+using Microsoft.Extensions.Time.Testing;
 using ModelContextProtocol.Protocol;
 using ModelContextProtocol.Server;
 using ModelContextProtocol.Tests.Utils;
 using System.Text.Json;
+using TestInMemoryMcpTaskStore = ModelContextProtocol.Tests.Internal.InMemoryMcpTaskStore;
 
 namespace ModelContextProtocol.Tests.Server;
 
@@ -1031,4 +1033,141 @@ public async Task CreateTaskAsync_MaxTasksPerSession_ExcludesExpiredTasks()
         // Assert
         Assert.NotNull(task2);
     }
+
+    [Fact]
+    public async Task ListTasksAsync_KeysetPaginationWorksWithIdenticalTimestamps()
+    {
+        // Arrange - Use a fake time provider to create tasks with identical timestamps
+        var fakeTime = new FakeTimeProvider(DateTimeOffset.UtcNow);
+        using var store = new TestInMemoryMcpTaskStore(
+            defaultTtl: null,
+            maxTtl: null,
+            pollInterval: null,
+            cleanupInterval: Timeout.InfiniteTimeSpan,
+            pageSize: 5,
+            maxTasks: null,
+            maxTasksPerSession: null,
+            timeProvider: fakeTime);
+
+        // Create 10 tasks - all with the EXACT same timestamp
+        var createdTasks = new List<McpTask>();
+        for (int i = 0; i < 10; i++)
+        {
+            var task = await store.CreateTaskAsync(
+                new McpTaskMetadata(),
+                new RequestId($"req-{i}"),
+                new JsonRpcRequest { Method = "test" },
+                null,
+                TestContext.Current.CancellationToken);
+            createdTasks.Add(task);
+        }
+
+        // Verify all tasks have the same CreatedAt timestamp
+        var firstTimestamp = createdTasks[0].CreatedAt;
+        Assert.All(createdTasks, task => Assert.Equal(firstTimestamp, task.CreatedAt));
+
+        // Act - Get first page
+        var result1 = await store.ListTasksAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        // Assert - First page should have 5 tasks
+        Assert.Equal(5, result1.Tasks.Length);
+        Assert.NotNull(result1.NextCursor);
+
+        // Get second page using cursor
+        var result2 = await store.ListTasksAsync(cursor: result1.NextCursor, cancellationToken: TestContext.Current.CancellationToken);
+
+        // Assert - Second page should have 5 tasks
+        Assert.Equal(5, result2.Tasks.Length);
+        Assert.Null(result2.NextCursor); // No more pages
+
+        // Verify no overlap between pages
+        var page1Ids = result1.Tasks.Select(t => t.TaskId).ToHashSet();
+        var page2Ids = result2.Tasks.Select(t => t.TaskId).ToHashSet();
+        Assert.Empty(page1Ids.Intersect(page2Ids));
+
+        // Verify we got all 10 tasks exactly once
+        var allReturnedIds = page1Ids.Union(page2Ids).ToHashSet();
+        var allCreatedIds = createdTasks.Select(t => t.TaskId).ToHashSet();
+        Assert.Equal(allCreatedIds, allReturnedIds);
+    }
+
+    [Fact]
+    public async Task ListTasksAsync_TasksCreatedAfterFirstPageWithSameTimestampAppearInSecondPage()
+    {
+        // Arrange - Use a fake time provider so we can control timestamps precisely
+        var fakeTime = new FakeTimeProvider(DateTimeOffset.UtcNow);
+        using var store = new TestInMemoryMcpTaskStore(
+            defaultTtl: null,
+            maxTtl: null,
+            pollInterval: null,
+            cleanupInterval: Timeout.InfiniteTimeSpan,
+            pageSize: 5,
+            maxTasks: null,
+            maxTasksPerSession: null,
+            timeProvider: fakeTime);
+
+        // Create initial 6 tasks - all with the same timestamp
+        // (6 so that first page has 5 and cursor points to task 5)
+        var initialTasks = new List<McpTask>();
+        for (int i = 0; i < 6; i++)
+        {
+            var task = await store.CreateTaskAsync(
+                new McpTaskMetadata(),
+                new RequestId($"req-initial-{i}"),
+                new JsonRpcRequest { Method = "test" },
+                null,
+                TestContext.Current.CancellationToken);
+            initialTasks.Add(task);
+        }
+
+        // Get first page - should have 5 tasks with a cursor
+        var result1 = await store.ListTasksAsync(cancellationToken: TestContext.Current.CancellationToken);
+        Assert.Equal(5, result1.Tasks.Length);
+        Assert.NotNull(result1.NextCursor);
+
+        // Now create 5 more tasks AFTER we got the first page cursor
+        // These tasks have the SAME timestamp as the cursor (time hasn't moved)
+        // Due to monotonic UUID v7 with counter, they should sort AFTER the cursor
+        var laterTasks = new List<McpTask>();
+        for (int i = 0; i < 5; i++)
+        {
+            var task = await store.CreateTaskAsync(
+                new McpTaskMetadata(),
+                new RequestId($"req-later-{i}"),
+                new JsonRpcRequest { Method = "test" },
+                null,
+                TestContext.Current.CancellationToken);
+            laterTasks.Add(task);
+        }
+
+        // Verify all tasks have the same timestamp
+        var allTasks = initialTasks.Concat(laterTasks).ToList();
+        var firstTimestamp = allTasks[0].CreatedAt;
+        Assert.All(allTasks, task => Assert.Equal(firstTimestamp, task.CreatedAt));
+
+        // Get ALL remaining pages
+        var allSubsequentTasks = new List<McpTask>();
+        string? cursor = result1.NextCursor;
+        while (cursor != null)
+        {
+            var result = await store.ListTasksAsync(cursor: cursor, cancellationToken: TestContext.Current.CancellationToken);
+            allSubsequentTasks.AddRange(result.Tasks);
+            cursor = result.NextCursor;
+        }
+
+        // Verify no overlap between first page and subsequent
+        var page1Ids = result1.Tasks.Select(t => t.TaskId).ToHashSet();
+        var subsequentIds = allSubsequentTasks.Select(t => t.TaskId).ToHashSet();
+        Assert.Empty(page1Ids.Intersect(subsequentIds));
+
+        // Verify we got all tasks
+        var allReturnedIds = page1Ids.Union(subsequentIds).ToHashSet();
+        var allCreatedIds = allTasks.Select(t => t.TaskId).ToHashSet();
+        Assert.Equal(allCreatedIds, allReturnedIds);
+
+        // Most importantly: verify ALL the later tasks (created after first page) are surfaced
+        // in the subsequent pages
+        var laterTaskIds = laterTasks.Select(t => t.TaskId).ToHashSet();
+        Assert.Superset(laterTaskIds, subsequentIds);
+    }
 }