Add articles on logging and progress #717
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
PederHP
reviewed
Aug 20, 2025
|
|
||
| [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingCapabilities)] | ||
|
|
||
| If the server supports logging, the client can set the level of log messages it wishes to receive with |
There was a problem hiding this comment.
The spec has been, and still is I think, a little unclear on whether this is a requirement or not. There may be servers using other SDKs, which don't start sending logging message until a log level has been set. So I would say it's good practice to always call if the server supports logging and the client wants to receive messages.
PederHP
reviewed
Aug 20, 2025
|
|
||
| [Initialization]: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle#initialization | ||
|
|
||
| Servers built with the C# SDK always declare the logging capability. The C# SDK provides an extension method |
There was a problem hiding this comment.
What about stateless http servers? It's difficult to support logging in a meaningful way with these.
PederHP
reviewed
Aug 20, 2025
|
|
||
| [progress tracking]: https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/progress | ||
|
|
||
| Typically progress tracking is supported by server tools that perform operations that take a significant amount of time to complete, such as data processing or complex calculations. |
There was a problem hiding this comment.
Image generation is also a classic.
PederHP
reviewed
Aug 20, 2025
| [IMcpServer]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Server.IMcpServer.html | ||
| [ProgressNotificationParams]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Protocol.ProgressNotificationParams.html | ||
|
|
||
| The server should verify that the caller provided a `progressToken` in the request and include it in the call to [sendNotificationAsync]. The following example demonstrates how a server can send a progress notification: |
There was a problem hiding this comment.
nit: I think this is a must and not a should. But I guess this is an article / sample and not a spec, so maybe should is better English. Not my first language, so I could be wrong on this. Mentioning it just in case.
PederHP
reviewed
Aug 20, 2025
| }).ConfigureAwait(false); | ||
| ``` | ||
|
|
||
| The second way is to pass a [Progress<T>] instance to the tool method. The MCP C# SDK will automatically handle progress notifications and report them through the [Progress<T>] instance. This notification handler will only receive progress updates for the specific request that was made, rather than all progress notifications from the server. |
There was a problem hiding this comment.
Developers might want guidance on what T they can / should use in this section.
|
|
||
| The server should verify that the caller provided a `progressToken` in the request and include it in the call to [sendNotificationAsync]. The following example demonstrates how a server can send a progress notification: | ||
|
|
||
| [!code-csharp[](samples/server/Tools/LongRunningTools.cs?name=snippet_SendProgress)] |
There was a problem hiding this comment.
This snippet appears to not load in the rendered docs:
| description: | ||
| uid: progress | ||
| --- | ||
| The Model Context Protocol (MCP) supports [progress tracking] for long-running operations through notification messages. |
There was a problem hiding this comment.
Nit: consider inserting a header reflecting the title here:
| [RegisterNotificationHandler]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.IMcpEndpoint.html#ModelContextProtocol_IMcpEndpoint_RegisterNotificationHandler_System_String_System_Func_ModelContextProtocol_Protocol_JsonRpcNotification_System_Threading_CancellationToken_System_Threading_Tasks_ValueTask__ | ||
|
|
||
| ```csharp | ||
| mcpClient.RegisterNotificationHandler(NotificationMethods.ProgressNotification, |
There was a problem hiding this comment.
Nit: consider using a compiled snippet so that the docs don't go out of sync in the future.
| }).ConfigureAwait(false); | ||
| ``` | ||
|
|
||
| The second way is to pass a [Progress<T>] instance to the tool method. The MCP C# SDK will automatically handle progress notifications and report them through the [Progress<T>] instance. This notification handler will only receive progress updates for the specific request that was made, rather than all progress notifications from the server. |
There was a problem hiding this comment.
Angle brackets won't render in raw markdown:
Suggested change
| The second way is to pass a [Progress<T>] instance to the tool method. The MCP C# SDK will automatically handle progress notifications and report them through the [Progress<T>] instance. This notification handler will only receive progress updates for the specific request that was made, rather than all progress notifications from the server. | |
| The second way is to pass a [`Progress<T>`] instance to the tool method. The MCP C# SDK will automatically handle progress notifications and report them through the [`Progress<T>`] instance. This notification handler will only receive progress updates for the specific request that was made, rather than all progress notifications from the server. |
|
|
||
| ### Server Implementation | ||
|
|
||
| When processing a request, the server can use the [sendNotificationAsync] extension method of [IMcpServer] to send progress updates, |
There was a problem hiding this comment.
Suggested change
| When processing a request, the server can use the [sendNotificationAsync] extension method of [IMcpServer] to send progress updates, | |
| When processing a request, the server can use the [`sendNotificationAsync`] extension method of [`IMcpServer`] to send progress updates, |
| specifying `"notifications/progress"` as the notification method name. | ||
| The C# SDK registers an instance of [IMcpServer] with the dependency injection container, | ||
| so tools can simply add a parameter of type [IMcpServer] to their method signature to access it. | ||
| The parameters passed to [sendNotificationAsync] should be an instance of [ProgressNotificationParams], which includes the current progress, total steps, and an optional message. |
There was a problem hiding this comment.
Suggested change
| The parameters passed to [sendNotificationAsync] should be an instance of [ProgressNotificationParams], which includes the current progress, total steps, and an optional message. | |
| The parameters passed to [`sendNotificationAsync`] should be an instance of [`ProgressNotificationParams`], which includes the current progress, total steps, and an optional message. |
|
|
||
| The second way is to pass a [Progress<T>] instance to the tool method. The MCP C# SDK will automatically handle progress notifications and report them through the [Progress<T>] instance. This notification handler will only receive progress updates for the specific request that was made, rather than all progress notifications from the server. | ||
|
|
||
| [Progress<T>]: https://learn.microsoft.com/en-us/dotnet/api/system.progress-1 |
There was a problem hiding this comment.
Suggested change
| [Progress<T>]: https://learn.microsoft.com/en-us/dotnet/api/system.progress-1 | |
| [`Progress<T>`]: https://learn.microsoft.com/en-us/dotnet/api/system.progress-1 |
| MCP Servers using the MCP C# SDK can obtain an [ILoggerProvider] from the IMcpServer [AsClientLoggerProvider] extension method, | ||
| and from that can create an [ILogger] instance for logging messages that should be sent to the MCP client. | ||
|
|
||
| [!code-csharp[](samples/server/Tools/LoggingTools.cs?name=snippet_LoggingConfiguration)] |
There was a problem hiding this comment.
This snippet is not loading in the render:
|
|
||
| [NotificationMethods.LoggingMessageNotification]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Protocol.NotificationMethods.html#ModelContextProtocol_Protocol_NotificationMethods_LoggingMessageNotification | ||
|
|
||
| [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingHandler)] |
There was a problem hiding this comment.
Likewise, this snippet is not loading in the render.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds a couple more conceptual docs articles, and introduces some structure into the set of conceptual docs.