ci: use npm ci with caching, validate typedoc links, align Node versions (#533)

- Switch npm install -> npm ci in ci.yml (build, build-wsl) and docs.yml
  to fail on lockfile drift rather than silently tolerating it
- Add cache: npm to all setup-node steps that have a lockfile to hash
  (skipped test-git-install which has no checkout, and WSL which has no
  setup-node action)
- Add TypeDoc link validation step after build (Linux x64 only, matching
  existing single-OS gate pattern for MCPB). Verified passing on main.
- Align all workflows on Node 22 (active LTS) — previously CI used 20
  but publish workflows used 22, so releases were tested on a different
  Node than PRs
- Add engines.node >=20 to package.json so consumers on Node 18 get a
  warning

.github/workflows/ci.yml

@@ -24,7 +24,8 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version: "20"
+          node-version: "22"
+          cache: npm
 
       - run: npm ci
 
@@ -71,12 +72,17 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version: "20"
+          node-version: "22"
+          cache: npm
 
-      - run: npm install
+      - run: npm ci
 
       - run: npm run build
 
+      - name: Validate TypeDoc links
+        if: runner.os == 'Linux' && matrix.name == 'Linux x64'
+        run: npm exec typedoc -- --treatValidationWarningsAsErrors --emit none
+
       - run: npm run examples:build
 
       - name: Verify generated schemas are up-to-date
@@ -111,7 +117,8 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version: "20"
+          node-version: "22"
+          cache: npm
 
       - uses: astral-sh/setup-uv@v7
 
@@ -147,13 +154,13 @@ jobs:
         shell: wsl-bash {0}
         run: |
           sudo apt-get update
-          curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+          curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
           sudo apt-get install -y nodejs
 
       - name: Build and test in WSL
         shell: wsl-bash {0}
         run: |
-          npm install
+          npm ci
           npm run build
           npm run examples:build
           npm test
@@ -182,7 +189,7 @@ jobs:
     steps:
       - uses: actions/setup-node@v6
         with:
-          node-version: "20"
+          node-version: "22"
 
       - name: Create test project and install from git
         shell: bash

.github/workflows/docs.yml

@@ -16,8 +16,9 @@ jobs:
       - uses: oven-sh/setup-bun@v2
       - uses: actions/setup-node@v6
         with:
-          node-version: "20"
-      - run: npm install
+          node-version: "22"
+          cache: npm
+      - run: npm ci
       - run: npm run build
       - run: npm run docs
       - uses: peaceiris/actions-gh-pages@v4

.github/workflows/update-snapshots.yml

@@ -59,7 +59,8 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version: "20"
+          node-version: "22"
+          cache: npm
 
       - uses: astral-sh/setup-uv@v7
 

package.json

@@ -9,6 +9,9 @@
   "license": "MIT",
   "description": "MCP Apps SDK — Enable MCP servers to display interactive user interfaces in conversational clients.",
   "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
   "main": "./dist/src/app.js",
   "exports": {
     ".": {