Improve progress reporting

- Enable injecting an `IProgress<>` into a tool call to report progress when the client has supplied a progress token
- Add a custom type for ProgressToken and ProgressNotification to map to the schema
- Simplify RequestId to match ProgressToken's shape
- Serialize StdioClientTransport's SendMessageAsync implementation
- Add strongly-typed names for all request methods
- Change all request IDs created by McpJsonRpcEndpoint to include a guid for that endpoint

Author: stephentoub

src/ModelContextProtocol/Client/McpClient.cs

@@ -41,7 +41,7 @@ public McpClient(IClientTransport transport, McpClientOptions options, McpServer
             }
 
             SetRequestHandler<CreateMessageRequestParams, CreateMessageResult>(
-                "sampling/createMessage",
+                RequestMethods.SamplingCreateMessage,
                 (request, ct) => samplingHandler(request, ct));
         }
 
@@ -53,7 +53,7 @@ public McpClient(IClientTransport transport, McpClientOptions options, McpServer
             }
 
             SetRequestHandler<ListRootsRequestParams, ListRootsResult>(
-                "roots/list",
+                RequestMethods.RootsList,
                 (request, ct) => rootsHandler(request, ct));
         }
     }
@@ -124,7 +124,7 @@ private async Task InitializeAsync(CancellationToken cancellationToken)
             var initializeResponse = await SendRequestAsync<InitializeResult>(
                 new JsonRpcRequest
                 {
-                    Method = "initialize",
+                    Method = RequestMethods.Initialize,
                     Params = new InitializeRequestParams()
                     {
                         ProtocolVersion = _options.ProtocolVersion,
@@ -152,7 +152,7 @@ private async Task InitializeAsync(CancellationToken cancellationToken)
 
             // Send initialized notification
             await SendMessageAsync(
-                new JsonRpcNotification { Method = "notifications/initialized" },
+                new JsonRpcNotification { Method = NotificationMethods.InitializedNotification },
                 initializationCts.Token).ConfigureAwait(false);
         }
         catch (OperationCanceledException) when (initializationCts.IsCancellationRequested)

src/ModelContextProtocol/Client/McpClientExtensions.cs

@@ -41,7 +41,7 @@ public static Task PingAsync(this IMcpClient client, CancellationToken cancellat
         Throw.IfNull(client);
 
         return client.SendRequestAsync<dynamic>(
-            CreateRequest("ping", null),
+            CreateRequest(RequestMethods.Ping, null),
             cancellationToken);
     }
 
@@ -61,7 +61,7 @@ public static async Task<IList<McpClientTool>> ListToolsAsync(
         do
         {
             var toolResults = await client.SendRequestAsync<ListToolsResult>(
-                CreateRequest("tools/list", CreateCursorDictionary(cursor)),
+                CreateRequest(RequestMethods.ToolsList, CreateCursorDictionary(cursor)),
                 cancellationToken).ConfigureAwait(false);
 
             tools ??= new List<McpClientTool>(toolResults.Tools.Count);
@@ -96,7 +96,7 @@ public static async IAsyncEnumerable<McpClientTool> EnumerateToolsAsync(
         do
         {
             var toolResults = await client.SendRequestAsync<ListToolsResult>(
-                CreateRequest("tools/list", CreateCursorDictionary(cursor)),
+                CreateRequest(RequestMethods.ToolsList, CreateCursorDictionary(cursor)),
                 cancellationToken).ConfigureAwait(false);
 
             foreach (var tool in toolResults.Tools)
@@ -126,7 +126,7 @@ public static async Task<IList<Prompt>> ListPromptsAsync(
         do
         {
             var promptResults = await client.SendRequestAsync<ListPromptsResult>(
-                CreateRequest("prompts/list", CreateCursorDictionary(cursor)),
+                CreateRequest(RequestMethods.PromptsList, CreateCursorDictionary(cursor)),
                 cancellationToken).ConfigureAwait(false);
 
             if (prompts is null)
@@ -164,7 +164,7 @@ public static async IAsyncEnumerable<Prompt> EnumeratePromptsAsync(
         do
         {
             var promptResults = await client.SendRequestAsync<ListPromptsResult>(
-                CreateRequest("prompts/list", CreateCursorDictionary(cursor)),
+                CreateRequest(RequestMethods.PromptsList, CreateCursorDictionary(cursor)),
                 cancellationToken).ConfigureAwait(false);
 
             foreach (var prompt in promptResults.Prompts)
@@ -192,7 +192,7 @@ public static Task<GetPromptResult> GetPromptAsync(
         Throw.IfNullOrWhiteSpace(name);
 
         return client.SendRequestAsync<GetPromptResult>(
-            CreateRequest("prompts/get", CreateParametersDictionary(name, arguments)),
+            CreateRequest(RequestMethods.PromptsGet, CreateParametersDictionary(name, arguments)),
             cancellationToken);
     }
 
@@ -213,7 +213,7 @@ public static async Task<IList<ResourceTemplate>> ListResourceTemplatesAsync(
         do
         {
             var templateResults = await client.SendRequestAsync<ListResourceTemplatesResult>(
-                CreateRequest("resources/templates/list", CreateCursorDictionary(cursor)),
+                CreateRequest(RequestMethods.ResourcesTemplatesList, CreateCursorDictionary(cursor)),
                 cancellationToken).ConfigureAwait(false);
 
             if (templates is null)
@@ -251,7 +251,7 @@ public static async IAsyncEnumerable<ResourceTemplate> EnumerateResourceTemplate
         do
         {
             var templateResults = await client.SendRequestAsync<ListResourceTemplatesResult>(
-                CreateRequest("resources/templates/list", CreateCursorDictionary(cursor)),
+                CreateRequest(RequestMethods.ResourcesTemplatesList, CreateCursorDictionary(cursor)),
                 cancellationToken).ConfigureAwait(false);
 
             foreach (var template in templateResults.ResourceTemplates)
@@ -281,7 +281,7 @@ public static async Task<IList<Resource>> ListResourcesAsync(
         do
         {
             var resourceResults = await client.SendRequestAsync<ListResourcesResult>(
-                CreateRequest("resources/list", CreateCursorDictionary(cursor)),
+                CreateRequest(RequestMethods.ResourcesList, CreateCursorDictionary(cursor)),
                 cancellationToken).ConfigureAwait(false);
 
             if (resources is null)
@@ -319,7 +319,7 @@ public static async IAsyncEnumerable<Resource> EnumerateResourcesAsync(
         do
         {
             var resourceResults = await client.SendRequestAsync<ListResourcesResult>(
-                CreateRequest("resources/list", CreateCursorDictionary(cursor)),
+                CreateRequest(RequestMethods.ResourcesList, CreateCursorDictionary(cursor)),
                 cancellationToken).ConfigureAwait(false);
 
             foreach (var resource in resourceResults.Resources)
@@ -345,7 +345,7 @@ public static Task<ReadResourceResult> ReadResourceAsync(
         Throw.IfNullOrWhiteSpace(uri);
 
         return client.SendRequestAsync<ReadResourceResult>(
-            CreateRequest("resources/read", new() { ["uri"] = uri }),
+            CreateRequest(RequestMethods.ResourcesRead, new() { ["uri"] = uri }),
             cancellationToken);
     }
 
@@ -369,7 +369,7 @@ public static Task<CompleteResult> GetCompletionAsync(this IMcpClient client, Re
         }
 
         return client.SendRequestAsync<CompleteResult>(
-            CreateRequest("completion/complete", new()
+            CreateRequest(RequestMethods.CompletionComplete, new()
             {
                 ["ref"] = reference,
                 ["argument"] = new Argument { Name = argumentName, Value = argumentValue }
@@ -389,7 +389,7 @@ public static Task SubscribeToResourceAsync(this IMcpClient client, string uri,
         Throw.IfNullOrWhiteSpace(uri);
 
         return client.SendRequestAsync<EmptyResult>(
-            CreateRequest("resources/subscribe", new() { ["uri"] = uri }),
+            CreateRequest(RequestMethods.ResourcesSubscribe, new() { ["uri"] = uri }),
             cancellationToken);
     }
 
@@ -405,7 +405,7 @@ public static Task UnsubscribeFromResourceAsync(this IMcpClient client, string u
         Throw.IfNullOrWhiteSpace(uri);
 
         return client.SendRequestAsync<EmptyResult>(
-            CreateRequest("resources/unsubscribe", new() { ["uri"] = uri }),
+            CreateRequest(RequestMethods.ResourcesUnsubscribe, new() { ["uri"] = uri }),
             cancellationToken);
     }
 
@@ -424,7 +424,7 @@ public static Task<CallToolResponse> CallToolAsync(
         Throw.IfNull(toolName);
 
         return client.SendRequestAsync<CallToolResponse>(
-            CreateRequest("tools/call", CreateParametersDictionary(toolName, arguments)),
+            CreateRequest(RequestMethods.ToolsCall, CreateParametersDictionary(toolName, arguments)),
             cancellationToken);
     }
 
@@ -570,7 +570,7 @@ public static Task SetLoggingLevel(this IMcpClient client, LoggingLevel level, C
         Throw.IfNull(client);
 
         return client.SendRequestAsync<EmptyResult>(
-            CreateRequest("logging/setLevel", new() { ["level"] = level }),
+            CreateRequest(RequestMethods.LoggingSetLevel, new() { ["level"] = level }),
             cancellationToken);
     }
 

src/ModelContextProtocol/NopProgress.cs

@@ -0,0 +1,12 @@
+namespace ModelContextProtocol;
+
+/// <summary>Provides an <see cref="IProgress{ProgressNotificationValue}"/> that's a nop.</summary>
+internal sealed class NullProgress : IProgress<ProgressNotificationValue>
+{
+    public static NullProgress Instance { get; } = new();
+
+    /// <inheritdoc />
+    public void Report(ProgressNotificationValue value)
+    {
+    }
+}

src/ModelContextProtocol/ProgressNotificationValue.cs

@@ -0,0 +1,14 @@
+namespace ModelContextProtocol;
+
+/// <summary>Provides a progress value that can be sent using <see cref="IProgress{ProgressNotificationValue}"/>.</summary>
+public record struct ProgressNotificationValue
+{
+    /// <summary>Gets or sets the progress thus far.</summary>
+    public required float Progress { get; init; }
+
+    /// <summary>Gets or sets the total number of items to process (or total progress required), if known.</summary>
+    public float? Total { get; init; }
+
+    /// <summary>Gets or sets an optional message describing the current progress.</summary>
+    public string? Message { get; init; }
+}

src/ModelContextProtocol/Protocol/Messages/NotificationMethods.cs

@@ -34,4 +34,27 @@ public static class NotificationMethods
     /// Sent by the server when a log message is generated.
     /// </summary>
     public const string LoggingMessageNotification = "notifications/message";
+
+    /// <summary>
+    /// Sent from the client to the server after initialization has finished.
+    /// </summary>
+    public const string InitializedNotification = "notifications/initialized";
+
+    /// <summary>
+    /// Sent to inform the receiver of a progress update for a long-running request.
+    /// </summary>
+    public const string ProgressNotification = "notifications/progress";
+
+    /// <summary>
+    /// Sent by either side to indicate that it is cancelling a previously-issued request.
+    /// </summary>
+    /// <remarks>
+    /// The request SHOULD still be in-flight, but due to communication latency, it is always possible that this notification
+    /// MAY arrive after the request has already finished.
+    /// 
+    /// This notification indicates that the result will be unused, so any associated processing SHOULD cease.
+    /// 
+    /// A client MUST NOT attempt to cancel its `initialize` request.".
+    /// </remarks>
+    public const string CancelledNotification = "notifications/cancelled";
 }

src/ModelContextProtocol/Protocol/Messages/OperationNames.cs

@@ -0,0 +1,112 @@
+using System.ComponentModel;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol.Messages;
+
+/// <summary>
+/// An out-of-band notification used to inform the receiver of a progress update for a long-running request.
+/// <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">See the schema for details</see>
+/// </summary>
+[JsonConverter(typeof(Converter))]
+public class ProgressNotification
+{
+    /// <summary>
+    /// The progress token which was given in the initial request, used to associate this notification with the request that is proceeding.
+    /// </summary>
+    public required ProgressToken ProgressToken { get; init; }
+
+    /// <summary>
+    /// The progress thus far. This should increase every time progress is made, even if the total is unknown.
+    /// </summary>
+    public required ProgressNotificationValue Progress { get; init; }
+
+    /// <summary>Provides a <see cref="JsonConverter"/> for <see cref="ProgressNotification"/>.</summary>
+    [EditorBrowsable(EditorBrowsableState.Never)]
+    public sealed class Converter : JsonConverter<ProgressNotification>
+    {
+        /// <inheritdoc />
+        public override ProgressNotification? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            ProgressToken? progressToken = null;
+            float? progress = null;
+            float? total = null;
+            string? message = null;
+            
+            while (reader.Read() && reader.TokenType != JsonTokenType.EndObject)
+            {
+                if (reader.TokenType == JsonTokenType.PropertyName)
+                {
+                    var propertyName = reader.GetString();
+                    reader.Read();
+                    switch (propertyName)
+                    {
+                        case "progressToken":
+                            if (JsonSerializer.Deserialize(ref reader, options.GetTypeInfo(typeof(ProgressToken))) is not ProgressToken token)
+                            {
+                                throw new JsonException("Invalid value for 'progressToken'.");
+                            }
+                            progressToken = token;
+                            break;
+
+                        case "progress":
+                            progress = reader.GetSingle();
+                            break;
+
+                        case "total":
+                            total = reader.GetSingle();
+                            break;
+
+                        case "message":
+                            message = reader.GetString();
+                            break;
+                    }
+                }
+            }
+
+            if (progress is null)
+            {
+                throw new JsonException("Missing required property 'progress'.");
+            }
+
+            if (progressToken is null)
+            {
+                throw new JsonException("Missing required property 'progressToken'.");
+            }
+
+            return new ProgressNotification
+            {
+                ProgressToken = progressToken.GetValueOrDefault(),
+                Progress = new ProgressNotificationValue()
+                {
+                    Progress = progress.GetValueOrDefault(),
+                    Total = total,
+                    Message = message
+                }
+            };
+        }
+
+        /// <inheritdoc />
+        public override void Write(Utf8JsonWriter writer, ProgressNotification value, JsonSerializerOptions options)
+        {
+            writer.WriteStartObject();
+
+            writer.WritePropertyName("progressToken");
+            JsonSerializer.Serialize(writer, value.ProgressToken, options.GetTypeInfo(typeof(ProgressToken)));
+
+            writer.WriteNumber("progress", value.Progress.Progress);
+
+            if (value.Progress.Total is { } total)
+            {
+                writer.WriteNumber("total", total);
+            }
+
+            if (value.Progress.Message is { } message)
+            {
+                writer.WriteString("message", message);
+            }
+
+            writer.WriteEndObject();
+        }
+    }
+}