feat(experimental): Create experimental/tasks module structure

Phase 1-2 of tasks experimental isolation:
- Create src/experimental/tasks/ directory structure
- Move TaskStore, TaskMessageQueue, and related interfaces to experimental/tasks/interfaces.ts
- Add experimental/tasks/types.ts for re-exporting spec types
- Update shared/task.ts to re-export from experimental for backward compatibility
- Add barrel exports for experimental module

All tests pass (1399 tests).

Author: felixweinberger

README.md

@@ -1385,6 +1385,8 @@ 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:
@@ -1400,7 +1402,7 @@ To enable task-based execution, configure your server with a `TaskStore` impleme
 
 ```typescript
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { TaskStore } from '@modelcontextprotocol/sdk/shared/task.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.)
@@ -1458,8 +1460,8 @@ const server = new Server(
     }
 );
 
-// Register a tool that supports tasks
-server.registerToolTask(
+// Register a tool that supports tasks using the experimental API
+server.experimental.tasks.registerToolTask(
     'my-echo-tool',
     {
         title: 'My Echo Tool',
@@ -1508,7 +1510,7 @@ server.registerToolTask(
 
 #### Client-Side: Using Task-Based Execution
 
-Clients use `callToolStream()` to initiate task-augmented tool calls. The returned `AsyncGenerator` abstracts automatic polling and status updates:
+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';
@@ -1521,8 +1523,8 @@ const client = new Client({
 
 // ... connect to server ...
 
-// Call the tool with task metadata using streaming API
-const stream = client.callToolStream(
+// 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!' }
@@ -1566,7 +1568,7 @@ if (taskStatus.status === 'completed') {
 }
 ```
 
-The `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.
+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
 

package.json

@@ -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/*"

src/client/index.test.ts

@@ -26,7 +26,7 @@ import { Transport } from '../shared/transport.js';
 import { Server } from '../server/index.js';
 import { McpServer } from '../server/mcp.js';
 import { InMemoryTransport } from '../inMemory.js';
-import { InMemoryTaskStore, InMemoryTaskMessageQueue } from '../examples/shared/inMemoryTaskStore.js';
+import { InMemoryTaskStore, InMemoryTaskMessageQueue } from '../experimental/tasks/stores/in-memory.js';
 import * as z3 from 'zod/v3';
 import * as z4 from 'zod/v4';
 
@@ -1818,7 +1818,7 @@ describe('Task-based execution', () => {
                 }
             );
 
-            server.registerToolTask(
+            server.experimental.tasks.registerToolTask(
                 'test-tool',
                 {
                     description: 'A test tool',
@@ -1868,7 +1868,7 @@ describe('Task-based execution', () => {
             });
 
             // Verify task was created successfully by listing tasks
-            const taskList = await client.listTasks();
+            const taskList = await client.experimental.tasks.listTasks();
             expect(taskList.tasks.length).toBeGreaterThan(0);
             const task = taskList.tasks[0];
             expect(task.status).toBe('completed');
@@ -1894,7 +1894,7 @@ describe('Task-based execution', () => {
                 }
             );
 
-            server.registerToolTask(
+            server.experimental.tasks.registerToolTask(
                 'test-tool',
                 {
                     description: 'A test tool',
@@ -1942,7 +1942,7 @@ describe('Task-based execution', () => {
             });
 
             // Query task status by listing tasks and getting the first one
-            const taskList = await client.listTasks();
+            const taskList = await client.experimental.tasks.listTasks();
             expect(taskList.tasks.length).toBeGreaterThan(0);
             const task = taskList.tasks[0];
             expect(task).toBeDefined();
@@ -1971,7 +1971,7 @@ describe('Task-based execution', () => {
                 }
             );
 
-            server.registerToolTask(
+            server.experimental.tasks.registerToolTask(
                 'test-tool',
                 {
                     description: 'A test tool',
@@ -2015,7 +2015,7 @@ describe('Task-based execution', () => {
 
             // Create a task using callToolStream to capture the task ID
             let taskId: string | undefined;
-            const stream = client.callToolStream({ name: 'test-tool', arguments: {} }, CallToolResultSchema, {
+            const stream = client.experimental.tasks.callToolStream({ name: 'test-tool', arguments: {} }, CallToolResultSchema, {
                 task: { ttl: 60000 }
             });
 
@@ -2028,7 +2028,7 @@ describe('Task-based execution', () => {
             expect(taskId).toBeDefined();
 
             // Query task result using the captured task ID
-            const result = await client.getTaskResult({ taskId: taskId! }, CallToolResultSchema);
+            const result = await client.experimental.tasks.getTaskResult(taskId!, CallToolResultSchema);
             expect(result.content).toEqual([{ type: 'text', text: 'Result data!' }]);
         });
 
@@ -2052,7 +2052,7 @@ describe('Task-based execution', () => {
                 }
             );
 
-            server.registerToolTask(
+            server.experimental.tasks.registerToolTask(
                 'test-tool',
                 {
                     description: 'A test tool',
@@ -2103,15 +2103,15 @@ describe('Task-based execution', () => {
                 });
 
                 // Get the task ID from the task list
-                const taskList = await client.listTasks();
+                const taskList = await client.experimental.tasks.listTasks();
                 const newTask = taskList.tasks.find(t => !createdTaskIds.includes(t.taskId));
                 if (newTask) {
                     createdTaskIds.push(newTask.taskId);
                 }
             }
 
             // Query task list
-            const taskList = await client.listTasks();
+            const taskList = await client.experimental.tasks.listTasks();
             expect(taskList.tasks.length).toBeGreaterThanOrEqual(2);
             for (const taskId of createdTaskIds) {
                 expect(taskList.tasks).toContainEqual(
@@ -2224,7 +2224,7 @@ describe('Task-based execution', () => {
             const taskId = createTaskResult.task.taskId;
 
             // Verify task was created
-            const task = await server.getTask({ taskId });
+            const task = await server.experimental.tasks.getTask(taskId);
             expect(task.status).toBe('completed');
         });
 
@@ -2314,7 +2314,7 @@ describe('Task-based execution', () => {
             const taskId = createTaskResult.task.taskId;
 
             // Query task status
-            const task = await server.getTask({ taskId });
+            const task = await server.experimental.tasks.getTask(taskId);
             expect(task).toBeDefined();
             expect(task.taskId).toBe(taskId);
             expect(task.status).toBe('completed');
@@ -2406,7 +2406,7 @@ describe('Task-based execution', () => {
             const taskId = createTaskResult.task.taskId;
 
             // Query task result using getTaskResult
-            const taskResult = await server.getTaskResult({ taskId }, ElicitResultSchema);
+            const taskResult = await server.experimental.tasks.getTaskResult(taskId, ElicitResultSchema);
             expect(taskResult.action).toBe('accept');
             expect(taskResult.content).toEqual({ username: 'result-user' });
         });
@@ -2500,7 +2500,7 @@ describe('Task-based execution', () => {
             }
 
             // Query task list
-            const taskList = await server.listTasks();
+            const taskList = await server.experimental.tasks.listTasks();
             expect(taskList.tasks.length).toBeGreaterThanOrEqual(2);
             for (const taskId of createdTaskIds) {
                 expect(taskList.tasks).toContainEqual(
@@ -2535,7 +2535,7 @@ describe('Task-based execution', () => {
             }
         );
 
-        server.registerToolTask(
+        server.experimental.tasks.registerToolTask(
             'test-tool',
             {
                 description: 'A test tool',
@@ -2601,21 +2601,21 @@ describe('Task-based execution', () => {
             });
 
             // Get the task ID from the task list
-            const taskList = await client.listTasks();
+            const taskList = await client.experimental.tasks.listTasks();
             const newTask = taskList.tasks.find(t => !createdTaskIds.includes(t.taskId));
             if (newTask) {
                 createdTaskIds.push(newTask.taskId);
             }
         }
 
         // List all tasks without cursor
-        const firstPage = await client.listTasks();
+        const firstPage = await client.experimental.tasks.listTasks();
         expect(firstPage.tasks.length).toBeGreaterThan(0);
         expect(firstPage.tasks.map(t => t.taskId)).toEqual(expect.arrayContaining(createdTaskIds));
 
         // If there's a cursor, test pagination
         if (firstPage.nextCursor) {
-            const secondPage = await client.listTasks({ cursor: firstPage.nextCursor });
+            const secondPage = await client.experimental.tasks.listTasks(firstPage.nextCursor);
             expect(secondPage.tasks).toBeDefined();
         }
 
@@ -2680,7 +2680,7 @@ describe('Task-based execution', () => {
             await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
 
             // Try to get a task that doesn't exist
-            await expect(client.getTask({ taskId: 'non-existent-task' })).rejects.toThrow();
+            await expect(client.experimental.tasks.getTask('non-existent-task')).rejects.toThrow();
         });
 
         test('should throw error when querying result of non-existent task from server', async () => {
@@ -2727,7 +2727,7 @@ describe('Task-based execution', () => {
             await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
 
             // Try to get result of a task that doesn't exist
-            await expect(client.getTaskResult({ taskId: 'non-existent-task' }, CallToolResultSchema)).rejects.toThrow();
+            await expect(client.experimental.tasks.getTaskResult('non-existent-task', CallToolResultSchema)).rejects.toThrow();
         });
 
         test('should throw error when server queries non-existent task from client', async () => {
@@ -2779,7 +2779,7 @@ describe('Task-based execution', () => {
             await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
 
             // Try to query a task that doesn't exist on client
-            await expect(server.getTask({ taskId: 'non-existent-task' })).rejects.toThrow();
+            await expect(server.experimental.tasks.getTask('non-existent-task')).rejects.toThrow();
         });
     });
 });
@@ -2805,7 +2805,7 @@ test('should respect server task capabilities', async () => {
         }
     );
 
-    server.registerToolTask(
+    server.experimental.tasks.registerToolTask(
         'test-tool',
         {
             description: 'A test tool',
@@ -2871,7 +2871,7 @@ test('should respect server task capabilities', async () => {
             task: { ttl: 60000 }
         })
     ).resolves.not.toThrow();
-    await expect(client.listTasks()).resolves.not.toThrow();
+    await expect(client.experimental.tasks.listTasks()).resolves.not.toThrow();
 
     // tools/list doesn't support task creation, but it shouldn't throw - it should just ignore the task metadata
     await expect(
@@ -2928,7 +2928,7 @@ test('should expose requestStream() method for streaming responses', async () =>
     expect(regularResult.content).toEqual([{ type: 'text', text: 'Tool result' }]);
 
     // Test requestStream with non-task request (should yield only result)
-    const stream = client.requestStream(
+    const stream = client.experimental.tasks.requestStream(
         {
             method: 'tools/call',
             params: { name: 'test-tool', arguments: {} }
@@ -2989,7 +2989,7 @@ test('should expose callToolStream() method for streaming tool calls', async ()
     await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
 
     // Test callToolStream
-    const stream = client.callToolStream({ name: 'test-tool', arguments: {} });
+    const stream = client.experimental.tasks.callToolStream({ name: 'test-tool', arguments: {} });
 
     const messages = [];
     for await (const message of stream) {
@@ -3070,7 +3070,7 @@ test('should validate structured output in callToolStream()', async () => {
     await client.listTools();
 
     // Test callToolStream with valid structured output
-    const stream = client.callToolStream({ name: 'structured-tool', arguments: {} });
+    const stream = client.experimental.tasks.callToolStream({ name: 'structured-tool', arguments: {} });
 
     const messages = [];
     for await (const message of stream) {