Fix XML documentation spelling, grammar, and correctness issues across SDK (#1372)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Stephen Toub <stoub@microsoft.com>
Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com>

src/Common/Experimentals.cs

@@ -3,7 +3,7 @@ using System.Diagnostics.CodeAnalysis;
 namespace ModelContextProtocol;
 
 /// <summary>
-/// Defines diagnostic IDs, Messages, and Urls for APIs annotated with <see cref="ExperimentalAttribute"/>.
+/// Defines diagnostic IDs, messages, and URLs for APIs annotated with <see cref="ExperimentalAttribute"/>.
 /// </summary>
 /// <remarks>
 /// When an experimental API is associated with an experimental specification, the message

src/Common/Obsoletions.cs

@@ -1,10 +1,10 @@
 namespace ModelContextProtocol;
 
 /// <summary>
-/// Defines diagnostic IDs, Messages, and Urls for APIs annotated with <see cref="ObsoleteAttribute"/>.
+/// Defines diagnostic IDs, messages, and URLs for APIs annotated with <see cref="ObsoleteAttribute"/>.
 /// </summary>
 /// <remarks>
-/// When a deprecated API is associated with an specification change, the message
+/// When a deprecated API is associated with a specification change, the message
 /// should refer to the specification version that introduces the change and the SEP
 /// when available. If there is a SEP associated with the experimental API, the Url should
 /// point to the SEP issue.

src/ModelContextProtocol.Analyzers/EquatableArray.cs

@@ -15,7 +15,7 @@ internal readonly struct EquatableArray<T> : IEnumerable<T>, IEquatable<Equatabl
     /// <param name="source">The source to enumerate and wrap.</param>
     public EquatableArray(IEnumerable<T> source) => _array = source.ToArray();
 
-    /// <param name="source">The source to wrap.</param>
+    /// <param name="array">The source to wrap.</param>
     public EquatableArray(T[] array) => _array = array;
 
     /// <summary>Gets a reference to an item at a specified position within the array.</summary>

src/ModelContextProtocol.AspNetCore/Authentication/McpAuthenticationExtensions.cs

@@ -4,12 +4,12 @@ using ModelContextProtocol.AspNetCore.Authentication;
 namespace Microsoft.Extensions.DependencyInjection;
 
 /// <summary>
-/// Extension methods for adding MCP authorization support to ASP.NET Core applications.
+/// Extension methods for adding MCP authentication support to ASP.NET Core applications.
 /// </summary>
 public static class McpAuthenticationExtensions
 {
     /// <summary>
-    /// Adds MCP authorization support to the application.
+    /// Adds MCP authentication support to the application.
     /// </summary>
     /// <param name="builder">The authentication builder.</param>
     /// <param name="configureOptions">An action to configure MCP authentication options.</param>
@@ -26,7 +26,7 @@ public static class McpAuthenticationExtensions
     }
 
     /// <summary>
-    /// Adds MCP authorization support to the application with a custom scheme name.
+    /// Adds MCP authentication support to the application with a custom scheme name.
     /// </summary>
     /// <param name="builder">The authentication builder.</param>
     /// <param name="authenticationScheme">The authentication scheme name to use.</param>

src/ModelContextProtocol.AspNetCore/HttpMcpServerBuilderExtensions.cs

@@ -20,7 +20,7 @@ public static class HttpMcpServerBuilderExtensions
     /// <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>.
+    /// to control things like port binding and 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

@@ -5,7 +5,7 @@ namespace ModelContextProtocol.AspNetCore;
 
 /// <summary>
 /// Represents configuration options for <see cref="M:McpEndpointRouteBuilderExtensions.MapMcp"/>,
-/// which implements the Streaming HTTP transport for the Model Context Protocol.
+/// which implements the Streamable 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-11-25/basic/transports#streamable-http"/>
 /// </summary>
 /// <remarks>
@@ -23,7 +23,7 @@ public class HttpServerTransportOptions
     /// Gets or sets an optional asynchronous callback for running new MCP sessions manually.
     /// </summary>
     /// <remarks>
-    /// This callback is useful for running logic before a sessions starts and after it completes.
+    /// This callback is useful for running logic before a session starts and after it completes.
     /// </remarks>
     public Func<HttpContext, McpServer, CancellationToken, Task>? RunSessionHandler { get; set; }
 
@@ -36,7 +36,7 @@ public class HttpServerTransportOptions
     /// </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.
+    /// the <see cref="RunSessionHandler"/> will be called once 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
     /// might arrive at another ASP.NET Core application process.
     /// Client sampling, elicitation, and roots capabilities are also disabled in stateless mode, because the server cannot make requests.
@@ -87,7 +87,7 @@ public class HttpServerTransportOptions
     public TimeSpan IdleTimeout { get; set; } = TimeSpan.FromHours(2);
 
     /// <summary>
-    /// 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.
+    /// Gets or sets the 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.

src/ModelContextProtocol.Core/AIContentExtensions.cs

@@ -367,7 +367,7 @@ public static class AIContentExtensions
     /// </para>
     /// <para>
     /// Each <see cref="ResourceContents"/> object is converted using <see cref="ToAIContent(ResourceContents)"/>,
-    /// preserving the type-specific conversion logic: text resources become <see cref="TextContentBlock"/> objects and
+    /// preserving the type-specific conversion logic: text resources become <see cref="TextContent"/> objects and
     /// binary resources become <see cref="DataContent"/> objects.
     /// </para>
     /// </remarks>

src/ModelContextProtocol.Core/Authentication/ClientOAuthProvider.cs

@@ -772,7 +772,7 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
     /// <param name="response">The HTTP response containing the WWW-Authenticate header.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
     /// <returns>The resource metadata if the resource matches the server, otherwise throws an exception.</returns>
-    /// <exception cref="InvalidOperationException">Thrown when the response is not a 401, the metadata can't be fetched, or the resource URI doesn't match the server URL.</exception>
+    /// <exception cref="McpException">Thrown when the metadata can't be fetched or the resource URI doesn't match the server URL.</exception>
     private async Task<ProtectedResourceMetadata> ExtractProtectedResourceMetadata(HttpResponseMessage response, CancellationToken cancellationToken)
     {
         Uri resourceUri = _serverUrl;

src/ModelContextProtocol.Core/Authentication/ProtectedResourceMetadata.cs

@@ -4,8 +4,7 @@ using System.Text.Json.Serialization;
 namespace ModelContextProtocol.Authentication;
 
 /// <summary>
-/// Represents the resource metadata for OAuth authorization as defined in RFC 9396.
-/// Defined by <see href="https://datatracker.ietf.org/doc/rfc9728/">RFC 9728</see>.
+/// Represents the resource metadata for OAuth authorization as defined in <see href="https://datatracker.ietf.org/doc/rfc9728/">RFC 9728</see>.
 /// </summary>
 public sealed class ProtectedResourceMetadata
 {

src/ModelContextProtocol.Core/Client/HttpClientTransportOptions.cs

@@ -105,7 +105,7 @@ public sealed class HttpClientTransportOptions
     public bool OwnsSession { get; set; } = true;
 
     /// <summary>
-    /// Gets sor sets the authorization provider to use for authentication.
+    /// Gets or sets the authorization provider to use for authentication.
     /// </summary>
     public ClientOAuthOptions? OAuth { get; set; }
 
@@ -127,13 +127,13 @@ public sealed class HttpClientTransportOptions
     /// Gets or sets the default interval at which the client attempts reconnection after an SSE stream is disconnected.
     /// </summary>
     /// <remarks>
-    /// <p>
+    /// <para>
     /// The default value is 1 second.
-    /// </p>
-    /// <p>
+    /// </para>
+    /// <para>
     /// If the server sends a message specifying a different reconnection interval, that new value will be used for all
     /// subsequent reconnection attempts for that stream.
-    /// </p>
+    /// </para>
     /// </remarks>
     public TimeSpan DefaultReconnectionInterval { get; set; } = TimeSpan.FromSeconds(1);
 }

src/ModelContextProtocol.Core/Client/IClientTransport.cs

@@ -11,7 +11,7 @@ namespace ModelContextProtocol.Client;
 /// and servers, allowing different transport protocols to be used interchangeably.
 /// </para>
 /// <para>
-/// When creating an <see cref="McpClient"/>, <see cref="McpClient"/> is typically used, and is
+/// When creating an <see cref="McpClient"/>, <see cref="McpClient.CreateAsync"/> is typically used, and is
 /// provided with the <see cref="IClientTransport"/> based on expected server configuration.
 /// </para>
 /// </remarks>

src/ModelContextProtocol.Core/Client/McpClientHandlers.cs

@@ -14,7 +14,7 @@ namespace ModelContextProtocol.Client;
 /// <para>
 /// Each handler in this class corresponds to a specific client endpoint in the Model Context Protocol and
 /// is responsible for processing a particular type of message. The handlers are used to customize
-/// the behavior of the MCP server by providing implementations for the various protocol operations.
+/// the behavior of the MCP client by providing implementations for the various protocol operations.
 /// </para>
 /// <para>
 /// When a server sends a message to the client, the appropriate handler is invoked to process it
@@ -47,7 +47,7 @@ public sealed class McpClientHandlers
     /// Gets or sets the handler for <see cref="RequestMethods.RootsList"/> requests.
     /// </summary>
     /// <remarks>
-    /// This handler is invoked when a client sends a <see cref="RequestMethods.RootsList"/> request to retrieve available roots.
+    /// This handler is invoked when the server sends a <see cref="RequestMethods.RootsList"/> request to retrieve available roots.
     /// The handler receives request parameters and should return a <see cref="ListRootsResult"/> containing the collection of available roots.
     /// </remarks>
     public Func<ListRootsRequestParams?, CancellationToken, ValueTask<ListRootsResult>>? RootsHandler { get; set; }

src/ModelContextProtocol.Core/Client/McpClientOptions.cs

@@ -43,7 +43,7 @@ public sealed class McpClientOptions
     /// 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.
+    /// but will allow any supported version that the server advertises in its response.
     /// </para>
     /// </remarks>
     public string? ProtocolVersion { get; set; }

src/ModelContextProtocol.Core/Client/McpClientTool.cs

@@ -171,7 +171,7 @@ public sealed class McpClientTool : AIFunction
     /// </returns>
     /// <remarks>
     /// The base <see cref="AIFunction.InvokeAsync"/> method is overridden to invoke this <see cref="CallAsync"/> method.
-    /// The only difference in behavior is that <see cref="AIFunction.InvokeAsync"/> serializes the resulting <see cref="CallToolResult"/>"/>
+    /// The only difference in behavior is that <see cref="AIFunction.InvokeAsync"/> serializes the resulting <see cref="CallToolResult"/>
     /// such that the <see cref="object"/> returned is a <see cref="JsonElement"/> containing the serialized <see cref="CallToolResult"/>.
     /// This <see cref="CallAsync"/> method is intended to be called directly by user code, whereas the base <see cref="AIFunction.InvokeAsync"/>
     /// is intended to be used polymorphically via the base class, typically as part of an <see cref="IChatClient"/> operation.
@@ -247,7 +247,6 @@ public sealed class McpClientTool : AIFunction
     /// the value returned from this instance's <see cref="AITool.Name"/>.
     /// </para>
     /// </remarks>
-    /// <returns>A new instance of <see cref="McpClientTool"/> with the provided name.</returns>
     public McpClientTool WithName(string name) =>
         new(_client, ProtocolTool, JsonSerializerOptions, name, _description, _progress, _meta);
 

src/ModelContextProtocol.Core/Client/ResumeClientSessionOptions.cs

@@ -8,7 +8,7 @@ namespace ModelContextProtocol.Client;
 public sealed class ResumeClientSessionOptions
 {
     /// <summary>
-    /// Gets or sets the server capabilities that were negotiated during the original session setialization.
+    /// Gets or sets the server capabilities that were negotiated during the original session initialization.
     /// </summary>
     public required ServerCapabilities ServerCapabilities { get; set; }
 

src/ModelContextProtocol.Core/McpException.cs

@@ -3,7 +3,7 @@ using ModelContextProtocol.Protocol;
 namespace ModelContextProtocol;
 
 /// <summary>
-/// Represents an exception that is thrown when an Model Context Protocol (MCP) error occurs.
+/// Represents an exception that is thrown when a Model Context Protocol (MCP) error occurs.
 /// </summary>
 /// <remarks>
 /// The <see cref="Exception.Message"/> from a <see cref="McpException"/> might be propagated to the remote

src/ModelContextProtocol.Core/McpSession.Methods.cs

@@ -49,7 +49,7 @@ public abstract partial class McpSession : IAsyncDisposable
     /// <param name="method">The JSON-RPC method name to invoke.</param>
     /// <param name="parameters">The request parameters.</param>
     /// <param name="parametersTypeInfo">The type information for request parameter serialization.</param>
-    /// <param name="resultTypeInfo">The type information for request parameter deserialization.</param>
+    /// <param name="resultTypeInfo">The type information for result deserialization.</param>
     /// <param name="requestId">The request ID for the request.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>A task that represents the asynchronous operation. The task result contains the deserialized result.</returns>
@@ -138,7 +138,7 @@ public abstract partial class McpSession : IAsyncDisposable
     }
 
     /// <summary>
-    /// Sends a notification to the server with parameters.
+    /// Sends a notification to the connected session with parameters.
     /// </summary>
     /// <param name="method">The JSON-RPC method name to invoke.</param>
     /// <param name="parameters">The request parameters.</param>

src/ModelContextProtocol.Core/McpSession.cs

@@ -17,8 +17,8 @@ namespace ModelContextProtocol;
 /// </list>
 /// </para>
 /// <para>
-/// <see cref="McpSession"/> serves as the base interface for both <see cref="McpClient"/> and
-/// <see cref="McpServer"/> interfaces, providing the common functionality needed for MCP protocol
+/// <see cref="McpSession"/> serves as the base class for both <see cref="McpClient"/> and
+/// <see cref="McpServer"/>, providing the common functionality needed for MCP protocol
 /// communication. Most applications will use these more specific interfaces rather than working with
 /// <see cref="McpSession"/> directly.
 /// </para>
@@ -85,7 +85,7 @@ public abstract partial class McpSession : IAsyncDisposable
     /// <summary>Registers a handler to be invoked when a notification for the specified method is received.</summary>
     /// <param name="method">The notification method.</param>
     /// <param name="handler">The handler to be invoked.</param>
-    /// <returns>An <see cref="IDisposable"/> that will remove the registered handler when disposed.</returns>
+    /// <returns>An <see cref="IAsyncDisposable"/> that will remove the registered handler when disposed.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="method"/> or <paramref name="handler"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentException"><paramref name="method"/> is empty or composed entirely of whitespace.</exception>
     public abstract IAsyncDisposable RegisterNotificationHandler(string method, Func<JsonRpcNotification, CancellationToken, ValueTask> handler);

src/ModelContextProtocol.Core/McpSessionHandler.cs

@@ -47,7 +47,7 @@ internal sealed partial class McpSessionHandler : IAsyncDisposable
     /// Checks if the given protocol version supports priming events.
     /// </summary>
     /// <param name="protocolVersion">The protocol version to check.</param>
-    /// <returns>True if the protocol version supports resumability.</returns>
+    /// <returns>True if the protocol version supports priming events.</returns>
     /// <remarks>
     /// Priming events are only supported in protocol version &gt;= 2025-11-25.
     /// Older clients may crash when receiving SSE events with empty data.
@@ -463,7 +463,7 @@ internal sealed partial class McpSessionHandler : IAsyncDisposable
 
     /// <summary>
     /// Sends a JSON-RPC request to the server.
-    /// It is strongly recommended use the capability-specific methods instead of this one.
+    /// It is strongly recommended to use the capability-specific methods instead of this one.
     /// Use this method for custom requests or those not yet covered explicitly by the endpoint implementation.
     /// </summary>
     /// <param name="request">The JSON-RPC request to send.</param>

src/ModelContextProtocol.Core/NotificationHandlers.cs

@@ -152,7 +152,7 @@ internal sealed class NotificationHandlers
         /// by that handler are no longer in use and may be cleaned up. If <see cref="DisposeAsync"/> were to be invoked
         /// and its task awaited from within the invocation of the handler, however, that would result in deadlock, since
         /// the task wouldn't complete until the invocation completed, and the invocation wouldn't complete until the task
-        /// completed. To circument that, we track via an <see cref="AsyncLocal{Int32}"/> in-flight invocations. If
+        /// completed. To circumvent that, we track via an <see cref="AsyncLocal{Int32}"/> in-flight invocations. If
         /// <see cref="DisposeAsync"/> detects it's being invoked from within an invocation, it will avoid waiting. For
         /// simplicity, we don't require that it's the same handler.
         /// </remarks>