Merge remote-tracking branch 'origin/main' into ochafik/map-interact

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
@@ -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,15 +189,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.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

@@ -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
 

.husky/pre-commit

@@ -14,8 +14,15 @@ 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)
+STAGED=$(git diff --name-only --cached)
+
 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
 

build.bun.ts

@@ -1,9 +1,15 @@
 #!/usr/bin/env bun
 import { $ } from "bun";
+import { cpSync, mkdirSync } from "node:fs";
 
 // Run TypeScript compiler for type declarations
 await $`tsc`;
 
+// Copy schema.json (tsc is emitDeclarationOnly, Bun.build doesn't emit JSON assets).
+// Needed for the "./schema.json" package export.
+mkdirSync("dist/src/generated", { recursive: true });
+cpSync("src/generated/schema.json", "dist/src/generated/schema.json");
+
 const isDevelopment = Bun.env.NODE_ENV === "development";
 
 // Build all JavaScript/TypeScript files
@@ -25,30 +31,34 @@ function buildJs(
   });
 }
 
+// zod is a peerDependency — keep it external so consumers share a single
+// zod instance (instanceof ZodError / schema.extend() break with duplicate copies).
+const PEER_EXTERNALS = ["@modelcontextprotocol/sdk", "zod"];
+
 await Promise.all([
   buildJs("src/app.ts", {
     outdir: "dist/src",
-    external: ["@modelcontextprotocol/sdk"],
+    external: PEER_EXTERNALS,
   }),
   buildJs("src/app.ts", {
     outdir: "dist/src",
     naming: { entry: "app-with-deps.js" },
   }),
   buildJs("src/app-bridge.ts", {
     outdir: "dist/src",
-    external: ["@modelcontextprotocol/sdk"],
+    external: PEER_EXTERNALS,
   }),
   buildJs("src/react/index.tsx", {
     outdir: "dist/src/react",
-    external: ["react", "react-dom", "@modelcontextprotocol/sdk"],
+    external: ["react", "react-dom", ...PEER_EXTERNALS],
   }),
   buildJs("src/react/index.tsx", {
     outdir: "dist/src/react",
-    external: ["react", "react-dom", "@modelcontextprotocol/sdk"],
+    external: ["react", "react-dom", ...PEER_EXTERNALS],
     naming: { entry: "react-with-deps.js" },
   }),
   buildJs("src/server/index.ts", {
     outdir: "dist/src/server",
-    external: ["@modelcontextprotocol/sdk"],
+    external: PEER_EXTERNALS,
   }),
 ]);

examples/basic-host/package.json

@@ -1,7 +1,7 @@
 {
   "homepage": "https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host",
   "name": "@modelcontextprotocol/ext-apps-basic-host",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "type": "module",
   "scripts": {
     "build": "tsc --noEmit && concurrently \"cross-env INPUT=index.html vite build\" \"cross-env INPUT=sandbox.html vite build\"",

examples/basic-server-preact/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelcontextprotocol/server-basic-preact",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "type": "module",
   "description": "Basic MCP App Server example using Preact",
   "repository": {