docs: update v1 references to link to hosted V1 API docs (#1584)

.github/workflows/deploy-docs.yml

@@ -0,0 +1,53 @@
+name: Deploy Docs
+
+on:
+    push:
+        branches:
+            - main
+            - v1.x
+    workflow_dispatch:
+
+concurrency:
+    group: deploy-docs
+    cancel-in-progress: true
+
+jobs:
+    deploy-docs:
+        runs-on: ubuntu-latest
+
+        permissions:
+            contents: read
+            pages: write
+            id-token: write
+
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Install pnpm
+              uses: pnpm/action-setup@v4
+              with:
+                  run_install: false
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 24
+                  cache: pnpm
+                  cache-dependency-path: pnpm-lock.yaml
+
+            - name: Generate multi-version docs
+              run: bash scripts/generate-multidoc.sh tmp/docs-combined
+
+            - name: Configure Pages
+              uses: actions/configure-pages@v5
+
+            - name: Upload Pages artifact
+              uses: actions/upload-pages-artifact@v3
+              with:
+                  path: tmp/docs-combined
+
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v4

.github/workflows/main.yml

@@ -109,13 +109,14 @@ jobs:
               env:
                   NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-    # Generates API documentation and deploys to GitHub Pages on any release
+    # Generates API documentation (V1 + V2) and deploys to GitHub Pages on any release
     deploy-docs:
         runs-on: ubuntu-latest
         if: github.event_name == 'release'
         needs: [publish]
 
         permissions:
+            contents: read
             pages: write
             id-token: write
 
@@ -136,14 +137,8 @@ jobs:
                   cache: pnpm
                   cache-dependency-path: pnpm-lock.yaml
 
-            - name: Install dependencies
-              run: pnpm install
-
-            - name: Build packages
-              run: pnpm build:all
-
-            - name: Generate documentation
-              run: pnpm docs
+            - name: Generate multi-version docs
+              run: bash scripts/generate-multidoc.sh tmp/docs-combined
 
             - name: Configure Pages
               uses: actions/configure-pages@v5
@@ -151,7 +146,7 @@ jobs:
             - name: Upload Pages artifact
               uses: actions/upload-pages-artifact@v3
               with:
-                  path: tmp/docs
+                  path: tmp/docs-combined
 
             - name: Deploy to GitHub Pages
               id: deployment

.gitignore

@@ -138,5 +138,8 @@ dist/
 .idea/
 .cursor/
 
+# Git worktrees for local doc generation
+.worktrees/
+
 # Conformance test results
 results/

README.md

@@ -4,7 +4,7 @@
 >
 > We anticipate a stable v2 release in Q1 2026. Until then, **v1.x remains the recommended version** for production use. v1.x will continue to receive bug fixes and security updates for at least 6 months after v2 ships to give people time to upgrade.
 >
-> For v1 documentation and code, see the [`v1.x` branch](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x).
+> For v1 documentation, see the [V1 API docs](https://modelcontextprotocol.github.io/typescript-sdk/). For v2 API docs, see [`/v2/`](https://modelcontextprotocol.github.io/typescript-sdk/v2/).
 
 ![NPM Version](https://img.shields.io/npm/v/%40modelcontextprotocol%2Fserver) ![NPM Version](https://img.shields.io/npm/v/%40modelcontextprotocol%2Fclient) ![MIT licensed](https://img.shields.io/npm/l/%40modelcontextprotocol%2Fserver)
 
@@ -136,10 +136,20 @@ Next steps:
     - [MCP Specification](https://spec.modelcontextprotocol.io)
     - [Example Servers](https://github.com/modelcontextprotocol/servers)
 
+### Building docs locally
+
+To generate the API reference documentation locally:
+
+```bash
+pnpm docs          # Generate V2 docs only (output: tmp/docs/)
+pnpm docs:multi    # Generate combined V1 + V2 docs (output: tmp/docs-combined/)
+```
+
+The `docs:multi` script checks out both the `v1.x` and `main` branches via git worktrees, builds each, and produces a combined site with V1 docs at the root and V2 docs under `/v2/`.
+
 ## v1 (legacy) documentation and fixes
 
-If you are using the **v1** generation of the SDK, the **v1 documentation** (and any v1-specific fixes) live on the long-lived [`v1.x` branch](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x). See:
-[`https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x`](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x).
+If you are using the **v1** generation of the SDK, the **v1 API documentation** is available at [`https://modelcontextprotocol.github.io/typescript-sdk/`](https://modelcontextprotocol.github.io/typescript-sdk/). The v1 source code and any v1-specific fixes live on the long-lived [`v1.x` branch](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x). V2 API docs are at [`/v2/`](https://modelcontextprotocol.github.io/typescript-sdk/v2/).
 
 ## Contributing
 

docs/faq.md

@@ -82,4 +82,4 @@ wanting to switch to `v2` and using SSE should migrate to Streamable HTTP.
 
 ### Where do v1 documentation and v1-specific fixes live?
 
-The v1 generation of this SDK is maintained on the long-lived [`v1.x` branch](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x). If you’re using v1, refer to that branch for documentation and any v1-specific fixes.
+The v1 API documentation is available at [`https://modelcontextprotocol.github.io/typescript-sdk/`](https://modelcontextprotocol.github.io/typescript-sdk/). The v1 source code and any v1-specific fixes live on the long-lived [`v1.x` branch](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x). V2 API docs are at [`/v2/`](https://modelcontextprotocol.github.io/typescript-sdk/v2/).

docs/v2-banner.js

@@ -0,0 +1,9 @@
+document.addEventListener("DOMContentLoaded", function () {
+    var banner = document.createElement("div");
+    banner.innerHTML =
+        "This documents a <strong>pre-release</strong> version of the SDK. Expect breaking changes. For the stable SDK, see the <a href='/'>V1 docs</a>.";
+    banner.style.cssText =
+        "background:#fff3cd;color:#856404;border-bottom:1px solid #ffc107;padding:8px 16px;text-align:center;font-size:14px;";
+    banner.querySelector("a").style.cssText = "color:#856404;text-decoration:underline;";
+    document.body.insertBefore(banner, document.body.firstChild);
+});

package.json

@@ -26,6 +26,7 @@
         "sync:snippets": "tsx scripts/sync-snippets.ts",
         "examples:simple-server:w": "pnpm --filter @modelcontextprotocol/examples-server exec tsx --watch src/simpleStreamableHttp.ts --oauth",
         "docs": "typedoc",
+        "docs:multi": "bash scripts/generate-multidoc.sh",
         "docs:check": "typedoc",
         "typecheck:all": "pnpm -r typecheck",
         "build:all": "pnpm -r build",

scripts/generate-multidoc.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+#
+# Generate combined V1 + V2 TypeDoc documentation.
+#
+# V1 docs (from the v1.x branch) are placed at the root.
+# V2 docs (from main) are placed under /v2/.
+#
+# This script can be run from any branch — it fetches both v1.x and main
+# via git worktrees.
+#
+# Usage:
+#   scripts/generate-multidoc.sh [output-dir]
+#
+# Default output directory: tmp/docs-combined
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+OUTPUT_DIR="${1:-$REPO_ROOT/tmp/docs-combined}"
+V1_WORKTREE="$REPO_ROOT/.worktrees/v1-docs"
+V2_WORKTREE="$REPO_ROOT/.worktrees/v2-docs"
+
+cleanup() {
+    echo "Cleaning up worktrees..."
+    cd "$REPO_ROOT"
+    git worktree remove --force "$V1_WORKTREE" 2>/dev/null || true
+    git worktree remove --force "$V2_WORKTREE" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+rm -rf "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR"
+
+# ---------------------------------------------------------------------------
+# Step 1: Generate V1 docs from v1.x branch
+# ---------------------------------------------------------------------------
+echo "=== Generating V1 docs ==="
+
+git fetch origin v1.x
+
+git worktree remove --force "$V1_WORKTREE" 2>/dev/null || true
+rm -rf "$V1_WORKTREE"
+git worktree add "$V1_WORKTREE" "origin/v1.x" --detach
+
+cd "$V1_WORKTREE"
+npm install
+npm install --save-dev typedoc@^0.28.14
+
+cat > typedoc.json << 'TYPEDOC_EOF'
+{
+  "name": "MCP TypeScript SDK",
+  "entryPoints": [
+    "src/client/index.ts",
+    "src/server/index.ts",
+    "src/shared/protocol.ts",
+    "src/shared/transport.ts",
+    "src/types.ts",
+    "src/inMemory.ts",
+    "src/validation/index.ts",
+    "src/experimental/index.ts"
+  ],
+  "tsconfig": "tsconfig.json",
+  "out": "tmp/docs",
+  "exclude": [
+    "**/*.test.ts",
+    "**/__fixtures__/**",
+    "**/__mocks__/**",
+    "src/examples/**"
+  ],
+  "projectDocuments": [
+    "docs/server.md",
+    "docs/client.md",
+    "docs/capabilities.md",
+    "docs/protocol.md",
+    "docs/faq.md"
+  ],
+  "navigationLinks": {
+    "V2 Docs": "/v2/"
+  },
+  "headings": {
+    "readme": false
+  },
+  "skipErrorChecking": true
+}
+TYPEDOC_EOF
+
+# Rewrite relative .ts links to point to GitHub source instead of media downloads
+V1_GITHUB="https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x"
+sed -i "s|(src/examples/|(${V1_GITHUB}/src/examples/|g" README.md
+sed -i "s|(../src/examples/|(${V1_GITHUB}/src/examples/|g" docs/*.md
+
+npx typedoc
+
+cp -r "$V1_WORKTREE/tmp/docs/"* "$OUTPUT_DIR/"
+
+# ---------------------------------------------------------------------------
+# Step 2: Generate V2 docs from main branch
+# ---------------------------------------------------------------------------
+echo "=== Generating V2 docs ==="
+
+git fetch origin main
+
+git worktree remove --force "$V2_WORKTREE" 2>/dev/null || true
+rm -rf "$V2_WORKTREE"
+git worktree add "$V2_WORKTREE" "origin/main" --detach
+
+cd "$V2_WORKTREE"
+pnpm install
+pnpm -r --filter='./packages/**' build
+
+# Write the V2 pre-release banner script
+cat > docs/v2-banner.js << 'BANNER_EOF'
+document.addEventListener("DOMContentLoaded", function () {
+    var banner = document.createElement("div");
+    banner.innerHTML =
+        "This documents a <strong>pre-release</strong> version of the SDK. Expect breaking changes. For the stable SDK, see the <a href='/'>V1 docs</a>.";
+    banner.style.cssText =
+        "background:#fff3cd;color:#856404;border-bottom:1px solid #ffc107;padding:8px 16px;text-align:center;font-size:14px;";
+    banner.querySelector("a").style.cssText = "color:#856404;text-decoration:underline;";
+    document.body.insertBefore(banner, document.body.firstChild);
+
+
+});
+BANNER_EOF
+
+# Patch the V2 typedoc config to add navigation links, base URL, and banner
+node -e "
+import fs from 'fs';
+const cfg = fs.readFileSync('typedoc.config.mjs', 'utf8');
+const patched = cfg.replace(
+  /export default \{/,
+  \"export default {\\n    hostedBaseUrl: 'https://modelcontextprotocol.github.io/typescript-sdk/v2/',\\n    customJs: 'docs/v2-banner.js',\"
+).replace(
+  /navigation:/,
+  \"navigationLinks: {\\n        'V1 Docs': '/',\\n    },\\n    navigation:\"
+);
+fs.writeFileSync('typedoc.config.mjs', patched);
+"
+
+npx typedoc  # outputs to tmp/docs/ per typedoc.config.mjs
+
+mkdir -p "$OUTPUT_DIR/v2"
+cp -r "$V2_WORKTREE/tmp/docs/"* "$OUTPUT_DIR/v2/"
+
+cd "$REPO_ROOT"
+echo "=== Combined docs generated at $OUTPUT_DIR ==="

typedoc.config.mjs

@@ -24,7 +24,7 @@ console.log(
 
 /** @type {Partial<import("typedoc").TypeDocOptions>} */
 export default {
-    name: 'MCP TypeScript SDK',
+    name: 'MCP TypeScript SDK (V2)',
     entryPointStrategy: 'packages',
     entryPoints,
     packageOptions: {
@@ -33,6 +33,9 @@ export default {
     },
     highlightLanguages: [...OptionDefaults.highlightLanguages, 'powershell'],
     projectDocuments: ['docs/documents.md'],
+    navigationLinks: {
+        'V1 Docs': '/'
+    },
     navigation: {
         compactFolders: true,
         includeFolders: false
@@ -40,6 +43,7 @@ export default {
     headings: {
         readme: false
     },
+    customJs: 'docs/v2-banner.js',
     treatWarningsAsErrors: true,
     out: 'tmp/docs/',
 };