Introduce extension SDK for TS

.github/workflows/ci.yml

@@ -2,19 +2,52 @@ name: CI
 
 on:
   push:
-    branches: [main]
   pull_request:
-    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  check-schema:
+  validate:
+    name: Validate repository
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Check schemas, package, and packed consumers
+        run: npm run check
+      - name: Build documentation
+        run: npm run docs:build
+
+  peer-range:
+    name: Peer range (${{ matrix.client-version }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        client-version: ["2.0.0", "2"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
         with:
           node-version: "24"
-      - run: npm ci
-      - run: npm run check:schema:ts
-      - run: npm run check:schema:json
-      - run: npm run docs:build
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Build package
+        run: npm run build:package
+      - name: Check packed package against client peer endpoint
+        run: npm run check:peer-range -- ${{ matrix.client-version }}

.github/workflows/deploy.yml

@@ -16,21 +16,22 @@ concurrency:
 
 jobs:
   build:
+    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
       - name: Setup Pages
         uses: actions/configure-pages@v4
       - name: Install dependencies
         run: npm ci
+      - name: Validate repository
+        run: npm run check
       - name: Build with VitePress
         run: npm run docs:build
       - name: Upload artifact

.gitignore

@@ -5,6 +5,7 @@ node_modules/
 .claude/
 .jj/
 *.tsbuildinfo
+*.tgz
 dist/
 schema/**/generated/
 .vitepress/cache

.vitepress/config.mts

@@ -12,12 +12,61 @@ export default withMermaid(
       outline: [2, 3],
 
       nav: [
+        { text: "SDK", link: "/typescript/" },
         { text: "SEPs", link: "/seps/2663-tasks-extension" },
         { text: "Specification", link: "/specification/2026-07-28/tasks" },
       ],
 
       sidebar: {
-        "specification/": [
+        "/typescript/": [
+          {
+            text: "Introduction",
+            items: [
+              { text: "Getting started", link: "/typescript/" },
+              {
+                text: "Call your first tool",
+                link: "/typescript/getting-started",
+              },
+              {
+                text: "Migrate from the base SDK",
+                link: "/typescript/migrating-from-the-sdk",
+              },
+            ],
+          },
+          {
+            text: "Clients",
+            items: [
+              {
+                text: "Observe and control execution",
+                link: "/typescript/client/execution",
+              },
+              {
+                text: "Handle input and recover tasks",
+                link: "/typescript/client/input-and-recovery",
+              },
+              {
+                text: "[2025-11-25] Receive sampling and elicitation requests",
+                link: "/typescript/receiver",
+              },
+            ],
+          },
+          {
+            text: "Advanced",
+            items: [
+              {
+                text: "Integrate adapters and schemas",
+                link: "/typescript/adapters-and-schemas",
+              },
+            ],
+          },
+          {
+            text: "Help",
+            items: [
+              { text: "Troubleshooting", link: "/typescript/troubleshooting" },
+            ],
+          },
+        ],
+        "/specification/": [
           {
             text: "Specification",
             items: [
@@ -29,7 +78,7 @@ export default withMermaid(
             ],
           },
         ],
-        "seps/": [
+        "/seps/": [
           {
             text: "SEPs",
             items: [

README.md

@@ -1,24 +1,25 @@
 # MCP Tasks Extension
-This repository contains the official [Model Context Protocol](https://modelcontextprotocol.io) Tasks extension (`io.modelcontextprotocol/tasks`), based on [SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663).
 
-## Overview
+This repository contains the official [Model Context Protocol](https://modelcontextprotocol.io) Tasks extension (`io.modelcontextprotocol/tasks`), based on [SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663).
 
-This extension defines the **Tasks** primitive for the Model Context Protocol (MCP). Tasks are durable state machines that carry information about the underlying execution state of a request, enabling requestor polling and deferred result retrieval. Each task is uniquely identifiable by a receiver-generated **task ID**.
+## Why Tasks?
 
-Tasks are useful for:
+Some MCP requests finish quickly. Others run for minutes, wait for human input, or need to survive a disconnected client. The Tasks extension lets a receiver return a durable task handle so the requester can follow progress and retrieve the result later.
 
-- Representing expensive computations and batch processing requests
-- Integrating seamlessly with external job/workflow APIs
-- Enabling call-now, fetch-later execution patterns
+Use Tasks for long computations, approval workflows, external job systems, and call-now/fetch-later APIs.
 
 **Extension Identifier:** `io.modelcontextprotocol/tasks`
 
+## Use it from TypeScript
+
+The `@modelcontextprotocol/ext-tasks` package provides generation-agnostic requester lifecycle APIs and 2025-11-25 Tasks receiver support. Start with the [TypeScript package guide](https://modelcontextprotocol.github.io/ext-tasks/typescript/) or [call your first task-enabled tool](https://modelcontextprotocol.github.io/ext-tasks/typescript/getting-started.html).
+
 ## Schemas
 
-| Version | Status | TypeScript | JSON Schema |
-| --- | --- | --- | --- |
-| `2026-07-28` | Stable | [`schema.ts`](schema/2026-07-28/schema.ts) | [`schema.json`](schema/2026-07-28/schema.json) |
-| `draft` | Development | [`schema.ts`](schema/draft/schema.ts) | [`schema.json`](schema/draft/schema.json) |
+| Version      | Status      | TypeScript                                 | JSON Schema                                    |
+| ------------ | ----------- | ------------------------------------------ | ---------------------------------------------- |
+| `2026-07-28` | Stable      | [`schema.ts`](schema/2026-07-28/schema.ts) | [`schema.json`](schema/2026-07-28/schema.json) |
+| `draft`      | Development | [`schema.ts`](schema/draft/schema.ts)      | [`schema.json`](schema/draft/schema.json)      |
 
 Released schema directories are immutable snapshots with version-specific JSON Schema identifiers. Development and schema generation target `schema/draft/` only. To create a release snapshot from the current draft:
 
@@ -28,6 +29,23 @@ npm run snapshot:schema -- YYYY-MM-DD
 
 ## Development
 
+### SDK Package
+
+The redistributable package lives in `packages/ext-tasks` and publishes as `@modelcontextprotocol/ext-tasks`.
+
+```bash
+# Run schema, package, and packed-consumer checks
+npm run check
+
+# Run the package tests in watch mode
+npm run test:watch
+
+# Create the publishable tarball
+npm run pack:package
+```
+
+The package intentionally has no root export. Consumers import `/client`, `/receiver`, `/core`, `/core/v1`, or `/core/v2`; the guide explains which entry point owns each workflow.
+
 ### Schema Generation
 
 The draft JSON Schema is auto-generated from the TypeScript type definitions using [ts-to-zod](https://github.com/fabien0102/ts-to-zod) and Zod's `toJSONSchema()`. Do not hand-edit `schema.json` or `generated/schema.ts`.