modelcontextprotocol/typescript-sdk
Watch
1
0
Fork
You've already forked typescript-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

[SEP-2663] refactor!: remove 2025-11 experimental tasks (#2128)

Browse source
This commit is contained in:
Felix Weinberger 2026-06-02 13:04:18 +01:00 • committed by GitHub
commit c8d7401b46
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 423 additions and 18280 deletions
Download patch file Download diff file Expand all files Collapse all files

122
packages/client/src/client/client.ts
View file

@ -29,24 +29,19 @@ import type {
Result,
ServerCapabilities,
SubscribeRequest,
TaskManagerOptions,
Tool,
Transport,
UnsubscribeRequest
} from '@modelcontextprotocol/core';
import {
assertClientRequestTaskCapability,
assertToolsCallTaskCapability,
CallToolResultSchema,
CompleteResultSchema,
CreateMessageRequestSchema,
CreateMessageResultSchema,
CreateMessageResultWithToolsSchema,
CreateTaskResultSchema,
ElicitRequestSchema,
ElicitResultSchema,
EmptyResultSchema,
extractTaskManagerOptions,
GetPromptResultSchema,
InitializeResultSchema,
LATEST_PROTOCOL_VERSION,
@ -65,8 +60,6 @@ import {
SdkErrorCode
} from '@modelcontextprotocol/core';
import { ExperimentalClientTasks } from '../experimental/tasks/client.js';
/**
* Elicitation default application helper. Applies defaults to the `data` based on the `schema`.
*
@ -141,19 +134,11 @@ export function getSupportedElicitationModes(capabilities: ClientCapabilities['e
return { supportsFormMode, supportsUrlMode };
}
/**
* Extended tasks capability that includes runtime configuration (store, messageQueue).
* The runtime-only fields are stripped before advertising capabilities to servers.
*/
export type ClientTasksCapabilityWithRuntime = NonNullable<ClientCapabilities['tasks']> & TaskManagerOptions;
export type ClientOptions = ProtocolOptions & {
/**
* Capabilities to advertise as being supported by this client.
*/
capabilities?: Omit<ClientCapabilities, 'tasks'> & {
tasks?: ClientTasksCapabilityWithRuntime;
};
capabilities?: ClientCapabilities;
/**
* JSON Schema validator for tool output validation.
@ -230,9 +215,6 @@ export class Client extends Protocol<ClientContext> {
private _instructions?: string;
private _jsonSchemaValidator: jsonSchemaValidator;
private _cachedToolOutputValidators: Map<string, JsonSchemaValidator<unknown>> = new Map();
private _cachedKnownTaskTools: Set<string> = new Set();
private _cachedRequiredTaskTools: Set<string> = new Set();
private _experimental?: { tasks: ExperimentalClientTasks };
private _listChangedDebounceTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
private _pendingListChangedConfig?: ListChangedHandlers;
private _enforceStrictCapabilities: boolean;
@ -244,22 +226,11 @@ export class Client extends Protocol<ClientContext> {
private _clientInfo: Implementation,
options?: ClientOptions
) {
super({
...options,
tasks: extractTaskManagerOptions(options?.capabilities?.tasks)
});
super(options);
this._capabilities = options?.capabilities ? { ...options.capabilities } : {};
this._jsonSchemaValidator = options?.jsonSchemaValidator ?? new DefaultJsonSchemaValidator();
this._enforceStrictCapabilities = options?.enforceStrictCapabilities ?? false;
// Strip runtime-only fields from advertised capabilities
if (options?.capabilities?.tasks) {
// eslint-disable-next-line @typescript-eslint/no-unused-vars
const { taskStore, taskMessageQueue, defaultTaskPollInterval, maxTaskQueueSize, ...wireCapabilities } =
options.capabilities.tasks;
this._capabilities.tasks = wireCapabilities;
}
// Store list changed config for setup after connection (when we know server capabilities)
if (options?.listChanged) {
this._pendingListChangedConfig = options.listChanged;
@ -299,22 +270,6 @@ export class Client extends Protocol<ClientContext> {
}
}
/**
* Access experimental features.
*
* WARNING: These APIs are experimental and may change without notice.
*
* @experimental
*/
get experimental(): { tasks: ExperimentalClientTasks } {
if (!this._experimental) {
this._experimental = {
tasks: new ExperimentalClientTasks(this)
};
}
return this._experimental;
}
/**
* Registers new capabilities. This can only be called before connecting to a transport.
*
@ -360,20 +315,6 @@ export class Client extends Protocol<ClientContext> {
const result = await handler(request, ctx);
// When task creation is requested, validate and return CreateTaskResult
if (params.task) {
const taskValidationResult = parseSchema(CreateTaskResultSchema, result);
if (!taskValidationResult.success) {
const errorMessage =
taskValidationResult.error instanceof Error
? taskValidationResult.error.message
: String(taskValidationResult.error);
throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid task creation result: ${errorMessage}`);
}
return taskValidationResult.data;
}
// For non-task requests, validate against ElicitResultSchema
const validationResult = parseSchema(ElicitResultSchema, result);
if (!validationResult.success) {
// Type guard: if success is false, error is guaranteed to exist
@ -416,20 +357,6 @@ export class Client extends Protocol<ClientContext> {
const result = await handler(request, ctx);
// When task creation is requested, validate and return CreateTaskResult
if (params.task) {
const taskValidationResult = parseSchema(CreateTaskResultSchema, result);
if (!taskValidationResult.success) {
const errorMessage =
taskValidationResult.error instanceof Error
? taskValidationResult.error.message
: String(taskValidationResult.error);
throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid task creation result: ${errorMessage}`);
}
return taskValidationResult.data;
}
// For non-task requests, validate against appropriate schema based on tools presence
const hasTools = params.tools || params.toolChoice;
const resultSchema = hasTools ? CreateMessageResultWithToolsSchema : CreateMessageResultSchema;
const validationResult = parseSchema(resultSchema, result);
@ -701,14 +628,6 @@ export class Client extends Protocol<ClientContext> {
}
}
protected assertTaskCapability(method: string): void {
assertToolsCallTaskCapability(this._serverCapabilities?.tasks?.requests, method, 'Server');
}
protected assertTaskHandlerCapability(method: string): void {
assertClientRequestTaskCapability(this._capabilities?.tasks?.requests, method, 'Client');
}
async ping(options?: RequestOptions) {
return this._requestWithSchema({ method: 'ping' }, EmptyResultSchema, options);
}
@ -828,8 +747,6 @@ export class Client extends Protocol<ClientContext> {
* a problem), and thrown {@linkcode ProtocolError} for protocol-level failures or {@linkcode SdkError} for
* SDK-level issues (timeouts, missing capabilities).
*
* For task-based execution with streaming behavior, use {@linkcode ExperimentalClientTasks.callToolStream | client.experimental.tasks.callToolStream()} instead.
*
* @example Basic usage
* ```ts source="./client.examples.ts#Client_callTool_basic"
* const result = await client.callTool({
@ -860,14 +777,6 @@ export class Client extends Protocol<ClientContext> {
* ```
*/
async callTool(params: CallToolRequest['params'], options?: RequestOptions) {
// Guard: required-task tools need experimental API
if (this.isToolTaskRequired(params.name)) {
throw new ProtocolError(
ProtocolErrorCode.InvalidRequest,
`Tool "${params.name}" requires task-based execution. Use client.experimental.tasks.callToolStream() instead.`
);
}
const result = await this._requestWithSchema({ method: 'tools/call', params }, CallToolResultSchema, options);
// Check if the tool has an outputSchema
@ -908,30 +817,12 @@ export class Client extends Protocol<ClientContext> {
return result;
}
private isToolTask(toolName: string): boolean {
if (!this._serverCapabilities?.tasks?.requests?.tools?.call) {
return false;
}
return this._cachedKnownTaskTools.has(toolName);
}
/**
* Check if a tool requires task-based execution.
* Unlike {@linkcode isToolTask} which includes `'optional'` tools, this only checks for `'required'`.
*/
private isToolTaskRequired(toolName: string): boolean {
return this._cachedRequiredTaskTools.has(toolName);
}
/**
* Cache validators for tool output schemas.
* Called after {@linkcode listTools | listTools()} to pre-compile validators for better performance.
*/
private cacheToolMetadata(tools: Tool[]): void {
this._cachedToolOutputValidators.clear();
this._cachedKnownTaskTools.clear();
this._cachedRequiredTaskTools.clear();
for (const tool of tools) {
// If the tool has an outputSchema, create and cache the validator
@ -939,15 +830,6 @@ export class Client extends Protocol<ClientContext> {
const toolValidator = this._jsonSchemaValidator.getValidator(tool.outputSchema as JsonSchemaType);
this._cachedToolOutputValidators.set(tool.name, toolValidator);
}
// If the tool supports task-based execution, cache that information
const taskSupport = tool.execution?.taskSupport;
if (taskSupport === 'required' || taskSupport === 'optional') {
this._cachedKnownTaskTools.add(tool.name);
}
if (taskSupport === 'required') {
this._cachedRequiredTaskTools.add(tool.name);
}
}
}

2
packages/client/src/client/streamableHttp.examples.ts
View file

@ -18,7 +18,7 @@ declare const platformBackgroundTask: {
};
/**
* Example: Using a platform background-task API to schedule reconnections.
* Example: Using a platform background-scheduler API to schedule reconnections.
*/
function ReconnectionScheduler_basicUsage() {
//#region ReconnectionScheduler_basicUsage

13
packages/client/src/experimental/index.ts
View file

@ -1,13 +0,0 @@
/**
* Experimental MCP SDK features.
* WARNING: These APIs are experimental and may change without notice.
*
* Import experimental features from this module:
* ```typescript
* import { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';
* ```
*
* @experimental
*/
export * from './tasks/client.js';

70
packages/client/src/experimental/tasks/client.examples.ts
View file

@ -1,70 +0,0 @@
/**
* Type-checked examples for `client.ts`.
*
* These examples are synced into JSDoc comments via the sync-snippets script.
* Each function's region markers define the code snippet that appears in the docs.
*
* @module
*/
import type { RequestOptions } from '@modelcontextprotocol/core';
import type { Client } from '../../client/client.js';
/**
* Example: Using callToolStream to execute a tool with task lifecycle events.
*/
async function ExperimentalClientTasks_callToolStream(client: Client) {
//#region ExperimentalClientTasks_callToolStream
const stream = client.experimental.tasks.callToolStream({ name: 'myTool', arguments: {} });
for await (const message of stream) {
switch (message.type) {
case 'taskCreated': {
console.log('Tool execution started:', message.task.taskId);
break;
}
case 'taskStatus': {
console.log('Tool status:', message.task.status);
break;
}
case 'result': {
console.log('Tool result:', message.result);
break;
}
case 'error': {
console.error('Tool error:', message.error);
break;
}
}
}
//#endregion ExperimentalClientTasks_callToolStream
}
/**
* Example: Using requestStream to consume task lifecycle events for any request type.
*/
async function ExperimentalClientTasks_requestStream(client: Client, options: RequestOptions) {
//#region ExperimentalClientTasks_requestStream
const stream = client.experimental.tasks.requestStream({ method: 'tools/call', params: { name: 'my-tool', arguments: {} } }, options);
for await (const message of stream) {
switch (message.type) {
case 'taskCreated': {
console.log('Task created:', message.task.taskId);
break;
}
case 'taskStatus': {
console.log('Task status:', message.task.status);
break;
}
case 'result': {
console.log('Final result:', message.result);
break;
}
case 'error': {
console.error('Error:', message.error);
break;
}
}
}
//#endregion ExperimentalClientTasks_requestStream
}

277
packages/client/src/experimental/tasks/client.ts
View file

@ -1,277 +0,0 @@
/**
* Experimental client task features for MCP SDK.
* WARNING: These APIs are experimental and may change without notice.
*
* @experimental
*/
import type {
AnyObjectSchema,
CallToolRequest,
CallToolResult,
CancelTaskResult,
CreateTaskResult,
GetTaskPayloadResult,
GetTaskResult,
ListTasksResult,
Request,
RequestMethod,
RequestOptions,
ResponseMessage,
ResultTypeMap
} from '@modelcontextprotocol/core';
import {
CallToolResultSchema,
getResultSchema,
GetTaskPayloadResultSchema,
ProtocolError,
ProtocolErrorCode
} from '@modelcontextprotocol/core';
import type { Client } from '../../client/client.js';
/**
* Internal interface for accessing {@linkcode Client}'s private methods.
* @internal
*/
interface ClientInternal {
isToolTask(toolName: string): boolean;
getToolOutputValidator(toolName: string): ((data: unknown) => { valid: boolean; errorMessage?: string }) | undefined;
}
/**
* Experimental task features for MCP clients.
*
* Access via `client.experimental.tasks`:
* ```typescript
* const stream = client.experimental.tasks.callToolStream({ name: 'tool', arguments: {} });
* const task = await client.experimental.tasks.getTask(taskId);
* ```
*
* @experimental
*/
export class ExperimentalClientTasks {
constructor(private readonly _client: Client) {}
private get _module() {
return this._client.taskManager;
}
/**
* Calls a tool and returns an AsyncGenerator that yields response messages.
* The generator is guaranteed to end with either a `'result'` or `'error'` message.
*
* This method provides streaming access to tool execution, allowing you to
* observe intermediate task status updates for long-running tool calls.
* Automatically validates structured output if the tool has an `outputSchema`.
*
* @example
* ```ts source="./client.examples.ts#ExperimentalClientTasks_callToolStream"
* const stream = client.experimental.tasks.callToolStream({ name: 'myTool', arguments: {} });
* for await (const message of stream) {
* switch (message.type) {
* case 'taskCreated': {
* console.log('Tool execution started:', message.task.taskId);
* break;
* }
* case 'taskStatus': {
* console.log('Tool status:', message.task.status);
* break;
* }
* case 'result': {
* console.log('Tool result:', message.result);
* break;
* }
* case 'error': {
* console.error('Tool error:', message.error);
* break;
* }
* }
* }
* ```
*
* @param params - Tool call parameters (name and arguments)
* @param options - Optional request options (timeout, signal, task creation params, etc.)
* @returns AsyncGenerator that yields {@linkcode ResponseMessage} objects
*
* @experimental
*/
async *callToolStream(
params: CallToolRequest['params'],
options?: RequestOptions
): AsyncGenerator<ResponseMessage<CallToolResult | CreateTaskResult>, void, void> {
// Access Client's internal methods
const clientInternal = this._client as unknown as ClientInternal;
// Add task creation parameters if server supports it and not explicitly provided
const optionsWithTask = {
...options,
// We check if the tool is known to be a task during auto-configuration, but assume
// the caller knows what they're doing if they pass this explicitly
task: options?.task ?? (clientInternal.isToolTask(params.name) ? {} : undefined)
};
const stream = this._module.requestStream({ method: 'tools/call', params }, CallToolResultSchema, optionsWithTask);
// Get the validator for this tool (if it has an output schema)
const validator = clientInternal.getToolOutputValidator(params.name);
// Iterate through the stream and validate the final result if needed
for await (const message of stream) {
// If this is a result message and the tool has an output schema, validate it
// Only validate CallToolResult (has 'content'), not CreateTaskResult (has 'task')
if (message.type === 'result' && validator && 'content' in message.result) {
const result = message.result as CallToolResult;
// If tool has outputSchema, it MUST return structuredContent (unless it's an error)
if (!result.structuredContent && !result.isError) {
yield {
type: 'error',
error: new ProtocolError(
ProtocolErrorCode.InvalidRequest,
`Tool ${params.name} has an output schema but did not return structured content`
)
};
return;
}
// Only validate structured content if present (not when there's an error)
if (result.structuredContent) {
try {
// Validate the structured content against the schema
const validationResult = validator(result.structuredContent);
if (!validationResult.valid) {
yield {
type: 'error',
error: new ProtocolError(
ProtocolErrorCode.InvalidParams,
`Structured content does not match the tool's output schema: ${validationResult.errorMessage}`
)
};
return;
}
} catch (error) {
if (error instanceof ProtocolError) {
yield { type: 'error', error };
return;
}
yield {
type: 'error',
error: new ProtocolError(
ProtocolErrorCode.InvalidParams,
`Failed to validate structured content: ${error instanceof Error ? error.message : String(error)}`
)
};
return;
}
}
}
// Yield the message (either validated result or any other message type)
yield message;
}
}
/**
* Gets the current status of a task.
*
* @param taskId - The task identifier
* @param options - Optional request options
* @returns The task status
*
* @experimental
*/
async getTask(taskId: string, options?: RequestOptions): Promise<GetTaskResult> {
return this._module.getTask({ taskId }, options);
}
/**
* Retrieves the result of a completed task.
*
* @param taskId - The task identifier
* @param options - Optional request options
* @returns The task result. The payload structure matches the result type of the
* original request (e.g., a `tools/call` task returns a `CallToolResult`).
*
* @experimental
*/
async getTaskResult(taskId: string, options?: RequestOptions): Promise<GetTaskPayloadResult> {
return this._module.getTaskResult({ taskId }, GetTaskPayloadResultSchema, options);
}
/**
* Lists tasks with optional pagination.
*
* @param cursor - Optional pagination cursor
* @param options - Optional request options
* @returns List of tasks with optional next cursor
*
* @experimental
*/
async listTasks(cursor?: string, options?: RequestOptions): Promise<ListTasksResult> {
return this._module.listTasks(cursor ? { cursor } : undefined, options);
}
/**
* Cancels a running task.
*
* @param taskId - The task identifier
* @param options - Optional request options
*
* @experimental
*/
async cancelTask(taskId: string, options?: RequestOptions): Promise<CancelTaskResult> {
return this._module.cancelTask({ taskId }, options);
}
/**
* Sends a request and returns an AsyncGenerator that yields response messages.
* The generator is guaranteed to end with either a `'result'` or `'error'` message.
*
* This method provides streaming access to request processing, allowing you to
* observe intermediate task status updates for task-augmented requests.
*
* @example
* ```ts source="./client.examples.ts#ExperimentalClientTasks_requestStream"
* const stream = client.experimental.tasks.requestStream({ method: 'tools/call', params: { name: 'my-tool', arguments: {} } }, options);
* for await (const message of stream) {
* switch (message.type) {
* case 'taskCreated': {
* console.log('Task created:', message.task.taskId);
* break;
* }
* case 'taskStatus': {
* console.log('Task status:', message.task.status);
* break;
* }
* case 'result': {
* console.log('Final result:', message.result);
* break;
* }
* case 'error': {
* console.error('Error:', message.error);
* break;
* }
* }
* }
* ```
*
* @param request - The request to send
* @param options - Optional request options (timeout, signal, task creation params, etc.)
* @returns AsyncGenerator that yields {@linkcode ResponseMessage} objects
*
* @experimental
*/
requestStream<M extends RequestMethod>(
request: { method: M; params?: Record<string, unknown> },
options?: RequestOptions
): AsyncGenerator<ResponseMessage<ResultTypeMap[M]>, void, void> {
const resultSchema = getResultSchema(request.method) as unknown as AnyObjectSchema;
return this._module.requestStream(request as Request, resultSchema, options) as AsyncGenerator<
ResponseMessage<ResultTypeMap[M]>,
void,
void
>;
}
}

3
packages/client/src/index.ts
View file

@ -71,9 +71,6 @@ export type {
} from './client/streamableHttp.js';
export { StreamableHTTPClientTransport } from './client/streamableHttp.js';
// experimental exports
export { ExperimentalClientTasks } from './experimental/tasks/client.js';
// runtime-aware wrapper (shadows core/public's fromJsonSchema with optional validator)
export { fromJsonSchema } from './fromJsonSchema.js';