Merge branch 'main' into spec/sampling-includecontext

Author: LucaButBoring

CONTRIBUTING.md

@@ -70,6 +70,10 @@ npm run check:docs
 npm run format
 ```
 
+> [!NOTE]
+> You can run all schema/documentation
+> changes at once with `npm run prep:changes`.
+
 ## Blog changes
 
 The blog is built using [Hugo](https://gohugo.io/installation/) and located in the [`blog`](./blog) directory.
@@ -80,7 +84,7 @@ To preview blog changes locally:
 npm run serve:blog
 ```
 
-## Documentation Guidelines
+### Documentation Guidelines
 
 When contributing to the documentation:
 

docs/docs/develop/build-server.mdx

@@ -1658,10 +1658,10 @@ namespace QuickstartWeatherServer.Tools;
 [McpServerToolType]
 public static class WeatherTools
 {
-    [McpServerTool, Description("Get weather alerts for a US state.")]
+    [McpServerTool, Description("Get weather alerts for a US state code.")]
     public static async Task<string> GetAlerts(
         HttpClient client,
-        [Description("The US state to get alerts for.")] string state)
+        [Description("The US state code to get alerts for.")] string state)
     {
         using var jsonDocument = await client.ReadJsonDocumentAsync($"/alerts/active/area/{state}");
         var jsonElement = jsonDocument.RootElement;

docs/legacy/concepts/prompts.mdx

@@ -28,7 +28,8 @@ Each prompt is defined with:
 ```typescript
 {
   name: string;              // Unique identifier for the prompt
-  description?: string;      // Human-readable description
+  title?: string;            // Optional human-readable name of the prompt for display purposes
+  description?: string;      // Optional human-readable description
   arguments?: [              // Optional list of arguments
     {
       name: string;          // Argument identifier
@@ -54,6 +55,7 @@ Clients can discover available prompts by sending a `prompts/list` request:
   prompts: [
     {
       name: "analyze-code",
+      title: "Request Analyze Code",
       description: "Analyze code for potential improvements",
       arguments: [
         {

docs/legacy/concepts/resources.mdx

@@ -83,7 +83,8 @@ Servers expose a list of resources via the `resources/list` request. Each resour
 ```typescript
 {
   uri: string;           // Unique identifier for the resource
-  name: string;          // Human-readable name
+  name: string;          // The name of the resource
+  title?: string;        // Optional human-readable name of the resource for display purposes
   description?: string;  // Optional description
   mimeType?: string;     // Optional MIME type
   size?: number;         // Optional size in bytes
@@ -97,7 +98,8 @@ For dynamic resources, servers can expose [URI templates](https://datatracker.ie
 ```typescript
 {
   uriTemplate: string;   // URI template following RFC 6570
-  name: string;          // Human-readable name for this type
+  name: string;          // The name of the type
+  title?: string;        // Optional Human-readable name of the type for display purposes
   description?: string;  // Optional description
   mimeType?: string;     // Optional MIME type for all matching resources
 }
@@ -114,6 +116,8 @@ The server responds with a list of resource contents:
   contents: [
     {
       uri: string;        // The URI of the resource
+      name?: string;      // The name of the resource
+      title?: string;     // Optional human-readable name of the resource for display purposes
       mimeType?: string;  // Optional MIME type
 
       // One of:

docs/legacy/concepts/tools.mdx

@@ -28,6 +28,7 @@ Each tool is defined with the following structure:
 ```typescript
 {
   name: string;          // Unique identifier for the tool
+  title?: string;        // Optional human-readable name of the tool for display purposes
   description?: string;  // Human-readable description
   inputSchema: {         // JSON Schema for the tool's parameters
     type: "object",
@@ -68,6 +69,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     tools: [
       {
         name: "calculate_sum",
+        title: "Calculate Sum",
         description: "Add two numbers together",
         inputSchema: {
           type: "object",
@@ -107,6 +109,7 @@ async def list_tools() -> list[types.Tool]:
     return [
         types.Tool(
             name="calculate_sum",
+            title="Calculate Sum",
             description="Add two numbers together",
             inputSchema={
                 "type": "object",
@@ -145,6 +148,7 @@ Tools that interact with the local system:
 ```typescript
 {
   name: "execute_command",
+  title: "Execute Command",
   description: "Run a shell command",
   inputSchema: {
     type: "object",
@@ -163,6 +167,7 @@ Tools that wrap external APIs:
 ```typescript
 {
   name: "github_create_issue",
+  title: "Create GitHub Issue",
   description: "Create a GitHub issue",
   inputSchema: {
     type: "object",
@@ -182,6 +187,7 @@ Tools that transform or analyze data:
 ```typescript
 {
   name: "analyze_csv",
+  title: "Analyze CSV",
   description: "Analyze a CSV file",
   inputSchema: {
     type: "object",
@@ -359,6 +365,7 @@ Here's how to define tools with annotations for different scenarios:
 // A read-only search tool
 {
   name: "web_search",
+  title: "Web Search",
   description: "Search the web for information",
   inputSchema: {
     type: "object",
@@ -377,6 +384,7 @@ Here's how to define tools with annotations for different scenarios:
 // A destructive file deletion tool
 {
   name: "delete_file",
+  title: "Delete File",
   description: "Delete a file from the filesystem",
   inputSchema: {
     type: "object",
@@ -397,6 +405,7 @@ Here's how to define tools with annotations for different scenarios:
 // A non-destructive database record creation tool
 {
   name: "create_record",
+  title: "Create Database Record",
   description: "Create a new record in the database",
   inputSchema: {
     type: "object",
@@ -426,6 +435,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     tools: [
       {
         name: "calculate_sum",
+        title: "Calculate Sum",
         description: "Add two numbers together",
         inputSchema: {
           type: "object",

docs/specification/2025-03-26/server/resources.mdx

@@ -243,6 +243,10 @@ sequenceDiagram
     Client->>Server: resources/list
     Server-->>Client: List of resources
 
+    Note over Client,Server: Resource Template Discovery
+    Client->>Server: resources/templates/list
+    Server-->>Client: List of resource templates
+
     Note over Client,Server: Resource Access
     Client->>Server: resources/read
     Server-->>Client: Resource contents

docs/specification/2025-06-18/server/resources.mdx

@@ -247,6 +247,10 @@ sequenceDiagram
     Client->>Server: resources/list
     Server-->>Client: List of resources
 
+    Note over Client,Server: Resource Template Discovery
+    Client->>Server: resources/templates/list
+    Server-->>Client: List of resource templates
+
     Note over Client,Server: Resource Access
     Client->>Server: resources/read
     Server-->>Client: Resource contents

docs/specification/draft/basic/authorization.mdx

@@ -479,7 +479,7 @@ response.
 
 MCP clients **MUST NOT** send tokens to the MCP server other than ones issued by the MCP server's authorization server.
 
-Authorization servers **MUST** only accept tokens that are valid for use with their
+MCP servers **MUST** only accept tokens that are valid for use with their
 own resources.
 
 MCP servers **MUST NOT** accept or transit any other tokens.

docs/specification/draft/basic/transports.mdx

@@ -28,8 +28,10 @@ In the **stdio** transport:
   to its standard output (`stdout`).
 - Messages are individual JSON-RPC requests, notifications, or responses.
 - Messages are delimited by newlines, and **MUST NOT** contain embedded newlines.
-- The server **MAY** write UTF-8 strings to its standard error (`stderr`) for logging
-  purposes. Clients **MAY** capture, forward, or ignore this logging.
+- The server **MAY** write UTF-8 strings to its standard error (`stderr`) for any
+  logging purposes including informational, debug, and error messages.
+- The client **MAY** capture, forward, or ignore the server's `stderr` output
+  and **SHOULD NOT** assume `stderr` output indicates error conditions.
 - The server **MUST NOT** write anything to its `stdout` that is not a valid MCP message.
 - The client **MUST NOT** write anything to the server's `stdin` that is not a valid MCP
   message.
@@ -202,6 +204,7 @@ servers which want to establish stateful sessions:
      securely generated UUID, a JWT, or a cryptographic hash).
    - The session ID **MUST** only contain visible ASCII characters (ranging from 0x21 to
      0x7E).
+   - The client **MUST** handle the session ID in a secure manner, see [Session Hijacking mitigations](/specification/draft/basic/security_best_practices#session-hijacking) for more details.
 2. If an `Mcp-Session-Id` is returned by the server during initialization, clients using
    the Streamable HTTP transport **MUST** include it in the `Mcp-Session-Id` header on
    all of their subsequent HTTP requests.

docs/specification/draft/basic/utilities/tasks.mdx

@@ -160,6 +160,7 @@ To create a task, requestors send a request with the `task` field included in th
       "status": "working",
       "statusMessage": "The operation is now in progress.",
       "createdAt": "2025-11-25T10:30:00Z",
+      "lastUpdatedAt": "2025-11-25T10:40:00Z",
       "ttl": 60000,
       "pollInterval": 5000
     }
@@ -219,6 +220,7 @@ Requestors **SHOULD** continue polling until the task reaches a terminal status
     "status": "working",
     "statusMessage": "The operation is now in progress.",
     "createdAt": "2025-11-25T10:30:00Z",
+    "lastUpdatedAt": "2025-11-25T10:40:00Z",
     "ttl": 30000,
     "pollInterval": 5000
   }
@@ -291,6 +293,7 @@ When a task status changes, receivers **MAY** send a [`notifications/tasks/statu
     "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
     "status": "completed",
     "createdAt": "2025-11-25T10:30:00Z",
+    "lastUpdatedAt": "2025-11-25T10:50:00Z",
     "ttl": 60000,
     "pollInterval": 5000
   }
@@ -330,13 +333,15 @@ To retrieve a list of tasks, requestors can send a [`tasks/list`](/specification
         "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
         "status": "working",
         "createdAt": "2025-11-25T10:30:00Z",
+        "lastUpdatedAt": "2025-11-25T10:40:00Z",
         "ttl": 30000,
         "pollInterval": 5000
       },
       {
         "taskId": "abc123-def456-ghi789",
         "status": "completed",
         "createdAt": "2025-11-25T09:15:00Z",
+        "lastUpdatedAt": "2025-11-25T10:40:00Z",
         "ttl": 60000
       }
     ],
@@ -373,6 +378,7 @@ To explicitly cancel a task, requestors can send a [`tasks/cancel`](/specificati
     "status": "cancelled",
     "statusMessage": "The task was cancelled by request.",
     "createdAt": "2025-11-25T10:30:00Z",
+    "lastUpdatedAt": "2025-11-25T10:40:00Z",
     "ttl": 30000,
     "pollInterval": 5000
   }
@@ -448,6 +454,7 @@ While this note is not prescriptive regarding the specific usage of SSE streams,
 ### TTL and Resource Management
 
 1. Receivers **MUST** include a `createdAt` [ISO 8601](https://datatracker.ietf.org/doc/html/rfc3339#section-5)-formatted timestamp in all task responses to indicate when the task was created.
+1. Receivers **MUST** include a `lastUpdatedAt` [ISO 8601](https://datatracker.ietf.org/doc/html/rfc3339#section-5)-formatted timestamp in all task responses to indicate when the task was last updated.
 1. Receivers **MAY** override the requested `ttl` duration.
 1. Receivers **MUST** include the actual `ttl` duration (or `null` for unlimited) in `tasks/get` responses.
 1. After a task's `ttl` lifetime has elapsed, receivers **MAY** delete the task and its results, regardless of the task status.
@@ -704,6 +711,7 @@ A task represents the execution state of a request. The task state includes:
 - `createdAt`: ISO 8601 timestamp when the task was created
 - `ttl`: Time in milliseconds from creation before task may be deleted
 - `pollInterval`: Suggested time in milliseconds between status checks
+- `lastUpdatedAt`: ISO 8601 timestamp when the task status was last updated
 
 ### Task Status
 
@@ -842,6 +850,7 @@ When the underlying request does not complete successfully, the task moves to th
     "taskId": "786512e2-9e0d-44bd-8f29-789f820fe840",
     "status": "failed",
     "createdAt": "2025-11-25T10:30:00Z",
+    "lastUpdatedAt": "2025-11-25T10:40:00Z",
     "ttl": 30000,
     "statusMessage": "Tool execution failed: API rate limit exceeded"
   }