Merge branch 'main' into feature/example-decorators

Author: KKonstantinov

.changeset/fix-failed-task-result-retrieval.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+Fix `requestStream` to call `tasks/result` for failed tasks instead of yielding a hardcoded `ProtocolError`. When a task reaches the `failed` terminal status, the stream now retrieves and yields the actual stored result (matching the behavior for `completed` tasks), as required by the spec.

README.md

@@ -14,7 +14,7 @@
 - [Overview](#overview)
 - [Packages](#packages)
 - [Installation](#installation)
-- [Quick Start (runnable examples)](#quick-start-runnable-examples)
+- [Getting Started](#getting-started)
 - [Documentation](#documentation)
 - [Contributing](#contributing)
 - [License](#license)
@@ -90,59 +90,53 @@ npm install @modelcontextprotocol/express express
 npm install @modelcontextprotocol/hono hono
 ```
 
-## Quick Start (runnable examples)
+## Getting Started
 
-The runnable examples live under `examples/` and are kept in sync with the docs.
+Here is what an MCP server looks like. This minimal example exposes a single `greet` tool over stdio:
 
-1. **Install dependencies** (from repo root):
+```typescript
+import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import * as z from 'zod/v4';
 
-```bash
-pnpm install
-```
-
-2. **Run a Streamable HTTP example server**:
-
-```bash
-pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts
-```
+const server = new McpServer({ name: 'greeting-server', version: '1.0.0' });
 
-Alternatively, from within the example package:
+server.registerTool(
+  'greet',
+  {
+    description: 'Greet someone by name',
+    inputSchema: z.object({ name: z.string() }),
+  },
+  async ({ name }) => ({
+    content: [{ type: 'text', text: `Hello, ${name}!` }],
+  }),
+);
 
-```bash
-cd examples/server
-pnpm tsx src/simpleStreamableHttp.ts
-```
-
-3. **Run the interactive client in another terminal**:
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
 
-```bash
-pnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts
+main();
 ```
 
-Alternatively, from within the example package:
+Ready to build something real? Follow the step-by-step quickstart tutorials:
 
-```bash
-cd examples/client
-pnpm tsx src/simpleStreamableHttp.ts
-```
+- [Build a weather server](docs/server-quickstart.md) — server quickstart
+- [Build an LLM-powered chatbot](docs/client-quickstart.md) — client quickstart
 
-Next steps:
+The complete code for each tutorial is in [`examples/server-quickstart/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/server-quickstart/) and [`examples/client-quickstart/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/client-quickstart/). For more advanced runnable examples, see:
 
-- Server examples index: [`examples/server/README.md`](examples/server/README.md)
-- Client examples index: [`examples/client/README.md`](examples/client/README.md)
-- Guided walkthroughs: [`docs/server.md`](docs/server.md) and [`docs/client.md`](docs/client.md)
+- [`examples/server/README.md`](examples/server/README.md) — server examples index
+- [`examples/client/README.md`](examples/client/README.md) — client examples index
 
 ## Documentation
 
-- Local SDK docs:
-    - [docs/server.md](docs/server.md) – building MCP servers: transports, tools, resources, prompts, server-initiated requests, and deployment
-    - [docs/client.md](docs/client.md) – building MCP clients: connecting, tools, resources, prompts, server-initiated requests, and error handling
-    - [docs/faq.md](docs/faq.md) – frequently asked questions and troubleshooting
-- External references:
-    - [SDK API documentation](https://ts.sdk.modelcontextprotocol.io/)
-    - [Model Context Protocol documentation](https://modelcontextprotocol.io)
-    - [MCP Specification](https://spec.modelcontextprotocol.io)
-    - [Example Servers](https://github.com/modelcontextprotocol/servers)
+- [Server Guide](docs/server.md) — building MCP servers: transports, tools, resources, prompts, server-initiated requests, and deployment
+- [Client Guide](docs/client.md) — building MCP clients: connecting, tools, resources, prompts, server-initiated requests, and error handling
+- [FAQ](docs/faq.md) — frequently asked questions and troubleshooting
+- [API docs](https://modelcontextprotocol.github.io/typescript-sdk/)
+- [MCP documentation](https://modelcontextprotocol.io/docs)
+- [MCP specification](https://modelcontextprotocol.io/specification/latest)
 
 ### Building docs locally
 

docs/faq.md

@@ -67,7 +67,7 @@ For production use, you can either:
 
 ### Where can I find runnable server examples?
 
-The SDK ships several runnable server examples under `examples/server/src`. Start from the server examples index in [`examples/server/README.md`](../examples/server/README.md) and the entry-point quick start in the root [`README.md`](../README.md).
+The [server quickstart](./server-quickstart.md) walks you through building a weather server from scratch. Its complete source lives in [`examples/server-quickstart/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/server-quickstart/). For more advanced examples (OAuth, streaming, sessions, etc.), see the server examples index in [`examples/server/README.md`](../examples/server/README.md).
 
 ### Why did we remove `server` auth exports?
 

packages/core/src/shared/taskManager.ts

@@ -302,15 +302,12 @@ export class TaskManager {
 
                 if (isTerminal(task.status)) {
                     switch (task.status) {
-                        case 'completed': {
+                        case 'completed':
+                        case 'failed': {
                             const result = await this.getTaskResult({ taskId }, resultSchema, options);
                             yield { type: 'result', result };
                             break;
                         }
-                        case 'failed': {
-                            yield { type: 'error', error: new ProtocolError(ProtocolErrorCode.InternalError, `Task ${taskId} failed`) };
-                            break;
-                        }
                         case 'cancelled': {
                             yield {
                                 type: 'error',

packages/core/src/types/spec.types.ts

@@ -3,7 +3,7 @@
  *
  * Source: https://github.com/modelcontextprotocol/modelcontextprotocol
  * Pulled from: https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/main/schema/draft/schema.ts
- * Last updated from commit: 838d6f69055f1d14400d67a47eb1d76207c7c34b
+ * Last updated from commit: 5c25208be86db5033f644a4e0d005e08f699ef3d
  *
  * DO NOT EDIT THIS FILE MANUALLY. Changes will be overwritten by automated updates.
  * To update this file, run: pnpm run fetch:spec-types
@@ -1848,6 +1848,7 @@ export interface Task {
 
     /**
      * Actual retention duration from creation in milliseconds, null for unlimited.
+     * @nullable
      */
     ttl: number | null;
 
@@ -2628,6 +2629,8 @@ export interface CompleteResult extends Result {
     completion: {
         /**
          * An array of completion values. Must not exceed 100 items.
+         *
+         * @maxItems 100
          */
         values: string[];
         /**

test/integration/test/taskLifecycle.test.ts

@@ -1502,6 +1502,50 @@ describe('Task Lifecycle Integration Tests', () => {
         });
     });
 
+    describe('callToolStream with failed task', () => {
+        it('should yield stored result (isError: true) when task fails, not a generic ProtocolError', async () => {
+            const client = new Client(
+                {
+                    name: 'test-client',
+                    version: '1.0.0'
+                },
+                {
+                    capabilities: { tasks: {} }
+                }
+            );
+
+            const transport = new StreamableHTTPClientTransport(baseUrl);
+            await client.connect(transport);
+
+            // Use callToolStream with shouldFail: true so the tool stores a failed result
+            const stream = client.experimental.tasks.callToolStream(
+                { name: 'long-task', arguments: { duration: 100, shouldFail: true } },
+                { task: { ttl: 60_000 } }
+            );
+
+            // Collect all stream messages
+            const messages: Array<{ type: string; task?: unknown; result?: unknown; error?: unknown }> = [];
+            for await (const message of stream) {
+                messages.push(message);
+            }
+
+            // First message should be taskCreated
+            expect(messages[0]!.type).toBe('taskCreated');
+
+            // Last message must be 'result' (carrying the stored isError content),
+            // NOT 'error' (which would mean the generic hardcoded ProtocolError was returned)
+            const lastMessage = messages.at(-1)!;
+            expect(lastMessage.type).toBe('result');
+
+            // The stored result should contain isError: true and the real failure content
+            const result = lastMessage.result as { content: Array<{ type: string; text: string }>; isError: boolean };
+            expect(result.isError).toBe(true);
+            expect(result.content).toEqual([{ type: 'text', text: 'Task failed as requested' }]);
+
+            await transport.close();
+        }, 15_000);
+    });
+
     describe('callToolStream with elicitation', () => {
         it('should deliver elicitation via callToolStream and complete task', async () => {
             const client = new Client(