Docs edit pass (MCP.AspNetCore and a few other files) (#1034)

Co-authored-by: Stephen Toub <[email protected]>
Co-authored-by: Mike Kistler <[email protected]>

Author: 3 people

src/ModelContextProtocol.AspNetCore/Authentication/McpAuthenticationDefaults.cs

@@ -1,7 +1,7 @@
 namespace ModelContextProtocol.AspNetCore.Authentication;
 
 /// <summary>
-/// Default values used by MCP authentication.
+/// Represents default values used by MCP authentication.
 /// </summary>
 public static class McpAuthenticationDefaults
 {
@@ -14,4 +14,4 @@ public static class McpAuthenticationDefaults
     /// The default value used for authentication scheme display name.
     /// </summary>
     public const string DisplayName = "MCP Authentication";
-}
+}

src/ModelContextProtocol.AspNetCore/Authentication/McpAuthenticationEvents.cs

@@ -6,12 +6,12 @@
 public class McpAuthenticationEvents
 {
     /// <summary>
-    /// Gets or sets the function that is invoked when resource metadata is requested.
+    /// Gets or sets the function that's invoked when resource metadata is requested.
     /// </summary>
     /// <remarks>
     /// This function is called when a resource metadata request is made to the protected resource metadata endpoint.
     /// The implementer should set the <see cref="ResourceMetadataRequestContext.ResourceMetadata"/> property
     /// to provide the appropriate metadata for the current request.
     /// </remarks>
     public Func<ResourceMetadataRequestContext, Task> OnResourceMetadataRequest { get; set; } = context => Task.CompletedTask;
-}
+}

src/ModelContextProtocol.AspNetCore/Authentication/McpAuthenticationHandler.cs

@@ -8,7 +8,7 @@
 namespace ModelContextProtocol.AspNetCore.Authentication;
 
 /// <summary>
-/// Authentication handler for MCP protocol that adds resource metadata to challenge responses
+/// Represents an authentication handler for MCP protocol that adds resource metadata to challenge responses
 /// and handles resource metadata endpoint requests.
 /// </summary>
 public class McpAuthenticationHandler : AuthenticationHandler<McpAuthenticationOptions>, IAuthenticationRequestHandler

src/ModelContextProtocol.AspNetCore/Authentication/McpAuthenticationOptions.cs

@@ -4,7 +4,7 @@
 namespace ModelContextProtocol.AspNetCore.Authentication;
 
 /// <summary>
-/// Options for the MCP authentication handler.
+/// Represents options for the MCP authentication handler.
 /// </summary>
 public class McpAuthenticationOptions : AuthenticationSchemeOptions
 {
@@ -25,16 +25,16 @@ public McpAuthenticationOptions()
     /// Gets or sets the events used to handle authentication events.
     /// </summary>
     public new McpAuthenticationEvents Events
-    { 
-        get => (McpAuthenticationEvents)base.Events!; 
+    {
+        get => (McpAuthenticationEvents)base.Events!;
         set => base.Events = value;
     }
 
     /// <summary>
-    /// The URI to the resource metadata document.
+    /// Gets or sets the URI to the resource metadata document.
     /// </summary>
     /// <remarks>
-    /// This URI will be included in the WWW-Authenticate header when a 401 response is returned.
+    /// This URI is included in the WWW-Authenticate header when a 401 response is returned.
     /// </remarks>
     public Uri ResourceMetadataUri { get; set; }
 
@@ -46,4 +46,4 @@ public McpAuthenticationOptions()
     /// supported scopes, and other information needed for clients to authenticate.
     /// </remarks>
     public ProtectedResourceMetadata? ResourceMetadata { get; set; }
-}
+}

src/ModelContextProtocol.AspNetCore/Authentication/ResourceMetadataRequestContext.cs

@@ -5,7 +5,7 @@
 namespace ModelContextProtocol.AspNetCore.Authentication;
 
 /// <summary>
-/// Context for resource metadata request events.
+/// Represents the context for resource metadata request events.
 /// </summary>
 public class ResourceMetadataRequestContext : HandleRequestContext<McpAuthenticationOptions>
 {

src/ModelContextProtocol.AspNetCore/HttpMcpServerBuilderExtensions.cs

@@ -13,13 +13,15 @@ public static class HttpMcpServerBuilderExtensions
 {
     /// <summary>
     /// Adds the services necessary for <see cref="M:McpEndpointRouteBuilderExtensions.MapMcp"/>
-    /// to handle MCP requests and sessions using the MCP Streamable HTTP transport. For more information on configuring the underlying HTTP server
-    /// to control things like port binding custom TLS certificates, see the <see href="https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis">Minimal APIs quick reference</see>.
+    /// to handle MCP requests and sessions using the MCP Streamable HTTP transport.
     /// </summary>
     /// <param name="builder">The builder instance.</param>
     /// <param name="configureOptions">Configures options for the Streamable HTTP transport. This allows configuring per-session
     /// <see cref="McpServerOptions"/> and running logic before and after a session.</param>
     /// <returns>The builder provided in <paramref name="builder"/>.</returns>
+    /// <remarks>For more information on configuring the underlying HTTP server
+    /// to control things like port binding custom TLS certificates, see the <see href="https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis">Minimal APIs quick reference</see>.
+    /// </remarks>
     /// <exception cref="ArgumentNullException"><paramref name="builder"/> is <see langword="null"/>.</exception>
     public static IMcpServerBuilder WithHttpTransport(this IMcpServerBuilder builder, Action<HttpServerTransportOptions>? configureOptions = null)
     {

src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs

@@ -4,10 +4,13 @@
 namespace ModelContextProtocol.AspNetCore;
 
 /// <summary>
-/// Configuration options for <see cref="M:McpEndpointRouteBuilderExtensions.MapMcp"/>.
+/// Represents configuration options for <see cref="M:McpEndpointRouteBuilderExtensions.MapMcp"/>,
 /// which implements the Streaming HTTP transport for the Model Context Protocol.
 /// See the protocol specification for details on the Streamable HTTP transport. <see href="https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http"/>
 /// </summary>
+/// <remarks>
+/// For details on the Streamable HTTP transport, see the <see href="https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http">protocol specification</see>.
+/// </remarks>
 public class HttpServerTransportOptions
 {
     /// <summary>
@@ -18,61 +21,71 @@ public class HttpServerTransportOptions
 
     /// <summary>
     /// Gets or sets an optional asynchronous callback for running new MCP sessions manually.
-    /// This is useful for running logic before a sessions starts and after it completes.
     /// </summary>
+    /// <remarks>
+    /// This callback is useful for running logic before a sessions starts and after it completes.
+    /// </remarks>
     public Func<HttpContext, McpServer, CancellationToken, Task>? RunSessionHandler { get; set; }
 
     /// <summary>
-    /// Gets or sets whether the server should run in a stateless mode which does not track state between requests
+    /// Gets or sets a value that indicates whether the server runs in a stateless mode that doesn't track state between requests,
     /// allowing for load balancing without session affinity.
     /// </summary>
+    /// <value>
+    /// <see langword="true"/> if the server runs in a stateless mode; <see langword="false"/> if the server tracks state between requests. The default is <see langword="false"/>.
+    /// </value>
     /// <remarks>
     /// If <see langword="true"/>, <see cref="McpSession.SessionId"/> will be null, and the "MCP-Session-Id" header will not be used,
     /// the <see cref="RunSessionHandler"/> will be called once for for each request, and the "/sse" endpoint will be disabled.
     /// Unsolicited server-to-client messages and all server-to-client requests are also unsupported, because any responses
-    /// may arrive at another ASP.NET Core application process.
+    /// might arrive at another ASP.NET Core application process.
     /// Client sampling and roots capabilities are also disabled in stateless mode, because the server cannot make requests.
-    /// Defaults to <see langword="false"/>.
     /// </remarks>
     public bool Stateless { get; set; }
 
     /// <summary>
-    /// Gets or sets whether the server should use a single execution context for the entire session.
+    /// Gets or sets a value that indicates whether the server uses a single execution context for the entire session.
+    /// </summary>
+    /// <value>
+    /// <see langword="true"/> if the server uses a single execution context for the entire session; otherwise, <see langword="false"/>. The default is <see langword="false"/>.
+    /// </value>
+    /// <remarks>
     /// If <see langword="false"/>, handlers like tools get called with the <see cref="ExecutionContext"/>
-    /// belonging to the corresponding HTTP request which can change throughout the MCP session.
+    /// belonging to the corresponding HTTP request, which can change throughout the MCP session.
     /// If <see langword="true"/>, handlers will get called with the same <see cref="ExecutionContext"/>
     /// used to call <see cref="ConfigureSessionOptions" /> and <see cref="RunSessionHandler"/>.
-    /// </summary>
-    /// <remarks>
     /// Enabling a per-session <see cref="ExecutionContext"/> can be useful for setting <see cref="AsyncLocal{T}"/> variables
     /// that persist for the entire session, but it prevents you from using IHttpContextAccessor in handlers.
-    /// Defaults to <see langword="false"/>.
     /// </remarks>
     public bool PerSessionExecutionContext { get; set; }
 
     /// <summary>
     /// Gets or sets the duration of time the server will wait between any active requests before timing out an MCP session.
     /// </summary>
+    /// <value>
+    /// The amount of time the server waits between any active requests before timing out an MCP session. The default is 2 hours.
+    /// </value>
     /// <remarks>
-    /// This is checked in background every 5 seconds. A client trying to resume a session will receive a 404 status code
+    /// This value is checked in the background every 5 seconds. A client trying to resume a session will receive a 404 status code
     /// and should restart their session. A client can keep their session open by keeping a GET request open.
-    /// Defaults to 2 hours.
     /// </remarks>
     public TimeSpan IdleTimeout { get; set; } = TimeSpan.FromHours(2);
 
     /// <summary>
-    /// Gets or sets maximum number of idle sessions to track in memory. This is used to limit the number of sessions that can be idle at once.
+    /// Gets or sets maximum number of idle sessions to track in memory. This value is used to limit the number of sessions that can be idle at once.
     /// </summary>
+    /// <value>
+    /// The maximum number of idle sessions to track in memory. The default is 10,000 sessions.
+    /// </value>
     /// <remarks>
-    /// Past this limit, the server will log a critical error and terminate the oldest idle sessions even if they have not reached
-    /// their <see cref="IdleTimeout"/> until the idle session count is below this limit. Clients that keep their session open by
-    /// keeping a GET request open will not count towards this limit.
-    /// Defaults to 10,000 sessions.
+    /// Past this limit, the server logs a critical error and terminates the oldest idle sessions, even if they have not reached
+    /// their <see cref="IdleTimeout"/>, until the idle session count is below this limit. Clients that keep their session open by
+    /// keeping a GET request open don't count towards this limit.
     /// </remarks>
     public int MaxIdleSessionCount { get; set; } = 10_000;
 
     /// <summary>
-    /// Used for testing the <see cref="IdleTimeout"/>.
+    /// Gets or sets the time provider that's used for testing the <see cref="IdleTimeout"/>.
     /// </summary>
     public TimeProvider TimeProvider { get; set; } = TimeProvider.System;
 }

src/ModelContextProtocol.AspNetCore/McpEndpointRouteBuilderExtensions.cs

@@ -15,12 +15,14 @@ public static class McpEndpointRouteBuilderExtensions
 {
     /// <summary>
     /// Sets up endpoints for handling MCP Streamable HTTP transport.
-    /// See <see href="https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http">the 2025-06-18 protocol specification</see> for details about the Streamable HTTP transport.
-    /// Also maps legacy SSE endpoints for backward compatibility at the path "/sse" and "/message". <see href="https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse">the 2024-11-05 protocol specification</see> for details about the HTTP with SSE transport.
     /// </summary>
     /// <param name="endpoints">The web application to attach MCP HTTP endpoints.</param>
     /// <param name="pattern">The route pattern prefix to map to.</param>
     /// <returns>Returns a builder for configuring additional endpoint conventions like authorization policies.</returns>
+    /// <remarks>
+    /// For details about the Streamable HTTP transport, see the <see href="https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http">2025-06-18 protocol specification</see>.
+    /// This method also maps legacy SSE endpoints for backward compatibility at the path "/sse" and "/message". For details about the HTTP with SSE transport, see the <see href="https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse">2024-11-05 protocol specification</see>.
+    /// </remarks>
     public static IEndpointConventionBuilder MapMcp(this IEndpointRouteBuilder endpoints, [StringSyntax("Route")] string pattern = "")
     {
         var streamableHttpHandler = endpoints.ServiceProvider.GetService<StreamableHttpHandler>() ??