diff --git a/.github/workflows/markdown-link-check.yml b/.github/workflows/markdown-link-check.yml index 69bc633..dd907de 100644 --- a/.github/workflows/markdown-link-check.yml +++ b/.github/workflows/markdown-link-check.yml @@ -21,5 +21,13 @@ jobs: - name: Markup Link Checker (mlc) uses: becheran/mlc@7ec24825cefe0c9c8c6bac48430e1f69e3ec356e # v1.2.0 with: - # Ignore external links that result in 403 errors during CI. Do not warn for redirects where we want to keep the vanity URL in the markdown or for GitHub links that redirect to the login, and DocFX snippet links. - args: --ignore-links "https://www.anthropic.com/*,https://hackerone.com/anthropic-vdp/*" --do-not-warn-for-redirect-to "https://modelcontextprotocol.io/*,https://github.com/login?*" --ignore-links "*samples/*?name=snippet_*" ./docs + # Ignore DocFX cross-reference links (xref:) that mlc cannot check. + # Ignore DocFX snippet inclusion links. + # Do not warn for learn.microsoft.com locale redirects. + # Do not warn for modelcontextprotocol.io homepage/spec redirects. + args: >- + --ignore-links "xref:*" + --ignore-links "*samples/*?name=snippet_*" + --do-not-warn-for-redirect-to "https://learn.microsoft.com/en-us/*" + --do-not-warn-for-redirect-to "https://modelcontextprotocol.io/*" + ./docs diff --git a/docs/concepts/getting-started.md b/docs/concepts/getting-started.md index 938f575..6e096d7 100644 --- a/docs/concepts/getting-started.md +++ b/docs/concepts/getting-started.md @@ -19,11 +19,13 @@ The SDK ships as three NuGet packages. Pick the one that matches your scenario: | **[ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol/absoluteLatest)** | You're building a client or a **stdio-based** server and want hosting, dependency injection, and attribute-based tool/prompt/resource discovery. References `ModelContextProtocol.Core`. **This is the right starting point for most projects.** | | **[ModelContextProtocol.AspNetCore](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore/absoluteLatest)** | You're building an **HTTP-based** MCP server hosted in ASP.NET Core. References `ModelContextProtocol`, so you get everything above plus the HTTP transport. | + > [!TIP] > If you're unsure, start with the **ModelContextProtocol** package. You can always add **ModelContextProtocol.AspNetCore** later if you need HTTP transport support. ### Building an MCP server + > [!TIP] > You can also use the [MCP Server project template](https://learn.microsoft.com/dotnet/ai/quickstarts/build-mcp-server) to quickly scaffold a new MCP server project. diff --git a/docs/concepts/logging/logging.md b/docs/concepts/logging/logging.md index f50e874..f9a54d4 100644 --- a/docs/concepts/logging/logging.md +++ b/docs/concepts/logging/logging.md @@ -15,7 +15,7 @@ This document describes how to implement logging in MCP servers and how clients ### Logging Levels -MCP uses the logging levels defined in [RFC 5424](https://tools.ietf.org/html/rfc5424). +MCP uses the logging levels defined in [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424). The MCP C# SDK uses the standard .NET [ILogger] and [ILoggerProvider] abstractions, which support a slightly different set of logging levels. The following table shows the levels and how they map to standard .NET logging levels. diff --git a/docs/concepts/pagination/pagination.md b/docs/concepts/pagination/pagination.md index bb48ffa..1249acb 100644 --- a/docs/concepts/pagination/pagination.md +++ b/docs/concepts/pagination/pagination.md @@ -94,8 +94,10 @@ builder.Services.AddMcpServer() }); ``` + > [!NOTE] > The cursor format is opaque to the client. Servers can use any encoding scheme (numeric offsets, encoded tokens, database cursors, etc.) as long as they can parse their own cursors on subsequent requests. + > [!NOTE] > Because the cursor format is opaque to the client, _any_ value specified in the cursor, including the empty string, signals that more results are available. If an MCP server erroneously sends an empty string cursor with the final page of results, clients can implement their own low-level pagination scheme to work around this case. diff --git a/docs/concepts/resources/resources.md b/docs/concepts/resources/resources.md index 5d02680..c7e713c 100644 --- a/docs/concepts/resources/resources.md +++ b/docs/concepts/resources/resources.md @@ -43,7 +43,7 @@ public class MyResources Template resources use [URI templates (RFC 6570)] with parameters. They are returned separately in the resource templates list and can match a range of URIs: -[URI templates (RFC 6570)]: https://tools.ietf.org/html/rfc6570 +[URI templates (RFC 6570)]: https://datatracker.ietf.org/doc/html/rfc6570 ```csharp [McpServerResourceType] diff --git a/docs/concepts/tasks/tasks.md b/docs/concepts/tasks/tasks.md index 412b56b..1947d21 100644 --- a/docs/concepts/tasks/tasks.md +++ b/docs/concepts/tasks/tasks.md @@ -7,6 +7,7 @@ uid: tasks # MCP Tasks + > [!WARNING] > Tasks are an **experimental feature** in the MCP specification (version 2025-11-25). The API may change in future releases. See the [Experimental APIs](../../experimental.md) documentation for details on working with experimental APIs. @@ -207,6 +208,7 @@ public class MyTools(IMcpTaskStore taskStore) When a tool returns `McpTask`, the SDK bypasses automatic task wrapping and returns the task directly to the client. + > [!IMPORTANT] > **No Fault Tolerance Guarantees**: Both `InMemoryMcpTaskStore` and the automatic task support for `Task`-returning tool methods do **not** provide fault tolerance. Task state and execution are bounded by the memory of the server process. If the server crashes or restarts: > - All in-memory task metadata is lost @@ -359,6 +361,7 @@ var options = new McpClientOptions var client = await McpClient.CreateAsync(transport, options); ``` + > [!NOTE] > Clients should not rely on receiving status notifications. Notifications are optional and may not be sent in all scenarios. Always use polling as the primary mechanism for tracking task status. diff --git a/docs/concepts/transports/transports.md b/docs/concepts/transports/transports.md index 31477c8..55623d5 100644 --- a/docs/concepts/transports/transports.md +++ b/docs/concepts/transports/transports.md @@ -143,6 +143,7 @@ The [SSE (Server-Sent Events)] transport is a legacy mechanism that uses unidire [SSE (Server-Sent Events)]: https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse + > [!NOTE] > The SSE transport is considered legacy. The [Streamable HTTP](#streamable-http-transport) transport is the recommended approach for HTTP-based communication and supports bidirectional streaming. diff --git a/docs/index.md b/docs/index.md index f329a97..3e3d88c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,8 +8,8 @@ This SDK is the official C# SDK for the [Model Context Protocol](https://modelco For more details on available functionality, see: -- [Conceptual documentation](https://modelcontextprotocol.github.io/csharp-sdk/concepts/index.html) -- [API documentation](https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.html). +- [Conceptual documentation](https://csharp.sdk.modelcontextprotocol.io/concepts/index.html) +- [API documentation](https://csharp.sdk.modelcontextprotocol.io/api/ModelContextProtocol.html). ## About MCP diff --git a/docs/list-of-diagnostics.md b/docs/list-of-diagnostics.md index ede10d1..59666d5 100644 --- a/docs/list-of-diagnostics.md +++ b/docs/list-of-diagnostics.md @@ -9,7 +9,7 @@ Analyzer diagnostic IDs are in the format `MCP###`. | Diagnostic ID | Description | | :------------ | :---------- | | `MCP001` | Invalid XML documentation for MCP method | -| `MCP002` | MCP method must be partial to generate [Description] attributes | +| `MCP002` | MCP method must be partial to generate `[Description]` attributes | ## Experimental APIs diff --git a/docs/roadmap.md b/docs/roadmap.md index 5cf9c85..81955a7 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -6,7 +6,7 @@ uid: roadmap --- ## Spec Implementation Tracking -The C# SDK tracks implementation of MCP spec components using the [modelcontextprotocol project boards](https://github.com/orgs/modelcontextprotocol/projects), with a dedicated project board for each spec revision. For example, see the [2025-11-25 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/26). +The C# SDK tracks implementation of MCP spec components using the [modelcontextprotocol project boards](https://github.com/orgs/modelcontextprotocol/projects?query=is%3Aopen), with a dedicated project board for each spec revision. For example, see the [2025-11-25 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/26). ## Current Focus Areas diff --git a/docs/versioning.md b/docs/versioning.md index 93eea3c..68f147a 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -43,7 +43,7 @@ All releases are posted to https://github.com/modelcontextprotocol/csharp-sdk/re ### Specification schema changes -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. +If the MCP specification changes the schema for JSON payloads, the C# SDK might use the [`McpSession.NegotiatedProtocolVersion`](https://csharp.sdk.modelcontextprotocol.io/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. For illustrations of how this could be achieved, see the following prototypes: