Merge branch 'main' into fweinberger/abort-handlers-on-close

Author: felixweinberger

.changeset/add-resource-size-field.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+Add missing `size` field to `ResourceSchema` to match the MCP specification

.changeset/finish-sdkerror-capability.md

@@ -0,0 +1,7 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/server': patch
+---
+
+Convert remaining capability-assertion throws to `SdkError(SdkErrorCode.CapabilityNotSupported, ...)`. Follow-up to #1454 which missed `Client.assertCapability()`, the task capability helpers in `experimental/tasks/helpers.ts`, and the sampling/elicitation capability checks in `experimental/tasks/server.ts`.

docs/server.md

@@ -330,6 +330,26 @@ server.registerTool(
 >
 > For protocol details, see [Logging](https://modelcontextprotocol.io/specification/latest/server/utilities/logging) in the MCP specification.
 
+## Instructions
+
+Pass an `instructions` string in the server options to describe how to use the server and its features. This can be used by clients to improve the LLM's understanding of available tools, resources, and prompts. It can be thought of like a "hint" to the model — for example, a client MAY add it to the system prompt. See [Instructions](https://modelcontextprotocol.io/specification/latest/basic/lifecycle#instructions) in the MCP specification.
+
+```ts source="../examples/server/src/serverGuide.examples.ts#instructions_basic"
+const server = new McpServer(
+    {
+        name: 'multi-tool-server',
+        version: '1.0.0'
+    },
+    {
+        instructions: `This server provides data-pipeline tools. Always call "validate-schema"
+before calling "transform-data" to avoid runtime errors.`
+    }
+);
+```
+
+> [!TIP]
+> Use instructions for cross-tool relationships, workflow ordering, and constraints that individual tool descriptions cannot express on their own.
+
 ## Server‑initiated requests
 
 MCP is bidirectional — servers can also send requests *to* the client during tool execution, as long as the client declares matching capabilities.

examples/server/src/serverGuide.examples.ts

@@ -15,6 +15,27 @@ import type { CallToolResult, ResourceLink } from '@modelcontextprotocol/server'
 import { completable, McpServer, ResourceTemplate, StdioServerTransport } from '@modelcontextprotocol/server';
 import * as z from 'zod/v4';
 
+// ---------------------------------------------------------------------------
+// Instructions
+// ---------------------------------------------------------------------------
+
+/** Example: Providing server instructions to guide LLM usage. */
+function instructions_basic() {
+    //#region instructions_basic
+    const server = new McpServer(
+        {
+            name: 'multi-tool-server',
+            version: '1.0.0'
+        },
+        {
+            instructions: `This server provides data-pipeline tools. Always call "validate-schema"
+before calling "transform-data" to avoid runtime errors.`
+        }
+    );
+    //#endregion instructions_basic
+    return server;
+}
+
 // ---------------------------------------------------------------------------
 // Tools, resources, and prompts
 // ---------------------------------------------------------------------------
@@ -373,6 +394,7 @@ function dnsRebinding_allowedHosts() {
 }
 
 // Suppress unused-function warnings (functions exist solely for type-checking)
+void instructions_basic;
 void registerTool_basic;
 void registerTool_resourceLink;
 void registerTool_logging;

packages/client/src/client/client.ts

@@ -456,7 +456,7 @@ export class Client extends Protocol<ClientContext> {
 
     protected assertCapability(capability: keyof ServerCapabilities, method: string): void {
         if (!this._serverCapabilities?.[capability]) {
-            throw new Error(`Server does not support ${capability} (required for ${method})`);
+            throw new SdkError(SdkErrorCode.CapabilityNotSupported, `Server does not support ${capability} (required for ${method})`);
         }
     }
 

packages/core/src/experimental/tasks/helpers.ts

@@ -5,6 +5,8 @@
  * @experimental
  */
 
+import { SdkError, SdkErrorCode } from '../../errors/sdkErrors.js';
+
 /**
  * Type representing the task requests capability structure.
  * This is derived from `ClientTasksCapability.requests` and `ServerTasksCapability.requests`.
@@ -22,7 +24,7 @@ interface TaskRequestsCapability {
  * @param requests - The task requests capability object
  * @param method - The method being checked
  * @param entityName - `'Server'` or `'Client'` for error messages
- * @throws Error if the capability is not supported
+ * @throws {@linkcode SdkError} with {@linkcode SdkErrorCode.CapabilityNotSupported} if the capability is not supported
  *
  * @experimental
  */
@@ -32,13 +34,16 @@ export function assertToolsCallTaskCapability(
     entityName: 'Server' | 'Client'
 ): void {
     if (!requests) {
-        throw new Error(`${entityName} does not support task creation (required for ${method})`);
+        throw new SdkError(SdkErrorCode.CapabilityNotSupported, `${entityName} does not support task creation (required for ${method})`);
     }
 
     switch (method) {
         case 'tools/call': {
             if (!requests.tools?.call) {
-                throw new Error(`${entityName} does not support task creation for tools/call (required for ${method})`);
+                throw new SdkError(
+                    SdkErrorCode.CapabilityNotSupported,
+                    `${entityName} does not support task creation for tools/call (required for ${method})`
+                );
             }
             break;
         }
@@ -57,7 +62,7 @@ export function assertToolsCallTaskCapability(
  * @param requests - The task requests capability object
  * @param method - The method being checked
  * @param entityName - `'Server'` or `'Client'` for error messages
- * @throws Error if the capability is not supported
+ * @throws {@linkcode SdkError} with {@linkcode SdkErrorCode.CapabilityNotSupported} if the capability is not supported
  *
  * @experimental
  */
@@ -67,20 +72,26 @@ export function assertClientRequestTaskCapability(
     entityName: 'Server' | 'Client'
 ): void {
     if (!requests) {
-        throw new Error(`${entityName} does not support task creation (required for ${method})`);
+        throw new SdkError(SdkErrorCode.CapabilityNotSupported, `${entityName} does not support task creation (required for ${method})`);
     }
 
     switch (method) {
         case 'sampling/createMessage': {
             if (!requests.sampling?.createMessage) {
-                throw new Error(`${entityName} does not support task creation for sampling/createMessage (required for ${method})`);
+                throw new SdkError(
+                    SdkErrorCode.CapabilityNotSupported,
+                    `${entityName} does not support task creation for sampling/createMessage (required for ${method})`
+                );
             }
             break;
         }
 
         case 'elicitation/create': {
             if (!requests.elicitation?.create) {
-                throw new Error(`${entityName} does not support task creation for elicitation/create (required for ${method})`);
+                throw new SdkError(
+                    SdkErrorCode.CapabilityNotSupported,
+                    `${entityName} does not support task creation for elicitation/create (required for ${method})`
+                );
             }
             break;
         }

packages/core/src/types/schemas.ts

@@ -832,6 +832,13 @@ export const ResourceSchema = z.object({
      */
     mimeType: z.optional(z.string()),
 
+    /**
+     * The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.
+     *
+     * This can be used by Hosts to display file sizes and estimate context window usage.
+     */
+    size: z.optional(z.number()),
+
     /**
      * Optional annotations for the client.
      */

packages/server/src/experimental/tasks/server.ts

@@ -22,7 +22,7 @@ import type {
     ResponseMessage,
     ResultTypeMap
 } from '@modelcontextprotocol/core';
-import { getResultSchema, GetTaskPayloadResultSchema } from '@modelcontextprotocol/core';
+import { getResultSchema, GetTaskPayloadResultSchema, SdkError, SdkErrorCode } from '@modelcontextprotocol/core';
 
 import type { Server } from '../../server/server.js';
 
@@ -122,7 +122,7 @@ export class ExperimentalServerTasks {
 
         // Capability check - only required when tools/toolChoice are provided
         if ((params.tools || params.toolChoice) && !clientCapabilities?.sampling?.tools) {
-            throw new Error('Client does not support sampling tools capability.');
+            throw new SdkError(SdkErrorCode.CapabilityNotSupported, 'Client does not support sampling tools capability.');
         }
 
         // Message structure validation - always validate tool_use/tool_result pairs.
@@ -221,13 +221,13 @@ export class ExperimentalServerTasks {
         switch (mode) {
             case 'url': {
                 if (!clientCapabilities?.elicitation?.url) {
-                    throw new Error('Client does not support url elicitation.');
+                    throw new SdkError(SdkErrorCode.CapabilityNotSupported, 'Client does not support url elicitation.');
                 }
                 break;
             }
             case 'form': {
                 if (!clientCapabilities?.elicitation?.form) {
-                    throw new Error('Client does not support form elicitation.');
+                    throw new SdkError(SdkErrorCode.CapabilityNotSupported, 'Client does not support form elicitation.');
                 }
                 break;
             }