Merge branch 'main' into improvement/handle-string-expires_in

Author: KKonstantinov

README.md

@@ -26,6 +26,7 @@
     - [Improving Network Efficiency with Notification Debouncing](#improving-network-efficiency-with-notification-debouncing)
     - [Low-Level Server](#low-level-server)
     - [Eliciting User Input](#eliciting-user-input)
+    - [Task-Based Execution](#task-based-execution)
     - [Writing MCP Clients](#writing-mcp-clients)
     - [Proxy Authorization Requests Upstream](#proxy-authorization-requests-upstream)
     - [Backwards Compatibility](#backwards-compatibility)
@@ -38,7 +39,7 @@
 ## Overview
 
 The Model Context Protocol allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. This TypeScript SDK implements
-[the full MCP specification](https://modelcontextprotocol.io/specification/latest), making it easy to:
+[the full MCP specification](https://modelcontextprotocol.io/specification/draft), making it easy to:
 
 - Create MCP servers that expose resources, prompts and tools
 - Build MCP clients that can connect to any MCP server
@@ -158,7 +159,7 @@ const server = new McpServer({
 
 ### Tools
 
-[Tools](https://modelcontextprotocol.io/specification/latest/server/tools) let LLMs take actions through your server. Tools can perform computation, fetch data and have side effects. Tools should be designed to be model-controlled - i.e. AI models will decide which tools to call,
+[Tools](https://modelcontextprotocol.io/specification/draft/server/tools) let LLMs take actions through your server. Tools can perform computation, fetch data and have side effects. Tools should be designed to be model-controlled - i.e. AI models will decide which tools to call,
 and the arguments.
 
 ```typescript
@@ -259,7 +260,7 @@ Tools can return `ResourceLink` objects to reference resources without embedding
 
 ### Resources
 
-[Resources](https://modelcontextprotocol.io/specification/latest/server/resources) can also expose data to LLMs, but unlike tools shouldn't perform significant computation or have side effects.
+[Resources](https://modelcontextprotocol.io/specification/draft/server/resources) can also expose data to LLMs, but unlike tools shouldn't perform significant computation or have side effects.
 
 Resources are designed to be used in an application-driven way, meaning MCP client applications can decide how to expose them. For example, a client could expose a resource picker to the human, or could expose them to the model directly.
 
@@ -333,7 +334,7 @@ server.registerResource(
 
 ### Prompts
 
-[Prompts](https://modelcontextprotocol.io/specification/latest/server/prompts) are reusable templates that help humans prompt models to interact with your server. They're designed to be user-driven, and might appear as slash commands in a chat interface.
+[Prompts](https://modelcontextprotocol.io/specification/draft/server/prompts) are reusable templates that help humans prompt models to interact with your server. They're designed to be user-driven, and might appear as slash commands in a chat interface.
 
 ```typescript
 import { completable } from '@modelcontextprotocol/sdk/server/completable.js';
@@ -625,6 +626,11 @@ app.post('/mcp', async (req, res) => {
     }
 });
 
+// Handle GET requests when session management is not supported - the server must return an HTTP 405 status code in this case
+app.get('/mcp', (req, res) => {
+    res.status(405).end();
+});
+
 const port = parseInt(process.env.PORT || '3000');
 app.listen(port, () => {
     console.log(`MCP Server running on http://localhost:${port}/mcp`);
@@ -1382,6 +1388,206 @@ const client = new Client(
 );
 ```
 
+### Task-Based Execution
+
+> **⚠️ Experimental API**: Task-based execution is an experimental feature and may change without notice. Access these APIs via the `.experimental.tasks` namespace.
+
+Task-based execution enables "call-now, fetch-later" patterns for long-running operations. This is useful for tools that take significant time to complete, where clients may want to disconnect and check on progress or retrieve results later.
+
+Common use cases include:
+
+- Long-running data processing or analysis
+- Code migration or refactoring operations
+- Complex computational tasks
+- Operations that require periodic status updates
+
+#### Server-Side: Implementing Task Support
+
+To enable task-based execution, configure your server with a `TaskStore` implementation. The SDK doesn't provide a built-in TaskStore—you'll need to implement one backed by your database of choice:
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { TaskStore } from '@modelcontextprotocol/sdk/experimental';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+// Implement TaskStore backed by your database (e.g., PostgreSQL, Redis, etc.)
+class MyTaskStore implements TaskStore {
+    async createTask(taskParams, requestId, request, sessionId?): Promise<Task> {
+        // Generate unique taskId and lastUpdatedAt/createdAt timestamps
+        // Store task in your database, using the session ID as a proxy to restrict unauthorized access
+        // Return final Task object
+    }
+
+    async getTask(taskId): Promise<Task | null> {
+        // Retrieve task from your database
+    }
+
+    async updateTaskStatus(taskId, status, statusMessage?): Promise<void> {
+        // Update task status in your database
+    }
+
+    async storeTaskResult(taskId, result): Promise<void> {
+        // Store task result in your database
+    }
+
+    async getTaskResult(taskId): Promise<Result> {
+        // Retrieve task result from your database
+    }
+
+    async listTasks(cursor?, sessionId?): Promise<{ tasks: Task[]; nextCursor?: string }> {
+        // List tasks with pagination support
+    }
+}
+
+const taskStore = new MyTaskStore();
+
+const server = new Server(
+    {
+        name: 'task-enabled-server',
+        version: '1.0.0'
+    },
+    {
+        capabilities: {
+            tools: {},
+            // Declare capabilities
+            tasks: {
+                list: {},
+                cancel: {},
+                requests: {
+                    tools: {
+                        // Declares support for tasks on tools/call
+                        call: {}
+                    }
+                }
+            }
+        },
+        taskStore // Enable task support
+    }
+);
+
+// Register a tool that supports tasks using the experimental API
+server.experimental.tasks.registerToolTask(
+    'my-echo-tool',
+    {
+        title: 'My Echo Tool',
+        description: 'A simple task-based echo tool.',
+        inputSchema: {
+            message: z.string().describe('Message to send')
+        }
+    },
+    {
+        async createTask({ message }, { taskStore, taskRequestedTtl, requestId }) {
+            // Create the task
+            const task = await taskStore.createTask({
+                ttl: taskRequestedTtl
+            });
+
+            // Simulate out-of-band work
+            (async () => {
+                await new Promise(resolve => setTimeout(resolve, 5000));
+                await taskStore.storeTaskResult(task.taskId, 'completed', {
+                    content: [
+                        {
+                            type: 'text',
+                            text: message
+                        }
+                    ]
+                });
+            })();
+
+            // Return CreateTaskResult with the created task
+            return { task };
+        },
+        async getTask(_args, { taskId, taskStore }) {
+            // Retrieve the task
+            return await taskStore.getTask(taskId);
+        },
+        async getTaskResult(_args, { taskId, taskStore }) {
+            // Retrieve the result of the task
+            const result = await taskStore.getTaskResult(taskId);
+            return result as CallToolResult;
+        }
+    }
+);
+```
+
+**Note**: See `src/examples/shared/inMemoryTaskStore.ts` in the SDK source for a reference task store implementation suitable for development and testing.
+
+#### Client-Side: Using Task-Based Execution
+
+Clients use `experimental.tasks.callToolStream()` to initiate task-augmented tool calls. The returned `AsyncGenerator` abstracts automatic polling and status updates:
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const client = new Client({
+    name: 'task-client',
+    version: '1.0.0'
+});
+
+// ... connect to server ...
+
+// Call the tool with task metadata using the experimental streaming API
+const stream = client.experimental.tasks.callToolStream(
+    {
+        name: 'my-echo-tool',
+        arguments: { message: 'Hello, world!' }
+    },
+    CallToolResultSchema
+);
+
+// Iterate the stream and handle stream events
+let taskId = '';
+for await (const message of stream) {
+    switch (message.type) {
+        case 'taskCreated':
+            console.log('Task created successfully with ID:', message.task.taskId);
+            taskId = message.task.taskId;
+            break;
+        case 'taskStatus':
+            console.log(`  ${message.task.status}${message.task.statusMessage ?? ''}`);
+            break;
+        case 'result':
+            console.log('Task completed! Tool result:');
+            message.result.content.forEach(item => {
+                if (item.type === 'text') {
+                    console.log(`  ${item.text}`);
+                }
+            });
+            break;
+        case 'error':
+            throw message.error;
+    }
+}
+
+// Optional: Fire and forget - disconnect and reconnect later
+// (useful when you don't want to wait for long-running tasks)
+// Later, after disconnecting and reconnecting to the server:
+const taskStatus = await client.getTask({ taskId });
+console.log('Task status:', taskStatus.status);
+
+if (taskStatus.status === 'completed') {
+    const taskResult = await client.getTaskResult({ taskId }, CallToolResultSchema);
+    console.log('Retrieved result after reconnect:', taskResult);
+}
+```
+
+The `experimental.tasks.callToolStream()` method also works with non-task tools, making it a drop-in replacement for `callTool()` in applications that support it. When used to invoke a tool that doesn't support tasks, the `taskCreated` and `taskStatus` events will not be emitted.
+
+#### Task Status Lifecycle
+
+Tasks transition through the following states:
+
+- **working**: Task is actively being processed
+- **input_required**: Task is waiting for additional input (e.g., from elicitation)
+- **completed**: Task finished successfully
+- **failed**: Task encountered an error
+- **cancelled**: Task was cancelled by the client
+
+The `ttl` parameter suggests how long the server will manage the task for. If the task duration exceeds this, the server may delete the task prematurely. The client's suggested value may be overridden by the server, and the final TTL will be provided in `Task.ttl` in
+`taskCreated` and `taskStatus` events.
+
 ### Writing MCP Clients
 
 The SDK provides a high-level client interface:

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@modelcontextprotocol/sdk",
-    "version": "1.23.0-beta.0",
+    "version": "1.23.0",
     "description": "Model Context Protocol implementation for TypeScript",
     "license": "MIT",
     "author": "Anthropic, PBC (https://anthropic.com)",
@@ -43,6 +43,14 @@
             "import": "./dist/esm/validation/cfworker-provider.js",
             "require": "./dist/cjs/validation/cfworker-provider.js"
         },
+        "./experimental": {
+            "import": "./dist/esm/experimental/index.js",
+            "require": "./dist/cjs/experimental/index.js"
+        },
+        "./experimental/tasks": {
+            "import": "./dist/esm/experimental/tasks/index.js",
+            "require": "./dist/cjs/experimental/tasks/index.js"
+        },
         "./*": {
             "import": "./dist/esm/*",
             "require": "./dist/cjs/*"

package.json

@@ -625,10 +625,12 @@ export async function discoverOAuthProtectedResourceMetadata(
     });
 
     if (!response || response.status === 404) {
+        await response?.body?.cancel();
         throw new Error(`Resource server does not implement OAuth 2.0 Protected Resource Metadata.`);
     }
 
     if (!response.ok) {
+        await response.body?.cancel();
         throw new Error(`HTTP ${response.status} trying to load well-known OAuth protected resource metadata.`);
     }
     return OAuthProtectedResourceMetadataSchema.parse(await response.json());
@@ -756,10 +758,12 @@ export async function discoverOAuthMetadata(
     });
 
     if (!response || response.status === 404) {
+        await response?.body?.cancel();
         return undefined;
     }
 
     if (!response.ok) {
+        await response.body?.cancel();
         throw new Error(`HTTP ${response.status} trying to load well-known OAuth metadata`);
     }
 
@@ -869,6 +873,7 @@ export async function discoverAuthorizationServerMetadata(
         }
 
         if (!response.ok) {
+            await response.body?.cancel();
             // Continue looking for any 4xx response code.
             if (response.status >= 400 && response.status < 500) {
                 continue; // Try next URL