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

@@ -42,7 +42,7 @@ public McpClient(IClientTransport clientTransport, McpClientOptions options, Mcp
             }
 
             SetRequestHandler<CreateMessageRequestParams, CreateMessageResult>(
-                "sampling/createMessage",
+                RequestMethods.SamplingCreateMessage,
                 (request, ct) => samplingHandler(request, ct));
         }
 
@@ -54,7 +54,7 @@ public McpClient(IClientTransport clientTransport, McpClientOptions options, Mcp
             }
 
             SetRequestHandler<ListRootsRequestParams, ListRootsResult>(
-                "roots/list",
+                RequestMethods.RootsList,
                 (request, ct) => rootsHandler(request, ct));
         }
     }
@@ -89,21 +89,21 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
             using var initializationCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
             initializationCts.CancelAfter(_options.InitializationTimeout);
 
-            try
-            {
-                // Send initialize request
-                var initializeResponse = await SendRequestAsync<InitializeResult>(
-                    new JsonRpcRequest
+        try
+        {
+            // Send initialize request
+            var initializeResponse = await SendRequestAsync<InitializeResult>(
+                new JsonRpcRequest
+                {
+                    Method = RequestMethods.Initialize,
+                    Params = new InitializeRequestParams()
                     {
-                        Method = "initialize",
-                        Params = new InitializeRequestParams()
-                        {
-                            ProtocolVersion = _options.ProtocolVersion,
-                            Capabilities = _options.Capabilities ?? new ClientCapabilities(),
-                            ClientInfo = _options.ClientInfo,
-                        }
-                    },
-                    initializationCts.Token).ConfigureAwait(false);
+                        ProtocolVersion = _options.ProtocolVersion,
+                        Capabilities = _options.Capabilities ?? new ClientCapabilities(),
+                        ClientInfo = _options.ClientInfo
+                    }
+                },
+                initializationCts.Token).ConfigureAwait(false);
 
                 // Store server information
                 _logger.ServerCapabilitiesReceived(EndpointName,
@@ -123,7 +123,7 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
 
                 // 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";
 }