From fb25f499ec6d41042dad65108b27a6c8db3df1fc Mon Sep 17 00:00:00 2001 From: Jeff Handley Date: Thu, 26 Feb 2026 20:45:30 -0800 Subject: [PATCH] Clean up markdown-link-check workflow and fix stale URLs - Remove stale ignore rules for anthropic.com and hackerone.com - Add ignore rule for DocFX xref: links that mlc cannot check - Add redirect suppression for learn.microsoft.com locale redirects - Add redirect suppression for modelcontextprotocol.io homepage redirects - Update RFC URLs from tools.ietf.org to datatracker.ietf.org - Update GitHub Pages URLs to csharp.sdk.modelcontextprotocol.io custom domain - Fix GitHub org projects URL to include query parameter - Add mlc-disable-next-line comments for DocFX admonitions - Escape [Description] as inline code in list-of-diagnostics.md - Reformat args to multi-line with descriptive comments Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/markdown-link-check.yml | 12 ++++++++++-- docs/concepts/getting-started.md | 2 ++ docs/concepts/logging/logging.md | 2 +- docs/concepts/pagination/pagination.md | 2 ++ docs/concepts/resources/resources.md | 2 +- docs/concepts/tasks/tasks.md | 3 +++ docs/concepts/transports/transports.md | 1 + docs/index.md | 4 ++-- docs/list-of-diagnostics.md | 2 +- docs/roadmap.md | 2 +- docs/versioning.md | 2 +- 11 files changed, 25 insertions(+), 9 deletions(-) diff --git a/.github/workflows/markdown-link-check.yml b/.github/workflows/markdown-link-check.yml index 69bc6331f..dd907de65 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 938f57501..6e096d767 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 f50e874cc..f9a54d4aa 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 bb48ffa0b..1249acbf5 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 5d0268000..c7e713c51 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 412b56b7e..1947d210b 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 31477c8d9..55623d51a 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 f329a972e..3e3d88c48 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 ede10d127..59666d518 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 5cf9c8550..81955a710 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 93eea3cbd..68f147acb 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: