Merge remote-tracking branch 'origin/main' into claude/review-mcp-sampling-CkbHh

# Conflicts:
#	src/app.examples.ts

Author: ochafik

.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
@@ -97,7 +103,15 @@ jobs:
 
       - name: Build MCPB bundle (pdf-server)
         if: runner.os == 'Linux' && matrix.name == 'Linux x64'
-        run: npx -y @anthropic-ai/mcpb pack
+        run: node build-mcpb.mjs
+        working-directory: examples/pdf-server
+
+      - name: Smoke-test MCPB bundle starts
+        if: runner.os == 'Linux' && matrix.name == 'Linux x64'
+        run: |
+          unzip -q pdf-server.mcpb -d .mcpb-smoke
+          node .mcpb-smoke/dist/index.js --stdio < /dev/null 2>&1 | tee /tmp/mcpb-smoke.log
+          grep -q "Ready" /tmp/mcpb-smoke.log
         working-directory: examples/pdf-server
 
   e2e:
@@ -111,7 +125,8 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version: "20"
+          node-version: "22"
+          cache: npm
 
       - uses: astral-sh/setup-uv@v7
 
@@ -147,13 +162,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,15 +197,18 @@ jobs:
     steps:
       - uses: actions/setup-node@v6
         with:
-          node-version: "20"
+          node-version: "22"
 
       - name: Create test project and install from git
         shell: bash
+        env:
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+          HEAD_REF: ${{ github.head_ref || github.ref_name }}
         run: |
           mkdir test-project
           cd test-project
           npm init -y
           # Install from the PR branch (use head repo for fork PRs)
-          npm install "git+https://github.com/${{ github.event.pull_request.head.repo.full_name || github.repository }}#${{ github.head_ref || github.ref_name }}"
+          npm install "git+https://github.com/${HEAD_REPO}#${HEAD_REF}"
           # Verify the package is usable (ESM import)
           node --input-type=module -e "import { App } from '@modelcontextprotocol/ext-apps'; console.log('Import successful:', typeof App)"

.github/workflows/docs-preview.yml

@@ -0,0 +1,65 @@
+name: Docs Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "README.md"
+      - "typedoc.config.mjs"
+      - "scripts/typedoc-*.mjs"
+      - ".github/workflows/docs-preview.yml"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: docs-preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    # Refuse to run for fork PRs — forks do not have access to the Cloudflare
+    # secrets, so deploys would fail anyway.
+    if: >-
+      github.event.action != 'closed' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+
+      - run: npm ci
+
+      - run: npm run build
+
+      - run: npm run docs
+
+      - name: Deploy preview
+        uses: modelcontextprotocol/actions/cloudflare-pages-preview/deploy@main
+        with:
+          directory: docs
+          project-name: mcp-ext-apps-docs-preview
+          api-token: ${{ secrets.CF_PAGES_PREVIEW_API_TOKEN }}
+          account-id: ${{ secrets.CF_PAGES_PREVIEW_ACCOUNT_ID }}
+          comment-title: "📖 Docs Preview Deployed"
+          comment-marker: "<!-- docs-preview-comment -->"
+
+  cleanup:
+    if: >-
+      github.event.action == 'closed' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: modelcontextprotocol/actions/cloudflare-pages-preview/cleanup@main
+        with:
+          project-name: mcp-ext-apps-docs-preview
+          api-token: ${{ secrets.CF_PAGES_PREVIEW_API_TOKEN }}
+          account-id: ${{ secrets.CF_PAGES_PREVIEW_ACCOUNT_ID }}
+          comment-marker: "<!-- docs-preview-comment -->"

.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/npm-publish.yml

@@ -159,12 +159,8 @@ jobs:
           cache: npm
       - run: npm ci
 
-      - name: Build pdf-server
-        run: npm run build --workspace examples/pdf-server
-
-      - name: Pack MCPB bundle
-        run: npx -y @anthropic-ai/mcpb pack
-        working-directory: examples/pdf-server
+      - name: Build pdf-server + MCPB bundle
+        run: npm run build:mcpb --workspace examples/pdf-server
 
       - name: Upload MCPB to release
         run: gh release upload "${{ github.event.release.tag_name }}" examples/pdf-server/*.mcpb --clobber

.github/workflows/update-snapshots.yml

@@ -16,10 +16,14 @@ permissions:
 
 jobs:
   update-snapshots:
-    # Run on workflow_dispatch OR when someone comments "/update-snapshots" on a PR
+    # Run on workflow_dispatch OR when a maintainer comments "/update-snapshots" on a PR.
+    # author_association check prevents arbitrary commenters from triggering a job with
+    # contents:write that pushes a [skip ci] commit to the PR branch.
     if: >
       github.event_name == 'workflow_dispatch' ||
-      (github.event.issue.pull_request && contains(github.event.comment.body, '/update-snapshots'))
+      (github.event.issue.pull_request &&
+      contains(github.event.comment.body, '/update-snapshots') &&
+      contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association))
     runs-on: ubuntu-latest
     steps:
       - name: Get PR branch
@@ -59,7 +63,8 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version: "20"
+          node-version: "22"
+          cache: npm
 
       - uses: astral-sh/setup-uv@v7
 

.gitignore

@@ -15,4 +15,6 @@ __pycache__/
 *.pyc
 
 # MCPB bundles (built artifacts)
-*.mcpb
+*.mcpb
+.mcpb-stage/
+.mcpb-smoke/

.husky/pre-commit

@@ -14,8 +14,16 @@ if grep -E '"resolved": "https?://' package-lock.json | grep -v registry.npmjs.o
   exit 1
 fi
 
+# Capture staged files so we only re-stage what the user intended to commit
+# (avoids sweeping unrelated WIP into the commit). --diff-filter=d skips
+# deletions so the xargs git add below doesn't fail on removed paths.
+STAGED=$(git diff --name-only --cached --diff-filter=d)
+
 npm run build:all
 npm run prettier:fix
 
-# Stage any files reformatted by prettier (generated files, source, docs, etc.)
-git diff --name-only --diff-filter=M | xargs -r git add
+# Re-stage originally-staged files (prettier may have reformatted them)
+echo "$STAGED" | xargs -r git add
+
+# Also stage generated files (regenerated by build:all from spec.types.ts)
+git add src/generated/

.npmrc

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org/

AGENTS.md

@@ -39,7 +39,10 @@ npm test
 # Check JSDoc comment syntax and `{@link}` references
 npm exec typedoc -- --treatValidationWarningsAsErrors --emit none
 
-# Regenerate package-lock.json (especially on setups w/ custom npm registry)
+# Regenerate package-lock.json
+# Note: repo .npmrc pins registry to npmjs.org, so a plain `npm i` is safe even
+# if your global npm config points elsewhere. The Docker step below is optional
+# — it locks linux-amd64 optionalDependencies (sharp, rollup, bun) for CI.
 rm -fR  package-lock.json node_modules && \
   docker run  --rm -it --platform linux/amd64 -v $PWD:/src:rw -w /src node:latest npm i && \
   rm -fR node_modules && \

CONTRIBUTING.md

@@ -25,6 +25,7 @@ We welcome contributions to the MCP Apps SDK! This document outlines the process
 - Update documentation as needed
 - Keep changes focused and atomic
 - Provide a clear description of changes
+- **Keep "Allow edits by maintainers" checked** when opening your PR — this lets maintainers rebase your branch and lets the [`/update-snapshots` workflow](#updating-snapshots-in-ci) push updated screenshots to it
 
 ## Running Examples