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
48 changed files with 452 additions and 447 deletions
Download patch file Download diff file Expand all files Collapse all files

8
src/ModelContextProtocol.Core/Authentication/ClientOAuthOptions.cs
View file

@ -19,7 +19,7 @@ public sealed class ClientOAuthOptions
/// Gets or sets the OAuth client secret.
/// </summary>
/// <remarks>
/// This is optional for public clients or when using PKCE without client authentication.
/// This secret is optional for public clients or when using PKCE without client authentication.
/// </remarks>
public string? ClientSecret { get; set; }
@ -43,7 +43,7 @@ public sealed class ClientOAuthOptions
/// If not specified, the provider will use the scopes from the protected resource metadata.
/// </para>
/// <para>
/// Common OAuth scopes include "openid", "profile", "email", etc.
/// Common OAuth scopes include "openid", "profile", and "email".
/// </para>
/// </remarks>
public IEnumerable<string>? Scopes { get; set; }
@ -82,7 +82,7 @@ public sealed class ClientOAuthOptions
/// Gets or sets the options to use during dynamic client registration.
/// </summary>
/// <remarks>
/// Only used when a <see cref="ClientId"/> is not specified.
/// This value is only used when no <see cref="ClientId"/> is specified.
/// </remarks>
public DynamicClientRegistrationOptions? DynamicClientRegistration { get; set; }
@ -92,7 +92,7 @@ public sealed class ClientOAuthOptions
/// </summary>
/// <remarks>
/// <para>
/// Parameters specified cannot override or append to any automatically set parameters like the "redirect_uri"
/// Parameters specified cannot override or append to any automatically set parameters like the "redirect_uri",
/// which should instead be configured via <see cref="RedirectUri"/>.
/// </para>
/// </remarks>

10
src/ModelContextProtocol.Core/Authentication/ClientOAuthProvider.cs
View file

@ -52,9 +52,9 @@ internal sealed partial class ClientOAuthProvider
/// </summary>
/// <param name="serverUrl">The MCP server URL.</param>
/// <param name="options">The OAuth provider configuration options.</param>
/// <param name="httpClient">The HTTP client to use for OAuth requests. If null, a default HttpClient will be used.</param>
/// <param name="httpClient">The HTTP client to use for OAuth requests. If null, a default HttpClient is used.</param>
/// <param name="loggerFactory">A logger factory to handle diagnostic messages.</param>
/// <exception cref="ArgumentNullException">Thrown when serverUrl or options are null.</exception>
/// <exception cref="ArgumentNullException"><paramref name="serverUrl"/> or <paramref name="options"/> is null.</exception>
public ClientOAuthProvider(
Uri serverUrl,
ClientOAuthOptions options,
@ -136,7 +136,7 @@ internal sealed partial class ClientOAuthProvider
/// <param name="scheme">The authentication scheme to use.</param>
/// <param name="resourceUri">The URI of the resource requiring authentication.</param>
/// <param name="cancellationToken">A token to cancel the operation.</param>
/// <returns>An authentication token string or null if no token could be obtained for the specified scheme.</returns>
/// <returns>An authentication token string, or null if no token could be obtained for the specified scheme.</returns>
public async Task<string?> GetCredentialAsync(string scheme, Uri resourceUri, CancellationToken cancellationToken = default)
{
ThrowIfNotBearerScheme(scheme);
@ -186,8 +186,8 @@ internal sealed partial class ClientOAuthProvider
/// Performs OAuth authorization by selecting an appropriate authorization server and completing the OAuth flow.
/// </summary>
/// <param name="response">The 401 Unauthorized response containing authentication challenge.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>Result indicating whether authorization was successful.</returns>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>A result object indicating whether authorization was successful.</returns>
private async Task PerformOAuthAuthorizationAsync(
HttpResponseMessage response,
CancellationToken cancellationToken)

6
src/ModelContextProtocol.Core/Authentication/DynamicClientRegistrationOptions.cs
View file

@ -9,7 +9,7 @@ public sealed class DynamicClientRegistrationOptions
/// Gets or sets the client name to use during dynamic client registration.
/// </summary>
/// <remarks>
/// This is a human-readable name for the client that may be displayed to users during authorization.
/// This value is a human-readable name for the client that can be displayed to users during authorization.
/// </remarks>
public string? ClientName { get; set; }
@ -17,7 +17,7 @@ public sealed class DynamicClientRegistrationOptions
/// Gets or sets the client URI to use during dynamic client registration.
/// </summary>
/// <remarks>
/// This should be a URL pointing to the client's home page or information page.
/// This value should be a URL pointing to the client's home page or information page.
/// </remarks>
public Uri? ClientUri { get; set; }
@ -29,7 +29,7 @@ public sealed class DynamicClientRegistrationOptions
/// This token is used to authenticate the client during the registration process.
/// </para>
/// <para>
/// This is required if the authorization server does not allow anonymous client registration.
/// This token is required if the authorization server does not allow anonymous client registration.
/// </para>
/// </remarks>
public string? InitialAccessToken { get; set; }

16
src/ModelContextProtocol.Core/Authentication/DynamicClientRegistrationResponse.cs
View file

@ -8,49 +8,49 @@ namespace ModelContextProtocol.Authentication;
public sealed class DynamicClientRegistrationResponse
{
/// <summary>
/// Gets or sets the client identifier.
/// Gets or initializes the client identifier.
/// </summary>
[JsonPropertyName("client_id")]
public required string ClientId { get; init; }
/// <summary>
/// Gets or sets the client secret.
/// Gets or initializes the client secret.
/// </summary>
[JsonPropertyName("client_secret")]
public string? ClientSecret { get; init; }
/// <summary>
/// Gets or sets the redirect URIs for the client.
/// Gets or initializes the redirect URIs for the client.
/// </summary>
[JsonPropertyName("redirect_uris")]
public string[]? RedirectUris { get; init; }
/// <summary>
/// Gets or sets the token endpoint authentication method.
/// Gets or initializes the token endpoint authentication method.
/// </summary>
[JsonPropertyName("token_endpoint_auth_method")]
public string? TokenEndpointAuthMethod { get; init; }
/// <summary>
/// Gets or sets the grant types that the client will use.
/// Gets or initializes the grant types that the client will use.
/// </summary>
[JsonPropertyName("grant_types")]
public string[]? GrantTypes { get; init; }
/// <summary>
/// Gets or sets the response types that the client will use.
/// Gets or initializes the response types that the client will use.
/// </summary>
[JsonPropertyName("response_types")]
public string[]? ResponseTypes { get; init; }
/// <summary>
/// Gets or sets the client ID issued timestamp.
/// Gets or initializes the timestamp at which the client ID was issued.
/// </summary>
[JsonPropertyName("client_id_issued_at")]
public long? ClientIdIssuedAt { get; init; }
/// <summary>
/// Gets or sets the client secret expiration time.
/// Gets or initializes the client secret expiration time.
/// </summary>
[JsonPropertyName("client_secret_expires_at")]
public long? ClientSecretExpiresAt { get; init; }

101
src/ModelContextProtocol.Core/Authentication/ProtectedResourceMetadata.cs
View file

@ -9,66 +9,81 @@ namespace ModelContextProtocol.Authentication;
public sealed class ProtectedResourceMetadata
{
/// <summary>
/// The resource URI.
/// Gets or sets the resource URI.
/// </summary>
/// <value>
/// The protected resource's resource identifier.
/// </value>
/// <remarks>
/// REQUIRED. The protected resource's resource identifier.
/// REQUIRED.
/// </remarks>
[JsonPropertyName("resource")]
public required Uri Resource { get; set; }
/// <summary>
/// The list of authorization server URIs.
/// Gets or sets the list of authorization server URIs.
/// </summary>
/// <remarks>
/// OPTIONAL. JSON array containing a list of OAuth authorization server issuer identifiers
/// <value>
/// A JSON array containing a list of OAuth authorization server issuer identifiers
/// for authorization servers that can be used with this protected resource.
/// </value>
/// <remarks>
/// OPTIONAL.
/// </remarks>
[JsonPropertyName("authorization_servers")]
public List<Uri> AuthorizationServers { get; set; } = [];
/// <summary>
/// The supported bearer token methods.
/// Gets or sets the supported bearer token methods.
/// </summary>
/// <remarks>
/// OPTIONAL. JSON array containing a list of the supported methods of sending an OAuth 2.0 bearer token
/// <value>
/// A JSON array containing a list of the supported methods of sending an OAuth 2.0 bearer token
/// to the protected resource. Defined values are ["header", "body", "query"].
/// </value>
/// <remarks>
/// OPTIONAL.
/// </remarks>
[JsonPropertyName("bearer_methods_supported")]
public List<string> BearerMethodsSupported { get; set; } = ["header"];
/// <summary>
/// The supported scopes.
/// Gets or sets the supported scopes.
/// </summary>
/// <remarks>
/// RECOMMENDED. JSON array containing a list of scope values that are used in authorization
/// <value>
/// A JSON array containing a list of scope values that are used in authorization
/// requests to request access to this protected resource.
/// </value>
/// <remarks>
/// RECOMMENDED.
/// </remarks>
[JsonPropertyName("scopes_supported")]
public List<string> ScopesSupported { get; set; } = [];
/// <summary>
/// URL of the protected resource's JSON Web Key (JWK) Set document.
/// Gets or sets the URL of the protected resource's JSON Web Key (JWK) Set document.
/// </summary>
/// <remarks>
/// OPTIONAL. This contains public keys belonging to the protected resource, such as signing key(s)
/// that the resource server uses to sign resource responses. This URL MUST use the https scheme.
/// OPTIONAL. This document contains public keys belonging to the protected resource, such as signing keys
/// that the resource server uses to sign resource responses. This URL MUST use the HTTPS scheme.
/// </remarks>
[JsonPropertyName("jwks_uri")]
public Uri? JwksUri { get; set; }
/// <summary>
/// List of the JWS signing algorithms supported by the protected resource for signing resource responses.
/// Gets or sets the list of the JWS signing algorithms supported by the protected resource for signing resource responses.
/// </summary>
/// <value>
/// A JSON array containing a list of the JWS signing algorithms (alg values) supported by the protected resource
/// for signing resource responses.
/// </value>
/// <remarks>
/// OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the protected resource
/// for signing resource responses. No default algorithms are implied if this entry is omitted. The value none MUST NOT be used.
/// OPTIONAL. No default algorithms are implied if this entry is omitted. The value "none" MUST NOT be used.
/// </remarks>
[JsonPropertyName("resource_signing_alg_values_supported")]
public List<string>? ResourceSigningAlgValuesSupported { get; set; }
/// <summary>
/// Human-readable name of the protected resource intended for display to the end user.
/// Gets or sets the human-readable name of the protected resource intended for display to the end user.
/// </summary>
/// <remarks>
/// RECOMMENDED. It is recommended that protected resource metadata include this field.
@ -78,26 +93,32 @@ public sealed class ProtectedResourceMetadata
public string? ResourceName { get; set; }
/// <summary>
/// The URI to the resource documentation.
/// Gets or sets the URI to the resource documentation.
/// </summary>
/// <remarks>
/// OPTIONAL. URL of a page containing human-readable information that developers might want or need to know
/// <value>
/// The URL of a page containing human-readable information that developers might want or need to know
/// when using the protected resource.
/// </value>
/// <remarks>
/// OPTIONAL.
/// </remarks>
[JsonPropertyName("resource_documentation")]
public Uri? ResourceDocumentation { get; set; }
/// <summary>
/// URL of a page containing human-readable information about the protected resource's requirements.
/// Gets or sets the URL of a page containing human-readable information about the protected resource's requirements.
/// </summary>
/// <value>
/// The URL of a page that contains information about how the client can use the data provided by the protected resource.
/// </value>
/// <remarks>
/// OPTIONAL. Information about how the client can use the data provided by the protected resource.
/// OPTIONAL.
/// </remarks>
[JsonPropertyName("resource_policy_uri")]
public Uri? ResourcePolicyUri { get; set; }
/// <summary>
/// URL of a page containing human-readable information about the protected resource's terms of service.
/// Gets or sets the URL of a page containing human-readable information about the protected resource's terms of service.
/// </summary>
/// <remarks>
/// OPTIONAL. The value of this field MAY be internationalized.
@ -106,39 +127,51 @@ public sealed class ProtectedResourceMetadata
public Uri? ResourceTosUri { get; set; }
/// <summary>
/// Boolean value indicating protected resource support for mutual-TLS client certificate-bound access tokens.
/// Gets or sets a value indicating whether there is protected resource support for mutual-TLS client certificate-bound access tokens.
/// </summary>
/// <value>
/// <see langword="true"/> if there's protected resource support for mutual-TLS client certificate-bound access tokens; otherwise, <see langword="false"/>. The default is <see langword="false"/>.
/// </value>
/// <remarks>
/// OPTIONAL. If omitted, the default value is false.
/// OPTIONAL.
/// </remarks>
[JsonPropertyName("tls_client_certificate_bound_access_tokens")]
public bool? TlsClientCertificateBoundAccessTokens { get; set; }
/// <summary>
/// List of the authorization details type values supported by the resource server.
/// Gets or sets the list of the authorization details type values supported by the resource server.
/// </summary>
/// <remarks>
/// OPTIONAL. JSON array containing a list of the authorization details type values supported by the resource server
/// <value>
/// A JSON array containing a list of the authorization details type values supported by the resource server
/// when the authorization_details request parameter is used.
/// </value>
/// <remarks>
/// OPTIONAL.
/// </remarks>
[JsonPropertyName("authorization_details_types_supported")]
public List<string>? AuthorizationDetailsTypesSupported { get; set; }
/// <summary>
/// List of the JWS algorithm values supported by the resource server for validating DPoP proof JWTs.
/// Gets or sets the list of the JWS algorithm values supported by the resource server for validating DPoP proof JWTs.
/// </summary>
/// <remarks>
/// OPTIONAL. JSON array containing a list of the JWS alg values supported by the resource server
/// <value>
/// A JSON array containing a list of the JWS alg values supported by the resource server
/// for validating Demonstrating Proof of Possession (DPoP) proof JWTs.
/// </value>
/// <remarks>
/// OPTIONAL.
/// </remarks>
[JsonPropertyName("dpop_signing_alg_values_supported")]
public List<string>? DpopSigningAlgValuesSupported { get; set; }
/// <summary>
/// Boolean value specifying whether the protected resource always requires the use of DPoP-bound access tokens.
/// Gets or sets a value indicating whether the protected resource always requires the use of DPoP-bound access tokens.
/// </summary>
/// <value>
/// <see langword="true"/> if the protected resource always requires the use of DPoP-bound access tokens; otherwise, <see langword="false"/>. The default is <see langword="false"/>.
/// </value>
/// <remarks>
/// OPTIONAL. If omitted, the default value is false.
/// OPTIONAL.
/// </remarks>
[JsonPropertyName("dpop_bound_access_tokens_required")]
public bool? DpopBoundAccessTokensRequired { get; set; }

10
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.

26
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.

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

@ -26,7 +26,7 @@ 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

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)
{

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

@ -42,7 +42,7 @@ public abstract partial class McpClient : McpSession, IMcpClient
/// </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.
/// 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; }

14
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
{
@ -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>
@ -57,7 +55,7 @@ public static class McpClientExtensions
/// </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.
/// <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
@ -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}"/>
@ -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>

4
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>

8
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; }
@ -50,17 +50,19 @@ 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);

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

@ -39,8 +39,7 @@ public sealed class McpClientPrompt
/// 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);
@ -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>

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

@ -34,8 +34,7 @@ public sealed class McpClientResource
/// 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);
@ -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>

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

@ -34,8 +34,7 @@ public sealed class McpClientResourceTemplate
/// 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);
@ -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>

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

@ -44,7 +44,7 @@ public sealed class McpClientTool : AIFunction
/// <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.
/// <see cref="McpJsonUtilities.DefaultOptions"/> is used.
/// </param>
/// <remarks>
/// <para>
@ -58,8 +58,7 @@ public sealed class McpClientTool : AIFunction
/// 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,16 +202,16 @@ 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
@ -220,6 +219,7 @@ public sealed class McpClientTool : AIFunction
/// the value returned from this instance's <see cref="AITool.Name"/>.
/// </para>
/// </remarks>
/// <returns>A new instance of <see cref="McpClientTool"/> with the provided name.</returns>
public McpClientTool WithName(string name) =>
new(_client, ProtocolTool, JsonSerializerOptions, name, _description, _progress);
@ -233,9 +233,9 @@ 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
@ -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>

4
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);
@ -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.

Some files were not shown because too many files have changed in this diff Show more