Second batch of AI generated /// comment updates

Author: robch

src/ModelContextProtocol/AIContentExtensions.cs

@@ -33,9 +33,46 @@ namespace ModelContextProtocol;
 /// </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>
+    /// <para>
+    /// 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.
+    /// </para>
+    /// <para>
+    /// The role mapping is preserved in the conversion:
+    /// <list type="bullet">
+    ///   <item><description><see cref="Role.User"/> → <see cref="ChatRole.User"/></description></item>
+    ///   <item><description><see cref="Role.Assistant"/> → <see cref="ChatRole.Assistant"/></description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// The original <see cref="PromptMessage"/> object is stored in the <see cref="AIContent.RawRepresentation"/>
+    /// property, enabling round-trip conversions if needed.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // Get a prompt message from an MCP source
+    /// PromptMessage promptMessage = new PromptMessage
+    /// {
+    ///     Role = Role.User,
+    ///     Content = new Content { Text = "Hello, AI!", Type = "text" }
+    /// };
+    /// 
+    /// // Convert to ChatMessage for use with AI clients
+    /// ChatMessage chatMessage = promptMessage.ToChatMessage();
+    /// 
+    /// // Use the chat message with Microsoft.Extensions.AI
+    /// Console.WriteLine($"{chatMessage.Role}: {chatMessage.Contents.FirstOrDefault()?.ToString()}");
+    /// </code>
+    /// </example>
+    /// <seealso cref="ToChatMessages(GetPromptResult)"/>
+    /// <seealso cref="ToPromptMessages(ChatMessage)"/>
     public static ChatMessage ToChatMessage(this PromptMessage promptMessage)
     {
         Throw.IfNull(promptMessage);
@@ -131,6 +168,59 @@ 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>
+    /// <para>
+    /// 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.
+    /// </para>
+    /// <para>
+    /// The conversion follows these rules:
+    /// <list type="bullet">
+    ///   <item><description>When <see cref="Content.Type"/> is "image" or "audio" with data → <see cref="DataContent"/> with base64-decoded data and preserved MIME type</description></item>
+    ///   <item><description>When <see cref="Content.Resource"/> is not null → Uses <see cref="ToAIContent(ResourceContents)"/> for the resource</description></item>
+    ///   <item><description>Otherwise → <see cref="TextContent"/> using the text content</description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// The original <see cref="Content"/> object is stored in the <see cref="AIContent.RawRepresentation"/>
+    /// property, enabling round-trip conversions if needed.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // Convert a Content with text to AIContent
+    /// var textContent = new Content 
+    /// {
+    ///     Text = "Hello, world!",
+    ///     Type = "text"
+    /// };
+    /// AIContent aiContent = textContent.ToAIContent();
+    /// 
+    /// // Convert a Content with image data to AIContent
+    /// var imageContent = new Content
+    /// {
+    ///     Type = "image",
+    ///     MimeType = "image/png",
+    ///     Data = Convert.ToBase64String(imageBytes)
+    /// };
+    /// AIContent aiImageContent = imageContent.ToAIContent();
+    /// 
+    /// // Convert a Content with a resource to AIContent
+    /// var resourceContent = new Content
+    /// {
+    ///     Type = "resource",
+    ///     Resource = new TextResourceContents
+    ///     {
+    ///         Uri = "resource://document.txt",
+    ///         Text = "This is a resource text"
+    ///     }
+    /// };
+    /// AIContent aiResourceContent = resourceContent.ToAIContent();
+    /// </code>
+    /// </example>
+    /// <seealso cref="ToAIContent(ResourceContents)"/>
+    /// <seealso cref="DataContent"/>
+    /// <seealso cref="TextContent"/>
     public static AIContent ToAIContent(this Content content)
     {
         Throw.IfNull(content);
@@ -157,6 +247,65 @@ 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>
+    /// <para>
+    /// 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.
+    /// </para>
+    /// <para>
+    /// The conversion follows these rules:
+    /// <list type="bullet">
+    ///   <item><description><see cref="BlobResourceContents"/> → <see cref="DataContent"/> with base64-decoded data and preserved MIME type</description></item>
+    ///   <item><description><see cref="TextResourceContents"/> → <see cref="TextContent"/> with the text preserved</description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// The URI of the resource is preserved in the <see cref="AIContent.AdditionalProperties"/> dictionary
+    /// with the key "uri", allowing applications to maintain resource identifiers.
+    /// </para>
+    /// <para>
+    /// The original <see cref="ResourceContents"/> object is stored in the <see cref="AIContent.RawRepresentation"/>
+    /// property, enabling round-trip conversions if needed.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // Convert a TextResourceContents to AIContent
+    /// var textResource = new TextResourceContents
+    /// {
+    ///     Uri = "resource://document.txt",
+    ///     MimeType = "text/plain",
+    ///     Text = "This is a text resource"
+    /// };
+    /// AIContent textContent = textResource.ToAIContent();
+    /// 
+    /// // Use the converted content with Microsoft.Extensions.AI client
+    /// await aiClient.GenerateTextAsync(new TextGenerationOptions
+    /// {
+    ///     Messages = [
+    ///         new ChatMessage
+    ///         {
+    ///             Role = ChatRole.User,
+    ///             Contents = [textContent]
+    ///         }
+    ///     ]
+    /// });
+    /// 
+    /// // Convert a BlobResourceContents to AIContent
+    /// var blobResource = new BlobResourceContents
+    /// {
+    ///     Uri = "resource://image.png",
+    ///     MimeType = "image/png",
+    ///     Blob = Convert.ToBase64String(imageBytes)
+    /// };
+    /// AIContent imageContent = blobResource.ToAIContent();
+    /// </code>
+    /// </example>
+    /// <exception cref="NotSupportedException">Thrown when the resource type is not supported.</exception>
+    /// <seealso cref="BlobResourceContents"/>
+    /// <seealso cref="TextResourceContents"/>
+    /// <seealso cref="DataContent"/>
+    /// <seealso cref="TextContent"/>
     public static AIContent ToAIContent(this ResourceContents content)
     {
         Throw.IfNull(content);
@@ -177,6 +326,40 @@ 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>
+    /// <example>
+    /// <code>
+    /// // Get Content objects from a source
+    /// IEnumerable&lt;Content&gt; contents = someResponse.Contents;
+    /// 
+    /// // Convert all Content objects to AIContent objects
+    /// IList&lt;AIContent&gt; aiContents = contents.ToAIContents();
+    /// 
+    /// // Use the converted contents
+    /// foreach (var content in aiContents)
+    /// {
+    ///     if (content is TextContent textContent)
+    ///     {
+    ///         Console.WriteLine($"Text content: {textContent.Text}");
+    ///     }
+    ///     else if (content is DataContent dataContent)
+    ///     {
+    ///         Console.WriteLine($"Binary content: {dataContent.MediaType}, {dataContent.Data.Length} bytes");
+    ///     }
+    /// }
+    /// </code>
+    /// </example>
+    /// <seealso cref="ToAIContent(Content)"/>
     public static IList<AIContent> ToAIContents(this IEnumerable<Content> contents)
     {
         Throw.IfNull(contents);
@@ -186,7 +369,43 @@ 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>
+    /// <example>
+    /// <code>
+    /// // Get resources from a read resource result
+    /// ReadResourceResult result = await client.ReadResourceAsync("resource://folder");
+    /// 
+    /// // Convert all resources to AIContent objects
+    /// IList&lt;AIContent&gt; aiContents = result.Contents.ToAIContents();
+    /// 
+    /// // Use the converted contents
+    /// foreach (var content in aiContents)
+    /// {
+    ///     if (content is TextContent textContent)
+    ///     {
+    ///         Console.WriteLine($"Text content: {textContent.Text}");
+    ///     }
+    ///     else if (content is DataContent dataContent)
+    ///     {
+    ///         Console.WriteLine($"Binary content: {dataContent.MediaType}, {dataContent.Data.Length} bytes");
+    ///     }
+    /// }
+    /// </code>
+    /// </example>
+    /// <seealso cref="ToAIContent(ResourceContents)"/>
+    /// <seealso cref="ReadResourceResult.Contents"/>
     public static IList<AIContent> ToAIContents(this IEnumerable<ResourceContents> contents)
     {
         Throw.IfNull(contents);

src/ModelContextProtocol/Client/IMcpClient.cs

@@ -53,6 +53,35 @@ public interface IMcpClient : IMcpEndpoint
     /// <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>
+    /// <para>
+    /// The property will throw an InvalidOperationException if accessed before a successful connection is established.
+    /// </para>
+    /// <para>
+    /// Example usage:
+    /// <code>
+    /// // Connect to the server
+    /// await mcpClient.ConnectAsync(cancellationToken);
+    /// 
+    /// // Access server information
+    /// Console.WriteLine($"Connected to {mcpClient.ServerInfo.Name} version {mcpClient.ServerInfo.Version}");
+    /// 
+    /// // Use server information for version compatibility checks
+    /// if (Version.TryParse(mcpClient.ServerInfo.Version, out var version) &amp;&amp; version.Major >= 2)
+    /// {
+    ///     // Use features only available in version 2.0+
+    /// }
+    /// </code>
+    /// </para>
+    /// </remarks>
     Implementation ServerInfo { get; }
 
     /// <summary>