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

.github/workflows/npm-publish.yml

@@ -0,0 +1,127 @@
+# Publishes the @modelcontextprotocol/ext-tasks package to npm when a GitHub
+# Release is published. Versioning is manual: bump packages/ext-tasks/package.json
+# in the release commit, then cut the GitHub Release from that tag — this workflow
+# picks it up from there.
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate before publishing
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    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
+      # Full gate: schema provenance, format, lint, typecheck, tests, build, and
+      # the packed-consumer check. Runs again here rather than trusting CI, so a
+      # publish can never proceed from a commit CI hasn't fully validated.
+      - name: Check schemas, package, and packed consumers
+        run: npm run check
+      - name: Build documentation
+        run: npm run docs:build
+
+  publish:
+    name: Publish
+    needs: validate
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+          registry-url: "https://registry.npmjs.org"
+      - name: Install dependencies
+        run: npm ci
+      # Node 24's bundled npm satisfies the >= 11.5.1 OIDC requirement only from
+      # ~24.6 onward; pin explicitly so the publish never depends on which Node
+      # patch the runner resolves.
+      - name: Ensure npm CLI supports OIDC trusted publishing
+        run: npm install -g npm@11.5.1
+      # The tag is compared to the manifest before anything reaches npm, because
+      # a release cut from the wrong commit (or tagged with the wrong version)
+      # would otherwise publish a version that does not match its tag.
+      - name: Validate release tag against package.json
+        env:
+          # Passed through env rather than interpolated into the script,
+          # so a tag name can never be evaluated as shell syntax.
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          VERSION=$(node -p "require('./packages/ext-tasks/package.json').version")
+          if [[ "${RELEASE_TAG#v}" != "$VERSION" ]]; then
+            echo "Release tag ${RELEASE_TAG} does not match package.json version ${VERSION}."
+            exit 1
+          fi
+      - name: Determine npm dist-tag
+        id: npm-tag
+        run: |
+          VERSION=$(node -p "require('./packages/ext-tasks/package.json').version")
+          # Pre-release versions publish under the beta dist-tag.
+          if [[ "$VERSION" == *"-"* ]]; then
+            echo "tag=--tag beta" >> "$GITHUB_OUTPUT"
+          # Releases cut from a non-main branch (patch/maintenance lines) publish
+          # under release-X.Y so they never displace latest.
+          elif [[ "${{ github.event.release.target_commitish }}" != "main" ]]; then
+            MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1,2)
+            echo "tag=--tag release-${MAJOR_MINOR}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Publish to npm
+        run: npm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
+        working-directory: packages/ext-tasks
+        env:
+          NPM_CONFIG_PROVENANCE: "true"
+
+  verify:
+    name: Verify published package
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+      - name: Wait for npm to serve the version
+        run: |
+          VERSION=$(node -p "require('./packages/ext-tasks/package.json').version")
+          for i in $(seq 1 30); do
+            if npm view "@modelcontextprotocol/ext-tasks@${VERSION}" version >/dev/null 2>&1; then
+              echo "npm is serving ${VERSION}."
+              exit 0
+            fi
+            echo "Not visible yet (attempt ${i}/30); waiting 10s..."
+            sleep 10
+          done
+          echo "npm never served ${VERSION} within 5 minutes of publishing."
+          exit 1

.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`.