Merge branch 'main' into dependabot/nuget/testing-frameworks-485962a2b3

Author: halter73

Directory.Packages.props

@@ -4,7 +4,7 @@
     <System8Version>8.0.22</System8Version>
     <System9Version>9.0.11</System9Version>
     <System10Version>10.0.3</System10Version>
-    <MicrosoftExtensionsVersion>10.2.0</MicrosoftExtensionsVersion>
+    <MicrosoftExtensionsVersion>10.3.0</MicrosoftExtensionsVersion>
   </PropertyGroup>
 
   <!-- Product dependencies shared -->
@@ -87,7 +87,7 @@
     <PackageVersion Include="Serilog.Sinks.Console" Version="6.1.1" />
     <PackageVersion Include="Serilog.Sinks.Debug" Version="3.0.0" />
     <PackageVersion Include="Serilog.Sinks.File" Version="7.0.0" />
-    <PackageVersion Include="Serilog" Version="4.3.0" />
+    <PackageVersion Include="Serilog" Version="4.3.1" />
     <PackageVersion Include="System.Linq.AsyncEnumerable" Version="$(System10Version)" />
     <PackageVersion Include="xunit.v3" Version="3.2.2" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -339,6 +339,7 @@ internal static void InitializeSseResponse(HttpContext context)
 
         // Make sure we disable all response buffering for SSE.
         context.Response.Headers.ContentEncoding = "identity";
+        context.Response.Headers["X-Accel-Buffering"] = "no";
         context.Features.GetRequiredFeature<IHttpResponseBodyFeature>().DisableBuffering();
     }
 

src/ModelContextProtocol.Core/Client/McpClient.cs

@@ -35,11 +35,11 @@ public abstract partial class McpClient : McpSession
     /// <remarks>
     /// <para>
     /// This property contains instructions provided by the server during initialization that explain
-    /// how to effectively use its capabilities. These instructions can include details about available
-    /// tools, expected input formats, limitations, or any other helpful information.
+    /// how to effectively use its capabilities. They should focus on guidance that helps a model
+    /// use the server effectively and should avoid duplicating tool, prompt, or resource descriptions.
     /// </para>
     /// <para>
-    /// This can be used by clients to improve an LLM's understanding of available tools, prompts, and resources.
+    /// This can be used by clients to improve an LLM's understanding of how to use the server.
     /// It can be thought of like a "hint" to the model and can be added to a system prompt.
     /// </para>
     /// </remarks>

src/ModelContextProtocol.Core/Protocol/CreateMessageRequestParams.cs

@@ -33,25 +33,38 @@ public sealed class CreateMessageRequestParams : RequestParams
     /// Gets or sets the maximum number of tokens to generate in the LLM response, as requested by the server.
     /// </summary>
     /// <remarks>
+    /// <para>
     /// A token is generally a word or part of a word in the text. Setting this value helps control
     /// response length and computation time. The client can choose to sample fewer tokens than requested.
+    /// </para>
+    /// <para>
+    /// The client must respect the <see cref="MaxTokens"/> parameter.
+    /// </para>
     /// </remarks>
     [JsonPropertyName("maxTokens")]
     public required int MaxTokens { get; set; }
 
     /// <summary>
     /// Gets or sets the messages requested by the server to be included in the prompt.
     /// </summary>
+    /// <remarks>
+    /// The list of messages in a sampling request should not be retained between separate requests.
+    /// </remarks>
     [JsonPropertyName("messages")]
     public IList<SamplingMessage> Messages { get; set; } = [];
 
     /// <summary>
     /// Gets or sets optional metadata to pass through to the LLM provider.
     /// </summary>
     /// <remarks>
+    /// <para>
     /// The format of this metadata is provider-specific and can include model-specific settings or
     /// configuration that isn't covered by standard parameters. This allows for passing custom parameters
     /// that are specific to certain AI models or providers.
+    /// </para>
+    /// <para>
+    /// The client may modify or ignore metadata.
+    /// </para>
     /// </remarks>
     [JsonPropertyName("metadata")]
     public JsonElement? Metadata { get; set; }
@@ -90,6 +103,9 @@ public sealed class CreateMessageRequestParams : RequestParams
     /// sequence exactly matches one of the provided sequences. Common uses include ending markers like "END", punctuation
     /// like ".", or special delimiter sequences like "###".
     /// </para>
+    /// <para>
+    /// The client may modify or ignore stop sequences.
+    /// </para>
     /// </remarks>
     [JsonPropertyName("stopSequences")]
     public IList<string>? StopSequences { get; set; }
@@ -106,18 +122,34 @@ public sealed class CreateMessageRequestParams : RequestParams
     /// <summary>
     /// Gets or sets the temperature to use for sampling, as requested by the server.
     /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Temperature controls randomness in model responses. Higher values produce higher randomness,
+    /// and lower values produce more stable output. The valid range depends on the model provider.
+    /// </para>
+    /// <para>
+    /// The client may modify or ignore this value.
+    /// </para>
+    /// </remarks>
     [JsonPropertyName("temperature")]
     public float? Temperature { get; set; }
 
     /// <summary>
     /// Gets or sets tools that the model can use during generation.
     /// </summary>
+    /// <remarks>
+    /// The tool definitions in this array are scoped to this sampling request.
+    /// They do not need to correspond to tools registered on the server via <see cref="RequestMethods.ToolsList"/>.
+    /// </remarks>
     [JsonPropertyName("tools")]
     public IList<Tool>? Tools { get; set; }
 
     /// <summary>
     /// Gets or sets controls for how the model uses tools.
     /// </summary>
+    /// <remarks>
+    /// This controls whether and how the model uses the request-scoped <see cref="Tools"/> during sampling.
+    /// </remarks>
     [JsonPropertyName("toolChoice")]
     public ToolChoice? ToolChoice { get; set; }
 

src/ModelContextProtocol.Core/Protocol/CreateMessageResult.cs

@@ -41,7 +41,7 @@ public sealed class CreateMessageResult : Result
     /// <remarks>
     /// Standard values include:
     /// <list type="bullet">
-    ///   <item><term>endTurn</term><description>The model naturally completed its response.</description></item>
+    ///   <item><term>endTurn</term><description>The participant is yielding the conversation to the other party.</description></item>
     ///   <item><term>maxTokens</term><description>The response was truncated due to reaching token limits.</description></item>
     ///   <item><term>stopSequence</term><description>A specific stop sequence was encountered during generation.</description></item>
     ///   <item><term>toolUse</term><description>The model wants to use one or more tools.</description></item>

src/ModelContextProtocol.Core/Protocol/InitializeResult.cs

@@ -65,9 +65,10 @@ public sealed class InitializeResult : Result
     /// </summary>
     /// <remarks>
     /// <para>
-    /// These instructions provide guidance to clients on how to effectively use the server's capabilities.
-    /// They can include details about available tools, expected input formats, limitations,
-    /// or any other information that helps clients interact with the server properly.
+    /// These instructions should focus on guidance that helps a model use the server effectively,
+    /// such as workflow tips, capability relationships, and server-specific conventions.
+    /// They should avoid repeating tool descriptions, prompt descriptions, or resource descriptions
+    /// that are already available through other protocol responses.
     /// </para>
     /// <para>
     /// Client applications often use these instructions as system messages for LLM interactions

src/ModelContextProtocol.Core/Protocol/ReadResourceRequestParams.cs

@@ -7,8 +7,18 @@ namespace ModelContextProtocol.Protocol;
 /// Represents the parameters used with a <see cref="RequestMethods.ResourcesRead"/> request from a client to get a resource provided by a server.
 /// </summary>
 /// <remarks>
+/// <para>
 /// The server will respond with a <see cref="ReadResourceResult"/> containing the resulting resource data.
+/// </para>
+/// <para>
+/// Alternatively, if the resource URI uses the <c>https://</c> scheme, clients may fetch the resource
+/// directly from the web instead of using <see cref="RequestMethods.ResourcesRead"/>.
+/// Servers should only use the <c>https://</c> scheme when the client is able to fetch and load the
+/// resource directly on its own.
+/// </para>
+/// <para>
 /// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </para>
 /// </remarks>
 public sealed class ReadResourceRequestParams : RequestParams
 {

src/ModelContextProtocol.Core/Server/McpServerOptions.cs

@@ -54,8 +54,9 @@ public sealed class McpServerOptions
     /// </summary>
     /// <remarks>
     /// These instructions are sent to clients during the initialization handshake and provide
-    /// guidance on how to effectively use the server's capabilities. They can include details
-    /// about available tools, expected input formats, limitations, or other helpful information.
+    /// guidance on how to effectively use the server's capabilities. They should focus on
+    /// information that helps models use the server effectively and should not duplicate
+    /// tool, prompt, or resource descriptions already exposed elsewhere.
     /// Client applications typically use these instructions as system messages for LLM interactions
     /// to provide context about available functionality.
     /// </remarks>

tests/ModelContextProtocol.AspNetCore.Tests/ClientConformanceTests.cs

@@ -1,5 +1,6 @@
 using System.Diagnostics;
 using System.Text;
+using System.Text.RegularExpressions;
 using ModelContextProtocol.Tests.Utils;
 
 namespace ModelContextProtocol.ConformanceTests;
@@ -118,10 +119,32 @@ public async Task RunConformanceTest(string scenario)
             );
         }
 
+        var output = outputBuilder.ToString();
+        var error = errorBuilder.ToString();
+        var success = process.ExitCode == 0 || HasOnlyWarnings(output, error);
+
         return (
-            Success: process.ExitCode == 0,
-            Output: outputBuilder.ToString(),
-            Error: errorBuilder.ToString()
+            Success: success,
+            Output: output,
+            Error: error
         );
     }
+
+    /// <summary>
+    /// Checks if the conformance test output indicates that all checks passed with only
+    /// warnings (no actual failures). The conformance runner exits with code 1 for warnings,
+    /// but warnings represent acceptable behavior (e.g., timing tolerances in CI environments).
+    /// </summary>
+    private static bool HasOnlyWarnings(string output, string error)
+    {
+        // The conformance runner outputs a summary line like:
+        //   "Passed: 2/2, 0 failed, 1 warnings"
+        // If there are 0 failures but warnings > 0, the test behavior is acceptable.
+        var combined = output + error;
+        var match = Regex.Match(combined, @"(?<failed>\d+) failed, (?<warnings>\d+) warnings");
+        return match.Success
+            && match.Groups["failed"].Value == "0"
+            && int.TryParse(match.Groups["warnings"].Value, out var warnings)
+            && warnings > 0;
+    }
 }

tests/ModelContextProtocol.AspNetCore.Tests/SseServerIntegrationTests.cs

@@ -26,6 +26,7 @@ public async Task EventSourceResponse_Includes_ExpectedHeaders()
         Assert.NotNull(sseResponse.Headers.CacheControl);
         Assert.True(sseResponse.Headers.CacheControl.NoStore);
         Assert.True(sseResponse.Headers.CacheControl.NoCache);
+        Assert.Equal("no", Assert.Single(sseResponse.Headers.GetValues("X-Accel-Buffering")));
     }
 
     [Fact]