Merge branch 'main' into localden/experimental

Author: localden

src/Directory.Build.props

@@ -6,7 +6,7 @@
     <RepositoryUrl>https://github.com/modelcontextprotocol/csharp-sdk</RepositoryUrl>
     <RepositoryType>git</RepositoryType>
     <VersionPrefix>0.2.0</VersionPrefix>
-    <VersionSuffix>preview.3</VersionSuffix>
+    <VersionSuffix>preview.4</VersionSuffix>
     <Authors>ModelContextProtocolOfficial</Authors>
     <Copyright>© Anthropic and Contributors.</Copyright>
     <PackageTags>ModelContextProtocol;mcp;ai;llm</PackageTags>

src/ModelContextProtocol.Core/Client/McpClient.cs

@@ -129,11 +129,12 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
             try
             {
                 // Send initialize request
+                string requestProtocol = _options.ProtocolVersion ?? McpSession.LatestProtocolVersion;
                 var initializeResponse = await this.SendRequestAsync(
                     RequestMethods.Initialize,
                     new InitializeRequestParams
                     {
-                        ProtocolVersion = _options.ProtocolVersion,
+                        ProtocolVersion = requestProtocol,
                         Capabilities = _options.Capabilities ?? new ClientCapabilities(),
                         ClientInfo = _options.ClientInfo ?? DefaultImplementation,
                     },
@@ -154,10 +155,13 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
                 _serverInstructions = initializeResponse.Instructions;
 
                 // Validate protocol version
-                if (initializeResponse.ProtocolVersion != _options.ProtocolVersion)
+                bool isResponseProtocolValid =
+                    _options.ProtocolVersion is { } optionsProtocol ? optionsProtocol == initializeResponse.ProtocolVersion :
+                    McpSession.SupportedProtocolVersions.Contains(initializeResponse.ProtocolVersion);
+                if (!isResponseProtocolValid)
                 {
-                    LogServerProtocolVersionMismatch(EndpointName, _options.ProtocolVersion, initializeResponse.ProtocolVersion);
-                    throw new McpException($"Server protocol version mismatch. Expected {_options.ProtocolVersion}, got {initializeResponse.ProtocolVersion}");
+                    LogServerProtocolVersionMismatch(EndpointName, requestProtocol, initializeResponse.ProtocolVersion);
+                    throw new McpException($"Server protocol version mismatch. Expected {requestProtocol}, got {initializeResponse.ProtocolVersion}");
                 }
 
                 // Send initialized notification

src/ModelContextProtocol.Core/Client/McpClientOptions.cs

@@ -34,11 +34,18 @@ public class McpClientOptions
     /// Gets or sets the protocol version to request from the server, using a date-based versioning scheme.
     /// </summary>
     /// <remarks>
+    /// <para>
     /// The protocol version is a key part of the initialization handshake. The client and server must 
-    /// agree on a compatible protocol version to communicate successfully. If the server doesn't support
-    /// the requested version, it will respond with a version mismatch error.
+    /// agree on a compatible protocol version to communicate successfully.
+    /// </para>
+    /// <para>
+    /// If non-<see langword="null"/>, this version will be sent to the server, and the handshake
+    /// will fail if the version in the server's response does not match this version.
+    /// If <see langword="null"/>, the client will request the latest version supported by the server
+    /// but will allow any supported version that the server advertizes in its response.
+    /// </para>
     /// </remarks>
-    public string ProtocolVersion { get; set; } = "2024-11-05";
+    public string? ProtocolVersion { get; set; }
 
     /// <summary>
     /// Gets or sets a timeout for the client-server initialization handshake sequence.

src/ModelContextProtocol.Core/Client/StreamableHttpClientSessionTransport.cs

@@ -97,30 +97,30 @@ internal async Task<HttpResponseMessage> SendHttpRequestAsync(JsonRpcMessage mes
         }
 
         var rpcRequest = message as JsonRpcRequest;
-        JsonRpcMessage? rpcResponseCandidate = null;
+        JsonRpcMessageWithId? rpcResponseOrError = null;
 
         if (response.Content.Headers.ContentType?.MediaType == "application/json")
         {
             var responseContent = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
-            rpcResponseCandidate = await ProcessMessageAsync(responseContent, cancellationToken).ConfigureAwait(false);
+            rpcResponseOrError = await ProcessMessageAsync(responseContent, rpcRequest, cancellationToken).ConfigureAwait(false);
         }
         else if (response.Content.Headers.ContentType?.MediaType == "text/event-stream")
         {
             using var responseBodyStream = await response.Content.ReadAsStreamAsync(cancellationToken);
-            rpcResponseCandidate = await ProcessSseResponseAsync(responseBodyStream, rpcRequest, cancellationToken).ConfigureAwait(false);
+            rpcResponseOrError = await ProcessSseResponseAsync(responseBodyStream, rpcRequest, cancellationToken).ConfigureAwait(false);
         }
 
         if (rpcRequest is null)
         {
             return response;
         }
 
-        if (rpcResponseCandidate is not JsonRpcMessageWithId messageWithId || messageWithId.Id != rpcRequest.Id)
+        if (rpcResponseOrError is null)
         {
             throw new McpException($"Streamable HTTP POST response completed without a reply to request with ID: {rpcRequest.Id}");
         }
 
-        if (rpcRequest.Method == RequestMethods.Initialize && rpcResponseCandidate is JsonRpcResponse)
+        if (rpcRequest.Method == RequestMethods.Initialize && rpcResponseOrError is JsonRpcResponse)
         {
             // We've successfully initialized! Copy session-id and start GET request if any.
             if (response.Headers.TryGetValues("mcp-session-id", out var sessionIdValues))
@@ -199,20 +199,20 @@ private async Task ReceiveUnsolicitedMessagesAsync()
                 continue;
             }
 
-            var message = await ProcessMessageAsync(sseEvent.Data, cancellationToken).ConfigureAwait(false);
+            var rpcResponseOrError = await ProcessMessageAsync(sseEvent.Data, relatedRpcRequest, cancellationToken).ConfigureAwait(false);
 
-            // The server SHOULD end the response here anyway, but we won't leave it to chance. This transport makes
+            // The server SHOULD end the HTTP response body here anyway, but we won't leave it to chance. This transport makes
             // a GET request for any notifications that might need to be sent after the completion of each POST.
-            if (message is JsonRpcMessageWithId messageWithId && relatedRpcRequest?.Id == messageWithId.Id)
+            if (rpcResponseOrError is not null)
             {
-                return messageWithId;
+                return rpcResponseOrError;
             }
         }
 
         return null;
     }
 
-    private async Task<JsonRpcMessage?> ProcessMessageAsync(string data, CancellationToken cancellationToken)
+    private async Task<JsonRpcMessageWithId?> ProcessMessageAsync(string data, JsonRpcRequest? relatedRpcRequest, CancellationToken cancellationToken)
     {
         try
         {
@@ -224,7 +224,12 @@ private async Task ReceiveUnsolicitedMessagesAsync()
             }
 
             await WriteMessageAsync(message, cancellationToken).ConfigureAwait(false);
-            return message;
+            if (message is JsonRpcResponse or JsonRpcError &&
+                message is JsonRpcMessageWithId rpcResponseOrError &&
+                rpcResponseOrError.Id == relatedRpcRequest?.Id)
+            {
+                return rpcResponseOrError;
+            }
         }
         catch (JsonException ex)
         {

src/ModelContextProtocol.Core/McpSession.cs

@@ -28,6 +28,16 @@ internal sealed partial class McpSession : IDisposable
     private static readonly Histogram<double> s_serverOperationDuration = Diagnostics.CreateDurationHistogram(
         "mcp.server.operation.duration", "Measures the duration of inbound message processing.", longBuckets: false);
 
+    /// <summary>The latest version of the protocol supported by this implementation.</summary>
+    internal const string LatestProtocolVersion = "2025-03-26";
+
+    /// <summary>All protocol versions supported by this implementation.</summary>
+    internal static readonly string[] SupportedProtocolVersions =
+    [
+        "2024-11-05",
+        LatestProtocolVersion,
+    ];
+
     private readonly bool _isServer;
     private readonly string _transportKind;
     private readonly ITransport _transport;

src/ModelContextProtocol.Core/Protocol/PaginatedRequest.cs

@@ -6,7 +6,7 @@ namespace ModelContextProtocol.Protocol;
 /// Provides a base class for paginated requests.
 /// </summary>
 /// <remarks>
-/// <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/2024-11-05/schema.json">See the schema for details</see>
+/// <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">See the schema for details</see>
 /// </remarks>
 public class PaginatedRequestParams : RequestParams
 {

src/ModelContextProtocol.Core/README.md

@@ -102,11 +102,3 @@ await server.RunAsync(stdioTransport, CancellationToken.None);
 ```
 
 For more advanced scenarios with dependency injection, hosting, and automatic tool discovery, see the `ModelContextProtocol` package.
-
-## Acknowledgements
-
-The MCP C# SDK builds upon the excellent work from the [mcpdotnet](https://github.com/ReallyLiri/mcpdotnet) project by [Liri](https://github.com/ReallyLiri). We extend our gratitude for providing a foundational implementation that inspired this SDK.
-
-## License
-
-This project is licensed under the MIT License. See the [LICENSE](../../LICENSE) file for details.

src/ModelContextProtocol.Core/Server/McpServer.cs

@@ -161,9 +161,20 @@ private void ConfigureInitialize(McpServerOptions options)
                 UpdateEndpointNameWithClientInfo();
                 GetSessionOrThrow().EndpointName = EndpointName;
 
+                // Negotiate a protocol version. If the server options provide one, use that.
+                // Otherwise, try to use whatever the client requested as long as it's supported.
+                // If it's not supported, fall back to the latest supported version.
+                string? protocolVersion = options.ProtocolVersion;
+                if (protocolVersion is null)
+                {
+                    protocolVersion = request?.ProtocolVersion is string clientProtocolVersion && McpSession.SupportedProtocolVersions.Contains(clientProtocolVersion) ?
+                        clientProtocolVersion :
+                        McpSession.LatestProtocolVersion;
+                }
+
                 return new InitializeResult
                 {
-                    ProtocolVersion = options.ProtocolVersion,
+                    ProtocolVersion = protocolVersion,
                     Instructions = options.ServerInstructions,
                     ServerInfo = options.ServerInfo ?? DefaultImplementation,
                     Capabilities = ServerCapabilities ?? new(),

src/ModelContextProtocol.Core/Server/McpServerOptions.cs

@@ -32,8 +32,11 @@ public class McpServerOptions
     /// <remarks>
     /// The protocol version defines which features and message formats this server supports.
     /// This uses a date-based versioning scheme in the format "YYYY-MM-DD".
+    /// If <see langword="null"/>, the server will advertize to the client the version requested
+    /// by the client if that version is known to be supported, and otherwise will advertize the latest
+    /// version supported by the server.
     /// </remarks>
-    public string ProtocolVersion { get; set; } = "2024-11-05";
+    public string? ProtocolVersion { get; set; }
 
     /// <summary>
     /// Gets or sets a timeout used for the client-server initialization handshake sequence.

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs

@@ -60,7 +60,7 @@ public async ValueTask DisposeAsync()
         {
             yield return message;
 
-            if (message.Data is JsonRpcMessageWithId response && response.Id == _pendingRequest)
+            if (message.Data is JsonRpcResponse or JsonRpcError && ((JsonRpcMessageWithId)message.Data).Id == _pendingRequest)
             {
                 // Complete the SSE response stream now that all pending requests have been processed.
                 break;