MCP Core docs edit pass (#1033)

Co-authored-by: Stephen Toub <stoub@microsoft.com>

src/ModelContextProtocol.Core/Authentication/ClientOAuthOptions.cs

@@ -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>
@@ -103,4 +103,4 @@ public sealed class ClientOAuthOptions
     /// If none is provided, tokens will be cached with the transport.
     /// </summary>
     public ITokenCache? TokenCache { get; set; }
-}
+}

src/ModelContextProtocol.Core/Authentication/ClientOAuthProvider.cs

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

src/ModelContextProtocol.Core/Authentication/DynamicClientRegistrationOptions.cs

@@ -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; }
@@ -46,4 +46,4 @@ public sealed class DynamicClientRegistrationOptions
     /// </para>
     /// </remarks>
     public Func<DynamicClientRegistrationResponse, CancellationToken, Task>? ResponseDelegate { get; set; }
-}
+}

src/ModelContextProtocol.Core/Authentication/DynamicClientRegistrationResponse.cs

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

src/ModelContextProtocol.Core/Authentication/ProtectedResourceMetadata.cs

@@ -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,40 +127,52 @@ 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; }
-}
+}