Merge branch 'main' into middleware-remove-console-warn

KKonstantinov · web-flow · commit 28fd4ada13c7 · 2026-03-27T16:16:40.000+02:00
diff --git a/.changeset/abort-handlers-on-close.md b/.changeset/abort-handlers-on-close.md
@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+Abort in-flight request handlers when the connection closes. Previously, request handlers would continue running after the transport disconnected, wasting resources and preventing proper cleanup. Also fixes `InMemoryTransport.close()` firing `onclose` twice on the initiating side.
diff --git a/.changeset/stdio-skip-non-json.md b/.changeset/stdio-skip-non-json.md
@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+`ReadBuffer.readMessage()` now silently skips non-JSON lines instead of throwing `SyntaxError`. This prevents noisy `onerror` callbacks when hot-reload tools (tsx, nodemon) write debug output like "Gracefully restarting..." to stdout. Lines that parse as JSON but fail JSONRPC schema validation still throw.
diff --git a/.github/workflows/conformance.yml b/.github/workflows/conformance.yml
@@ -18,12 +18,12 @@ jobs:
         runs-on: ubuntu-latest
         continue-on-error: true
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v6
             - name: Install pnpm
-              uses: pnpm/action-setup@v4
+              uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
               with:
                   run_install: false
-            - uses: actions/setup-node@v4
+            - uses: actions/setup-node@v6
               with:
                   node-version: 24
                   cache: pnpm
@@ -36,12 +36,12 @@ jobs:
         runs-on: ubuntu-latest
         continue-on-error: true
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v6
             - name: Install pnpm
-              uses: pnpm/action-setup@v4
+              uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
               with:
                   run_install: false
-            - uses: actions/setup-node@v4
+            - uses: actions/setup-node@v6
               with:
                   node-version: 24
                   cache: pnpm
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -25,13 +25,13 @@ jobs:
             url: ${{ steps.deployment.outputs.page_url }}
 
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v6
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v4
+              uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
               with:
                   run_install: false
-            - uses: actions/setup-node@v4
+            - uses: actions/setup-node@v6
               with:
                   node-version: 24
                   cache: pnpm
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -19,7 +19,7 @@ jobs:
             - uses: actions/checkout@v6
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v4
+              uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
               id: pnpm-install
               with:
                   run_install: false
@@ -44,7 +44,7 @@ jobs:
             - uses: actions/checkout@v6
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v4
+              uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
               id: pnpm-install
               with:
                   run_install: false
@@ -71,7 +71,7 @@ jobs:
         steps:
             - uses: actions/checkout@v6
             - name: Install pnpm
-              uses: pnpm/action-setup@v4
+              uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
               with:
                   run_install: false
             - uses: actions/setup-node@v6
@@ -81,12 +81,12 @@ jobs:
                   cache-dependency-path: pnpm-lock.yaml
             - name: Set up Bun
               if: matrix.runtime == 'bun'
-              uses: oven-sh/setup-bun@v2
+              uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
               with:
                   bun-version: ${{ matrix.version }}
             - name: Set up Deno
               if: matrix.runtime == 'deno'
-              uses: denoland/setup-deno@v2
+              uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282 # v2
               with:
                   deno-version: ${{ matrix.version }}
             - run: pnpm install
@@ -105,14 +105,14 @@ jobs:
             id-token: write
 
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v6
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v4
+              uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
               id: pnpm-install
               with:
                   run_install: false
-            - uses: actions/setup-node@v4
+            - uses: actions/setup-node@v6
               with:
                   node-version: 24
                   cache: pnpm
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -19,7 +19,7 @@ jobs:
             - uses: actions/checkout@v6
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v4
+              uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
               with:
                   run_install: false
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -19,7 +19,7 @@ jobs:
             - uses: actions/checkout@v6
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v4
+              uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
               with:
                   run_install: false
 
@@ -36,7 +36,7 @@ jobs:
 
             - name: Create Release Pull Request or Publish to npm
               id: changesets
-              uses: changesets/action@v1
+              uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1
               with:
                   publish: pnpm run build:all && pnpm changeset publish
               env:
diff --git a/.github/workflows/update-spec-types.yml b/.github/workflows/update-spec-types.yml
@@ -18,7 +18,7 @@ jobs:
               uses: actions/checkout@v6
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v4
+              uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
               id: pnpm-install
               with:
                   run_install: false
diff --git a/docs/server.md b/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.
diff --git a/examples/server/src/serverGuide.examples.ts b/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;
diff --git a/packages/core/src/shared/protocol.ts b/packages/core/src/shared/protocol.ts
@@ -457,8 +457,11 @@ export abstract class Protocol<ContextT extends BaseContext> {
         this._transport = transport;
         const _onclose = this.transport?.onclose;
         this._transport.onclose = () => {
-            _onclose?.();
-            this._onclose();
+            try {
+                _onclose?.();
+            } finally {
+                this._onclose();
+            }
         };
 
         const _onerror = this.transport?.onerror;
@@ -494,13 +497,28 @@ export abstract class Protocol<ContextT extends BaseContext> {
         this._taskManager.onClose();
         this._pendingDebouncedNotifications.clear();
 
+        for (const info of this._timeoutInfo.values()) {
+            clearTimeout(info.timeoutId);
+        }
+        this._timeoutInfo.clear();
+
+        const requestHandlerAbortControllers = this._requestHandlerAbortControllers;
+        this._requestHandlerAbortControllers = new Map();
+
         const error = new SdkError(SdkErrorCode.ConnectionClosed, 'Connection closed');
 
         this._transport = undefined;
-        this.onclose?.();
 
-        for (const handler of responseHandlers.values()) {
-            handler(error);
+        try {
+            this.onclose?.();
+        } finally {
+            for (const handler of responseHandlers.values()) {
+                handler(error);
+            }
+
+            for (const controller of requestHandlerAbortControllers.values()) {
+                controller.abort(error);
+            }
         }
     }
 
@@ -642,7 +660,9 @@ export abstract class Protocol<ContextT extends BaseContext> {
             )
             .catch(error => this._onerror(new Error(`Failed to send response: ${error}`)))
             .finally(() => {
-                this._requestHandlerAbortControllers.delete(request.id);
+                if (this._requestHandlerAbortControllers.get(request.id) === abortController) {
+                    this._requestHandlerAbortControllers.delete(request.id);
+                }
             });
     }
 
diff --git a/packages/core/src/shared/stdio.ts b/packages/core/src/shared/stdio.ts
@@ -12,18 +12,28 @@ export class ReadBuffer {
     }
 
     readMessage(): JSONRPCMessage | null {
-        if (!this._buffer) {
-            return null;
+        while (this._buffer) {
+            const index = this._buffer.indexOf('\n');
+            if (index === -1) {
+                return null;
+            }
+
+            const line = this._buffer.toString('utf8', 0, index).replace(/\r$/, '');
+            this._buffer = this._buffer.subarray(index + 1);
+
+            try {
+                return deserializeMessage(line);
+            } catch (error) {
+                // Skip non-JSON lines (e.g., debug output from hot-reload tools like
+                // tsx or nodemon that write to stdout). Schema validation errors still
+                // throw so malformed-but-valid-JSON messages surface via onerror.
+                if (error instanceof SyntaxError) {
+                    continue;
+                }
+                throw error;
+            }
         }
-
-        const index = this._buffer.indexOf('\n');
-        if (index === -1) {
-            return null;
-        }
-
-        const line = this._buffer.toString('utf8', 0, index).replace(/\r$/, '');
-        this._buffer = this._buffer.subarray(index + 1);
-        return deserializeMessage(line);
+        return null;
     }
 
     clear(): void {
diff --git a/packages/core/src/shared/taskManager.ts b/packages/core/src/shared/taskManager.ts
@@ -801,6 +801,7 @@ export class TaskManager {
 
     onClose(): void {
         this._taskProgressTokens.clear();
+        this._requestResolvers.clear();
     }
 
     // -- Private helpers --
@@ -893,8 +894,4 @@ export class NullTaskManager extends TaskManager {
     ): Promise<{ queued: boolean; jsonrpcNotification?: JSONRPCNotification }> {
         return { queued: false, jsonrpcNotification: { ...notification, jsonrpc: '2.0' } };
     }
-
-    override onClose(): void {
-        // No-op
-    }
 }
diff --git a/packages/core/src/util/inMemory.ts b/packages/core/src/util/inMemory.ts
@@ -13,6 +13,7 @@ interface QueuedMessage {
 export class InMemoryTransport implements Transport {
     private _otherTransport?: InMemoryTransport;
     private _messageQueue: QueuedMessage[] = [];
+    private _closed = false;
 
     onclose?: () => void;
     onerror?: (error: Error) => void;
@@ -39,10 +40,16 @@ export class InMemoryTransport implements Transport {
     }
 
     async close(): Promise<void> {
+        if (this._closed) return;
+        this._closed = true;
+
         const other = this._otherTransport;
         this._otherTransport = undefined;
-        await other?.close();
-        this.onclose?.();
+        try {
+            await other?.close();
+        } finally {
+            this.onclose?.();
+        }
     }
 
     /**
diff --git a/packages/core/test/inMemory.test.ts b/packages/core/test/inMemory.test.ts
diff --git a/packages/core/test/shared/protocol.test.ts b/packages/core/test/shared/protocol.test.ts
diff --git a/packages/core/test/shared/stdio.test.ts b/packages/core/test/shared/stdio.test.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@modelcontextprotocol/core': patch
 +---
++
 +Abort in-flight request handlers when the connection closes. Previously, request handlers would continue running after the transport disconnected, wasting resources and preventing proper cleanup. Also fixes `InMemoryTransport.close()` firing `onclose` twice on the initiating side.