Merge branch 'main' into halter73/split-filters

# Conflicts:
#	tests/ModelContextProtocol.TestSseServer/Program.cs

Author: halter73

ModelContextProtocol.slnx

@@ -78,5 +78,6 @@
     <Project Path="tests/ModelContextProtocol.Tests/ModelContextProtocol.Tests.csproj" />
     <Project Path="tests/ModelContextProtocol.TestServer/ModelContextProtocol.TestServer.csproj" />
     <Project Path="tests/ModelContextProtocol.TestSseServer/ModelContextProtocol.TestSseServer.csproj" />
+    <Project Path="tests/ModelContextProtocol.ExperimentalApiRegressionTest/ModelContextProtocol.ExperimentalApiRegressionTest.csproj" />
   </Folder>
 </Solution>

docs/concepts/tasks/tasks.md

@@ -8,7 +8,7 @@ uid: tasks
 # MCP Tasks
 
 > [!WARNING]
-> Tasks are an **experimental feature** in the MCP specification (version 2025-11-25). The API may change in future releases.
+> Tasks are an **experimental feature** in the MCP specification (version 2025-11-25). The API may change in future releases. See the [Experimental APIs](../../experimental.md) documentation for details on working with experimental APIs.
 
 The Model Context Protocol (MCP) supports [task-based execution] for long-running operations. Tasks enable a "call-now, fetch-later" pattern where clients can initiate operations that may take significant time to complete, then poll for status and retrieve results when ready.
 

docs/experimental.md

@@ -0,0 +1,70 @@
+---
+title: Experimental APIs
+author: MackinnonBuck
+description: Working with experimental APIs in the MCP C# SDK
+uid: experimental
+---
+
+The Model Context Protocol C# SDK uses the [`[Experimental]`](https://learn.microsoft.com/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute) attribute to mark APIs that are still in development and may change without notice. For more details on the SDK's versioning policy around experimental APIs, see the [Versioning](versioning.md) documentation.
+
+## Suppressing experimental diagnostics
+
+When you use an experimental API, the compiler produces a diagnostic (e.g., `MCPEXP001`) to ensure you're aware the API may change. If you want to use the API, suppress the diagnostic in one of these ways:
+
+### Project-wide suppression
+
+Add the diagnostic ID to `<NoWarn>` in your project file:
+
+```xml
+<PropertyGroup>
+  <NoWarn>$(NoWarn);MCPEXP001</NoWarn>
+</PropertyGroup>
+```
+
+### Per-call suppression
+
+Use `#pragma warning disable` around specific call sites:
+
+```csharp
+#pragma warning disable MCPEXP001 // The Tasks feature is experimental per the MCP specification and is subject to change.
+tool.Execution = new ToolExecution { ... };
+#pragma warning restore MCPEXP001
+```
+
+For a full list of experimental diagnostic IDs and their descriptions, see the [list of diagnostics](list-of-diagnostics.md#experimental-apis).
+
+## Serialization behavior
+
+Experimental properties on protocol types are fully serialized and deserialized when using the SDK's built-in serialization via <xref:ModelContextProtocol.McpJsonUtilities.DefaultOptions>. This means experimental data is transmitted on the wire even if your application code doesn't directly interact with it, preserving protocol compatibility.
+
+The behavior of experimental properties differs depending on whether you use [reflection-based or source-generated](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json/source-generation) serialization:
+
+- **Reflection-based serialization** (the default when no `JsonSerializerContext` is used): Experimental properties are included. No special configuration is needed.
+- **Source-generated serialization** (using a custom `JsonSerializerContext`): Experimental properties are **not** included in your context's serialization contract. This is by design, as it protects your compiled code against binary breaking changes to experimental APIs.
+
+This means that switching between reflection-based and source-generated serialization can silently change which properties are serialized. To avoid this, source-generation users should configure a `TypeInfoResolverChain` as described below.
+
+### Custom `JsonSerializerContext`
+
+If you define your own `JsonSerializerContext` that includes MCP protocol types, configure a `TypeInfoResolverChain` so the SDK's resolver handles MCP types:
+
+```csharp
+using ModelContextProtocol;
+
+JsonSerializerOptions options = new()
+{
+    TypeInfoResolverChain =
+    {
+        McpJsonUtilities.DefaultOptions.TypeInfoResolver!,
+        MyCustomContext.Default,
+    }
+};
+```
+
+By placing the SDK's resolver first, MCP types are serialized using the SDK's contract (which includes experimental properties), while your custom context handles your own types. This is recommended even if you aren't currently using experimental APIs, since it ensures your serialization configuration remains correct as new experimental properties are introduced or as you adopt experimental features in the future.
+
+## See also
+
+- [Versioning](versioning.md)
+- [List of diagnostics](list-of-diagnostics.md#experimental-apis)
+- [Tasks](concepts/tasks/tasks.md) (an experimental feature)

docs/toc.yml

@@ -5,5 +5,7 @@ items:
   href: api/ModelContextProtocol.yml
 - name: Versioning
   href: versioning.md
+- name: Experimental APIs
+  href: experimental.md
 - name: GitHub
   href: https://github.com/ModelContextProtocol/csharp-sdk

samples/EverythingServer/Resources/SimpleResourceType.cs

@@ -1,6 +1,7 @@
 using ModelContextProtocol.Protocol;
 using ModelContextProtocol.Server;
 using System.ComponentModel;
+using System.Text;
 
 namespace EverythingServer.Resources;
 
@@ -31,7 +32,7 @@ public static ResourceContents TemplateResource(RequestContext<ReadResourceReque
             } :
             new BlobResourceContents
             {
-                Blob = resource.Description!,
+                Blob = Encoding.UTF8.GetBytes(resource.Description!),
                 MimeType = resource.MimeType,
                 Uri = resource.Uri,
             };

samples/EverythingServer/Tools/AnnotatedMessageTool.cs

@@ -1,6 +1,7 @@
 using ModelContextProtocol.Protocol;
 using ModelContextProtocol.Server;
 using System.ComponentModel;
+using System.Text;
 
 namespace EverythingServer.Tools;
 
@@ -41,7 +42,7 @@ public static IEnumerable<ContentBlock> AnnotatedMessage(MessageType messageType
         {
             contents.Add(new ImageContentBlock
             {
-                Data = TinyImageTool.MCP_TINY_IMAGE.Split(",").Last(),
+                Data = Encoding.UTF8.GetBytes(TinyImageTool.MCP_TINY_IMAGE.Split(",").Last()),
                 MimeType = "image/png",
                 Annotations = new() { Audience = [Role.User], Priority = 0.5f }
             });

src/Common/EncodingUtilities.cs

@@ -0,0 +1,59 @@
+using System.Buffers;
+using System.Buffers.Text;
+using System.Diagnostics;
+using System.Text;
+
+namespace ModelContextProtocol;
+
+/// <summary>Provides helper methods for encoding operations.</summary>
+internal static class EncodingUtilities
+{
+    /// <summary>
+    /// Converts UTF-16 characters to UTF-8 bytes without intermediate string allocations.
+    /// </summary>
+    /// <param name="utf16">The UTF-16 character span to convert.</param>
+    /// <returns>A byte array containing the UTF-8 encoded bytes.</returns>
+    public static byte[] GetUtf8Bytes(ReadOnlySpan<char> utf16)
+    {
+        byte[] bytes = new byte[Encoding.UTF8.GetByteCount(utf16)];
+        Encoding.UTF8.GetBytes(utf16, bytes);
+        return bytes;
+    }
+
+    /// <summary>
+    /// Encodes binary data to base64-encoded UTF-8 bytes.
+    /// </summary>
+    /// <param name="data">The binary data to encode.</param>
+    /// <returns>A ReadOnlyMemory containing the base64-encoded UTF-8 bytes.</returns>
+    public static ReadOnlyMemory<byte> EncodeToBase64Utf8(ReadOnlyMemory<byte> data)
+    {
+        int maxLength = Base64.GetMaxEncodedToUtf8Length(data.Length);
+        byte[] buffer = new byte[maxLength];
+        OperationStatus status = Base64.EncodeToUtf8(data.Span, buffer, out _, out int bytesWritten);
+        Debug.Assert(status == OperationStatus.Done, "Base64 encoding should succeed for valid input data");
+        Debug.Assert(bytesWritten == buffer.Length, "Base64 encoding should always produce the same length as the max length");
+        return buffer.AsMemory(0, bytesWritten);
+    }
+
+    /// <summary>
+    /// Decodes base64-encoded UTF-8 bytes to binary data.
+    /// </summary>
+    /// <param name="base64Data">The base64-encoded UTF-8 bytes to decode.</param>
+    /// <returns>A ReadOnlyMemory containing the decoded binary data.</returns>
+    /// <exception cref="FormatException">The input is not valid base64 data.</exception>
+    public static ReadOnlyMemory<byte> DecodeFromBase64Utf8(ReadOnlyMemory<byte> base64Data)
+    {
+        int maxLength = Base64.GetMaxDecodedFromUtf8Length(base64Data.Length);
+        byte[] buffer = new byte[maxLength];
+        if (Base64.DecodeFromUtf8(base64Data.Span, buffer, out _, out int bytesWritten) == OperationStatus.Done)
+        {
+            // Base64 decoding may produce fewer bytes than the max length, due to whitespace anywhere in the string or padding.
+            Debug.Assert(bytesWritten <= buffer.Length, "Base64 decoding should never produce more bytes than the max length");
+            return buffer.AsMemory(0, bytesWritten);
+        }
+        else
+        {
+            throw new FormatException("Invalid base64 data");
+        }
+    }
+}

src/Common/Polyfills/System/Text/EncodingExtensions.cs

@@ -0,0 +1,50 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#if !NET
+
+namespace System.Text;
+
+internal static class EncodingExtensions
+{
+    /// <summary>
+    /// Gets the number of bytes required to encode the specified characters.
+    /// </summary>
+    public static int GetByteCount(this Encoding encoding, ReadOnlySpan<char> chars)
+    {
+        if (chars.IsEmpty)
+        {
+            return 0;
+        }
+
+        unsafe
+        {
+            fixed (char* charsPtr = chars)
+            {
+                return encoding.GetByteCount(charsPtr, chars.Length);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Encodes the specified characters into the specified byte span.
+    /// </summary>
+    public static int GetBytes(this Encoding encoding, ReadOnlySpan<char> chars, Span<byte> bytes)
+    {
+        if (chars.IsEmpty)
+        {
+            return 0;
+        }
+
+        unsafe
+        {
+            fixed (char* charsPtr = chars)
+            fixed (byte* bytesPtr = bytes)
+            {
+                return encoding.GetBytes(charsPtr, chars.Length, bytesPtr, bytes.Length);
+            }
+        }
+    }
+}
+
+#endif

src/Common/ServerSentEvents/SseEventWriterHelpers.cs

@@ -47,20 +47,12 @@ public static void WriteUtf8String(this IBufferWriter<byte> writer, ReadOnlySpan
             return;
         }
 
-#if NET
         int maxByteCount = Encoding.UTF8.GetMaxByteCount(value.Length);
         Span<byte> buffer = writer.GetSpan(maxByteCount);
         Debug.Assert(buffer.Length >= maxByteCount);
 
         int bytesWritten = Encoding.UTF8.GetBytes(value, buffer);
         writer.Advance(bytesWritten);
-#else
-        // netstandard2.0 doesn't have the Span overload of GetBytes
-        byte[] bytes = Encoding.UTF8.GetBytes(value.ToString());
-        Span<byte> buffer = writer.GetSpan(bytes.Length);
-        bytes.AsSpan().CopyTo(buffer);
-        writer.Advance(bytes.Length);
-#endif
     }
 
     public static bool ContainsLineBreaks(this ReadOnlySpan<char> text) =>

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -23,15 +23,34 @@ internal sealed class StreamableHttpHandler(
     ILoggerFactory loggerFactory)
 {
     private const string McpSessionIdHeaderName = "Mcp-Session-Id";
+    private const string McpProtocolVersionHeaderName = "MCP-Protocol-Version";
     private const string LastEventIdHeaderName = "Last-Event-ID";
 
+    /// <summary>
+    /// All protocol versions supported by this implementation.
+    /// Keep in sync with McpSessionHandler.SupportedProtocolVersions in ModelContextProtocol.Core.
+    /// </summary>
+    private static readonly HashSet<string> s_supportedProtocolVersions =
+    [
+        "2024-11-05",
+        "2025-03-26",
+        "2025-06-18",
+        "2025-11-25",
+    ];
+
     private static readonly JsonTypeInfo<JsonRpcMessage> s_messageTypeInfo = GetRequiredJsonTypeInfo<JsonRpcMessage>();
     private static readonly JsonTypeInfo<JsonRpcError> s_errorTypeInfo = GetRequiredJsonTypeInfo<JsonRpcError>();
 
     public HttpServerTransportOptions HttpServerTransportOptions => httpServerTransportOptions.Value;
 
     public async Task HandlePostRequestAsync(HttpContext context)
     {
+        if (!ValidateProtocolVersionHeader(context, out var errorMessage))
+        {
+            await WriteJsonRpcErrorAsync(context, errorMessage!, StatusCodes.Status400BadRequest);
+            return;
+        }
+
         // The Streamable HTTP spec mandates the client MUST accept both application/json and text/event-stream.
         // ASP.NET Core Minimal APIs mostly try to stay out of the business of response content negotiation,
         // so we have to do this manually. The spec doesn't mandate that servers MUST reject these requests,
@@ -74,6 +93,12 @@ await WriteJsonRpcErrorAsync(context,
 
     public async Task HandleGetRequestAsync(HttpContext context)
     {
+        if (!ValidateProtocolVersionHeader(context, out var errorMessage))
+        {
+            await WriteJsonRpcErrorAsync(context, errorMessage!, StatusCodes.Status400BadRequest);
+            return;
+        }
+
         if (!context.Request.GetTypedHeaders().Accept.Any(MatchesTextEventStreamMediaType))
         {
             await WriteJsonRpcErrorAsync(context,
@@ -171,6 +196,12 @@ private static async Task HandleResumePostResponseStreamAsync(HttpContext contex
 
     public async Task HandleDeleteRequestAsync(HttpContext context)
     {
+        if (!ValidateProtocolVersionHeader(context, out var errorMessage))
+        {
+            await WriteJsonRpcErrorAsync(context, errorMessage!, StatusCodes.Status400BadRequest);
+            return;
+        }
+
         var sessionId = context.Request.Headers[McpSessionIdHeaderName].ToString();
         if (sessionManager.TryRemove(sessionId, out var session))
         {
@@ -391,6 +422,24 @@ internal static Task RunSessionAsync(HttpContext httpContext, McpServer session,
 
     internal static JsonTypeInfo<T> GetRequiredJsonTypeInfo<T>() => (JsonTypeInfo<T>)McpJsonUtilities.DefaultOptions.GetTypeInfo(typeof(T));
 
+    /// <summary>
+    /// Validates the MCP-Protocol-Version header if present. A missing header is allowed for backwards compatibility,
+    /// but an invalid or unsupported value must be rejected with 400 Bad Request per the MCP spec.
+    /// </summary>
+    private static bool ValidateProtocolVersionHeader(HttpContext context, out string? errorMessage)
+    {
+        var protocolVersionHeader = context.Request.Headers[McpProtocolVersionHeaderName].ToString();
+        if (!string.IsNullOrEmpty(protocolVersionHeader) &&
+            !s_supportedProtocolVersions.Contains(protocolVersionHeader))
+        {
+            errorMessage = $"Bad Request: The MCP-Protocol-Version header value '{protocolVersionHeader}' is not supported.";
+            return false;
+        }
+
+        errorMessage = null;
+        return true;
+    }
+
     private static bool MatchesApplicationJsonMediaType(MediaTypeHeaderValue acceptHeaderValue)
         => acceptHeaderValue.MatchesMediaType("application/json");