Support multiple contents in sampling results.

Author: eiriktsarpalis

src/ModelContextProtocol.Core/Client/McpClientExtensions.cs

@@ -957,7 +957,7 @@ internal static CreateMessageResult ToCreateMessageResult(this ChatResponse chat
 
         return new()
         {
-            Content = content ?? new TextContentBlock { Text = lastMessage?.Text ?? string.Empty },
+            Contents = [content ?? new TextContentBlock { Text = lastMessage?.Text ?? string.Empty }],
             Model = chatResponse.ModelId ?? "unknown",
             Role = lastMessage?.Role == ChatRole.User ? Role.User : Role.Assistant,
             StopReason = chatResponse.FinishReason == ChatFinishReason.Length ? "maxTokens" : "endTurn",

src/ModelContextProtocol.Core/McpEndpointExtensions.cs

@@ -83,11 +83,11 @@ internal static async ValueTask<TResult> SendRequestAsync<TParameters, TResult>(
         {
             Id = requestId,
             Method = method,
-            Params = JsonSerializer.SerializeToNode(parameters, parametersTypeInfo),
+            Params = McpJsonUtilities.SerializeContextual(parameters, parametersTypeInfo, endpoint),
         };
 
         JsonRpcResponse response = await endpoint.SendRequestAsync(jsonRpcRequest, cancellationToken).ConfigureAwait(false);
-        return JsonSerializer.Deserialize(response.Result, resultTypeInfo) ?? throw new JsonException("Unexpected JSON result in response.");
+        return McpJsonUtilities.DeserializeContextual(response.Result, resultTypeInfo, endpoint) ?? throw new JsonException("Unexpected JSON result in response.");
     }
 
     /// <summary>

src/ModelContextProtocol.Core/McpJsonUtilities.McpJsonConverter.cs

@@ -0,0 +1,91 @@
+using System.ComponentModel;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using System.Text.Json.Serialization;
+using System.Text.Json.Serialization.Metadata;
+
+namespace ModelContextProtocol;
+
+public static partial class McpJsonUtilities
+{
+    [ThreadStatic]
+    private static IMcpEndpoint? t_currentMcpEndpoint;
+
+    /// <summary>
+    /// Serializes the given value to a <see cref="JsonNode"/> using the provided <see cref="JsonTypeInfo{T}"/>,
+    /// </summary>
+    internal static JsonNode? SerializeContextual<T>(T? value, JsonTypeInfo<T> typeInfo, IMcpEndpoint endpoint)
+    {
+        if (endpoint is null)
+        {
+            Throw.IfNull(endpoint);
+        }
+
+        if (t_currentMcpEndpoint is not null)
+        {
+            throw new InvalidOperationException("Reentrant call to McpJsonUtilities.SerializeContextual detected.");
+        }
+
+        t_currentMcpEndpoint = endpoint;
+        try
+        {
+            return JsonSerializer.SerializeToNode(value!, typeInfo);
+        }
+        finally
+        {
+            t_currentMcpEndpoint = null;
+        }
+    }
+
+    /// <summary>
+    /// Deserializes the given value to a <see cref="JsonNode"/> using the provided <see cref="JsonTypeInfo{T}"/>,
+    /// </summary>
+    internal static T? DeserializeContextual<T>(JsonNode? node, JsonTypeInfo<T> typeInfo, IMcpEndpoint endpoint)
+    {
+        if (endpoint is null)
+        {
+            Throw.IfNull(endpoint);
+        }
+
+        if (t_currentMcpEndpoint is not null)
+        {
+            throw new InvalidOperationException("Reentrant call to McpJsonUtilities.DeserializeContextual detected.");
+        }
+
+        t_currentMcpEndpoint = endpoint;
+        try
+        {
+            return JsonSerializer.Deserialize(node, typeInfo);
+        }
+        finally
+        {
+            t_currentMcpEndpoint = null;
+        }
+    }
+
+    /// <summary>
+    /// Defines an abstract JSON converter that has access to the current <see cref="IMcpEndpoint"/> context during serialization and deserialization.
+    /// </summary>
+    /// <typeparam name="T">The type being converted.</typeparam>
+    [EditorBrowsable(EditorBrowsableState.Never)]
+    public abstract class McpContextualJsonConverter<T> : JsonConverter<T>
+    {
+        /// <summary>
+        /// Reads the JSON representation of the value.
+        /// </summary>
+        public abstract T? Read(ref Utf8JsonReader reader, IMcpEndpoint? endpoint, JsonSerializerOptions options);
+
+        /// <summary>
+        /// Writes the JSON representation of the value.
+        /// </summary>
+        public abstract void Write(Utf8JsonWriter writer, T value, IMcpEndpoint? endpoint, JsonSerializerOptions options);
+
+        /// <inheritdoc/>
+        public sealed override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
+            Read(ref reader, t_currentMcpEndpoint, options);
+
+        /// <inheritdoc/>
+        public sealed override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options) =>
+            Write(writer, value, t_currentMcpEndpoint, options);
+    }
+}

src/ModelContextProtocol.Core/Protocol/CreateMessageResult.cs

@@ -1,3 +1,5 @@
+using System.ComponentModel;
+using System.Text.Json;
 using System.Text.Json.Serialization;
 
 namespace ModelContextProtocol.Protocol;
@@ -14,7 +16,26 @@ public sealed class CreateMessageResult : Result
     /// Gets or sets the content of the message.
     /// </summary>
     [JsonPropertyName("content")]
-    public required ContentBlock Content { get; init; }
+    [JsonConverter(typeof(SingleOrArrayContentConverter))]
+    public required List<ContentBlock> Contents
+    {
+        get;
+        init
+        { 
+            if (value is null or [])
+            {
+                throw new ArgumentException(nameof(Contents));
+            }
+
+            field = value;
+        }
+    }
+
+    /// <summary>
+    /// Gets or sets the content of the message.
+    /// </summary>
+    [JsonIgnore]
+    public ContentBlock Content { get => Contents.First(); init => Contents = [value]; }
 
     /// <summary>
     /// Gets or sets the name of the model that generated the message.
@@ -50,4 +71,36 @@ public sealed class CreateMessageResult : Result
     /// </summary>
     [JsonPropertyName("role")]
     public required Role Role { get; init; }
+
+    /// <summary>
+    /// Defines a converter that handles deserialization of a single <see cref="ContentBlock"/> or an array of <see cref="ContentBlock"/> into a <see cref="List{ContentBlock}"/>.
+    /// </summary>
+    [EditorBrowsable(EditorBrowsableState.Never)]
+    public sealed class SingleOrArrayContentConverter : McpJsonUtilities.McpContextualJsonConverter<List<ContentBlock>>
+    {
+        /// <inheritdoc/>
+        public override List<ContentBlock>? Read(ref Utf8JsonReader reader, IMcpEndpoint? endpoint, JsonSerializerOptions options)
+        {
+            if (reader.TokenType is JsonTokenType.StartObject)
+            {
+                var single = JsonSerializer.Deserialize(ref reader, options.GetTypeInfo<ContentBlock>());
+                return [single];
+            }
+
+            return JsonSerializer.Deserialize(ref reader, options.GetTypeInfo<List<ContentBlock>>());
+        }
+
+        /// <inheritdoc/>
+        public override void Write(Utf8JsonWriter writer, List<ContentBlock> value, IMcpEndpoint? endpoint, JsonSerializerOptions options)
+        {
+            if (endpoint?.NegotiatedProtocolVersion is string version &&
+                DateTime.Parse(version) < new DateTime(2025, 09, 18)) // A hypothetical future version
+            {
+                // The negotiated protocol version is before 2025-09-18, so we need to serialize as a single object.
+                JsonSerializer.Serialize(value.Single(), options.GetTypeInfo<ContentBlock>());
+            }
+
+            JsonSerializer.Serialize(value, options.GetTypeInfo<List<ContentBlock>>());
+        }
+    }
 }

tests/Common/Utils/TestServerTransport.cs

@@ -75,7 +75,7 @@ private async Task SamplingAsync(JsonRpcRequest request, CancellationToken cance
         await WriteMessageAsync(new JsonRpcResponse
         {
             Id = request.Id,
-            Result = JsonSerializer.SerializeToNode(new CreateMessageResult { Content = new TextContentBlock { Text = "" }, Model = "model", Role = Role.User }, McpJsonUtilities.DefaultOptions),
+            Result = JsonSerializer.SerializeToNode(new CreateMessageResult { Contents = [new TextContentBlock { Text = "" }], Model = "model", Role = Role.User }, McpJsonUtilities.DefaultOptions),
         }, cancellationToken);
     }
 

tests/ModelContextProtocol.AspNetCore.Tests/HttpServerIntegrationTests.cs

@@ -259,7 +259,7 @@ public async Task Sampling_Sse_TestServer()
             {
                 Model = "test-model",
                 Role = Role.Assistant,
-                Content = new TextContentBlock { Text = "Test response" },
+                Contents = [new TextContentBlock { Text = "Test response" }],
             };
         };
         await using var client = await GetClientAsync(options);

tests/ModelContextProtocol.AspNetCore.Tests/MapMcpTests.cs

@@ -179,7 +179,7 @@ public async Task Sampling_DoesNotCloseStream_Prematurely()
                         {
                             Model = "test-model",
                             Role = Role.Assistant,
-                            Content = new TextContentBlock { Text = "Sampling response from client" },
+                            Contents = [new TextContentBlock { Text = "Sampling response from client" }],
                         };
                     },
                 },

tests/ModelContextProtocol.Tests/Client/McpClientFactoryTests.cs

@@ -70,10 +70,10 @@ public async Task CreateAsync_WithCapabilitiesOptions(Type transportType)
                     SamplingHandler = async (c, p, t) =>
                         new CreateMessageResult 
                         { 
-                            Content = new TextContentBlock { Text = "result" }, 
-                            Model = "test-model", 
-                            Role = Role.User, 
-                            StopReason = "endTurn" 
+                            Contents = [new TextContentBlock { Text = "result" }],
+                            Model = "test-model",
+                            Role = Role.User,
+                            StopReason = "endTurn"
                         },
                 },
                 Roots = new RootsCapability

tests/ModelContextProtocol.Tests/ClientIntegrationTests.cs

@@ -381,7 +381,7 @@ public async Task Sampling_Stdio(string clientId)
                         {
                             Model = "test-model",
                             Role = Role.Assistant,
-                            Content = new TextContentBlock { Text = "Test response" },
+                            Contents = [new TextContentBlock { Text = "Test response" }],
                         };
                     },
                 },

tests/ModelContextProtocol.Tests/DockerEverythingServerTests.cs

@@ -83,7 +83,7 @@ public async Task Sampling_Sse_EverythingServer()
                         {
                             Model = "test-model",
                             Role = Role.Assistant,
-                            Content = new TextContentBlock { Text = "Test response" },
+                            Contents = [new TextContentBlock { Text = "Test response" }],
                         };
                     },
                 },