AI seeded comments from robch and then edited by stephentoub (#238)

* AI generated `///` comment updates

* Fix compilation issues

* Fix incorrect XML comment structure

* Update all Client comments

* Update all Configuration comments

* Update all Messages comments

* Update all Transport comments

* Update all Types comments

* Update all Server comments

* Undo some commenting

---------

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

Author: Rob Chambers

src/Common/Polyfills/System/IO/TextWriterExtensions.cs

@@ -1,6 +1,3 @@
-using ModelContextProtocol.Utils;
-using System.Runtime.InteropServices;
-
 namespace System.IO;
 
 internal static class TextWriterExtensions

src/Common/Throw.cs

@@ -1,4 +1,4 @@
-using System.Diagnostics.CodeAnalysis;
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 
 namespace ModelContextProtocol.Utils;
@@ -38,4 +38,4 @@ private static void ThrowArgumentNullOrWhiteSpaceException(string? parameterName
 
     [DoesNotReturn]
     private static void ThrowArgumentNullException(string? parameterName) => throw new ArgumentNullException(parameterName);
-}
+}

src/ModelContextProtocol.AspNetCore/McpEndpointRouteBuilderExtensions.cs

@@ -18,7 +18,7 @@
 namespace Microsoft.AspNetCore.Builder;
 
 /// <summary>
-/// Extension methods for <see cref="IEndpointRouteBuilder"/> to add MCP endpoints.
+/// Provides extension methods for <see cref="IEndpointRouteBuilder"/> to add MCP endpoints.
 /// </summary>
 public static class McpEndpointRouteBuilderExtensions
 {

src/ModelContextProtocol/AIContentExtensions.cs

@@ -1,4 +1,4 @@
-using Microsoft.Extensions.AI;
+using Microsoft.Extensions.AI;
 using ModelContextProtocol.Protocol.Types;
 using ModelContextProtocol.Utils;
 using ModelContextProtocol.Utils.Json;
@@ -7,12 +7,24 @@
 
 namespace ModelContextProtocol;
 
-/// <summary>Provides helpers for conversions related to <see cref="AIContent"/>.</summary>
+/// <summary>
+/// Provides extension methods for converting between Model Context Protocol (MCP) types and Microsoft.Extensions.AI types.
+/// </summary>
+/// <remarks>
+/// This class serves as an adapter layer between Model Context Protocol (MCP) types and the <see cref="AIContent"/> model types
+/// from the Microsoft.Extensions.AI namespace.
+/// </remarks>
 public static class AIContentExtensions
 {
-    /// <summary>Creates a <see cref="ChatMessage"/> from a <see cref="PromptMessage"/>.</summary>
-    /// <param name="promptMessage">The message to convert.</param>
-    /// <returns>The created <see cref="ChatMessage"/>.</returns>
+    /// <summary>
+    /// Converts a <see cref="PromptMessage"/> to a <see cref="ChatMessage"/> object.
+    /// </summary>
+    /// <param name="promptMessage">The prompt message to convert.</param>
+    /// <returns>A <see cref="ChatMessage"/> object created from the prompt message.</returns>
+    /// <remarks>
+    /// This method transforms a protocol-specific <see cref="PromptMessage"/> from the Model Context Protocol
+    /// into a standard <see cref="ChatMessage"/> object that can be used with AI client libraries.
+    /// </remarks>
     public static ChatMessage ToChatMessage(this PromptMessage promptMessage)
     {
         Throw.IfNull(promptMessage);
@@ -25,19 +37,32 @@ public static ChatMessage ToChatMessage(this PromptMessage promptMessage)
         };
     }
 
-    /// <summary>Creates <see cref="ChatMessage"/>s from a <see cref="GetPromptResult"/>.</summary>
-    /// <param name="promptResult">The messages to convert.</param>
-    /// <returns>The created <see cref="ChatMessage"/>.</returns>
+    /// <summary>
+    /// Converts a <see cref="GetPromptResult"/> to a list of <see cref="ChatMessage"/> objects.
+    /// </summary>
+    /// <param name="promptResult">The prompt result containing messages to convert.</param>
+    /// <returns>A list of <see cref="ChatMessage"/> objects created from the prompt messages.</returns>
+    /// <remarks>
+    /// This method transforms protocol-specific <see cref="PromptMessage"/> objects from a Model Context Protocol
+    /// prompt result into standard <see cref="ChatMessage"/> objects that can be used with AI client libraries.
+    /// </remarks>
     public static IList<ChatMessage> ToChatMessages(this GetPromptResult promptResult)
     {
         Throw.IfNull(promptResult);
 
         return promptResult.Messages.Select(m => m.ToChatMessage()).ToList();
     }
 
-    /// <summary>Gets <see cref="PromptMessage"/> instances for the specified <see cref="ChatMessage"/>.</summary>
-    /// <param name="chatMessage">The message for which to extract its contents as <see cref="PromptMessage"/> instances.</param>
-    /// <returns>The converted content.</returns>
+    /// <summary>
+    /// Converts a <see cref="ChatMessage"/> to a list of <see cref="PromptMessage"/> objects.
+    /// </summary>
+    /// <param name="chatMessage">The chat message to convert.</param>
+    /// <returns>A list of <see cref="PromptMessage"/> objects created from the chat message's contents.</returns>
+    /// <remarks>
+    /// This method transforms standard <see cref="ChatMessage"/> objects used with AI client libraries into
+    /// protocol-specific <see cref="PromptMessage"/> objects for the Model Context Protocol system.
+    /// Only representable content items are processed.
+    /// </remarks>
     public static IList<PromptMessage> ToPromptMessages(this ChatMessage chatMessage)
     {
         Throw.IfNull(chatMessage);
@@ -59,6 +84,10 @@ public static IList<PromptMessage> ToPromptMessages(this ChatMessage chatMessage
     /// <summary>Creates a new <see cref="AIContent"/> from the content of a <see cref="Content"/>.</summary>
     /// <param name="content">The <see cref="Content"/> to convert.</param>
     /// <returns>The created <see cref="AIContent"/>.</returns>
+    /// <remarks>
+    /// This method converts Model Context Protocol content types to the equivalent Microsoft.Extensions.AI 
+    /// content types, enabling seamless integration between the protocol and AI client libraries.
+    /// </remarks>
     public static AIContent ToAIContent(this Content content)
     {
         Throw.IfNull(content);
@@ -85,6 +114,10 @@ public static AIContent ToAIContent(this Content content)
     /// <summary>Creates a new <see cref="AIContent"/> from the content of a <see cref="ResourceContents"/>.</summary>
     /// <param name="content">The <see cref="ResourceContents"/> to convert.</param>
     /// <returns>The created <see cref="AIContent"/>.</returns>
+    /// <remarks>
+    /// This method converts Model Context Protocol resource types to the equivalent Microsoft.Extensions.AI 
+    /// content types, enabling seamless integration between the protocol and AI client libraries.
+    /// </remarks>
     public static AIContent ToAIContent(this ResourceContents content)
     {
         Throw.IfNull(content);
@@ -105,6 +138,17 @@ public static AIContent ToAIContent(this ResourceContents content)
     /// <summary>Creates a list of <see cref="AIContent"/> from a sequence of <see cref="Content"/>.</summary>
     /// <param name="contents">The <see cref="Content"/> instances to convert.</param>
     /// <returns>The created <see cref="AIContent"/> instances.</returns>
+    /// <remarks>
+    /// <para>
+    /// This method converts a collection of Model Context Protocol content objects into a collection of
+    /// Microsoft.Extensions.AI content objects. It's useful when working with multiple content items, such as
+    /// when processing the contents of a message or response.
+    /// </para>
+    /// <para>
+    /// Each <see cref="Content"/> object is converted using <see cref="ToAIContent(Content)"/>,
+    /// preserving the type-specific conversion logic for text, images, audio, and resources.
+    /// </para>
+    /// </remarks>
     public static IList<AIContent> ToAIContents(this IEnumerable<Content> contents)
     {
         Throw.IfNull(contents);
@@ -114,7 +158,19 @@ public static IList<AIContent> ToAIContents(this IEnumerable<Content> contents)
 
     /// <summary>Creates a list of <see cref="AIContent"/> from a sequence of <see cref="ResourceContents"/>.</summary>
     /// <param name="contents">The <see cref="ResourceContents"/> instances to convert.</param>
-    /// <returns>The created <see cref="AIContent"/> instances.</returns>
+    /// <returns>A list of <see cref="AIContent"/> objects created from the resource contents.</returns>
+    /// <remarks>
+    /// <para>
+    /// This method converts a collection of Model Context Protocol resource objects into a collection of
+    /// Microsoft.Extensions.AI content objects. It's useful when working with multiple resources, such as
+    /// when processing the contents of a <see cref="ReadResourceResult"/>.
+    /// </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="TextContent"/> objects and
+    /// binary resources become <see cref="DataContent"/> objects.
+    /// </para>
+    /// </remarks>
     public static IList<AIContent> ToAIContents(this IEnumerable<ResourceContents> contents)
     {
         Throw.IfNull(contents);

src/ModelContextProtocol/Client/IMcpClient.cs

@@ -1,28 +1,47 @@
-using ModelContextProtocol.Protocol.Types;
+using ModelContextProtocol.Protocol.Types;
 
 namespace ModelContextProtocol.Client;
 
 /// <summary>
-/// Represents an instance of an MCP client connecting to a specific server.
+/// Represents an instance of a Model Context Protocol (MCP) client that connects to and communicates with an MCP server.
 /// </summary>
 public interface IMcpClient : IMcpEndpoint
 {
     /// <summary>
     /// Gets the capabilities supported by the connected server.
     /// </summary>
+    /// <exception cref="InvalidOperationException">The client is not connected.</exception>
     ServerCapabilities ServerCapabilities { get; }
 
     /// <summary>
     /// Gets the implementation information of the connected server.
     /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This property provides identification details about the connected server, including its name and version.
+    /// It is populated during the initialization handshake and is available after a successful connection.
+    /// </para>
+    /// <para>
+    /// This information can be useful for logging, debugging, compatibility checks, and displaying server
+    /// information to users.
+    /// </para>
+    /// </remarks>
+    /// <exception cref="InvalidOperationException">The client is not connected.</exception>
     Implementation ServerInfo { get; }
 
     /// <summary>
     /// Gets any instructions describing how to use the connected server and its features.
     /// </summary>
     /// <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.
+    /// </para>
+    /// <para>
     /// This can be used by clients to improve an LLM's understanding of available tools, prompts, and resources. 
     /// It can be thought of like a "hint" to the model and may be added to a system prompt.
+    /// </para>
     /// </remarks>
     string? ServerInstructions { get; }
 }

src/ModelContextProtocol/Client/McpClient.cs

@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 using ModelContextProtocol.Logging;
 using ModelContextProtocol.Protocol.Messages;
 using ModelContextProtocol.Protocol.Transport;
@@ -96,6 +96,9 @@ public McpClient(IClientTransport clientTransport, McpClientOptions? options, IL
     /// <inheritdoc/>
     public override string EndpointName { get; }
 
+    /// <summary>
+    /// Asynchronously connects to an MCP server, establishes the transport connection, and completes the initialization handshake.
+    /// </summary>
     public async Task ConnectAsync(CancellationToken cancellationToken = default)
     {
         _connectCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
@@ -185,4 +188,4 @@ public override async ValueTask DisposeUnsynchronizedAsync()
             }
         }
     }
-}
+}