From 6a2e0cb5e3edccad23a8725c23294aa8938a8548 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 24 Nov 2025 18:08:16 -0800 Subject: [PATCH] style edits --- docs/concepts/elicitation/elicitation.md | 22 ++++++++-------- docs/concepts/filters.md | 22 ++++++++++------ docs/concepts/httpcontext/httpcontext.md | 4 +-- docs/concepts/logging/logging.md | 10 ++++---- docs/concepts/progress/progress.md | 4 +-- docs/index.md | 6 ++--- docs/versioning.md | 32 ++++++++++++------------ 7 files changed, 54 insertions(+), 46 deletions(-) diff --git a/docs/concepts/elicitation/elicitation.md b/docs/concepts/elicitation/elicitation.md index bc1fc7ee2..86ed4ba58 100644 --- a/docs/concepts/elicitation/elicitation.md +++ b/docs/concepts/elicitation/elicitation.md @@ -15,21 +15,22 @@ Servers request structured data from users with the 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. -Primitive types (string, number, boolean) and enum types are supported for elicitation requests. -The schema may include a description to help the user understand what is being requested. +The MCP Server must specify the schema of each input value it's requesting from the user. +Primitive types (string, number, Boolean) and enum types are supported for elicitation requests. +The schema might include a description to help the user understand what's being requested. For enum types, the SDK supports several schema formats: -- **UntitledSingleSelectEnumSchema**: A single-select enum where the enum values serve as both the value and display text -- **TitledSingleSelectEnumSchema**: A single-select enum with separate display titles for each option (using JSON Schema `oneOf` with `const` and `title`) -- **UntitledMultiSelectEnumSchema**: A multi-select enum allowing multiple values to be selected -- **TitledMultiSelectEnumSchema**: A multi-select enum with display titles for each option -- **LegacyTitledEnumSchema** (deprecated): The legacy enum schema using `enumNames` for backward compatibility + +- **UntitledSingleSelectEnumSchema**: A single-select enum where the enum values serve as both the value and display text. +- **TitledSingleSelectEnumSchema**: A single-select enum with separate display titles for each option (using JSON Schema `oneOf` with `const` and `title`). +- **UntitledMultiSelectEnumSchema**: A multi-select enum allowing multiple values to be selected. +- **TitledMultiSelectEnumSchema**: A multi-select enum with display titles for each option. +- **LegacyTitledEnumSchema** (deprecated): The legacy enum schema using `enumNames` for backward compatibility. The server can request a single input or multiple inputs at once. To help distinguish multiple inputs, each input has a unique name. -The following example demonstrates how a server could request a boolean response from the user. +The following example demonstrates how a server could request a Boolean response from the user. [!code-csharp[](samples/server/Tools/InteractiveTools.cs?name=snippet_GuessTheNumber)] @@ -46,7 +47,6 @@ This will be highly dependent on the client application and how it interacts wit 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: +Here's an example implementation of how a console application might handle elicitation requests: [!code-csharp[](samples/client/Program.cs?name=snippet_ElicitationHandler)] diff --git a/docs/concepts/filters.md b/docs/concepts/filters.md index 3e081d123..91b11d6af 100644 --- a/docs/concepts/filters.md +++ b/docs/concepts/filters.md @@ -66,6 +66,7 @@ Execution flow: `filter1 -> filter2 -> filter3 -> baseHandler -> filter3 -> filt ## Common Use Cases ### Logging + ```csharp .AddListToolsFilter(next => async (context, cancellationToken) => { @@ -79,6 +80,7 @@ Execution flow: `filter1 -> filter2 -> filter3 -> baseHandler -> filter3 -> filt ``` ### Error Handling + ```csharp .AddCallToolFilter(next => async (context, cancellationToken) => { @@ -98,6 +100,7 @@ Execution flow: `filter1 -> filter2 -> filter3 -> baseHandler -> filter3 -> filt ``` ### Performance Monitoring + ```csharp .AddListToolsFilter(next => async (context, cancellationToken) => { @@ -112,6 +115,7 @@ Execution flow: `filter1 -> filter2 -> filter3 -> baseHandler -> filter3 -> filt ``` ### Caching + ```csharp .AddListResourcesFilter(next => async (context, cancellationToken) => { @@ -214,9 +218,11 @@ public class RestrictedTools The authorization filters work differently for list operations versus individual operations: #### List Operations (ListTools, ListPrompts, ListResources) + For list operations, the filters automatically remove unauthorized items from the results. Users only see tools, prompts, or resources they have permission to access. #### Individual Operations (CallTool, GetPrompt, ReadResource) + For individual operations, the filters throw an `McpException` with "Access forbidden" message. These get turned into JSON-RPC errors if uncaught by middleware. ### Filter Execution Order and Authorization @@ -224,12 +230,14 @@ For individual operations, the filters throw an `McpException` with "Access forb Authorization filters are applied automatically when you call `AddAuthorizationFilters()`. These filters run at a specific point in the filter pipeline, which means: **Filters added before authorization filters** can see: -- Unauthorized requests for operations before they are rejected by the authorization filters -- Complete listings for unauthorized primitives before they are filtered out by the authorization filters + +- Unauthorized requests for operations before they are rejected by the authorization filters. +- Complete listings for unauthorized primitives before they are filtered out by the authorization filters. **Filters added after authorization filters** will only see: -- Authorized requests that passed authorization checks -- Filtered listings containing only authorized primitives + +- Authorized requests that passed authorization checks. +- Filtered listings containing only authorized primitives. This allows you to implement logging, metrics, or other cross-cutting concerns that need to see all requests, while still maintaining proper authorization: @@ -312,6 +320,6 @@ You can also create custom authorization filters using the filter methods: Within filters, you have access to: -- `context.User` - The current user's `ClaimsPrincipal` -- `context.Services` - The request's service provider for resolving authorization services -- `context.MatchedPrimitive` - The matched tool/prompt/resource with its metadata including authorization attributes via `context.MatchedPrimitive.Metadata` +- `context.User` - The current user's `ClaimsPrincipal`. +- `context.Services` - The request's service provider for resolving authorization services. +- `context.MatchedPrimitive` - The matched tool/prompt/resource with its metadata including authorization attributes via `context.MatchedPrimitive.Metadata`. diff --git a/docs/concepts/httpcontext/httpcontext.md b/docs/concepts/httpcontext/httpcontext.md index 51bbd050a..32c0eb2fd 100644 --- a/docs/concepts/httpcontext/httpcontext.md +++ b/docs/concepts/httpcontext/httpcontext.md @@ -7,11 +7,11 @@ uid: httpcontext ## HTTP Context -When using the Streamable HTTP transport, an MCP server may need to access the underlying [HttpContext] for a request. +When using the Streamable HTTP transport, an MCP server might need to access the underlying [HttpContext] for a request. The [HttpContext] contains request metadata such as the HTTP headers, authorization context, and the actual path and query string for the request. To access the [HttpContext], the MCP server should add the [IHttpContextAccessor] service to the application service collection (typically in Program.cs). -Then any classes, e.g. a class containing MCP tools, should accept an [IHttpContextAccessor] in their constructor and store this for use by its methods. +Then any classes, for example, a class containing MCP tools, should accept an [IHttpContextAccessor] in their constructor and store this for use by its methods. Methods then use the [HttpContext property][IHttpContextAccessor.HttpContext] of the accessor to get the current context. [HttpContext]: https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.http.httpcontext diff --git a/docs/concepts/logging/logging.md b/docs/concepts/logging/logging.md index 742aa9fc1..d5aba253e 100644 --- a/docs/concepts/logging/logging.md +++ b/docs/concepts/logging/logging.md @@ -7,7 +7,7 @@ uid: logging ## Logging -MCP servers may expose log messages to clients through the [Logging utility]. +MCP servers can expose log messages to clients through the [Logging utility]. [Logging utility]: https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging @@ -18,7 +18,7 @@ This document describes how to implement logging in MCP servers and how clients MCP uses the logging levels defined in [RFC 5424](https://tools.ietf.org/html/rfc5424). The MCP C# SDK uses the standard .NET [ILogger] and [ILoggerProvider] abstractions, which support a slightly -different set of logging levels. Here's the levels and how they map to standard .NET logging levels. +different set of logging levels. The following table shows the levels and how they map to standard .NET logging levels. | Level | .NET | Description | Example Use Case | |-----------|------|-----------------------------------|------------------------------| @@ -46,8 +46,8 @@ MCP servers that implement the Logging utility must declare this in the capabili [Initialization]: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle#initialization Servers built with the C# SDK always declare the logging capability. Doing so does not obligate the server -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. +to send log messages—only allows it. Note that stateless MCP servers might not be capable of sending log +messages as there might 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 server to perform any special logic it wants to perform when a client sets the logging level. However, the @@ -70,7 +70,7 @@ Clients should check if the server supports logging by checking 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 +to send all log messages or none—this is not specified in the protocol. So it's 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. diff --git a/docs/concepts/progress/progress.md b/docs/concepts/progress/progress.md index f23f3e895..c941550c8 100644 --- a/docs/concepts/progress/progress.md +++ b/docs/concepts/progress/progress.md @@ -12,7 +12,7 @@ The Model Context Protocol (MCP) supports [progress tracking] for long-running o [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 image generation or complex calculations. -However, progress tracking is defined in the MCP specification as a general feature that can be implemented for any request that is handled by either a server or a client. +However, progress tracking is defined in the MCP specification as a general feature that can be implemented for any request that's handled by either a server or a client. This project illustrates the common case of a server tool that performs a long-running operation and sends progress updates to the client. ### Server Implementation @@ -30,7 +30,7 @@ The server must verify that the caller provided a `progressToken` in the request ### Client Implementation Clients request progress updates by including a `progressToken` in the parameters of a request. -Note that servers are not required to support progress tracking, so clients should not depend on receiving progress updates. +Note that servers aren't required to support progress tracking, so clients should not depend on receiving progress updates. 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. diff --git a/docs/index.md b/docs/index.md index 29fecac38..0f039b2f8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ _layout: landing # Overview -The official C# SDK for the [Model Context Protocol](https://modelcontextprotocol.io/), enabling .NET applications, services, and libraries to implement and interact with MCP clients and servers. Please visit our [API documentation](https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.html) for more details on available functionality. +The official C# SDK for the [Model Context Protocol](https://modelcontextprotocol.io/), enabling .NET applications, services, and libraries to implement and interact with MCP clients and servers. For more details on available functionality, please see the [API documentation](https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.html). ## About MCP @@ -16,11 +16,11 @@ For more information about MCP: - [Protocol Specification](https://modelcontextprotocol.io/specification/) - [GitHub Organization](https://github.com/modelcontextprotocol) -For how-to guides, tutorials, and additional guidance, refer to the [official MCP documentation](https://modelcontextprotocol.io/). +For how-to guides, tutorials, and additional guidance, see the [official MCP documentation](https://modelcontextprotocol.io/). ## Official SDK packages -The official C# SDK packages for stable and pre-release versions are published to the [NuGet Gallery](https://www.nuget.org) under the [ModelContextProtocolOfficial](https://www.nuget.org/profiles/ModelContextProtocolOfficial) profile. +The official C# SDK packages for stable and prerelease versions are published to the [NuGet Gallery](https://www.nuget.org) under the [ModelContextProtocolOfficial](https://www.nuget.org/profiles/ModelContextProtocolOfficial) profile. Continuous integration builds are published to the modelcontextprotocol organization's [GitHub NuGet package registry](https://github.com/orgs/modelcontextprotocol/packages?ecosystem=nuget). diff --git a/docs/versioning.md b/docs/versioning.md index d4ea7403a..93eea3cbd 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -4,32 +4,32 @@ author: jeffhandley description: ModelContextProtocol C# SDK approach to versioning, breaking changes, and support uid: versioning --- -The ModelContextProtocol specification continues to evolve rapidly, and it's important for the C# SDK to remain current with specification additions and updates. To enable this, all NuGet packages that compose the SDK will follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) with MAJOR.MINOR.PATCH version numbers, and optional pre-release versions. +The ModelContextProtocol specification continues to evolve rapidly, and it's important for the C# SDK to remain current with specification additions and updates. To enable this, all NuGet packages that compose the SDK follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) with MAJOR.MINOR.PATCH version numbers, and optional prerelease versions. -Given a version number MAJOR.MINOR.PATCH, the package versions will increment the: +Given a version number MAJOR.MINOR.PATCH, the package versions increment the: * MAJOR version when incompatible API changes are included * MINOR version when functionality is added in a backward-compatible manner * PATCH version when backward-compatible bug fixes are included -*A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements.* +*A prerelease version indicates that the version is unstable and might not satisfy the intended compatibility requirements.* ## Supported versions Beginning with the 1.0.0 release, the following support policy will be applied for the official C# ModelContextProtocol SDK packages: -1. New functionality and additive APIs will be introduced in MINOR releases within the current MAJOR version only - * New functionality will not be added to an earlier MAJOR version +1. New functionality and additive APIs will be introduced in MINOR releases within the current MAJOR version only. + * New functionality will not be added to an earlier MAJOR version. 2. Bugs will be fixed in either: - 1. A PATCH release against the latest MAJOR.MINOR version within _the latest_ MAJOR version only - 2. A MINOR release against the latest MAJOR version within _the latest_ MAJOR version only + 1. A PATCH release against the latest MAJOR.MINOR version within _the latest_ MAJOR version only. + 2. A MINOR release against the latest MAJOR version within _the latest_ MAJOR version only. 3. Bugs deemed by the maintainers to be critical or blocking will be fixed in both: - 1. A PATCH release against _the latest_ MAJOR version, within its latest MAJOR.MINOR version - 2. A PATCH release against _one previous_ MAJOR version, within its latest MAJOR.MINOR version + 1. A PATCH release against _the latest_ MAJOR version, within its latest MAJOR.MINOR version. + 2. A PATCH release against _one previous_ MAJOR version, within its latest MAJOR.MINOR version. ## Experimental APIs -MAJOR or MINOR version updates might introduce or alter APIs annotated as [`[Experimental]`](https://learn.microsoft.com/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute). This attribute indicates that an API is experimental and it may change at any time--including within PATCH or MINOR version updates. +MAJOR or MINOR version updates might introduce or alter APIs annotated as [`[Experimental]`](https://learn.microsoft.com/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute). This attribute indicates that an API is experimental and might change at any time—including within PATCH or MINOR version updates. Experimental APIs require suppression of diagnostic codes specific to the MCP SDK APIs, using an `MCP` prefix. @@ -37,15 +37,15 @@ Experimental APIs require suppression of diagnostic codes specific to the MCP SD Prior to the release of a stable 1.0.0 set of NuGet packages, the SDK remains in preview and breaking changes can be introduced without prior notice. Thereafter, the SDK follows Semantic Versioning and breaking changes against stable releases require increments to the MAJOR version. -If feasible, the SDK will support all versions of the MCP spec. However, if breaking changes to the spec make this infeasible, preference will be given to the most recent version of the MCP spec, and this would be considered a breaking change necessitating a new MAJOR version. +If feasible, the SDK will support all versions of the MCP spec. However, if breaking changes to the spec make this infeasible, preference will be given to the most recent version of the MCP spec. This would be considered a breaking change necessitating a new MAJOR version. All releases are posted to https://github.com/modelcontextprotocol/csharp-sdk/releases with release notes. Issues and pull requests labeled with `breaking-change` are highlighted in the corresponding release notes. ### Specification schema changes -If the MCP specification changes the schema for JSON payloads, the C# SDK may use the [`McpSession.NegotiatedProtocolVersion`](https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.McpSession.html#ModelContextProtocol_McpSession_NegotiatedProtocolVersion) to dynamically change the payload schema, potentially using internal data transfer objects (DTOs) to achieve the needed deserialization behavior. These techniques will be applied where feasible to maintain backward- and forward-compatibility between MCP specification versions. +If the MCP specification changes the schema for JSON payloads, the C# SDK might use the [`McpSession.NegotiatedProtocolVersion`](https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.McpSession.html#ModelContextProtocol_McpSession_NegotiatedProtocolVersion) to dynamically change the payload schema, potentially using internal data transfer objects (DTOs) to achieve the needed deserialization behavior. These techniques will be applied where feasible to maintain backward-compatibility and forward-compatibility between MCP specification versions. -Refer to the following prototypes for illustrations of how this could be achieved: +For illustrations of how this could be achieved, see the following prototypes: * [Support multiple contents in sampling results](https://github.com/eiriktsarpalis/csharp-sdk/pull/2) * [Support multiple contents in sampling results (using DTOs)](https://github.com/eiriktsarpalis/csharp-sdk/pull/3) @@ -54,8 +54,8 @@ Refer to the following prototypes for illustrations of how this could be achieve If APIs within the SDK become obsolete due to changes in the MCP spec or other evolution of the SDK's APIs, the [`[Obsolete]`](https://learn.microsoft.com/dotnet/api/system.obsoleteattribute) attribute will be applied to the affected APIs. -1. Within a MINOR version update, APIs may be marked as `[Obsolete]` to produce _build warnings_ while the API remains functional. The build warnings will provide guidance specific to the affected APIs. -2. Within a MAJOR version update, APIs may be marked as `[Obsolete]` to produce _build errors_ indicating the API is no longer functional and always throws exceptions. The build errors will provide guidance specific to the affected APIs. -3. Within a MAJOR version update, obsolete APIs may be removed. API removals are expected to be rare and avoided wherever possible, and `[Obsolete]` attributes will be applied ahead of the API removal. +1. Within a MINOR version update, APIs might be marked as `[Obsolete]` to produce _build warnings_ while the API remains functional. The build warnings will provide guidance specific to the affected APIs. +2. Within a MAJOR version update, APIs might be marked as `[Obsolete]` to produce _build errors_ indicating the API is no longer functional and always throws exceptions. The build errors will provide guidance specific to the affected APIs. +3. Within a MAJOR version update, obsolete APIs might be removed. API removals are expected to be rare and avoided wherever possible, and `[Obsolete]` attributes will be applied ahead of the API removal. Beginning with the 1.0.0 release, all obsoletions will use diagnostic codes specific to the MCP SDK APIs, using an `MCP` prefix.