Merge branch 'main' of https://github.com/modelcontextprotocol/typescript-sdk into feat/elicitation-sampling-streaming

Author: LucaButBoring

.github/workflows/main.yml

@@ -67,8 +67,19 @@ jobs:
               id: npm-tag
               run: |
                   VERSION=$(node -p "require('./package.json').version")
+                  # Check if this is a beta release
                   if [[ "$VERSION" == *"-beta"* ]]; then
                     echo "tag=--tag beta" >> $GITHUB_OUTPUT
+                  # Check if this release is from a non-main branch (patch/maintenance release)
+                  elif [[ "${{ github.event.release.target_commitish }}" != "main" ]]; then
+                    # Use "release-X.Y" as tag for old branch releases (e.g., "release-1.23" for 1.23.x)
+                    # npm tags are mutable pointers to versions (like "latest" pointing to 1.24.3).
+                    # Using "release-1.23" means users can `npm install @modelcontextprotocol/[email protected]`
+                    # to get the latest patch on that minor version, and the tag updates if we
+                    # release 1.23.2, 1.23.3, etc.
+                    # Note: Can't use "v1.23" because npm rejects tags that look like semver ranges.
+                    MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1,2)
+                    echo "tag=--tag release-${MAJOR_MINOR}" >> $GITHUB_OUTPUT
                   else
                     echo "tag=" >> $GITHUB_OUTPUT
                   fi

docs/client.md

@@ -51,7 +51,7 @@ Examples:
 - [`simpleOAuthClient.ts`](../src/examples/client/simpleOAuthClient.ts)
 - [`simpleOAuthClientProvider.ts`](../src/examples/client/simpleOAuthClientProvider.ts)
 - [`simpleClientCredentials.ts`](../src/examples/client/simpleClientCredentials.ts)
-- Server-side auth demo: [`demoInMemoryOAuthProvider.ts`](../src/examples/server/demoInMemoryOAuthProvider.ts)
+- Server-side auth demo: [`demoInMemoryOAuthProvider.ts`](../src/examples/server/demoInMemoryOAuthProvider.ts) (tests live under `test/examples/server/demoInMemoryOAuthProvider.test.ts`)
 
 These examples show how to:
 

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@modelcontextprotocol/sdk",
-    "version": "1.24.2",
+    "version": "1.24.3",
     "description": "Model Context Protocol implementation for TypeScript",
     "license": "MIT",
     "author": "Anthropic, PBC (https://anthropic.com)",
@@ -96,6 +96,7 @@
         "express": "^5.0.1",
         "express-rate-limit": "^7.5.0",
         "jose": "^6.1.1",
+        "json-schema-typed": "^8.0.2",
         "pkce-challenge": "^5.0.0",
         "raw-body": "^3.0.0",
         "zod": "^3.25 || ^4.0",

package.json

@@ -42,7 +42,13 @@ import {
     ElicitRequestSchema,
     CreateTaskResultSchema,
     CreateMessageRequestSchema,
-    CreateMessageResultSchema
+    CreateMessageResultSchema,
+    ToolListChangedNotificationSchema,
+    PromptListChangedNotificationSchema,
+    ResourceListChangedNotificationSchema,
+    ListChangedOptions,
+    ListChangedOptionsBaseSchema,
+    type ListChangedHandlers
 } from '../types.js';
 import { AjvJsonSchemaValidator } from '../validation/ajv-provider.js';
 import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator } from '../validation/types.js';
@@ -87,14 +93,20 @@ function applyElicitationDefaults(schema: JsonSchemaType | undefined, data: unkn
 
     if (Array.isArray(schema.anyOf)) {
         for (const sub of schema.anyOf) {
-            applyElicitationDefaults(sub, data);
+            // Skip boolean schemas (true/false are valid JSON Schemas but have no defaults)
+            if (typeof sub !== 'boolean') {
+                applyElicitationDefaults(sub, data);
+            }
         }
     }
 
     // Combine schemas
     if (Array.isArray(schema.oneOf)) {
         for (const sub of schema.oneOf) {
-            applyElicitationDefaults(sub, data);
+            // Skip boolean schemas (true/false are valid JSON Schemas but have no defaults)
+            if (typeof sub !== 'boolean') {
+                applyElicitationDefaults(sub, data);
+            }
         }
     }
 }
@@ -163,6 +175,34 @@ export type ClientOptions = ProtocolOptions & {
      * ```
      */
     jsonSchemaValidator?: jsonSchemaValidator;
+
+    /**
+     * Configure handlers for list changed notifications (tools, prompts, resources).
+     *
+     * @example
+     * ```typescript
+     * const client = new Client(
+     *   { name: 'my-client', version: '1.0.0' },
+     *   {
+     *     listChanged: {
+     *       tools: {
+     *         onChanged: (error, tools) => {
+     *           if (error) {
+     *             console.error('Failed to refresh tools:', error);
+     *             return;
+     *           }
+     *           console.log('Tools updated:', tools);
+     *         }
+     *       },
+     *       prompts: {
+     *         onChanged: (error, prompts) => console.log('Prompts updated:', prompts)
+     *       }
+     *     }
+     *   }
+     * );
+     * ```
+     */
+    listChanged?: ListChangedHandlers;
 };
 
 /**
@@ -204,6 +244,8 @@ export class Client<
     private _cachedKnownTaskTools: Set<string> = new Set();
     private _cachedRequiredTaskTools: Set<string> = new Set();
     private _experimental?: { tasks: ExperimentalClientTasks<RequestT, NotificationT, ResultT> };
+    private _listChangedDebounceTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
+    private _pendingListChangedConfig?: ListChangedHandlers;
 
     /**
      * Initializes this client with the given name and version information.
@@ -215,6 +257,40 @@ export class Client<
         super(options);
         this._capabilities = options?.capabilities ?? {};
         this._jsonSchemaValidator = options?.jsonSchemaValidator ?? new AjvJsonSchemaValidator();
+
+        // Store list changed config for setup after connection (when we know server capabilities)
+        if (options?.listChanged) {
+            this._pendingListChangedConfig = options.listChanged;
+        }
+    }
+
+    /**
+     * Set up handlers for list changed notifications based on config and server capabilities.
+     * This should only be called after initialization when server capabilities are known.
+     * Handlers are silently skipped if the server doesn't advertise the corresponding listChanged capability.
+     * @internal
+     */
+    private _setupListChangedHandlers(config: ListChangedHandlers): void {
+        if (config.tools && this._serverCapabilities?.tools?.listChanged) {
+            this._setupListChangedHandler('tools', ToolListChangedNotificationSchema, config.tools, async () => {
+                const result = await this.listTools();
+                return result.tools;
+            });
+        }
+
+        if (config.prompts && this._serverCapabilities?.prompts?.listChanged) {
+            this._setupListChangedHandler('prompts', PromptListChangedNotificationSchema, config.prompts, async () => {
+                const result = await this.listPrompts();
+                return result.prompts;
+            });
+        }
+
+        if (config.resources && this._serverCapabilities?.resources?.listChanged) {
+            this._setupListChangedHandler('resources', ResourceListChangedNotificationSchema, config.resources, async () => {
+                const result = await this.listResources();
+                return result.resources;
+            });
+        }
     }
 
     /**
@@ -442,6 +518,12 @@ export class Client<
             await this.notification({
                 method: 'notifications/initialized'
             });
+
+            // Set up list changed handlers now that we know server capabilities
+            if (this._pendingListChangedConfig) {
+                this._setupListChangedHandlers(this._pendingListChangedConfig);
+                this._pendingListChangedConfig = undefined;
+            }
         } catch (error) {
             // Disconnect if initialization fails.
             void this.close();
@@ -757,6 +839,66 @@ export class Client<
         return result;
     }
 
+    /**
+     * Set up a single list changed handler.
+     * @internal
+     */
+    private _setupListChangedHandler<T>(
+        listType: string,
+        notificationSchema: { shape: { method: { value: string } } },
+        options: ListChangedOptions<T>,
+        fetcher: () => Promise<T[]>
+    ): void {
+        // Validate options using Zod schema (validates autoRefresh and debounceMs)
+        const parseResult = ListChangedOptionsBaseSchema.safeParse(options);
+        if (!parseResult.success) {
+            throw new Error(`Invalid ${listType} listChanged options: ${parseResult.error.message}`);
+        }
+
+        // Validate callback
+        if (typeof options.onChanged !== 'function') {
+            throw new Error(`Invalid ${listType} listChanged options: onChanged must be a function`);
+        }
+
+        const { autoRefresh, debounceMs } = parseResult.data;
+        const { onChanged } = options;
+
+        const refresh = async () => {
+            if (!autoRefresh) {
+                onChanged(null, null);
+                return;
+            }
+
+            try {
+                const items = await fetcher();
+                onChanged(null, items);
+            } catch (e) {
+                const error = e instanceof Error ? e : new Error(String(e));
+                onChanged(error, null);
+            }
+        };
+
+        const handler = () => {
+            if (debounceMs) {
+                // Clear any pending debounce timer for this list type
+                const existingTimer = this._listChangedDebounceTimers.get(listType);
+                if (existingTimer) {
+                    clearTimeout(existingTimer);
+                }
+
+                // Set up debounced refresh
+                const timer = setTimeout(refresh, debounceMs);
+                this._listChangedDebounceTimers.set(listType, timer);
+            } else {
+                // No debounce, refresh immediately
+                refresh();
+            }
+        };
+
+        // Register notification handler
+        this.setNotificationHandler(notificationSchema as AnyObjectSchema, handler);
+    }
+
     async sendRootsListChanged() {
         return this.notification({ method: 'notifications/roots/list_changed' });
     }

src/client/index.ts

@@ -281,6 +281,9 @@ export class SSEClientTransport implements Transport {
 
                 throw new Error(`Error POSTing to endpoint (HTTP ${response.status}): ${text}`);
             }
+
+            // Release connection - POST responses don't have content we need
+            await response.body?.cancel();
         } catch (error) {
             this.onerror?.(error as Error);
             throw error;

src/client/sse.ts

@@ -592,8 +592,12 @@ export class StreamableHTTPClientTransport implements Transport {
                         this.onmessage?.(msg);
                     }
                 } else {
+                    await response.body?.cancel();
                     throw new StreamableHTTPError(-1, `Unexpected content type: ${contentType}`);
                 }
+            } else {
+                // No requests in message but got 200 OK - still need to release connection
+                await response.body?.cancel();
             }
         } catch (error) {
             this.onerror?.(error as Error);

src/client/streamableHttp.ts

@@ -155,7 +155,7 @@ npx tsx src/examples/client/elicitationUrlExample.ts
 
 #### Deprecated SSE Transport
 
-A server that implements the deprecated HTTP+SSE transport (protocol version 2024-11-05). This example only used for testing backwards compatibility for clients.
+A server that implements the deprecated HTTP+SSE transport (protocol version 2024-11-05). This example is only used for testing backwards compatibility for clients.
 
 - Two separate endpoints: `/mcp` for the SSE stream (GET) and `/messages` for client messages (POST)
 - Tool implementation with a `start-notification-stream` tool that demonstrates sending periodic notifications

src/examples/README.md

@@ -62,6 +62,7 @@ import { Transport } from '../shared/transport.js';
 import { validateAndWarnToolName } from '../shared/toolNameValidation.js';
 import { ExperimentalMcpServerTasks } from '../experimental/tasks/mcp-server.js';
 import type { ToolTaskHandler } from '../experimental/tasks/interfaces.js';
+import { ZodOptional } from 'zod';
 
 /**
  * High-level MCP server that provides a simpler API for working with resources, tools, and prompts.
@@ -557,8 +558,6 @@ export class McpServer {
             throw new McpError(ErrorCode.InvalidParams, `Resource ${uri} not found`);
         });
 
-        this.setCompletionRequestHandler();
-
         this._resourceHandlersInitialized = true;
     }
 
@@ -623,8 +622,6 @@ export class McpServer {
             }
         });
 
-        this.setCompletionRequestHandler();
-
         this._promptHandlersInitialized = true;
     }
 
@@ -815,6 +812,14 @@ export class McpServer {
             }
         };
         this._registeredResourceTemplates[name] = registeredResourceTemplate;
+
+        // If the resource template has any completion callbacks, enable completions capability
+        const variableNames = template.uriTemplate.variableNames;
+        const hasCompleter = Array.isArray(variableNames) && variableNames.some(v => !!template.completeCallback(v));
+        if (hasCompleter) {
+            this.setCompletionRequestHandler();
+        }
+
         return registeredResourceTemplate;
     }
 
@@ -848,6 +853,18 @@ export class McpServer {
             }
         };
         this._registeredPrompts[name] = registeredPrompt;
+
+        // If any argument uses a Completable schema, enable completions capability
+        if (argsSchema) {
+            const hasCompletable = Object.values(argsSchema).some(field => {
+                const inner: unknown = field instanceof ZodOptional ? field._def?.innerType : field;
+                return isCompletable(inner);
+            });
+            if (hasCompletable) {
+                this.setCompletionRequestHandler();
+            }
+        }
+
         return registeredPrompt;
     }
 
@@ -889,6 +906,7 @@ export class McpServer {
                 if (typeof updates.title !== 'undefined') registeredTool.title = updates.title;
                 if (typeof updates.description !== 'undefined') registeredTool.description = updates.description;
                 if (typeof updates.paramsSchema !== 'undefined') registeredTool.inputSchema = objectFromShape(updates.paramsSchema);
+                if (typeof updates.outputSchema !== 'undefined') registeredTool.outputSchema = objectFromShape(updates.outputSchema);
                 if (typeof updates.callback !== 'undefined') registeredTool.handler = updates.callback;
                 if (typeof updates.annotations !== 'undefined') registeredTool.annotations = updates.annotations;
                 if (typeof updates._meta !== 'undefined') registeredTool._meta = updates._meta;