modelcontextprotocol/csharp-sdk
Watch
1
0
Fork
You've already forked csharp-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

MCP Core docs edit pass (#1033)

Browse source 
Co-authored-by: Stephen Toub <stoub@microsoft.com>
This commit is contained in:
Genevieve Warren 2025-11-26 05:36:19 -08:00 • committed by GitHub
commit 6ed728d005
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 452 additions and 447 deletions
Download patch file Download diff file Expand all files Collapse all files

12
src/ModelContextProtocol.Core/Client/HttpClientTransport.cs
View file

@ -9,7 +9,7 @@ namespace ModelContextProtocol.Client;
/// </summary>
/// <remarks>
/// This transport connects to an MCP server over HTTP using SSE or Streamable HTTP,
/// allowing for real-time server-to-client communication with a standard HTTP requests.
/// allowing for real-time server-to-client communication with standard HTTP requests.
/// Unlike the <see cref="StdioClientTransport"/>, this transport connects to an existing server
/// rather than launching a new process.
/// </remarks>
@ -24,8 +24,8 @@ public sealed class HttpClientTransport : IClientTransport, IAsyncDisposable
/// <summary>
/// Initializes a new instance of the <see cref="HttpClientTransport"/> class.
/// </summary>
/// <param name="transportOptions">Configuration options for the transport.</param>
/// <param name="loggerFactory">Logger factory for creating loggers used for diagnostic output during transport operations.</param>
/// <param name="transportOptions">The configuration options for the transport.</param>
/// <param name="loggerFactory">The logger factory for creating loggers used for diagnostic output during transport operations.</param>
public HttpClientTransport(HttpClientTransportOptions transportOptions, ILoggerFactory? loggerFactory = null)
: this(transportOptions, new HttpClient(), loggerFactory, ownsHttpClient: true)
{
@ -34,9 +34,9 @@ public sealed class HttpClientTransport : IClientTransport, IAsyncDisposable
/// <summary>
/// Initializes a new instance of the <see cref="HttpClientTransport"/> class with a provided HTTP client.
/// </summary>
/// <param name="transportOptions">Configuration options for the transport.</param>
/// <param name="transportOptions">The 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.</param>
/// <param name="loggerFactory">The 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.
@ -108,4 +108,4 @@ public sealed class HttpClientTransport : IClientTransport, IAsyncDisposable
_ownedHttpClient?.Dispose();
return default;
}
}
}

28
src/ModelContextProtocol.Core/Client/HttpClientTransportOptions.cs
View file

@ -33,18 +33,17 @@ public sealed class HttpClientTransportOptions
}
/// <summary>
/// Gets or sets the transport mode to use for the connection. Defaults to <see cref="HttpTransportMode.AutoDetect"/>.
/// Gets or sets the transport mode to use for the connection.
/// </summary>
/// <value>
/// The transport mode to use for the connection. The default is <see cref="HttpTransportMode.AutoDetect"/>.
/// </value>
/// <remarks>
/// <para>
/// When set to <see cref="HttpTransportMode.AutoDetect"/> (the default), the client will first attempt to use
/// Streamable HTTP transport and automatically fall back to SSE transport if the server doesn't support it.
/// </para>
/// <para>
/// <see href="https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http">Streamable HTTP transport specification</see>.
/// <see href="https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse">HTTP with SSE transport specification</see>.
/// </para>
/// </remarks>
/// <seealso href="https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http">Streamable HTTP transport specification</seealso>.
/// <seealso href="https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse">HTTP with SSE transport specification</seealso>.
public HttpTransportMode TransportMode { get; set; } = HttpTransportMode.AutoDetect;
/// <summary>
@ -53,20 +52,23 @@ public sealed class HttpClientTransportOptions
public string? Name { get; set; }
/// <summary>
/// Gets or sets a timeout used to establish the initial connection to the SSE server. Defaults to 30 seconds.
/// Gets or sets a timeout used to establish the initial connection to the SSE server.
/// </summary>
/// <value>
/// The timeout used to establish the initial connection to the SSE server. The default is 30 seconds.
/// </value>
/// <remarks>
/// This timeout controls how long the client waits for:
/// <list type="bullet">
/// <item><description>The initial HTTP connection to be established with the SSE server</description></item>
/// <item><description>The endpoint event to be received, which indicates the message endpoint URL</description></item>
/// <item><description>The initial HTTP connection to be established with the SSE server.</description></item>
/// <item><description>The endpoint event to be received, which indicates the message endpoint URL.</description></item>
/// </list>
/// If the timeout expires before the connection is established, a <see cref="TimeoutException"/> will be thrown.
/// If the timeout expires before the connection is established, a <see cref="TimeoutException"/> is thrown.
/// </remarks>
public TimeSpan ConnectionTimeout { get; set; } = TimeSpan.FromSeconds(30);
/// <summary>
/// Gets custom HTTP headers to include in requests to the SSE server.
/// Gets or sets custom HTTP headers to include in requests to the SSE server.
/// </summary>
/// <remarks>
/// Use this property to specify custom HTTP headers that should be sent with each request to the server.
@ -104,4 +106,4 @@ public sealed class HttpClientTransportOptions
/// Gets sor sets the authorization provider to use for authentication.
/// </summary>
public ClientOAuthOptions? OAuth { get; set; }
}
}

8
src/ModelContextProtocol.Core/Client/IClientTransport.cs
View file

@ -26,15 +26,15 @@ public interface IClientTransport
/// 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 message stream.</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
/// 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 messages over the established connection.
/// </para>
/// <para>
/// The lifetime of the returned <see cref="ITransport"/> instance is typically managed by the
/// 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>

29
src/ModelContextProtocol.Core/Client/McpClient.Methods.cs
View file

@ -17,14 +17,13 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// <summary>Creates an <see cref="McpClient"/>, connecting it to the specified server.</summary>
/// <param name="clientTransport">The transport instance used to communicate with the server.</param>
/// <param name="clientOptions">
/// A client configuration object which specifies client capabilities and protocol version.
/// If <see langword="null"/>, details based on the current process will be employed.
/// A client configuration object that specifies client capabilities and protocol version.
/// If <see langword="null"/>, details based on the current process are used.
/// </param>
/// <param name="loggerFactory">A logger factory for creating loggers for clients.</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>An <see cref="McpClient"/> that's connected to the specified server.</returns>
/// <exception cref="ArgumentNullException"><paramref name="clientTransport"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="clientOptions"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="clientTransport"/> or <paramref name="clientOptions"/> is <see langword="null"/>.</exception>
public static async Task<McpClient> CreateAsync(
IClientTransport clientTransport,
McpClientOptions? clientOptions = null,
@ -85,7 +84,7 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// </summary>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>A task that completes when the ping is successful.</returns>
/// <exception cref="McpException">Thrown when the server cannot be reached or returns an error response.</exception>
/// <exception cref="McpException">The server cannot be reached or returned an error response.</exception>
public Task PingAsync(CancellationToken cancellationToken = default)
{
var opts = McpJsonUtilities.DefaultOptions;
@ -100,7 +99,7 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// <summary>
/// Retrieves a list of available tools from the server.
/// </summary>
/// <param name="serializerOptions">The serializer options governing tool parameter serialization. If null, the default options will be used.</param>
/// <param name="serializerOptions">The serializer options governing tool parameter serialization. If null, the default options are used.</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>A list of all available tools as <see cref="McpClientTool"/> instances.</returns>
public async ValueTask<IList<McpClientTool>> ListToolsAsync(
@ -137,7 +136,7 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// <summary>
/// Creates an enumerable for asynchronously enumerating all available tools from the server.
/// </summary>
/// <param name="serializerOptions">The serializer options governing tool parameter serialization. If null, the default options will be used.</param>
/// <param name="serializerOptions">The serializer options governing tool parameter serialization. If null, the default options are used.</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>An asynchronous sequence of all available tools as <see cref="McpClientTool"/> instances.</returns>
public async IAsyncEnumerable<McpClientTool> EnumerateToolsAsync(
@ -231,7 +230,7 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// Retrieves a specific prompt from the MCP server.
/// </summary>
/// <param name="name">The name of the prompt to retrieve.</param>
/// <param name="arguments">Optional arguments for the prompt. Keys are parameter names, and values are the argument values.</param>
/// <param name="arguments">Optional arguments for the prompt. The dictionary keys are parameter names, and the values are the argument values.</param>
/// <param name="serializerOptions">The serialization options governing argument serialization.</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>A task containing the prompt's result with content and messages.</returns>
@ -379,7 +378,7 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// <summary>
/// Reads a resource from the server.
/// </summary>
/// <param name="uri">The uri of the resource.</param>
/// <param name="uri">The URI of the resource.</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
public ValueTask<ReadResourceResult> ReadResourceAsync(
string uri, CancellationToken cancellationToken = default)
@ -397,7 +396,7 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// <summary>
/// Reads a resource from the server.
/// </summary>
/// <param name="uri">The uri of the resource.</param>
/// <param name="uri">The URI of the resource.</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
public ValueTask<ReadResourceResult> ReadResourceAsync(
Uri uri, CancellationToken cancellationToken = default)
@ -410,7 +409,7 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// <summary>
/// Reads a resource from the server.
/// </summary>
/// <param name="uriTemplate">The uri template of the resource.</param>
/// <param name="uriTemplate">The URI template of the resource.</param>
/// <param name="arguments">Arguments to use to format <paramref name="uriTemplate"/>.</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
public ValueTask<ReadResourceResult> ReadResourceAsync(
@ -517,10 +516,10 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// <summary>
/// Invokes a tool on the server.
/// </summary>
/// <param name="toolName">The name of the tool to call on the server..</param>
/// <param name="toolName">The name of the tool to call on the server.</param>
/// <param name="arguments">An optional dictionary of arguments to pass to the tool.</param>
/// <param name="progress">Optional progress reporter for server notifications.</param>
/// <param name="serializerOptions">JSON serializer options.</param>
/// <param name="progress">An optional progress reporter for server notifications.</param>
/// <param name="serializerOptions">The JSON serializer options.</param>
/// <param name="cancellationToken">A cancellation token.</param>
/// <returns>The <see cref="CallToolResult"/> from the tool execution.</returns>
public ValueTask<CallToolResult> CallToolAsync(
@ -610,7 +609,7 @@ public abstract partial class McpClient : McpSession, IMcpClient
public Task SetLoggingLevel(LogLevel level, CancellationToken cancellationToken = default) =>
SetLoggingLevel(McpServerImpl.ToLoggingLevel(level), cancellationToken);
/// <summary>Convers a dictionary with <see cref="object"/> values to a dictionary with <see cref="JsonElement"/> values.</summary>
/// <summary>Converts a dictionary with <see cref="object"/> values to a dictionary with <see cref="JsonElement"/> values.</summary>
private static Dictionary<string, JsonElement>? ToArgumentsDictionary(
IReadOnlyDictionary<string, object?>? arguments, JsonSerializerOptions options)
{

4
src/ModelContextProtocol.Core/Client/McpClient.cs
View file

@ -41,8 +41,8 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// 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.
/// 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 can be added to a system prompt.
/// </para>
/// </remarks>
public abstract string? ServerInstructions { get; }

36
src/ModelContextProtocol.Core/Client/McpClientExtensions.cs
View file

@ -11,11 +11,9 @@ namespace ModelContextProtocol.Client;
/// Provides extension methods for interacting with an <see cref="McpClient"/>.
/// </summary>
/// <remarks>
/// <para>
/// This class contains extension methods that simplify common operations with an MCP client,
/// such as pinging a server, listing and working with tools, prompts, and resources, and
/// managing subscriptions to resources.
/// </para>
/// </remarks>
public static class McpClientExtensions
{
@ -28,7 +26,7 @@ public static class McpClientExtensions
/// <remarks>
/// <para>
/// This method is used to check if the MCP server is online and responding to requests.
/// It can be useful for health checking, ensuring the connection is established, or verifying
/// It can be useful for health checking, ensuring the connection is established, or verifying
/// that the client has proper authorization to communicate with the server.
/// </para>
/// <para>
@ -37,7 +35,7 @@ public static class McpClientExtensions
/// </para>
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="client"/> is <see langword="null"/>.</exception>
/// <exception cref="McpException">Thrown when the server cannot be reached or returns an error response.</exception>
/// <exception cref="McpException">The server cannot be reached or returned an error response.</exception>
[Obsolete($"Use {nameof(McpClient)}.{nameof(McpClient.PingAsync)} instead. This member will be removed in a subsequent release.")] // See: https://github.com/modelcontextprotocol/csharp-sdk/issues/774
[EditorBrowsable(EditorBrowsableState.Never)]
public static Task PingAsync(this IMcpClient client, CancellationToken cancellationToken = default)
@ -47,7 +45,7 @@ public static class McpClientExtensions
/// Retrieves a list of available tools from the server.
/// </summary>
/// <param name="client">The client instance used to communicate with the MCP server.</param>
/// <param name="serializerOptions">The serializer options governing tool parameter serialization. If null, the default options will be used.</param>
/// <param name="serializerOptions">The serializer options governing tool parameter serialization. If null, the default options are used.</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>A list of all available tools as <see cref="McpClientTool"/> instances.</returns>
/// <remarks>
@ -56,8 +54,8 @@ public static class McpClientExtensions
/// It automatically handles pagination with cursors if the server responds with only a portion per request.
/// </para>
/// <para>
/// For servers with a large number of tools and that responds with paginated responses, consider using
/// <see cref="EnumerateToolsAsync"/> instead, as it streams tools as they arrive rather than loading them all at once.
/// For servers with a large number of tools and that responds with paginated responses, consider using
/// <see cref="EnumerateToolsAsync"/> instead, because it streams tools as they arrive rather than loading them all at once.
/// </para>
/// <para>
/// The serializer options provided are flowed to each <see cref="McpClientTool"/> and will be used
@ -68,13 +66,13 @@ public static class McpClientExtensions
/// <code>
/// // Get all tools available on the server
/// var tools = await mcpClient.ListToolsAsync();
///
///
/// // Use tools with an AI client
/// ChatOptions chatOptions = new()
/// {
/// Tools = [.. tools]
/// };
///
///
/// await foreach (var update in chatClient.GetStreamingResponseAsync(userMessage, chatOptions))
/// {
/// Console.Write(update);
@ -94,7 +92,7 @@ public static class McpClientExtensions
/// Creates an enumerable for asynchronously enumerating all available tools from the server.
/// </summary>
/// <param name="client">The client instance used to communicate with the MCP server.</param>
/// <param name="serializerOptions">The serializer options governing tool parameter serialization. If null, the default options will be used.</param>
/// <param name="serializerOptions">The serializer options governing tool parameter serialization. If null, the default options are used.</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>An asynchronous sequence of all available tools as <see cref="McpClientTool"/> instances.</returns>
/// <remarks>
@ -105,7 +103,7 @@ public static class McpClientExtensions
/// </para>
/// <para>
/// The serializer options provided are flowed to each <see cref="McpClientTool"/> and will be used
/// when invoking tools in order to serialize any parameters.
/// when invoking tools to serialize any parameters.
/// </para>
/// <para>
/// Every iteration through the returned <see cref="IAsyncEnumerable{McpClientTool}"/>
@ -142,7 +140,7 @@ public static class McpClientExtensions
/// It automatically handles pagination with cursors if the server responds with only a portion per request.
/// </para>
/// <para>
/// For servers with a large number of prompts and that responds with paginated responses, consider using
/// For servers with a large number of prompts and that responds with paginated responses, consider using
/// <see cref="EnumeratePromptsAsync"/> instead, as it streams prompts as they arrive rather than loading them all at once.
/// </para>
/// </remarks>
@ -201,7 +199,7 @@ public static class McpClientExtensions
/// The server will process the arguments and return a prompt containing messages or other content.
/// </para>
/// <para>
/// Arguments are serialized into JSON and passed to the server, where they may be used to customize the
/// Arguments are serialized into JSON and passed to the server, where they may be used to customize the
/// prompt's behavior or content. Each prompt may have different argument requirements.
/// </para>
/// <para>
@ -233,7 +231,7 @@ public static class McpClientExtensions
/// It automatically handles pagination with cursors if the server responds with only a portion per request.
/// </para>
/// <para>
/// For servers with a large number of resource templates and that responds with paginated responses, consider using
/// For servers with a large number of resource templates and that responds with paginated responses, consider using
/// <see cref="EnumerateResourceTemplatesAsync"/> instead, as it streams templates as they arrive rather than loading them all at once.
/// </para>
/// </remarks>
@ -289,7 +287,7 @@ public static class McpClientExtensions
/// It automatically handles pagination with cursors if the server responds with only a portion per request.
/// </para>
/// <para>
/// For servers with a large number of resources and that responds with paginated responses, consider using
/// For servers with a large number of resources and that responds with paginated responses, consider using
/// <see cref="EnumerateResourcesAsync"/> instead, as it streams resources as they arrive rather than loading them all at once.
/// </para>
/// </remarks>
@ -297,7 +295,7 @@ public static class McpClientExtensions
/// <code>
/// // Get all resources available on the server
/// var resources = await client.ListResourcesAsync();
///
///
/// // Display information about each resource
/// foreach (var resource in resources)
/// {
@ -410,7 +408,7 @@ public static class McpClientExtensions
/// auto-completion in user interfaces.
/// </para>
/// <para>
/// When working with resource references, the server will return suggestions relevant to the specified
/// When working with resource references, the server will return suggestions relevant to the specified
/// resource URI.
/// </para>
/// </remarks>
@ -554,7 +552,7 @@ public static class McpClientExtensions
/// routed to this instance.
/// </param>
/// <param name="serializerOptions">
/// The JSON serialization options governing argument serialization. If <see langword="null"/>, the default serialization options will be used.
/// The JSON serialization options governing argument serialization. If <see langword="null"/>, the default serialization options are used.
/// </param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>
@ -607,4 +605,4 @@ public static class McpClientExtensions
$"'{nameof(McpClientExtensions)}.{memberName}' is obsolete and will be " +
$"removed in the future.");
}
}
}

8
src/ModelContextProtocol.Core/Client/McpClientHandlers.cs
View file

@ -26,7 +26,7 @@ public class McpClientHandlers
/// <summary>Gets or sets notification handlers to register with the client.</summary>
/// <remarks>
/// <para>
/// When constructed, the client will enumerate these handlers once, which may contain multiple handlers per notification method key.
/// When constructed, the client will enumerate these handlers, which might contain multiple handlers per notification method key, once.
/// The client will not re-enumerate the sequence after initialization.
/// </para>
/// <para>
@ -36,7 +36,7 @@ public class McpClientHandlers
/// </para>
/// <para>
/// Handlers provided via <see cref="NotificationHandlers"/> will be registered with the client for the lifetime of the client.
/// For transient handlers, <see cref="IMcpEndpoint.RegisterNotificationHandler"/> may be used to register a handler that can
/// For transient handlers, you can use <see cref="IMcpEndpoint.RegisterNotificationHandler"/> to register a handler that can
/// then be unregistered by disposing of the <see cref="IAsyncDisposable"/> returned from the method.
/// </para>
/// </remarks>
@ -75,8 +75,8 @@ public class McpClientHandlers
/// using an AI model. The client must set this property for the sampling capability to work.
/// </para>
/// <para>
/// The handler receives message parameters, a progress reporter for updates, and a
/// cancellation token. It should return a <see cref="CreateMessageResult"/> containing the
/// The handler receives message parameters, a progress reporter for updates, and a
/// cancellation token. It should return a <see cref="CreateMessageResult"/> containing the
/// generated content.
/// </para>
/// <para>

14
src/ModelContextProtocol.Core/Client/McpClientOptions.cs
View file

@ -20,7 +20,7 @@ public sealed class McpClientOptions
/// It's often displayed in server logs and can be used for debugging and compatibility checks.
/// </para>
/// <para>
/// When not specified, information sourced from the current process will be used.
/// When not specified, information sourced from the current process is used.
/// </para>
/// </remarks>
public Implementation? ClientInfo { get; set; }
@ -35,7 +35,7 @@ public sealed class McpClientOptions
/// </summary>
/// <remarks>
/// <para>
/// The protocol version is a key part of the initialization handshake. The client and server must
/// The protocol version is a key part of the initialization handshake. The client and server must
/// agree on a compatible protocol version to communicate successfully.
/// </para>
/// <para>
@ -50,25 +50,27 @@ public sealed class McpClientOptions
/// <summary>
/// Gets or sets a timeout for the client-server initialization handshake sequence.
/// </summary>
/// <value>
/// The timeout for the client-server initialization handshake sequence. The default value is 60 seconds.
/// </value>
/// <remarks>
/// <para>
/// This timeout determines how long the client will wait for the server to respond during
/// the initialization protocol handshake. If the server doesn't respond within this timeframe,
/// an exception will be thrown.
/// an exception is thrown.
/// </para>
/// <para>
/// Setting an appropriate timeout prevents the client from hanging indefinitely when
/// connecting to unresponsive servers.
/// </para>
/// <para>The default value is 60 seconds.</para>
/// </remarks>
public TimeSpan InitializationTimeout { get; set; } = TimeSpan.FromSeconds(60);
/// <summary>
/// Gets or sets the container of handlers used by the client for processing protocol messages.
/// </summary>
public McpClientHandlers Handlers
{
public McpClientHandlers Handlers
{
get => field ??= new();
set
{

17
src/ModelContextProtocol.Core/Client/McpClientPrompt.cs
View file

@ -30,17 +30,16 @@ public sealed class McpClientPrompt
/// <remarks>
/// <para>
/// This constructor enables reusing cached prompt definitions across different <see cref="McpClient"/> instances
/// without needing to call <see cref="McpClient.ListPromptsAsync"/> on every reconnect. This is particularly useful
/// without needing to call <see cref="McpClient.ListPromptsAsync"/> on every reconnect. This is particularly useful
/// in scenarios where prompt definitions are stable and network round-trips should be minimized.
/// </para>
/// <para>
/// The provided <paramref name="prompt"/> must represent a prompt that is actually available on the server
/// associated with the <paramref name="client"/>. Attempting to invoke a prompt that doesn't exist on the
/// The provided <paramref name="prompt"/> must represent a prompt that is actually available on the server
/// associated with the <paramref name="client"/>. Attempting to invoke a prompt that doesn't exist on the
/// server will result in an <see cref="McpException"/>.
/// </para>
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="client"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="prompt"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="client"/> or <paramref name="prompt"/> is <see langword="null"/>.</exception>
public McpClientPrompt(McpClient client, Prompt prompt)
{
Throw.IfNull(client);
@ -57,7 +56,7 @@ public sealed class McpClientPrompt
/// which can be useful for advanced scenarios or when implementing custom MCP client extensions.
/// </para>
/// <para>
/// For most common use cases, you can use the more convenient <see cref="Name"/> and
/// For most common use cases, you can use the more convenient <see cref="Name"/> and
/// <see cref="Description"/> properties instead of accessing the <see cref="ProtocolPrompt"/> directly.
/// </para>
/// </remarks>
@ -69,7 +68,7 @@ public sealed class McpClientPrompt
/// <summary>Gets the title of the prompt.</summary>
public string? Title => ProtocolPrompt.Title;
/// <summary>Gets a description of the prompt.</summary>
/// <summary>Gets the description of the prompt.</summary>
public string? Description => ProtocolPrompt.Description;
/// <summary>
@ -85,7 +84,7 @@ public sealed class McpClientPrompt
/// The server will process the request and return a result containing messages or other content.
/// </para>
/// <para>
/// This is a convenience method that internally calls <see cref="McpClient.GetPromptAsync"/>
/// This is a convenience method that internally calls <see cref="McpClient.GetPromptAsync"/>
/// with this prompt's name and arguments.
/// </para>
/// </remarks>
@ -100,4 +99,4 @@ public sealed class McpClientPrompt
return await _client.GetPromptAsync(ProtocolPrompt.Name, argDict, serializerOptions, cancellationToken: cancellationToken).ConfigureAwait(false);
}
}
}

17
src/ModelContextProtocol.Core/Client/McpClientResource.cs
View file

@ -25,17 +25,16 @@ public sealed class McpClientResource
/// <remarks>
/// <para>
/// This constructor enables reusing cached resource definitions across different <see cref="McpClient"/> instances
/// without needing to call <see cref="McpClient.ListResourcesAsync"/> on every reconnect. This is particularly useful
/// without needing to call <see cref="McpClient.ListResourcesAsync"/> on every reconnect. This is particularly useful
/// in scenarios where resource definitions are stable and network round-trips should be minimized.
/// </para>
/// <para>
/// The provided <paramref name="resource"/> must represent a resource that is actually available on the server
/// associated with the <paramref name="client"/>. Attempting to read a resource that doesn't exist on the
/// The provided <paramref name="resource"/> must represent a resource that is actually available on the server
/// associated with the <paramref name="client"/>. Attempting to read a resource that doesn't exist on the
/// server will result in an <see cref="McpException"/>.
/// </para>
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="client"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="resource"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="client"/> or <paramref name="resource"/> is <see langword="null"/>.</exception>
public McpClientResource(McpClient client, Resource resource)
{
Throw.IfNull(client);
@ -52,7 +51,7 @@ public sealed class McpClientResource
/// which can be useful for advanced scenarios or when implementing custom MCP client extensions.
/// </para>
/// <para>
/// For most common use cases, you can use the more convenient <see cref="Name"/> and
/// For most common use cases, you can use the more convenient <see cref="Name"/> and
/// <see cref="Description"/> properties instead of accessing the <see cref="ProtocolResource"/> directly.
/// </para>
/// </remarks>
@ -67,10 +66,10 @@ public sealed class McpClientResource
/// <summary>Gets the title of the resource.</summary>
public string? Title => ProtocolResource.Title;
/// <summary>Gets a description of the resource.</summary>
/// <summary>Gets the description of the resource.</summary>
public string? Description => ProtocolResource.Description;
/// <summary>Gets a media (MIME) type of the resource.</summary>
/// <summary>Gets the media (MIME) type of the resource.</summary>
public string? MimeType => ProtocolResource.MimeType;
/// <summary>
@ -86,4 +85,4 @@ public sealed class McpClientResource
public ValueTask<ReadResourceResult> ReadAsync(
CancellationToken cancellationToken = default) =>
_client.ReadResourceAsync(Uri, cancellationToken);
}
}

17
src/ModelContextProtocol.Core/Client/McpClientResourceTemplate.cs
View file

@ -25,17 +25,16 @@ public sealed class McpClientResourceTemplate
/// <remarks>
/// <para>
/// This constructor enables reusing cached resource template definitions across different <see cref="McpClient"/> instances
/// without needing to call <see cref="McpClient.ListResourceTemplatesAsync"/> on every reconnect. This is particularly useful
/// without needing to call <see cref="McpClient.ListResourceTemplatesAsync"/> on every reconnect. This is particularly useful
/// in scenarios where resource template definitions are stable and network round-trips should be minimized.
/// </para>
/// <para>
/// The provided <paramref name="resourceTemplate"/> must represent a resource template that is actually available on the server
/// associated with the <paramref name="client"/>. Attempting to read a resource template that doesn't exist on the
/// The provided <paramref name="resourceTemplate"/> must represent a resource template that is actually available on the server
/// associated with the <paramref name="client"/>. Attempting to read a resource template that doesn't exist on the
/// server will result in an <see cref="McpException"/>.
/// </para>
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="client"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="resourceTemplate"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="client"/> or <paramref name="resourceTemplate"/> is <see langword="null"/>.</exception>
public McpClientResourceTemplate(McpClient client, ResourceTemplate resourceTemplate)
{
Throw.IfNull(client);
@ -52,7 +51,7 @@ public sealed class McpClientResourceTemplate
/// which can be useful for advanced scenarios or when implementing custom MCP client extensions.
/// </para>
/// <para>
/// For most common use cases, you can use the more convenient <see cref="UriTemplate"/> and
/// For most common use cases, you can use the more convenient <see cref="UriTemplate"/> and
/// <see cref="Description"/> properties instead of accessing the <see cref="ProtocolResourceTemplate"/> directly.
/// </para>
/// </remarks>
@ -67,10 +66,10 @@ public sealed class McpClientResourceTemplate
/// <summary>Gets the title of the resource template.</summary>
public string? Title => ProtocolResourceTemplate.Title;
/// <summary>Gets a description of the resource template.</summary>
/// <summary>Gets the description of the resource template.</summary>
public string? Description => ProtocolResourceTemplate.Description;
/// <summary>Gets a media (MIME) type of the resource template.</summary>
/// <summary>Gets the media (MIME) type of the resource template.</summary>
public string? MimeType => ProtocolResourceTemplate.MimeType;
/// <summary>
@ -86,4 +85,4 @@ public sealed class McpClientResourceTemplate
IReadOnlyDictionary<string, object?> arguments,
CancellationToken cancellationToken = default) =>
_client.ReadResourceAsync(UriTemplate, arguments, cancellationToken);
}
}

46
src/ModelContextProtocol.Core/Client/McpClientTool.cs
View file

@ -10,7 +10,7 @@ namespace ModelContextProtocol.Client;
/// </summary>
/// <remarks>
/// <para>
/// The <see cref="McpClientTool"/> class encapsulates an <see cref="McpClient"/> along with a description of
/// The <see cref="McpClientTool"/> class encapsulates an <see cref="McpClient"/> along with a description of
/// a tool available via that client, allowing it to be invoked as an <see cref="AIFunction"/>. This enables integration
/// with AI models that support function calling capabilities.
/// </para>
@ -43,23 +43,22 @@ public sealed class McpClientTool : AIFunction
/// <param name="client">The <see cref="McpClient"/> instance to use for invoking the tool.</param>
/// <param name="tool">The protocol <see cref="Tool"/> definition describing the tool's metadata and schema.</param>
/// <param name="serializerOptions">
/// The JSON serialization options governing argument serialization. If <see langword="null"/>,
/// <see cref="McpJsonUtilities.DefaultOptions"/> will be used.
/// The JSON serialization options governing argument serialization. If <see langword="null"/>,
/// <see cref="McpJsonUtilities.DefaultOptions"/> is used.
/// </param>
/// <remarks>
/// <para>
/// This constructor enables reusing cached tool definitions across different <see cref="McpClient"/> instances
/// without needing to call <see cref="McpClient.ListToolsAsync"/> on every reconnect. This is particularly useful
/// without needing to call <see cref="McpClient.ListToolsAsync"/> on every reconnect. This is particularly useful
/// in scenarios where tool definitions are stable and network round-trips should be minimized.
/// </para>
/// <para>
/// The provided <paramref name="tool"/> must represent a tool that is actually available on the server
/// associated with the <paramref name="client"/>. Attempting to invoke a tool that doesn't exist on the
/// The provided <paramref name="tool"/> must represent a tool that is actually available on the server
/// associated with the <paramref name="client"/>. Attempting to invoke a tool that doesn't exist on the
/// server will result in an <see cref="McpException"/>.
/// </para>
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="client"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="tool"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="client"/> or <paramref name="tool"/> is <see langword="null"/>.</exception>
public McpClientTool(
McpClient client,
Tool tool,
@ -165,23 +164,23 @@ public sealed class McpClientTool : AIFunction
/// routed to this instance.
/// </param>
/// <param name="serializerOptions">
/// The JSON serialization options governing argument serialization. If <see langword="null"/>, the default serialization options will be used.
/// The JSON serialization options governing argument serialization. If <see langword="null"/>, the default serialization options are used.
/// </param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>
/// A task containing the <see cref="CallToolResult"/> from the tool execution. The response includes
/// the tool's output content, which may be structured data, text, or an error message.
/// the tool's output content, which can be structured data, text, or an error message.
/// </returns>
/// <remarks>
/// The base <see cref="AIFunction.InvokeAsync"/> method is overridden to invoke this <see cref="CallAsync"/> method.
/// The only difference in behavior is <see cref="AIFunction.InvokeAsync"/> will serialize 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="CallToolResult"/> 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.
/// </remarks>
/// <exception cref="McpException">The server could not find the requested tool, or the server encountered an error while processing the request.</exception>
/// <example>
/// <code>
/// <code language="csharp">
/// var result = await tool.CallAsync(
/// new Dictionary&lt;string, object?&gt;
/// {
@ -203,23 +202,24 @@ public sealed class McpClientTool : AIFunction
/// <returns>A new instance of <see cref="McpClientTool"/> with the provided name.</returns>
/// <remarks>
/// <para>
/// This is useful for optimizing the tool name for specific models or for prefixing the tool name
/// This method is useful for optimizing the tool name for specific models or for prefixing the tool name
/// with a namespace to avoid conflicts.
/// </para>
/// <para>
/// Changing the name can help with:
/// </para>
/// <list type="bullet">
/// <item>Making the tool name more intuitive for the model</item>
/// <item>Preventing name collisions when using tools from multiple sources</item>
/// <item>Creating specialized versions of a general tool for specific contexts</item>
/// <item>Making the tool name more intuitive for the model.</item>
/// <item>Preventing name collisions when using tools from multiple sources.</item>
/// <item>Creating specialized versions of a general tool for specific contexts.</item>
/// </list>
/// <para>
/// When invoking <see cref="AIFunction.InvokeAsync"/>, the MCP server will still be called with
/// When invoking <see cref="AIFunction.InvokeAsync"/>, the MCP server will still be called with
/// the original tool name, so no mapping is required on the server side. This new name only affects
/// 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);
@ -233,12 +233,12 @@ public sealed class McpClientTool : AIFunction
/// context about how the tool should be used. This is particularly useful when:
/// </para>
/// <list type="bullet">
/// <item>The original description is too technical or lacks clarity for the model</item>
/// <item>You want to add example usage scenarios to improve the model's understanding</item>
/// <item>You need to tailor the tool's description for specific model requirements</item>
/// <item>The original description is too technical or lacks clarity for the model.</item>
/// <item>You want to add example usage scenarios to improve the model's understanding.</item>
/// <item>You need to tailor the tool's description for specific model requirements.</item>
/// </list>
/// <para>
/// When invoking <see cref="AIFunction.InvokeAsync"/>, the MCP server will still be called with
/// When invoking <see cref="AIFunction.InvokeAsync"/>, the MCP server will still be called with
/// the original tool description, so no mapping is required on the server side. This new description only affects
/// the value returned from this instance's <see cref="AITool.Description"/>.
/// </para>
@ -260,7 +260,7 @@ public sealed class McpClientTool : AIFunction
/// </para>
/// <para>
/// Only one <see cref="IProgress{T}"/> can be specified at a time. Calling <see cref="WithProgress"/> again
/// will overwrite any previously specified progress instance.
/// overwrites any previously specified progress instance.
/// </para>
/// </remarks>
/// <returns>A new instance of <see cref="McpClientTool"/>, configured with the provided progress instance.</returns>
@ -270,4 +270,4 @@ public sealed class McpClientTool : AIFunction
return new McpClientTool(_client, ProtocolTool, JsonSerializerOptions, _name, _description, progress);
}
}
}

6
src/ModelContextProtocol.Core/Client/StdioClientTransport.cs
View file

@ -38,7 +38,7 @@ public sealed partial class StdioClientTransport : IClientTransport
/// Initializes a new instance of the <see cref="StdioClientTransport"/> class.
/// </summary>
/// <param name="options">Configuration options for the transport, including the command to execute, arguments, working directory, and environment variables.</param>
/// <param name="loggerFactory">Logger factory for creating loggers used for diagnostic output during transport operations.</param>
/// <param name="loggerFactory">A logger factory for creating loggers used for diagnostic output during transport operations.</param>
public StdioClientTransport(StdioClientTransportOptions options, ILoggerFactory? loggerFactory = null)
{
Throw.IfNull(options);
@ -91,7 +91,7 @@ public sealed partial class StdioClientTransport : IClientTransport
#endif
};
if (arguments is not null)
if (arguments is not null)
{
#if NET
foreach (string arg in arguments)
@ -234,7 +234,7 @@ public sealed partial class StdioClientTransport : IClientTransport
}
}
/// <summary>Gets whether <paramref name="process"/> has exited.</summary>
/// <summary>Gets a value that indicates whether <paramref name="process"/> has exited.</summary>
internal static bool HasExited(Process process)
{
try

10
src/ModelContextProtocol.Core/Client/StdioClientTransportOptions.cs
View file

@ -43,7 +43,7 @@ public sealed class StdioClientTransportOptions
/// <remarks>
/// <para>
/// This property allows you to specify environment variables that will be set in the server process's
/// environment. This is useful for passing configuration, authentication information, or runtime flags
/// environment. Setting these variables is useful for passing configuration, authentication information, or runtime flags
/// to the server without modifying its code.
/// </para>
/// <para>
@ -58,15 +58,15 @@ public sealed class StdioClientTransportOptions
/// <summary>
/// Gets or sets the timeout to wait for the server to shut down gracefully.
/// </summary>
/// <value>
/// The amount of time to wait for the server to shut down gracefully. The default is 5 seconds.
/// </value>
/// <remarks>
/// <para>
/// This property dictates how long the client should wait for the server process to exit cleanly during shutdown
/// before forcibly terminating it. This balances between giving the server enough time to clean up
/// before forcibly terminating it. This balances giving the server enough time to clean up
/// resources and not hanging indefinitely if a server process becomes unresponsive.
/// </para>
/// <para>
/// The default is five seconds.
/// </para>
/// </remarks>
public TimeSpan ShutdownTimeout { get; set; } = TimeSpan.FromSeconds(5);

4
src/ModelContextProtocol.Core/Client/StreamClientSessionTransport.cs
View file

@ -31,7 +31,7 @@ internal class StreamClientSessionTransport : TransportBase
/// A name that identifies this transport endpoint in logs.
/// </param>
/// <param name="loggerFactory">
/// Optional factory for creating loggers. If null, a NullLogger will be used.
/// Optional factory for creating loggers. If null, a NullLogger is used.
/// </param>
/// <remarks>
/// This constructor starts a background task to read messages from the server output stream.
@ -73,7 +73,7 @@ internal class StreamClientSessionTransport : TransportBase
/// A name that identifies this transport endpoint in logs.
/// </param>
/// <param name="loggerFactory">
/// Optional factory for creating loggers. If null, a NullLogger will be used.
/// Optional factory for creating loggers. If null, a NullLogger is used.
/// </param>
/// <remarks>
/// This constructor starts a background task to read messages from the server output stream.