Update all Transport comments

Author: stephentoub

src/ModelContextProtocol/Protocol/Transport/IClientTransport.cs

@@ -6,56 +6,42 @@ namespace ModelContextProtocol.Protocol.Transport;
 /// Represents a transport mechanism for Model Context Protocol (MCP) client-to-server communication.
 /// </summary>
 /// <remarks>
+/// <para>
 /// The <see cref="IClientTransport"/> interface abstracts the communication layer between MCP clients
-/// and servers, allowing different transport protocols to be used interchangeably. The protocol
-/// provides several built-in implementations:
-/// <list type="bullet">
-///   <item><description><see cref="SseClientTransport"/>: HTTP-based transport using Server-Sent Events (SSE)</description></item>
-///   <item><description><see cref="StdioClientTransport"/>: Process-based transport using standard input/output</description></item>
-///   <item><description><see cref="StreamClientTransport"/>: Transport based on arbitrary input/output streams</description></item>
-/// </list>
+/// and servers, allowing different transport protocols to be used interchangeably.
+/// </para>
 /// <para>
-/// When creating an MCP client, you typically use the <see cref="McpClientFactory"/> to create
-/// a client with the appropriate transport based on a server configuration:
+/// When creating an <see cref="IMcpClient"/>, <see cref="McpClientFactory"/> is typically used, and is
+/// provided with the <see cref="IClientTransport"/> based on expected server configuration.
 /// </para>
-/// <code>
-/// // Create an MCP client using a stdio transport
-/// await using var mcpClient = await McpClientFactory.CreateAsync(new()
-/// {
-///     Id = "demo-server",
-///     Name = "Demo Server",
-///     TransportType = TransportTypes.StdIo,
-///     TransportOptions = new()
-///     {
-///         ["command"] = "path/to/server",
-///         ["arguments"] = "--some-arg value",
-///     }
-/// });
-/// </code>
 /// </remarks>
 public interface IClientTransport
 {
     /// <summary>
-    /// Specifies a transport identifier used for logging purposes.
+    /// Gets a transport identifier, used for logging purposes.
     /// </summary>
     string Name { get; }
 
     /// <summary>
-    /// Asynchronously establishes a transport session with an MCP server and returns an interface for the duplex JSON-RPC message stream.
+    /// Asynchronously establishes a transport session with an MCP server and returns a transport for the duplex message stream.
     /// </summary>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>Returns an interface for the duplex JSON-RPC message stream.</returns>
+    /// <returns>Returns an interface for the duplex message stream.</returns>
     /// <remarks>
+    /// <para>
     /// This method is responsible for initializing the connection to the server using the specific transport 
     /// mechanism implemented by the derived class. The returned <see cref="ITransport"/> interface 
-    /// provides methods to send and receive JSON-RPC messages over the established connection.
-    /// 
-    /// <para>Implementations should handle connection errors appropriately and clean up resources if connection fails.</para>
-    /// 
-    /// <para>The lifetime of the returned <see cref="ITransport"/> instance is typically managed by the 
+    /// provides methods to send and receive messages over the established connection.
+    /// </para>
+    /// <para>
+    /// The lifetime of the returned <see cref="ITransport"/> instance is typically managed by the 
     /// <see cref="McpClient"/> that uses this transport. When the client is disposed, it will dispose
-    /// the transport session as well.</para>
+    /// the transport session as well.
+    /// </para>
+    /// <para>
+    /// This method is used by <see cref="McpClientFactory"/> to initialize the connection.
+    /// </para>
     /// </remarks>
-    /// <exception cref="McpTransportException">Thrown when the transport connection cannot be established.</exception>
+    /// <exception cref="McpTransportException">The transport connection could not be established.</exception>
     Task<ITransport> ConnectAsync(CancellationToken cancellationToken = default);
 }

src/ModelContextProtocol/Protocol/Transport/ITransport.cs

@@ -1,5 +1,7 @@
 using System.Threading.Channels;
+using ModelContextProtocol.Client;
 using ModelContextProtocol.Protocol.Messages;
+using ModelContextProtocol.Server;
 
 namespace ModelContextProtocol.Protocol.Transport;
 
@@ -8,32 +10,19 @@ namespace ModelContextProtocol.Protocol.Transport;
 /// </summary>
 /// <remarks>
 /// <para>
-/// The <see cref="ITransport"/> interface is the core abstraction for bidirectional communication in the MCP architecture.
-/// It provides methods for sending and receiving JSON-RPC messages regardless of the underlying transport mechanism,
-/// allowing protocol implementation to be decoupled from communication details.
+/// The <see cref="ITransport"/> interface is the core abstraction for bidirectional communication.
+/// It provides methods for sending and receiving messages, abstracting away the underlying transport mechanism
+/// and allowing protocol implementations to be decoupled from communication details.
 /// </para>
 /// <para>
 /// Implementations of <see cref="ITransport"/> handle the serialization, transmission, and reception of
-/// MCP messages over various channels like HTTP (Server-Sent Events), standard input/output streams,
-/// or arbitrary stream pairs.
+/// messages over various channels like standard input/output streams and HTTP (Server-Sent Events).
 /// </para>
 /// <para>
-/// While <see cref="IClientTransport"/> is responsible for establishing connections,
+/// While <see cref="IClientTransport"/> is responsible for establishing a client's connection,
 /// <see cref="ITransport"/> represents an established session. Client implementations typically obtain an
 /// <see cref="ITransport"/> instance by calling <see cref="IClientTransport.ConnectAsync"/>.
 /// </para>
-/// <para>
-/// The lifecycle of a transport typically follows this pattern:
-/// <list type="number">
-///   <item>Creation of the transport instance (via client connection or server acceptance)</item>
-///   <item>Usage through SendMessageAsync/MessageReader while IsConnected is true</item>
-///   <item>Disposal through DisposeAsync, which should clean up all resources</item>
-/// </list>
-/// </para>
-/// <para>
-/// Implementations must handle connection state changes, message serialization/deserialization,
-/// and proper resource cleanup when disposed.
-/// </para>
 /// </remarks>
 public interface ITransport : IAsyncDisposable
 {
@@ -43,15 +32,12 @@ public interface ITransport : IAsyncDisposable
     /// <remarks>
     /// <para>
     /// The <see cref="IsConnected"/> property indicates the current state of the transport connection.
-    /// When <c>true</c>, the transport is ready to send and receive messages. When <c>false</c>,
-    /// any attempt to send messages will typically throw an exception.
-    /// </para>
-    /// <para>
-    /// The property transitions to <c>true</c> when the transport successfully establishes a connection,
-    /// and transitions to <c>false</c> when the transport is disposed or encounters a connection error.
+    /// When <see langword="true"/>, the transport is ready to send and receive messages. When <see langword="false"/>,
+    /// any attempt to send messages will typically result in exceptions being thrown.
     /// </para>
     /// <para>
-    /// Consumers should check this property before attempting to send messages to prevent exceptions.
+    /// The property transitions to <see langword="true"/> when the transport successfully establishes a connection,
+    /// and transitions to <see langword="false"/> when the transport is disposed or encounters a connection error.
     /// </para>
     /// </remarks>
     bool IsConnected { get; }
@@ -65,50 +51,28 @@ public interface ITransport : IAsyncDisposable
     /// It returns a <see cref="ChannelReader{T}"/> which allows consuming messages in a thread-safe manner.
     /// </para>
     /// <para>
-    /// This property is typically used in one of the following ways:
-    /// <list type="bullet">
-    ///   <item>
-    ///     Async enumeration: <c>await foreach (var message in transport.MessageReader.ReadAllAsync(cancellationToken))</c>
-    ///   </item>
-    ///   <item>
-    ///     Wait and read pattern: <c>await transport.MessageReader.WaitToReadAsync(cancellationToken); transport.MessageReader.TryRead(out var message);</c>
-    ///   </item>
-    /// </list>
-    /// </para>
-    /// <para>
     /// The reader will continue to provide messages as long as the transport is connected. When the transport
-    /// is disconnected or disposed, the channel will be completed and no more messages will be available.
-    /// </para>
-    /// <para>
-    /// When using <see cref="MessageReader"/>, consumers should check <see cref="IsConnected"/> before performing long-running
-    /// operations to ensure the transport remains viable throughout message processing.
+    /// is disconnected or disposed, the channel will be completed and no more messages will be available after
+    /// any already transmitted messages are consumed.
     /// </para>
     /// </remarks>
     ChannelReader<IJsonRpcMessage> MessageReader { get; }
 
     /// <summary>
     /// Sends a JSON-RPC message through the transport.
     /// </summary>
-    /// <param name="message">The JSON-RPC message to send. This can be any type that implements IJsonRpcMessage.</param>
+    /// <param name="message">The JSON-RPC message to send.</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 send operation.</returns>
-    /// <exception cref="InvalidOperationException">Thrown when the transport is not connected.</exception>
+    /// <exception cref="InvalidOperationException">The transport is not connected.</exception>
     /// <remarks>
     /// <para>
     /// This method serializes and sends the provided JSON-RPC message through the transport connection.
-    /// Before sending, it checks if the transport is connected using the <see cref="IsConnected"/> property.
-    /// </para>
-    /// <para>
-    /// The behavior of this method varies by transport implementation:
-    /// <list type="bullet">
-    ///   <item>For SSE transports, messages are written to the SSE event stream</item>
-    ///   <item>For stream transports, messages are serialized and written to the underlying stream</item>
-    ///   <item>For stdio transports, messages are written to the standard output stream</item>
-    /// </list>
     /// </para>
     /// <para>
     /// This is a core method used by higher-level abstractions in the MCP protocol implementation.
-    /// Most client code should use the higher-level methods provided by <see cref="IMcpEndpoint"/>
+    /// Most client code should use the higher-level methods provided by <see cref="IMcpEndpoint"/>,
+    /// <see cref="McpEndpointExtensions"/>, <see cref="McpClientExtensions"/>, or <see cref="McpServerExtensions"/>,
     /// rather than accessing this method directly.
     /// </para>
     /// </remarks>

src/ModelContextProtocol/Protocol/Transport/McpTransportException.cs

@@ -1,22 +1,19 @@
-// Protocol/Transport/IMcpTransport.cs
-namespace ModelContextProtocol.Protocol.Transport;
-
-// Protocol/Transport/McpTransportException.cs
+namespace ModelContextProtocol.Protocol.Transport;
 
 /// <summary>
 /// Represents errors that occur in MCP transport operations.
 /// </summary>
 public class McpTransportException : Exception
 {
     /// <summary>
-    /// Initializes a new instance of the McpTransportException class.
+    /// Initializes a new instance of the <see cref="McpTransportException"/> class.
     /// </summary>
     public McpTransportException()
     {
     }
 
     /// <summary>
-    /// Initializes a new instance of the McpTransportException class with a specified error message.
+    /// Initializes a new instance of the <see cref="McpTransportException"/> class with a specified error message.
     /// </summary>
     /// <param name="message">The message that describes the error.</param>
     public McpTransportException(string message)
@@ -25,7 +22,7 @@ public McpTransportException(string message)
     }
 
     /// <summary>
-    /// Initializes a new instance of the McpTransportException class with a specified error message
+    /// Initializes a new instance of the <see cref="McpTransportException"/> class with a specified error message
     /// and a reference to the inner exception that is the cause of this exception.
     /// </summary>
     /// <param name="message">The message that describes the error.</param>

src/ModelContextProtocol/Protocol/Transport/SseClientTransport.cs

@@ -4,44 +4,13 @@
 namespace ModelContextProtocol.Protocol.Transport;
 
 /// <summary>
-/// The ServerSideEvents client transport implementation
+/// Provides an <see cref="IClientTransport"/> over HTTP using the Server-Sent Events (SSE) protocol.
 /// </summary>
 /// <remarks>
-/// <para>
-/// This transport connects to an MCP server over HTTP using the Server-Sent Events protocol,
+/// This transport connects to an MCP server over HTTP using SSE,
 /// allowing for real-time server-to-client communication with a standard HTTP request.
 /// Unlike the <see cref="StdioClientTransport"/>, this transport connects to an existing server
 /// rather than launching a new process.
-/// </para>
-/// <para>
-/// SSE is a unidirectional communication protocol where the server can push messages to the client
-/// in real-time. For bidirectional communication, this transport sends client messages via regular
-/// HTTP POST requests to a configured endpoint, while receiving server messages through the SSE connection.
-/// </para>
-/// <para>
-/// This transport is ideal for web-based scenarios where the server is accessible via HTTP/HTTPS
-/// and provides a standard way to integrate with MCP servers running in cloud environments or behind
-/// API gateways.
-/// </para>
-/// <example>
-/// <code>
-/// // Creating an MCP client with SSE transport
-/// await using var mcpClient = await McpClientFactory.CreateAsync(new McpServerConfig
-/// {
-///     Id = "server-id",
-///     Name = "Server Name",
-///     TransportType = TransportTypes.Sse,
-///     TransportOptions = new()
-///     {
-///         ["baseUrl"] = "https://api.example.com/mcp",
-///         ["headers"] = new Dictionary&lt;string, string&gt;
-///         {
-///             ["Authorization"] = "Bearer token123"
-///         }
-///     }
-/// });
-/// </code>
-/// </example>
 /// </remarks>
 public sealed class SseClientTransport : IClientTransport, IAsyncDisposable
 {
@@ -51,13 +20,12 @@ public sealed class SseClientTransport : IClientTransport, IAsyncDisposable
     private readonly bool _ownsHttpClient;
 
     /// <summary>
-    /// SSE transport for client endpoints. Unlike stdio it does not launch a process, but connects to an existing server.
-    /// The HTTP server can be local or remote, and must support the SSE protocol.
+    /// Initializes a new instance of the <see cref="SseClientTransport"/> class.
     /// </summary>
     /// <param name="transportOptions">Configuration options for the transport.</param>
-    /// <param name="loggerFactory">Logger factory for creating loggers.</param>
+    /// <param name="loggerFactory">Logger factory for creating loggers used for diagnostic output during transport operations.</param>
     public SseClientTransport(SseClientTransportOptions transportOptions, ILoggerFactory? loggerFactory = null)
-        : this(transportOptions, new HttpClient(), loggerFactory, true)
+        : this(transportOptions, new HttpClient(), loggerFactory, ownsHttpClient: true)
     {
     }
 
@@ -66,13 +34,11 @@ public SseClientTransport(SseClientTransportOptions transportOptions, ILoggerFac
     /// </summary>
     /// <param name="transportOptions">Configuration options for the transport.</param>
     /// <param name="httpClient">The HTTP client instance used for requests.</param>
-    /// <param name="loggerFactory">Logger factory for creating loggers. Used for diagnostic output during transport operations.
-    /// If null, a NullLogger will be used that doesn't produce any output.</param>
-    /// <param name="ownsHttpClient">True to dispose HTTP client when the transport is disposed; false to leave it for the caller to manage.</param>
-    /// <remarks>
-    /// This constructor allows providing an external HTTP client, which can be useful for advanced scenarios
-    /// where you need to configure the HTTP client with custom handlers, base address, or default headers.
-    /// </remarks>
+    /// <param name="loggerFactory">Logger factory for creating loggers used for diagnostic output during transport operations.</param>
+    /// <param name="ownsHttpClient">
+    /// <see langword="true"/> to dispose of <paramref name="httpClient"/> when the transport is disposed; 
+    /// <see langword="false"/> if the caller is retaining ownership of the <paramref name="httpClient"/>'s lifetime.
+    /// </param>
     public SseClientTransport(SseClientTransportOptions transportOptions, HttpClient httpClient, ILoggerFactory? loggerFactory = null, bool ownsHttpClient = false)
     {
         Throw.IfNull(transportOptions);