From 2b6937f5c1809c6da579c98138ca8dc9b8c3cf5b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 05:35:12 +0000 Subject: [PATCH 01/16] Initial plan From 8325f3ab51eb9e90246513fac18bf0419bc2a6d5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 05:44:25 +0000 Subject: [PATCH 02/16] Replace obsolete API references with xref tags in markdown docs Co-authored-by: eiriktsarpalis <2813363+eiriktsarpalis@users.noreply.github.com> --- docs/concepts/elicitation/elicitation.md | 20 +++++---------- docs/concepts/logging/logging.md | 31 ++++++------------------ docs/concepts/progress/progress.md | 28 +++++++-------------- 3 files changed, 22 insertions(+), 57 deletions(-) diff --git a/docs/concepts/elicitation/elicitation.md b/docs/concepts/elicitation/elicitation.md index ebda0979a..e8b55a350 100644 --- a/docs/concepts/elicitation/elicitation.md +++ b/docs/concepts/elicitation/elicitation.md @@ -11,12 +11,9 @@ The **elicitation** feature allows servers to request additional information fro ### Server Support for Elicitation -Servers request structured data from users with the [ElicitAsync] extension method on [IMcpServer]. -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. - -[ElicitAsync]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Server.McpServerExtensions.html#ModelContextProtocol_Server_McpServerExtensions_ElicitAsync_ModelContextProtocol_Server_IMcpServer_ModelContextProtocol_Protocol_ElicitRequestParams_System_Threading_CancellationToken_ -[IMcpServer]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Server.IMcpServer.html +Servers request structured data from users with the extension method on . +The C# SDK registers an instance of with the dependency injection container, +so tools can simply add a parameter of type to their method signature to access it. The MCP Server must specify the schema of each input value it is requesting from the user. Only primitive types (string, number, boolean) are supported for elicitation requests. @@ -31,10 +28,7 @@ The following example demonstrates how a server could request a boolean response ### Client Support for Elicitation -Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. In the MCP C# SDK, this is done by configuring an [ElicitationHandler] in the [McpClientOptions]: - -[ElicitationHandler]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Protocol.ElicitationCapability.html#ModelContextProtocol_Protocol_ElicitationCapability_ElicitationHandler -[McpClientOptions]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Client.McpClientOptions.html +Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. In the MCP C# SDK, this is done by configuring an in the : [!code-csharp[](samples/client/Program.cs?name=snippet_McpInitialize)] @@ -42,10 +36,8 @@ The ElicitationHandler is an asynchronous method that will be called when the se The ElicitationHandler must request input from the user and return the data in a format that matches the requested schema. This will be highly dependent on the client application and how it interacts with the user. -If the user provides the requested information, the ElicitationHandler should return an [ElicitResult] with the action set to "accept" and the content containing the user's input. -If the user does not provide the requested information, the ElicitationHandler should return an [ElicitResult] with the action set to "reject" and no content. - -[ElicitResult]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Protocol.ElicitResult.html +If the user provides the requested information, the ElicitationHandler should return an with the action set to "accept" and the content containing the user's input. +If the user does not provide the requested information, the ElicitationHandler should return an with the action set to "reject" and no content. Below is an example of how a console application might handle elicitation requests. Here's an example implementation: diff --git a/docs/concepts/logging/logging.md b/docs/concepts/logging/logging.md index 411a61b1c..81807c266 100644 --- a/docs/concepts/logging/logging.md +++ b/docs/concepts/logging/logging.md @@ -49,53 +49,36 @@ Servers built with the C# SDK always declare the logging capability. Doing so do to send log messages -- only allows it. Note that stateless MCP servers may not be capable of sending log messages as there may not be an open connection to the client on which the log messages could be sent. -The C# SDK provides an extension method [WithSetLoggingLevelHandler] on [IMcpServerBuilder] to allow the +The C# SDK provides an extension method on to allow the server to perform any special logic it wants to perform when a client sets the logging level. However, the -SDK already takes care of setting the [LoggingLevel] in the [IMcpServer], so most servers will not need to +SDK already takes care of setting the in the , so most servers will not need to implement this. -[IMcpServer]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Server.IMcpServer.html -[IMcpServerBuilder]: https://modelcontextprotocol.github.io/csharp-sdk/api/Microsoft.Extensions.DependencyInjection.IMcpServerBuilder.html -[WithSetLoggingLevelHandler]: https://modelcontextprotocol.github.io/csharp-sdk/api/Microsoft.Extensions.DependencyInjection.McpServerBuilderExtensions.html#Microsoft_Extensions_DependencyInjection_McpServerBuilderExtensions_WithSetLoggingLevelHandler_Microsoft_Extensions_DependencyInjection_IMcpServerBuilder_System_Func_ModelContextProtocol_Server_RequestContext_ModelContextProtocol_Protocol_SetLevelRequestParams__System_Threading_CancellationToken_System_Threading_Tasks_ValueTask_ModelContextProtocol_Protocol_EmptyResult___ -[LoggingLevel]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Server.IMcpServer.html#ModelContextProtocol_Server_IMcpServer_LoggingLevel - -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. +MCP Servers using the MCP C# SDK can obtain an from the extension method, +and from that can create an instance for logging messages that should be sent to the MCP client. [!code-csharp[](samples/server/Tools/LoggingTools.cs?name=snippet_LoggingConfiguration)] -[ILoggerProvider]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerprovider -[AsClientLoggerProvider]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Server.McpServerExtensions.html#ModelContextProtocol_Server_McpServerExtensions_AsClientLoggerProvider_ModelContextProtocol_Server_IMcpServer_ -[ILogger]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger - ### Client support for logging When the server indicates that it supports logging, clients should configure the logging level to specify which messages the server should send to the client. -Clients should check if the server supports logging by checking the [Logging] property of the [ServerCapabilities] field of [IMcpClient]. - -[IMcpClient]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Client.IMcpClient.html -[ServerCapabilities]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Client.IMcpClient.html#ModelContextProtocol_Client_IMcpClient_ServerCapabilities -[Logging]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Protocol.ServerCapabilities.html#ModelContextProtocol_Protocol_ServerCapabilities_Logging +Clients should check if the server supports logging by checking the property of the field of . [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingCapabilities)] If the server supports logging, the client should set the level of log messages it wishes to receive with -the [SetLoggingLevel] method on [IMcpClient]. If the client does not set a logging level, the server might choose +the method on . If the client does not set a logging level, the server might choose to send all log messages or none -- this is not specified in the protocol -- so it is important that the client sets a logging level to ensure it receives the desired log messages and only those messages. The `loggingLevel` set by the client is an MCP logging level. See the [Logging Levels](#logging-levels) section above for the mapping between MCP and .NET logging levels. -[SetLoggingLevel]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Client.McpClientExtensions.html#ModelContextProtocol_Client_McpClientExtensions_SetLoggingLevel_ModelContextProtocol_Client_IMcpClient_Microsoft_Extensions_Logging_LogLevel_System_Threading_CancellationToken_ - [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingLevel)] -Lastly, the client must configure a notification handler for [NotificationMethods.LoggingMessageNotification] notifications. +Lastly, the client must configure a notification handler for notifications. The following example simply writes the log messages to the console. -[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)] diff --git a/docs/concepts/progress/progress.md b/docs/concepts/progress/progress.md index ccdf9f19c..aeaa207a1 100644 --- a/docs/concepts/progress/progress.md +++ b/docs/concepts/progress/progress.md @@ -17,17 +17,13 @@ This project illustrates the common case of a server tool that performs a long-r ### Server Implementation -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 method of 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. +The C# SDK registers an instance of with the dependency injection container, +so tools can simply add a parameter of type to their method signature to access it. +The parameters passed to should be an instance of , which includes the current progress, total steps, and an optional message. -[sendNotificationAsync]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.McpEndpointExtensions.html#ModelContextProtocol_McpEndpointExtensions_SendNotificationAsync_ModelContextProtocol_IMcpEndpoint_System_String_System_Threading_CancellationToken_ -[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 must 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: +The server must verify that the caller provided a `progressToken` in the request and include it in the call to . The following example demonstrates how a server can send a progress notification: [!code-csharp[](samples/server/Tools/LongRunningTools.cs?name=snippet_SendProgress)] @@ -38,10 +34,7 @@ Note that servers are not required to support progress tracking, so clients shou In the MCP C# SDK, clients can specify a `progressToken` in the request parameters when calling a tool method. The client should also provide a notification handler to process "notifications/progress" notifications. -There are two way to do this. The first is to register a notification handler using the [RegisterNotificationHandler] method on the [IMcpClient] instance. A handler registered this way will receive all progress notifications sent by the server. - -[IMcpClient]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Client.IMcpClient.html -[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__ +There are two way to do this. The first is to register a notification handler using the method on the instance. A handler registered this way will receive all progress notifications sent by the server. ```csharp mcpClient.RegisterNotificationHandler(NotificationMethods.ProgressNotification, @@ -57,13 +50,10 @@ mcpClient.RegisterNotificationHandler(NotificationMethods.ProgressNotification, }).ConfigureAwait(false); ``` -The second way is to pass a [Progress``] instance to the tool method. [Progress``] is a standard .NET type that provides a way to receive progress updates. -For the purposes of MCP progress notifications, `T` should be [ProgressNotificationValue]. -The MCP C# SDK will automatically handle progress notifications and report them through the [Progress``] instance. +The second way is to pass a instance to the tool method. is a standard .NET type that provides a way to receive progress updates. +For the purposes of MCP progress notifications, `T` should be . +The MCP C# SDK will automatically handle progress notifications and report them through the 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``]: https://learn.microsoft.com/en-us/dotnet/api/system.progress-1 -[ProgressNotificationValue]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.ProgressNotificationValue.html - [!code-csharp[](samples/client/Program.cs?name=snippet_ProgressHandler)] From e4224e22a3b459dbe786ec44f3c2c194d88eb625 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 05:46:10 +0000 Subject: [PATCH 03/16] Add documentation guidelines for xref syntax Co-authored-by: eiriktsarpalis <2813363+eiriktsarpalis@users.noreply.github.com> --- docs/README.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..7c69c85ca --- /dev/null +++ b/docs/README.md @@ -0,0 +1,77 @@ +# Documentation Guidelines + +This directory contains the conceptual documentation for the MCP C# SDK, built using [DocFX](https://dotnetfoundation.github.io/docfx/). + +## Referencing API Types + +When referencing types from the MCP C# SDK API in markdown documentation, **always use DocFX xref syntax** instead of direct URLs to API documentation pages. This ensures that: + +1. Links remain valid even when API documentation structure changes +2. DocFX can validate that referenced types exist during build +3. Links work correctly in offline documentation +4. DocFX generates proper warnings if referenced types are obsolete or missing + +### xref Syntax + +Use the `` tag to reference types, methods, and properties: + +```markdown + + + + + + + + + + + + + + + +``` + +### Common Types to Reference + +When updating documentation, use these type names instead of obsolete interfaces: + +| Obsolete Interface | Current Type | xref | +|--------------------|--------------|------| +| `IMcpEndpoint` | `McpSession` | `` | +| `IMcpClient` | `McpClient` | `` | +| `IMcpServer` | `McpServer` | `` | + +Note: `IMcpServerBuilder` is NOT obsolete and should still be referenced. + +### Building Documentation + +To build the documentation locally and verify xref links: + +```bash +make generate-docs +``` + +This will: +1. Clean previous builds +2. Build the project +3. Generate API documentation +4. Build the DocFX site to `artifacts/_site` + +To serve the documentation locally: + +```bash +make serve-docs +``` + +Then navigate to `http://localhost:8080` to view the documentation. + +## External Links + +For links to external documentation (e.g., Microsoft Learn, MCP specification), regular markdown links are acceptable: + +```markdown +[Model Context Protocol](https://modelcontextprotocol.io/) +[ILogger](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger) +``` From acc65d880441868fe3d0eabff2ff907e32ad7c5a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 06:05:49 +0000 Subject: [PATCH 04/16] Fix: Only update link URLs, preserve document structure Co-authored-by: eiriktsarpalis <2813363+eiriktsarpalis@users.noreply.github.com> --- docs/concepts/elicitation/elicitation.md | 20 ++++++++++----- docs/concepts/logging/logging.md | 31 ++++++++++++++++++------ docs/concepts/progress/progress.md | 28 ++++++++++++++------- 3 files changed, 57 insertions(+), 22 deletions(-) diff --git a/docs/concepts/elicitation/elicitation.md b/docs/concepts/elicitation/elicitation.md index e8b55a350..028870ccb 100644 --- a/docs/concepts/elicitation/elicitation.md +++ b/docs/concepts/elicitation/elicitation.md @@ -11,9 +11,12 @@ The **elicitation** feature allows servers to request additional information fro ### Server Support for Elicitation -Servers request structured data from users with the extension method on . -The C# SDK registers an instance of with the dependency injection container, -so tools can simply add a parameter of type to their method signature to access it. +Servers request structured data from users with the [ElicitAsync] extension method on [IMcpServer]. +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. + +[ElicitAsync]: xref:ModelContextProtocol.Server.McpServerExtensions.ElicitAsync* +[IMcpServer]: xref:ModelContextProtocol.Server.McpServer The MCP Server must specify the schema of each input value it is requesting from the user. Only primitive types (string, number, boolean) are supported for elicitation requests. @@ -28,7 +31,10 @@ The following example demonstrates how a server could request a boolean response ### Client Support for Elicitation -Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. In the MCP C# SDK, this is done by configuring an in the : +Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. In the MCP C# SDK, this is done by configuring an [ElicitationHandler] in the [McpClientOptions]: + +[ElicitationHandler]: xref:ModelContextProtocol.Protocol.ElicitationCapability.ElicitationHandler +[McpClientOptions]: xref:ModelContextProtocol.Client.McpClientOptions [!code-csharp[](samples/client/Program.cs?name=snippet_McpInitialize)] @@ -36,8 +42,10 @@ The ElicitationHandler is an asynchronous method that will be called when the se The ElicitationHandler must request input from the user and return the data in a format that matches the requested schema. This will be highly dependent on the client application and how it interacts with the user. -If the user provides the requested information, the ElicitationHandler should return an with the action set to "accept" and the content containing the user's input. -If the user does not provide the requested information, the ElicitationHandler should return an with the action set to "reject" and no content. +If the user provides the requested information, the ElicitationHandler should return an [ElicitResult] with the action set to "accept" and the content containing the user's input. +If the user does not provide the requested information, the ElicitationHandler should return an [ElicitResult] with the action set to "reject" and no content. + +[ElicitResult]: xref:ModelContextProtocol.Protocol.ElicitResult Below is an example of how a console application might handle elicitation requests. Here's an example implementation: diff --git a/docs/concepts/logging/logging.md b/docs/concepts/logging/logging.md index 81807c266..f1474284e 100644 --- a/docs/concepts/logging/logging.md +++ b/docs/concepts/logging/logging.md @@ -49,36 +49,53 @@ Servers built with the C# SDK always declare the logging capability. Doing so do to send log messages -- only allows it. Note that stateless MCP servers may not be capable of sending log messages as there may not be an open connection to the client on which the log messages could be sent. -The C# SDK provides an extension method on to allow the +The C# SDK provides an extension method [WithSetLoggingLevelHandler] on [IMcpServerBuilder] to allow the server to perform any special logic it wants to perform when a client sets the logging level. However, the -SDK already takes care of setting the in the , so most servers will not need to +SDK already takes care of setting the [LoggingLevel] in the [IMcpServer], so most servers will not need to implement this. -MCP Servers using the MCP C# SDK can obtain an from the extension method, -and from that can create an instance for logging messages that should be sent to the MCP client. +[IMcpServer]: xref:ModelContextProtocol.Server.McpServer +[IMcpServerBuilder]: xref:Microsoft.Extensions.DependencyInjection.IMcpServerBuilder +[WithSetLoggingLevelHandler]: xref:Microsoft.Extensions.DependencyInjection.McpServerBuilderExtensions.WithSetLoggingLevelHandler* +[LoggingLevel]: xref:ModelContextProtocol.Server.McpServer.LoggingLevel + +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)] +[ILoggerProvider]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerprovider +[AsClientLoggerProvider]: xref:ModelContextProtocol.Server.McpServerExtensions.AsClientLoggerProvider* +[ILogger]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger + ### Client support for logging When the server indicates that it supports logging, clients should configure the logging level to specify which messages the server should send to the client. -Clients should check if the server supports logging by checking the property of the field of . +Clients should check if the server supports logging by checking the [Logging] property of the [ServerCapabilities] field of [IMcpClient]. + +[IMcpClient]: xref:ModelContextProtocol.Client.McpClient +[ServerCapabilities]: xref:ModelContextProtocol.Client.McpClient.ServerCapabilities +[Logging]: xref:ModelContextProtocol.Protocol.ServerCapabilities.Logging [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingCapabilities)] If the server supports logging, the client should set the level of log messages it wishes to receive with -the method on . If the client does not set a logging level, the server might choose +the [SetLoggingLevel] method on [IMcpClient]. If the client does not set a logging level, the server might choose to send all log messages or none -- this is not specified in the protocol -- so it is important that the client sets a logging level to ensure it receives the desired log messages and only those messages. The `loggingLevel` set by the client is an MCP logging level. See the [Logging Levels](#logging-levels) section above for the mapping between MCP and .NET logging levels. +[SetLoggingLevel]: xref:ModelContextProtocol.Client.McpClientExtensions.SetLoggingLevel* + [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingLevel)] -Lastly, the client must configure a notification handler for notifications. +Lastly, the client must configure a notification handler for [NotificationMethods.LoggingMessageNotification] notifications. The following example simply writes the log messages to the console. +[NotificationMethods.LoggingMessageNotification]: xref:ModelContextProtocol.Protocol.NotificationMethods.LoggingMessageNotification + [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingHandler)] diff --git a/docs/concepts/progress/progress.md b/docs/concepts/progress/progress.md index aeaa207a1..ae50d5c53 100644 --- a/docs/concepts/progress/progress.md +++ b/docs/concepts/progress/progress.md @@ -17,13 +17,17 @@ This project illustrates the common case of a server tool that performs a long-r ### Server Implementation -When processing a request, the server can use the method of 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 with the dependency injection container, -so tools can simply add a parameter of type to their method signature to access it. -The parameters passed to should be an instance of , which includes the current progress, total steps, and an optional message. +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. -The server must verify that the caller provided a `progressToken` in the request and include it in the call to . The following example demonstrates how a server can send a progress notification: +[sendNotificationAsync]: xref:ModelContextProtocol.McpSession.SendNotificationAsync* +[IMcpServer]: xref:ModelContextProtocol.Server.McpServer +[ProgressNotificationParams]: xref:ModelContextProtocol.Protocol.ProgressNotificationParams + +The server must 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)] @@ -34,7 +38,10 @@ Note that servers are not required to support progress tracking, so clients shou In the MCP C# SDK, clients can specify a `progressToken` in the request parameters when calling a tool method. The client should also provide a notification handler to process "notifications/progress" notifications. -There are two way to do this. The first is to register a notification handler using the method on the instance. A handler registered this way will receive all progress notifications sent by the server. +There are two way to do this. The first is to register a notification handler using the [RegisterNotificationHandler] method on the [IMcpClient] instance. A handler registered this way will receive all progress notifications sent by the server. + +[IMcpClient]: xref:ModelContextProtocol.Client.McpClient +[RegisterNotificationHandler]: xref:ModelContextProtocol.McpSession.RegisterNotificationHandler* ```csharp mcpClient.RegisterNotificationHandler(NotificationMethods.ProgressNotification, @@ -50,10 +57,13 @@ mcpClient.RegisterNotificationHandler(NotificationMethods.ProgressNotification, }).ConfigureAwait(false); ``` -The second way is to pass a instance to the tool method. is a standard .NET type that provides a way to receive progress updates. -For the purposes of MCP progress notifications, `T` should be . -The MCP C# SDK will automatically handle progress notifications and report them through the instance. +The second way is to pass a [Progress``] instance to the tool method. [Progress``] is a standard .NET type that provides a way to receive progress updates. +For the purposes of MCP progress notifications, `T` should be [ProgressNotificationValue]. +The MCP C# SDK will automatically handle progress notifications and report them through the [Progress``] 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``]: xref:System.Progress`1 +[ProgressNotificationValue]: xref:ModelContextProtocol.ProgressNotificationValue + [!code-csharp[](samples/client/Program.cs?name=snippet_ProgressHandler)] From bbd71877e6e881cbc38f0f011e314782b5cc5137 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 06:14:30 +0000 Subject: [PATCH 05/16] Add --warningsAsErrors flag to docfx command in Makefile Co-authored-by: eiriktsarpalis <2813363+eiriktsarpalis@users.noreply.github.com> --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index c2a0a012f..1d59b3adb 100644 --- a/Makefile +++ b/Makefile @@ -30,7 +30,7 @@ test: build generate-docs: clean restore dotnet build --no-restore --configuration Release - dotnet docfx $(DOCS_PATH)/docfx.json + dotnet docfx $(DOCS_PATH)/docfx.json --warningsAsErrors true serve-docs: generate-docs dotnet docfx serve $(ARTIFACT_PATH)/_site --port 8080 From 66bfb803b090723cf596f48215137bbb63c04920 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Tue, 14 Oct 2025 09:51:30 +0300 Subject: [PATCH 06/16] Add CI validation for document generation --- .github/workflows/ci-build-test.yml | 24 +++++++----------------- Makefile | 10 ++++++++-- 2 files changed, 15 insertions(+), 19 deletions(-) diff --git a/.github/workflows/ci-build-test.yml b/.github/workflows/ci-build-test.yml index 3d9aaf4a9..f8f0cf90c 100644 --- a/.github/workflows/ci-build-test.yml +++ b/.github/workflows/ci-build-test.yml @@ -66,25 +66,15 @@ jobs: - name: Install dependencies for tests run: npm install @modelcontextprotocol/server-memory - - name: Build - run: dotnet build --configuration ${{ matrix.configuration }} + - name: Build & Test + run: make build test CONFIGURATION=${{ matrix.configuration }} - name: Pack - run: dotnet pack --configuration ${{ matrix.configuration }} - - - name: Test - run: >- - dotnet test - --filter '(Execution!=Manual)' - --no-build - --configuration ${{ matrix.configuration }} - --logger "trx" - --logger "GitHubActions;summary.includePassedTests=true;summary.includeSkippedTests=true" - --blame - --blame-hang-timeout 7m - --blame-crash - --results-directory testresults - --collect "XPlat Code Coverage" -- RunConfiguration.CollectSourceInformation=true + if: matrix.configuration == 'Release' + run: make pack CONFIGURATION=${{ matrix.configuration }} + + - name: Generate docs + run: make generate-docs CONFIGURATION=${{ matrix.configuration }} - name: Upload test results artifact if: always() diff --git a/Makefile b/Makefile index 1d59b3adb..9fa3d44fa 100644 --- a/Makefile +++ b/Makefile @@ -21,14 +21,20 @@ test: build --configuration $(CONFIGURATION) \ --filter '(Execution!=Manual)' \ --blame \ + --blame-crash \ + --blame-hang-timeout 7m \ --diag "$(ARTIFACT_PATH)/diag.txt" \ --logger "trx" \ + --logger "GitHubActions;summary.includePassedTests=true;summary.includeSkippedTests=true" \ --collect "Code Coverage;Format=cobertura" \ - --results-directory $(ARTIFACT_PATH)/test-results \ + --results-directory $(ARTIFACT_PATH)/testresults \ -- \ RunConfiguration.CollectSourceInformation=true -generate-docs: clean restore +pack: restore + dotnet pack --no-restore --configuration $(CONFIGURATION) + +generate-docs: restore dotnet build --no-restore --configuration Release dotnet docfx $(DOCS_PATH)/docfx.json --warningsAsErrors true From 50323c546654a932db078752d3af1636956325be Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Tue, 14 Oct 2025 09:53:36 +0300 Subject: [PATCH 07/16] Fix broken link --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 7c69c85ca..da2c59cc3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Documentation Guidelines -This directory contains the conceptual documentation for the MCP C# SDK, built using [DocFX](https://dotnetfoundation.github.io/docfx/). +This directory contains the conceptual documentation for the MCP C# SDK, built using [DocFX](https://dotnet.github.io/docfx/). ## Referencing API Types From 45bb3f057e3b7d0bb89557aff6263ce357cf8a5f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 07:05:20 +0000 Subject: [PATCH 08/16] Fix invalid xref cross-references in documentation Co-authored-by: eiriktsarpalis <2813363+eiriktsarpalis@users.noreply.github.com> --- docs/concepts/elicitation/elicitation.md | 4 ++-- docs/concepts/logging/logging.md | 4 ++-- docs/concepts/progress/progress.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/concepts/elicitation/elicitation.md b/docs/concepts/elicitation/elicitation.md index 028870ccb..6894760cc 100644 --- a/docs/concepts/elicitation/elicitation.md +++ b/docs/concepts/elicitation/elicitation.md @@ -15,7 +15,7 @@ Servers request structured data from users with the [ElicitAsync] extension meth 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. -[ElicitAsync]: xref:ModelContextProtocol.Server.McpServerExtensions.ElicitAsync* +[ElicitAsync]: xref:ModelContextProtocol.Server.McpServer.ElicitAsync* [IMcpServer]: xref:ModelContextProtocol.Server.McpServer The MCP Server must specify the schema of each input value it is requesting from the user. @@ -33,7 +33,7 @@ The following example demonstrates how a server could request a boolean response Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. In the MCP C# SDK, this is done by configuring an [ElicitationHandler] in the [McpClientOptions]: -[ElicitationHandler]: xref:ModelContextProtocol.Protocol.ElicitationCapability.ElicitationHandler +[ElicitationHandler]: xref:ModelContextProtocol.Client.McpClientHandlers.ElicitationHandler [McpClientOptions]: xref:ModelContextProtocol.Client.McpClientOptions [!code-csharp[](samples/client/Program.cs?name=snippet_McpInitialize)] diff --git a/docs/concepts/logging/logging.md b/docs/concepts/logging/logging.md index f1474284e..73ac4bed0 100644 --- a/docs/concepts/logging/logging.md +++ b/docs/concepts/logging/logging.md @@ -65,7 +65,7 @@ and from that can create an [ILogger] instance for logging messages that should [!code-csharp[](samples/server/Tools/LoggingTools.cs?name=snippet_LoggingConfiguration)] [ILoggerProvider]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerprovider -[AsClientLoggerProvider]: xref:ModelContextProtocol.Server.McpServerExtensions.AsClientLoggerProvider* +[AsClientLoggerProvider]: xref:ModelContextProtocol.Server.McpServer.AsClientLoggerProvider* [ILogger]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger ### Client support for logging @@ -89,7 +89,7 @@ sets a logging level to ensure it receives the desired log messages and only tho The `loggingLevel` set by the client is an MCP logging level. See the [Logging Levels](#logging-levels) section above for the mapping between MCP and .NET logging levels. -[SetLoggingLevel]: xref:ModelContextProtocol.Client.McpClientExtensions.SetLoggingLevel* +[SetLoggingLevel]: xref:ModelContextProtocol.Client.McpClient.SetLoggingLevel* [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingLevel)] diff --git a/docs/concepts/progress/progress.md b/docs/concepts/progress/progress.md index ae50d5c53..af0055b3c 100644 --- a/docs/concepts/progress/progress.md +++ b/docs/concepts/progress/progress.md @@ -63,7 +63,7 @@ The MCP C# SDK will automatically handle progress notifications and report them This notification handler will only receive progress updates for the specific request that was made, rather than all progress notifications from the server. -[Progress``]: xref:System.Progress`1 +[Progress``]: https://learn.microsoft.com/dotnet/api/system.progress-1 [ProgressNotificationValue]: xref:ModelContextProtocol.ProgressNotificationValue [!code-csharp[](samples/client/Program.cs?name=snippet_ProgressHandler)] From a0c8624760d8314cf6237588aa9c9e29c8fad284 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Tue, 14 Oct 2025 10:08:42 +0300 Subject: [PATCH 09/16] Apply suggestion from @eiriktsarpalis --- docs/concepts/progress/progress.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/progress/progress.md b/docs/concepts/progress/progress.md index af0055b3c..4146c2501 100644 --- a/docs/concepts/progress/progress.md +++ b/docs/concepts/progress/progress.md @@ -63,7 +63,7 @@ The MCP C# SDK will automatically handle progress notifications and report them This notification handler will only receive progress updates for the specific request that was made, rather than all progress notifications from the server. -[Progress``]: https://learn.microsoft.com/dotnet/api/system.progress-1 +[Progress``]: [System.Progress](https://learn.microsoft.com/dotnet/api/system.progress-1> [ProgressNotificationValue]: xref:ModelContextProtocol.ProgressNotificationValue [!code-csharp[](samples/client/Program.cs?name=snippet_ProgressHandler)] From 6fad6a9dfbe3ed2290fd8301f06e0d5776aaedc5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 07:11:25 +0000 Subject: [PATCH 10/16] Fix Progress link syntax and remove docs/README.md Co-authored-by: eiriktsarpalis <2813363+eiriktsarpalis@users.noreply.github.com> --- docs/README.md | 77 ------------------------------ docs/concepts/progress/progress.md | 2 +- 2 files changed, 1 insertion(+), 78 deletions(-) delete mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index da2c59cc3..000000000 --- a/docs/README.md +++ /dev/null @@ -1,77 +0,0 @@ -# Documentation Guidelines - -This directory contains the conceptual documentation for the MCP C# SDK, built using [DocFX](https://dotnet.github.io/docfx/). - -## Referencing API Types - -When referencing types from the MCP C# SDK API in markdown documentation, **always use DocFX xref syntax** instead of direct URLs to API documentation pages. This ensures that: - -1. Links remain valid even when API documentation structure changes -2. DocFX can validate that referenced types exist during build -3. Links work correctly in offline documentation -4. DocFX generates proper warnings if referenced types are obsolete or missing - -### xref Syntax - -Use the `` tag to reference types, methods, and properties: - -```markdown - - - - - - - - - - - - - - - -``` - -### Common Types to Reference - -When updating documentation, use these type names instead of obsolete interfaces: - -| Obsolete Interface | Current Type | xref | -|--------------------|--------------|------| -| `IMcpEndpoint` | `McpSession` | `` | -| `IMcpClient` | `McpClient` | `` | -| `IMcpServer` | `McpServer` | `` | - -Note: `IMcpServerBuilder` is NOT obsolete and should still be referenced. - -### Building Documentation - -To build the documentation locally and verify xref links: - -```bash -make generate-docs -``` - -This will: -1. Clean previous builds -2. Build the project -3. Generate API documentation -4. Build the DocFX site to `artifacts/_site` - -To serve the documentation locally: - -```bash -make serve-docs -``` - -Then navigate to `http://localhost:8080` to view the documentation. - -## External Links - -For links to external documentation (e.g., Microsoft Learn, MCP specification), regular markdown links are acceptable: - -```markdown -[Model Context Protocol](https://modelcontextprotocol.io/) -[ILogger](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger) -``` diff --git a/docs/concepts/progress/progress.md b/docs/concepts/progress/progress.md index 4146c2501..f7df6945b 100644 --- a/docs/concepts/progress/progress.md +++ b/docs/concepts/progress/progress.md @@ -63,7 +63,7 @@ The MCP C# SDK will automatically handle progress notifications and report them This notification handler will only receive progress updates for the specific request that was made, rather than all progress notifications from the server. -[Progress``]: [System.Progress](https://learn.microsoft.com/dotnet/api/system.progress-1> +[Progress``]: [System.Progress](https://learn.microsoft.com/dotnet/api/system.progress-1) [ProgressNotificationValue]: xref:ModelContextProtocol.ProgressNotificationValue [!code-csharp[](samples/client/Program.cs?name=snippet_ProgressHandler)] From 8fe2d887c7e37cac884d7ba9df0019879b4cbab7 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Tue, 14 Oct 2025 10:13:21 +0300 Subject: [PATCH 11/16] Separate build & test targets --- .github/workflows/ci-build-test.yml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci-build-test.yml b/.github/workflows/ci-build-test.yml index f8f0cf90c..9baf5f5dd 100644 --- a/.github/workflows/ci-build-test.yml +++ b/.github/workflows/ci-build-test.yml @@ -66,8 +66,11 @@ jobs: - name: Install dependencies for tests run: npm install @modelcontextprotocol/server-memory - - name: Build & Test - run: make build test CONFIGURATION=${{ matrix.configuration }} + - name: Build + run: make build CONFIGURATION=${{ matrix.configuration }} + + - name: Test + run: make test CONFIGURATION=${{ matrix.configuration }} - name: Pack if: matrix.configuration == 'Release' From a0920b4da074098bb627750ffcb95b213e829795 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Tue, 14 Oct 2025 10:38:53 +0300 Subject: [PATCH 12/16] Apply suggestion from @eiriktsarpalis --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 9fa3d44fa..a96826fdc 100644 --- a/Makefile +++ b/Makefile @@ -26,7 +26,7 @@ test: build --diag "$(ARTIFACT_PATH)/diag.txt" \ --logger "trx" \ --logger "GitHubActions;summary.includePassedTests=true;summary.includeSkippedTests=true" \ - --collect "Code Coverage;Format=cobertura" \ + --collect "XPlat Code Coverage" \ --results-directory $(ARTIFACT_PATH)/testresults \ -- \ RunConfiguration.CollectSourceInformation=true From acdcfc9137216d8aa88a1b137c19ef0d3bcc83cd Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Tue, 14 Oct 2025 11:05:59 +0300 Subject: [PATCH 13/16] tweak Makefile --- Makefile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Makefile b/Makefile index a96826fdc..b9d0ffdd7 100644 --- a/Makefile +++ b/Makefile @@ -34,8 +34,7 @@ test: build pack: restore dotnet pack --no-restore --configuration $(CONFIGURATION) -generate-docs: restore - dotnet build --no-restore --configuration Release +generate-docs: build dotnet docfx $(DOCS_PATH)/docfx.json --warningsAsErrors true serve-docs: generate-docs From 03af7838c0a64b610cc01296bb89ba0b1d352e52 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Tue, 14 Oct 2025 12:35:09 +0300 Subject: [PATCH 14/16] Fix test results upload path --- .github/workflows/ci-build-test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci-build-test.yml b/.github/workflows/ci-build-test.yml index 9baf5f5dd..5f80f6b2e 100644 --- a/.github/workflows/ci-build-test.yml +++ b/.github/workflows/ci-build-test.yml @@ -84,7 +84,7 @@ jobs: uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 with: name: testresults-${{ matrix.os }}-${{ matrix.configuration }} - path: testresults/** + path: artifacts/testresults/** publish-coverage: if: github.actor != 'dependabot[bot]' From 262371e5365035598183578dfc61b25aa19afd34 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 09:50:00 +0000 Subject: [PATCH 15/16] Add emojis to CI workflow step names Co-authored-by: eiriktsarpalis <2813363+eiriktsarpalis@users.noreply.github.com> --- .github/workflows/ci-build-test.yml | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/workflows/ci-build-test.yml b/.github/workflows/ci-build-test.yml index 5f80f6b2e..dd648a6ca 100644 --- a/.github/workflows/ci-build-test.yml +++ b/.github/workflows/ci-build-test.yml @@ -34,12 +34,12 @@ jobs: runs-on: ${{ matrix.os }} steps: - - name: Clone the repo + - name: ๐Ÿ“ฅ Clone the repo uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 with: fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis - - name: Set up .NET + - name: ๐Ÿ”ง Set up .NET uses: actions/setup-dotnet@d4c94342e560b34958eacfc5d055d21461ed1c5d # v5.0.0 with: dotnet-version: | @@ -47,39 +47,39 @@ jobs: 9.0.x # NetFX testing on non-Windows requires mono - - name: Setup Mono + - name: ๐Ÿ”ง Setup Mono if: runner.os == 'Linux' run: sudo apt-get install -y mono-devel - - name: Setup Mono on macOS + - name: ๐Ÿ”ง Setup Mono on macOS if: runner.os == 'macOS' run: brew install mono - - name: Set up Node.js + - name: ๐Ÿ”ง Set up Node.js uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0 with: node-version: '20' - - name: Install dependencies for tests + - name: ๐Ÿ“ฆ Install dependencies for tests run: npm install @modelcontextprotocol/server-everything - - name: Install dependencies for tests + - name: ๐Ÿ“ฆ Install dependencies for tests run: npm install @modelcontextprotocol/server-memory - - name: Build + - name: ๐Ÿ—๏ธ Build run: make build CONFIGURATION=${{ matrix.configuration }} - - name: Test + - name: ๐Ÿงช Test run: make test CONFIGURATION=${{ matrix.configuration }} - - name: Pack + - name: ๐Ÿ“ฆ Pack if: matrix.configuration == 'Release' run: make pack CONFIGURATION=${{ matrix.configuration }} - - name: Generate docs + - name: ๐Ÿ“š Generate docs run: make generate-docs CONFIGURATION=${{ matrix.configuration }} - - name: Upload test results artifact + - name: ๐Ÿ“ค Upload test results artifact if: always() uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 with: From 29381105f49daecb67aed152e6d034ea1b293d62 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Tue, 14 Oct 2025 17:14:41 +0300 Subject: [PATCH 16/16] perform manual cleanups --- docs/concepts/elicitation/elicitation.md | 20 +++++---------- docs/concepts/logging/logging.md | 31 ++++++------------------ docs/concepts/progress/progress.md | 28 +++++++-------------- 3 files changed, 22 insertions(+), 57 deletions(-) diff --git a/docs/concepts/elicitation/elicitation.md b/docs/concepts/elicitation/elicitation.md index 6894760cc..2d9d43c9f 100644 --- a/docs/concepts/elicitation/elicitation.md +++ b/docs/concepts/elicitation/elicitation.md @@ -11,12 +11,9 @@ The **elicitation** feature allows servers to request additional information fro ### Server Support for Elicitation -Servers request structured data from users with the [ElicitAsync] extension method on [IMcpServer]. -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. - -[ElicitAsync]: xref:ModelContextProtocol.Server.McpServer.ElicitAsync* -[IMcpServer]: xref:ModelContextProtocol.Server.McpServer +Servers request structured data from users with the extension method on . +The C# SDK registers an instance of with the dependency injection container, +so tools can simply add a parameter of type to their method signature to access it. The MCP Server must specify the schema of each input value it is requesting from the user. Only primitive types (string, number, boolean) are supported for elicitation requests. @@ -31,10 +28,7 @@ The following example demonstrates how a server could request a boolean response ### Client Support for Elicitation -Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. In the MCP C# SDK, this is done by configuring an [ElicitationHandler] in the [McpClientOptions]: - -[ElicitationHandler]: xref:ModelContextProtocol.Client.McpClientHandlers.ElicitationHandler -[McpClientOptions]: xref:ModelContextProtocol.Client.McpClientOptions +Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. In the MCP C# SDK, this is done by configuring an in the : [!code-csharp[](samples/client/Program.cs?name=snippet_McpInitialize)] @@ -42,10 +36,8 @@ The ElicitationHandler is an asynchronous method that will be called when the se The ElicitationHandler must request input from the user and return the data in a format that matches the requested schema. This will be highly dependent on the client application and how it interacts with the user. -If the user provides the requested information, the ElicitationHandler should return an [ElicitResult] with the action set to "accept" and the content containing the user's input. -If the user does not provide the requested information, the ElicitationHandler should return an [ElicitResult] with the action set to "reject" and no content. - -[ElicitResult]: xref:ModelContextProtocol.Protocol.ElicitResult +If the user provides the requested information, the ElicitationHandler should return an with the action set to "accept" and the content containing the user's input. +If the user does not provide the requested information, the ElicitationHandler should return an [ with the action set to "reject" and no content. Below is an example of how a console application might handle elicitation requests. Here's an example implementation: diff --git a/docs/concepts/logging/logging.md b/docs/concepts/logging/logging.md index 73ac4bed0..742aa9fc1 100644 --- a/docs/concepts/logging/logging.md +++ b/docs/concepts/logging/logging.md @@ -49,53 +49,36 @@ Servers built with the C# SDK always declare the logging capability. Doing so do to send log messages -- only allows it. Note that stateless MCP servers may not be capable of sending log messages as there may not be an open connection to the client on which the log messages could be sent. -The C# SDK provides an extension method [WithSetLoggingLevelHandler] on [IMcpServerBuilder] to allow the +The C# SDK provides an extension method on to allow the server to perform any special logic it wants to perform when a client sets the logging level. However, the -SDK already takes care of setting the [LoggingLevel] in the [IMcpServer], so most servers will not need to +SDK already takes care of setting the in the , so most servers will not need to implement this. -[IMcpServer]: xref:ModelContextProtocol.Server.McpServer -[IMcpServerBuilder]: xref:Microsoft.Extensions.DependencyInjection.IMcpServerBuilder -[WithSetLoggingLevelHandler]: xref:Microsoft.Extensions.DependencyInjection.McpServerBuilderExtensions.WithSetLoggingLevelHandler* -[LoggingLevel]: xref:ModelContextProtocol.Server.McpServer.LoggingLevel - -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. +MCP Servers using the MCP C# SDK can obtain an [ILoggerProvider](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerprovider) from the IMcpServer extension method, +and from that can create an [ILogger](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger) instance for logging messages that should be sent to the MCP client. [!code-csharp[](samples/server/Tools/LoggingTools.cs?name=snippet_LoggingConfiguration)] -[ILoggerProvider]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerprovider -[AsClientLoggerProvider]: xref:ModelContextProtocol.Server.McpServer.AsClientLoggerProvider* -[ILogger]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger - ### Client support for logging When the server indicates that it supports logging, clients should configure the logging level to specify which messages the server should send to the client. -Clients should check if the server supports logging by checking the [Logging] property of the [ServerCapabilities] field of [IMcpClient]. - -[IMcpClient]: xref:ModelContextProtocol.Client.McpClient -[ServerCapabilities]: xref:ModelContextProtocol.Client.McpClient.ServerCapabilities -[Logging]: xref:ModelContextProtocol.Protocol.ServerCapabilities.Logging +Clients should check if the server supports logging by checking the property of the field of . [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingCapabilities)] If the server supports logging, the client should set the level of log messages it wishes to receive with -the [SetLoggingLevel] method on [IMcpClient]. If the client does not set a logging level, the server might choose +the method on . If the client does not set a logging level, the server might choose to send all log messages or none -- this is not specified in the protocol -- so it is important that the client sets a logging level to ensure it receives the desired log messages and only those messages. The `loggingLevel` set by the client is an MCP logging level. See the [Logging Levels](#logging-levels) section above for the mapping between MCP and .NET logging levels. -[SetLoggingLevel]: xref:ModelContextProtocol.Client.McpClient.SetLoggingLevel* - [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingLevel)] -Lastly, the client must configure a notification handler for [NotificationMethods.LoggingMessageNotification] notifications. +Lastly, the client must configure a notification handler for notifications. The following example simply writes the log messages to the console. -[NotificationMethods.LoggingMessageNotification]: xref:ModelContextProtocol.Protocol.NotificationMethods.LoggingMessageNotification - [!code-csharp[](samples/client/Program.cs?name=snippet_LoggingHandler)] diff --git a/docs/concepts/progress/progress.md b/docs/concepts/progress/progress.md index f7df6945b..f23f3e895 100644 --- a/docs/concepts/progress/progress.md +++ b/docs/concepts/progress/progress.md @@ -17,17 +17,13 @@ This project illustrates the common case of a server tool that performs a long-r ### Server Implementation -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 extension method of 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. +The C# SDK registers an instance of with the dependency injection container, +so tools can simply add a parameter of type to their method signature to access it. +The parameters passed to should be an instance of , which includes the current progress, total steps, and an optional message. -[sendNotificationAsync]: xref:ModelContextProtocol.McpSession.SendNotificationAsync* -[IMcpServer]: xref:ModelContextProtocol.Server.McpServer -[ProgressNotificationParams]: xref:ModelContextProtocol.Protocol.ProgressNotificationParams - -The server must 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: +The server must verify that the caller provided a `progressToken` in the request and include it in the call to . The following example demonstrates how a server can send a progress notification: [!code-csharp[](samples/server/Tools/LongRunningTools.cs?name=snippet_SendProgress)] @@ -38,10 +34,7 @@ Note that servers are not required to support progress tracking, so clients shou In the MCP C# SDK, clients can specify a `progressToken` in the request parameters when calling a tool method. The client should also provide a notification handler to process "notifications/progress" notifications. -There are two way to do this. The first is to register a notification handler using the [RegisterNotificationHandler] method on the [IMcpClient] instance. A handler registered this way will receive all progress notifications sent by the server. - -[IMcpClient]: xref:ModelContextProtocol.Client.McpClient -[RegisterNotificationHandler]: xref:ModelContextProtocol.McpSession.RegisterNotificationHandler* +There are two way to do this. The first is to register a notification handler using the method on the instance. A handler registered this way will receive all progress notifications sent by the server. ```csharp mcpClient.RegisterNotificationHandler(NotificationMethods.ProgressNotification, @@ -57,13 +50,10 @@ mcpClient.RegisterNotificationHandler(NotificationMethods.ProgressNotification, }).ConfigureAwait(false); ``` -The second way is to pass a [Progress``] instance to the tool method. [Progress``] is a standard .NET type that provides a way to receive progress updates. -For the purposes of MCP progress notifications, `T` should be [ProgressNotificationValue]. -The MCP C# SDK will automatically handle progress notifications and report them through the [Progress``] instance. +The second way is to pass a [`Progress`](https://learn.microsoft.com/dotnet/api/system.progress-1) instance to the tool method. `Progress` is a standard .NET type that provides a way to receive progress updates. +For the purposes of MCP progress notifications, `T` should be . +The MCP C# SDK will automatically handle progress notifications and report them through the `Progress` 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``]: [System.Progress](https://learn.microsoft.com/dotnet/api/system.progress-1) -[ProgressNotificationValue]: xref:ModelContextProtocol.ProgressNotificationValue - [!code-csharp[](samples/client/Program.cs?name=snippet_ProgressHandler)]