Address PR feedback on conceptual docs

- Minimize cancellation doc to focus on MCP protocol behavior, not
  CancellationToken patterns
- Simplify ping doc to a single API call example
- Soften capabilities overview to not prescribe initialize handshake steps
- Remove enum row from JSON Schema type mapping table
- Replace file path examples with ID-based lookups to avoid path traversal
- Use BlobResourceContents.FromBytes() factory consistently
- Switch inline markdown links to reference-style

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jeffhandley

docs/concepts/cancellation/cancellation.md

@@ -7,46 +7,18 @@ uid: cancellation
 
 ## Cancellation
 
-MCP supports [cancellation] of in-flight requests. Either side can cancel a previously issued request by using .NET's [task cancellation] with a `CancellationToken` to send a cancellation notification.
+MCP supports [cancellation] of in-flight requests. Either side can cancel a previously issued request, and `CancellationToken` parameters on MCP methods are wired to send and receive `notifications/cancelled` notifications over the protocol.
 
 [cancellation]: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation
 [task cancellation]: https://learn.microsoft.com/dotnet/standard/parallel-programming/task-cancellation
 
-### Overview
+### How cancellation maps to MCP notifications
 
-When a client cancels a pending request, a `notifications/cancelled` notification is sent to the server. The server's `CancellationToken` for that request is then triggered, allowing the server-side handler to stop work gracefully. This same mechanism works in reverse for server-to-client requests.
-
-### Client-side cancellation
-
-All client methods accept a `CancellationToken` parameter. Cancel a pending request by canceling the token:
-
-```csharp
-using var cts = new CancellationTokenSource();
-
-// Start a long-running tool call
-var toolTask = client.CallToolAsync(
-    "long_running_operation",
-    new Dictionary<string, object?> { ["duration"] = 60 },
-    cancellationToken: cts.Token);
-
-// Cancel after 5 seconds
-cts.CancelAfter(TimeSpan.FromSeconds(5));
-
-try
-{
-    var result = await toolTask;
-}
-catch (OperationCanceledException)
-{
-    Console.WriteLine("Tool call was cancelled.");
-}
-```
-
-When the `CancellationToken` is cancelled, a `notifications/cancelled` notification is automatically sent to the server with the request ID, allowing the server to stop processing.
+When a `CancellationToken` passed to a client method (such as <xref:ModelContextProtocol.Client.McpClient.CallToolAsync*>) is cancelled, a `notifications/cancelled` notification is sent to the server with the request ID. On the server side, the `CancellationToken` provided to the tool method is then triggered, allowing the handler to stop work gracefully. This same mechanism works in reverse for server-to-client requests.
 
 ### Server-side cancellation handling
 
-Server tool methods should accept a `CancellationToken` parameter and check it during long-running operations:
+Server tool methods receive a `CancellationToken` that is triggered when the client sends a cancellation notification. Pass this token through to any async operations so they stop promptly:
 
 ```csharp
 [McpServerTool, Description("A long-running computation")]
@@ -56,17 +28,14 @@ public static async Task<string> LongComputation(
 {
     for (int i = 0; i < iterations; i++)
     {
-        // Check for cancellation on each iteration
-        cancellationToken.ThrowIfCancellationRequested();
-
         await Task.Delay(1000, cancellationToken);
     }
 
     return $"Completed {iterations} iterations.";
 }
 ```
 
-When the client sends a cancellation notification, the `CancellationToken` provided to the tool method is automatically triggered. The `OperationCanceledException` propagates back to the client as a cancellation response.
+When the client sends a cancellation notification, the `OperationCanceledException` propagates back to the client as a cancellation response.
 
 ### Cancellation notification details
 
@@ -75,9 +44,9 @@ The cancellation notification includes:
 - **RequestId**: The ID of the request to cancel, allowing the receiver to correlate the cancellation with the correct in-flight request.
 - **Reason**: An optional human-readable reason for the cancellation.
 
+Cancellation notifications can be observed by registering a handler:
+
 ```csharp
-// This is sent automatically when a CancellationToken is cancelled,
-// but you can also observe cancellation notifications:
 mcpClient.RegisterNotificationHandler(
     NotificationMethods.CancelledNotification,
     (notification, ct) =>

docs/concepts/capabilities/capabilities.md

@@ -13,13 +13,7 @@ MCP uses a [capability negotiation] mechanism during connection initialization.
 
 ### Overview
 
-When a client connects to a server, the initialization handshake includes:
-
-1. The **client** sends an `initialize` request with its <xref:ModelContextProtocol.Protocol.ClientCapabilities> and protocol version.
-2. The **server** responds with its <xref:ModelContextProtocol.Protocol.ServerCapabilities> and the negotiated protocol version.
-3. The client sends an `initialized` notification to confirm the session is ready.
-
-Both sides should check the other's capabilities before using optional features.
+During connection setup, clients and servers exchange their supported capabilities so each side can adapt its behavior accordingly. After initialization, both sides should check the other's capabilities before using optional features.
 
 ### Client capabilities
 
@@ -119,9 +113,7 @@ if (client.ServerCapabilities.Completions is not null)
 
 ### Protocol version negotiation
 
-The client specifies the MCP protocol version it supports in the `initialize` request. The server responds with the negotiated protocol version, which may differ from the client's requested version if the server supports an earlier version.
-
-After initialization, the negotiated version is available on both sides:
+During connection setup, the client and server negotiate a mutually supported MCP protocol version. After initialization, the negotiated version is available on both sides:
 
 ```csharp
 // On the client

docs/concepts/ping/ping.md

@@ -11,45 +11,12 @@ MCP includes a [ping mechanism] that allows either side of a connection to verif
 
 [ping mechanism]: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping
 
-### Overview
-
-The ping operation is a simple request/response exchange. Either the client or the server can initiate a ping, and the other side responds automatically. Ping responses are handled automatically—callers only need to invoke the method to send a ping.
-
 ### Pinging from the client
 
 Use the <xref:ModelContextProtocol.Client.McpClient.PingAsync*> method to verify the server is responsive:
 
 ```csharp
-await using var client = await McpClient.CreateAsync(transport);
-
-try
-{
-    await client.PingAsync();
-    Console.WriteLine("Server is responsive.");
-}
-catch (OperationCanceledException)
-{
-    Console.WriteLine("Ping timed out - server may be unresponsive.");
-}
-catch (McpException ex)
-{
-    Console.WriteLine($"Ping failed: {ex.Message}");
-}
-```
-
-A timeout can also be specified using a `CancellationToken`:
-
-```csharp
-using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
-
-try
-{
-    await client.PingAsync(cancellationToken: cts.Token);
-}
-catch (OperationCanceledException)
-{
-    Console.WriteLine("Server did not respond within 5 seconds.");
-}
+await client.PingAsync(cancellationToken);
 ```
 
 ### Automatic ping handling

docs/concepts/prompts/prompts.md

@@ -94,11 +94,11 @@ public static IEnumerable<ChatMessage> AnalyzeImage(
 For protocol-specific content types like <xref:ModelContextProtocol.Protocol.EmbeddedResourceBlock>, use <xref:ModelContextProtocol.Protocol.PromptMessage> instead of `ChatMessage`. `PromptMessage` has a `Role` property and a single `Content` property of type <xref:ModelContextProtocol.Protocol.ContentBlock>:
 
 ```csharp
-[McpServerPrompt, Description("A prompt that includes a file resource")]
+[McpServerPrompt, Description("A prompt that includes a document resource")]
 public static IEnumerable<PromptMessage> ReviewDocument(
-    [Description("Path to the document to review")] string path)
+    [Description("The document ID to review")] string documentId)
 {
-    string content = File.ReadAllText(path);
+    string content = LoadDocument(documentId); // application logic to load by ID
     return
     [
         new PromptMessage
@@ -113,7 +113,7 @@ public static IEnumerable<PromptMessage> ReviewDocument(
             {
                 Resource = new TextResourceContents
                 {
-                    Uri = $"file:///{path}",
+                    Uri = $"docs://documents/{documentId}",
                     MimeType = "text/plain",
                     Text = content
                 }

docs/concepts/resources/resources.md

@@ -39,40 +39,25 @@ Template resources use [URI templates (RFC 6570)] with parameters. They are retu
 
 ```csharp
 [McpServerResourceType]
-public class FileResources
+public class DocumentResources
 {
-    // Configure a root directory for all file:// resources
-    private static readonly string RootDirectory = Path.GetFullPath(AppContext.BaseDirectory);
-
-    [McpServerResource(UriTemplate = "file:///{path}", Name = "File Resource")]
-    [Description("Reads a file by its path within the configured root directory")]
-    public static ResourceContents ReadFile(string path)
+    [McpServerResource(UriTemplate = "docs://articles/{id}", Name = "Article")]
+    [Description("Returns an article by its ID")]
+    public static ResourceContents GetArticle(string id)
     {
-        if (string.IsNullOrWhiteSpace(path))
-        {
-            throw new McpException("Path must be provided.");
-        }
+        string? content = LoadArticle(id); // application logic to load by ID
 
-        // Combine the requested path with the root directory and canonicalize it
-        var fullPath = Path.GetFullPath(Path.Combine(RootDirectory, path));
-
-        // Ensure the final path is still under the allowed root directory
-        if (!fullPath.StartsWith(RootDirectory, StringComparison.OrdinalIgnoreCase))
+        if (content is null)
         {
-            throw new McpException("Requested file path is outside the allowed directory.");
+            throw new McpException($"Article not found: {id}");
         }
 
-        if (File.Exists(fullPath))
+        return new TextResourceContents
         {
-            return new TextResourceContents
-            {
-                Uri = $"file:///{path}",
-                MimeType = "text/plain",
-                Text = File.ReadAllText(fullPath)
-            };
-        }
-
-        throw new McpException($"File not found: {path}");
+            Uri = $"docs://articles/{id}",
+            MimeType = "text/plain",
+            Text = content
+        };
     }
 }
 ```
@@ -83,7 +68,7 @@ Register resource types when building the server:
 builder.Services.AddMcpServer()
     .WithHttpTransport()
     .WithResources<MyResources>()
-    .WithResources<FileResources>();
+    .WithResources<DocumentResources>();
 ```
 
 ### Reading text resources

docs/concepts/tools/tools.md

@@ -84,16 +84,16 @@ Return an <xref:ModelContextProtocol.Protocol.EmbeddedResourceBlock> to embed a
 The resource can contain either text or binary data through <xref:ModelContextProtocol.Protocol.TextResourceContents> or <xref:ModelContextProtocol.Protocol.BlobResourceContents>:
 
 ```csharp
-[McpServerTool, Description("Returns a file as an embedded resource")]
-public static EmbeddedResourceBlock ReadFile(string path)
+[McpServerTool, Description("Returns a document as an embedded resource")]
+public static EmbeddedResourceBlock GetDocument()
 {
     return new EmbeddedResourceBlock
     {
         Resource = new TextResourceContents
         {
-            Uri = $"file:///{path}",
+            Uri = "docs://readme",
             MimeType = "text/plain",
-            Text = File.ReadAllText(path)
+            Text = "This is the document content."
         }
     };
 }
@@ -102,13 +102,13 @@ public static EmbeddedResourceBlock ReadFile(string path)
 For binary resources, use <xref:ModelContextProtocol.Protocol.BlobResourceContents>:
 
 ```csharp
-[McpServerTool, Description("Returns a binary file as an embedded resource")]
-public static EmbeddedResourceBlock ReadBinaryFile(string path)
+[McpServerTool, Description("Returns a binary resource")]
+public static EmbeddedResourceBlock GetBinaryData(string id)
 {
+    byte[] data = LoadData(id); // application logic to load data by ID
     return new EmbeddedResourceBlock
     {
-        Resource = BlobResourceContents.FromBytes(
-            File.ReadAllBytes(path), $"file:///{path}", "application/octet-stream")
+        Resource = BlobResourceContents.FromBytes(data, $"data://items/{id}", "application/octet-stream")
     };
 }
 ```
@@ -291,7 +291,6 @@ Tool parameters are described using [JSON Schema 2020-12]. JSON schemas are auto
 | `int`, `long` | `integer` |
 | `float`, `double` | `number` |
 | `bool` | `boolean` |
-| `enum` | `string` with `enum` values |
 | Complex types | `object` with `properties` |
 
 Use `[Description]` attributes on parameters to populate the `description` field in the generated schema. This helps LLMs understand what each parameter expects.