From 581dcb9b217b90054676233785c7aa587c7e58c8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 26 Mar 2026 10:04:44 +0000
Subject: [PATCH 1/5] ci: automate release process with workflow-driven version
 bumps and PR flow

Adds a Release workflow that bumps all package versions, generates release
notes, and opens a PR. Merging the PR auto-tags and creates the GitHub
Release, which triggers npm-publish. Also adds `npm run bump` for local use
and a release.yml config for categorized auto-generated notes.
---
 .github/release.yml           |  31 ++++++++++
 .github/workflows/release.yml | 104 ++++++++++++++++++++++++++++++++++
 CONTRIBUTING.md               |  41 ++++++--------
 package.json                  |   1 +
 scripts/bump-version.mjs      |  37 ++++++++++++
 5 files changed, 189 insertions(+), 25 deletions(-)
 create mode 100644 .github/release.yml
 create mode 100644 .github/workflows/release.yml
 create mode 100644 scripts/bump-version.mjs

diff --git a/.github/release.yml b/.github/release.yml
new file mode 100644
index 000000000..e57e2acdd
--- /dev/null
+++ b/.github/release.yml
@@ -0,0 +1,31 @@
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+      - release
+    authors:
+      - github-actions
+      - dependabot
+  categories:
+    - title: Breaking Changes
+      labels:
+        - breaking-change
+        - breaking
+    - title: New Features
+      labels:
+        - feature
+        - enhancement
+    - title: New Examples
+      labels:
+        - examples
+    - title: Bug Fixes
+      labels:
+        - bug
+        - fix
+    - title: Documentation
+      labels:
+        - documentation
+        - docs
+    - title: Other Changes
+      labels:
+        - "*"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 000000000..0ba6e02dd
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,104 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "patch | minor | major | prerelease | explicit version (e.g. 1.4.0)"
+        required: true
+        default: patch
+      preid:
+        description: "Prerelease identifier (only used with bump=prerelease)"
+        required: false
+        default: beta
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  GH_TOKEN: ${{ github.token }}
+
+jobs:
+  prepare:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+
+      - name: Bump versions
+        id: bump
+        run: |
+          VERSION=$(node scripts/bump-version.mjs "${{ inputs.bump }}" --preid="${{ inputs.preid }}")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Generate release notes and prepend to RELEASES.md
+        run: |
+          VERSION="${{ steps.bump.outputs.version }}"
+          PREV_TAG=$(gh release list --repo ${{ github.repository }} --limit 1 --json tagName -q '.[0].tagName // ""')
+          gh api repos/${{ github.repository }}/releases/generate-notes \
+            -f tag_name="v$VERSION" \
+            -f target_commitish="${{ github.ref_name }}" \
+            ${PREV_TAG:+-f previous_tag_name="$PREV_TAG"} \
+            --jq .body > /tmp/notes.md
+          {
+            echo "# Release Notes"
+            echo ""
+            echo "## $VERSION"
+            echo ""
+            cat /tmp/notes.md
+            echo ""
+            echo "---"
+            echo ""
+            tail -n +2 RELEASES.md
+          } > RELEASES.md.new
+          mv RELEASES.md.new RELEASES.md
+
+      - name: Create release PR
+        run: |
+          VERSION="${{ steps.bump.outputs.version }}"
+          BRANCH="release/v$VERSION"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add -u
+          git commit -m "chore: release v$VERSION"
+          git push -f -u origin "$BRANCH"
+          gh pr create \
+            --title "chore: release v$VERSION" \
+            --body "Bumps all packages to \`$VERSION\` and updates RELEASES.md. Merging this PR will automatically tag and publish the release." \
+            --label release \
+            --base main || gh pr edit "$BRANCH" --title "chore: release v$VERSION"
+
+  tag:
+    if: >
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.merged == true &&
+      contains(github.event.pull_request.labels.*.name, 'release')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: main
+
+      - name: Create tag and release
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          TAG="v$VERSION"
+          if gh release view "$TAG" --repo ${{ github.repository }} >/dev/null 2>&1; then
+            echo "Release $TAG already exists, skipping"
+            exit 0
+          fi
+          awk '/^## /{if(seen++) exit} seen' RELEASES.md | tail -n +2 | sed '/^---$/,$d' > /tmp/notes.md
+          git tag "$TAG"
+          git push origin "$TAG"
+          PRERELEASE=""
+          [[ "$VERSION" == *-* ]] && PRERELEASE="--prerelease"
+          gh release create "$TAG" --title "$TAG" --notes-file /tmp/notes.md $PRERELEASE
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4c364a29c..14972f602 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -539,40 +539,31 @@ Before publishing releases, ensure the following are configured:
 
 ### Publishing a Release
 
-Releases are published automatically via GitHub Actions when a GitHub Release is created.
+Releases are automated via the [Release workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/release.yml).
 
 #### Steps to publish:
 
-1. **Update the version** in `package.json`:
+1. **Trigger the Release workflow**:
+   - Go to Actions → [Release](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/release.yml) → "Run workflow"
+   - Select the bump type (`patch`, `minor`, `major`, or `prerelease`)
+   - Click "Run workflow"
 
-   ```bash
-   # For a regular release
-   npm version patch  # or minor, or major
+2. **Review the release PR**:
+   - The workflow bumps the version across all packages, generates release notes, and opens a PR labeled `release`
+   - Edit `RELEASES.md` in the PR if you want to adjust the generated notes
+   - Approve and merge the PR
 
-   # For a beta release
-   npm version prerelease --preid=beta
-   ```
+3. **Done** — merging the PR automatically tags the commit, creates the GitHub Release, and triggers the [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml) to publish to npm.
 
-2. **Commit the version bump** (if not done by `npm version`):
+#### Manual alternative
 
-   ```bash
-   git add package.json
-   git commit -m "Bump version to X.Y.Z"
-   git push origin main
-   ```
+You can also bump versions locally:
 
-3. **Create a GitHub Release**:
-   - Go to [Releases](https://github.com/modelcontextprotocol/ext-apps/releases)
-   - Click "Draft a new release"
-   - Create a new tag matching the version (e.g., `v0.1.0`)
-   - Set the target branch (usually `main`)
-   - Write release notes describing the changes
-   - Click "Publish release"
+```bash
+npm run bump patch   # or minor, major, prerelease --preid=beta
+```
 
-4. **Monitor the workflow**:
-   - The [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml) will trigger automatically
-   - It runs build and test jobs before publishing
-   - On success, the package is published to npm with provenance
+Then commit, push, and create a GitHub Release manually — the npm-publish workflow triggers on release creation.
 
 #### npm Tags
 
diff --git a/package.json b/package.json
index d1fa9dfaf..bb824ff91 100644
--- a/package.json
+++ b/package.json
@@ -71,6 +71,7 @@
     "prettier": "prettier -u \"**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --check",
     "prettier:fix": "prettier -u \"**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --write",
     "check:versions": "node scripts/check-versions.mjs",
+    "bump": "node scripts/bump-version.mjs",
     "update-lock:docker": "rm -rf node_modules package-lock.json examples/*/node_modules && docker run --rm --platform linux/amd64 -v $(pwd):/work -w /work -e HOME=/tmp node:latest npm i --registry=https://registry.npmjs.org/ --ignore-scripts && rm -rf node_modules examples/*/node_modules && npm i --registry=https://registry.npmjs.org/"
   },
   "author": "Olivier Chafik",
diff --git a/scripts/bump-version.mjs b/scripts/bump-version.mjs
new file mode 100644
index 000000000..3a618e62d
--- /dev/null
+++ b/scripts/bump-version.mjs
@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Bump the version in the root package.json and sync all workspace packages
+ * to the same version.
+ *
+ * Usage:
+ *   node scripts/bump-version.mjs patch
+ *   node scripts/bump-version.mjs minor
+ *   node scripts/bump-version.mjs major
+ *   node scripts/bump-version.mjs 1.4.0
+ *   node scripts/bump-version.mjs prerelease --preid=beta
+ *
+ * Writes the new version to stdout (logs go to stderr).
+ */
+
+import { execSync } from "node:child_process";
+
+const args = process.argv.slice(2);
+if (!args[0]) {
+  console.error(
+    "Usage: node scripts/bump-version.mjs <patch|minor|major|prerelease|X.Y.Z> [--preid=<id>]",
+  );
+  process.exit(1);
+}
+
+const exec = (cmd) =>
+  execSync(cmd, { stdio: ["inherit", "pipe", "inherit"] })
+    .toString()
+    .trim();
+
+const newVersion = exec(
+  `npm version ${args.join(" ")} --no-git-tag-version`,
+).replace(/^v/, "");
+exec(`npm pkg set version=${newVersion} --workspaces`);
+
+console.error(`Bumped root + workspaces to ${newVersion}`);
+console.log(newVersion);

From 68b9cb36ea40306c7da758a8f894d7074ae743cb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 26 Mar 2026 10:06:00 +0000
Subject: [PATCH 2/5] ci: simplify release workflow and flatten npm-publish
 approval chain

- Drop auto-generated RELEASES.md prepending (notes are written manually in PR)
- Flatten npm-publish job dependencies so all publish jobs wait for approval
  together instead of sequentially, reducing 3 approval clicks to 1
- Remove Release environment from publish-mcpb (only needs GH_TOKEN)
- Use --generate-notes for GitHub Release creation
---
 .github/workflows/npm-publish.yml |  9 ++++++---
 .github/workflows/release.yml     | 31 ++++++-------------------------
 CONTRIBUTING.md                   |  6 +++---
 3 files changed, 15 insertions(+), 31 deletions(-)

diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml
index ece35d392..6358c2ce5 100644
--- a/.github/workflows/npm-publish.yml
+++ b/.github/workflows/npm-publish.yml
@@ -42,6 +42,10 @@ jobs:
       - run: npm ci
       - run: npm test
 
+  # All publish jobs depend directly on [build, test] (not on each other) so
+  # they all enter "waiting for approval" together and can be approved in a
+  # single "Review deployments" click.
+
   publish:
     runs-on: ubuntu-latest
     if: github.event_name == 'release'
@@ -88,7 +92,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'release'
     environment: Release
-    needs: [publish]
+    needs: [build, test]
 
     permissions:
       contents: read
@@ -142,8 +146,7 @@ jobs:
   publish-mcpb:
     runs-on: ubuntu-latest
     if: github.event_name == 'release'
-    environment: Release
-    needs: [publish-examples]
+    needs: [build, test]
 
     permissions:
       contents: write
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 0ba6e02dd..0e51dfa45 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -23,6 +23,8 @@ env:
   GH_TOKEN: ${{ github.token }}
 
 jobs:
+  # Opens a PR that bumps all package versions. Add release notes to
+  # RELEASES.md in the PR before merging.
   prepare:
     if: github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
@@ -39,28 +41,6 @@ jobs:
           VERSION=$(node scripts/bump-version.mjs "${{ inputs.bump }}" --preid="${{ inputs.preid }}")
           echo "version=$VERSION" >> $GITHUB_OUTPUT
 
-      - name: Generate release notes and prepend to RELEASES.md
-        run: |
-          VERSION="${{ steps.bump.outputs.version }}"
-          PREV_TAG=$(gh release list --repo ${{ github.repository }} --limit 1 --json tagName -q '.[0].tagName // ""')
-          gh api repos/${{ github.repository }}/releases/generate-notes \
-            -f tag_name="v$VERSION" \
-            -f target_commitish="${{ github.ref_name }}" \
-            ${PREV_TAG:+-f previous_tag_name="$PREV_TAG"} \
-            --jq .body > /tmp/notes.md
-          {
-            echo "# Release Notes"
-            echo ""
-            echo "## $VERSION"
-            echo ""
-            cat /tmp/notes.md
-            echo ""
-            echo "---"
-            echo ""
-            tail -n +2 RELEASES.md
-          } > RELEASES.md.new
-          mv RELEASES.md.new RELEASES.md
-
       - name: Create release PR
         run: |
           VERSION="${{ steps.bump.outputs.version }}"
@@ -73,10 +53,12 @@ jobs:
           git push -f -u origin "$BRANCH"
           gh pr create \
             --title "chore: release v$VERSION" \
-            --body "Bumps all packages to \`$VERSION\` and updates RELEASES.md. Merging this PR will automatically tag and publish the release." \
+            --body "Bumps all packages to \`$VERSION\`. Add release notes to \`RELEASES.md\` before merging. Merging this PR will automatically tag and create the GitHub Release, which triggers npm-publish." \
             --label release \
             --base main || gh pr edit "$BRANCH" --title "chore: release v$VERSION"
 
+  # When a release PR is merged, tag the commit and create the GitHub Release.
+  # This triggers the npm-publish workflow.
   tag:
     if: >
       github.event_name == 'pull_request' &&
@@ -96,9 +78,8 @@ jobs:
             echo "Release $TAG already exists, skipping"
             exit 0
           fi
-          awk '/^## /{if(seen++) exit} seen' RELEASES.md | tail -n +2 | sed '/^---$/,$d' > /tmp/notes.md
           git tag "$TAG"
           git push origin "$TAG"
           PRERELEASE=""
           [[ "$VERSION" == *-* ]] && PRERELEASE="--prerelease"
-          gh release create "$TAG" --title "$TAG" --notes-file /tmp/notes.md $PRERELEASE
+          gh release create "$TAG" --title "$TAG" --generate-notes $PRERELEASE
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 14972f602..2fd49e12a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -549,11 +549,11 @@ Releases are automated via the [Release workflow](https://github.com/modelcontex
    - Click "Run workflow"
 
 2. **Review the release PR**:
-   - The workflow bumps the version across all packages, generates release notes, and opens a PR labeled `release`
-   - Edit `RELEASES.md` in the PR if you want to adjust the generated notes
+   - The workflow bumps the version across all packages and opens a PR labeled `release`
+   - Add release notes to `RELEASES.md` in the PR
    - Approve and merge the PR
 
-3. **Done** — merging the PR automatically tags the commit, creates the GitHub Release, and triggers the [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml) to publish to npm.
+3. **Done** — merging the PR automatically tags the commit and creates the GitHub Release (with auto-generated notes), which triggers the [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml). Approve the deployment once when prompted.
 
 #### Manual alternative
 

From e23acaa2441397de069fcf9e95290cb786c04996 Mon Sep 17 00:00:00 2001
From: Olivier Chafik <ochafik@anthropic.com>
Date: Thu, 26 Mar 2026 10:44:28 +0000
Subject: [PATCH 3/5] fix: address review findings in release automation

- release.yml: use RELEASE_TOKEN PAT for gh release create so the
  release:published event triggers npm-publish (GITHUB_TOKEN events
  don't cascade to other workflows)
- release.yml: checkout merge_commit_sha in tag job instead of ref:main
  to avoid tagging later commits
- release.yml: checkout ref:main in prepare job so dispatching from a
  feature branch doesn't pollute the release PR
- release.yml: constrain preid to type:choice[beta] to match
  npm-publish.yml's tag detection
- release.yml: drop -f on push so re-runs fail loudly instead of
  clobbering manual RELEASES.md edits; drop pr-edit fallback
- release.yml: ensure release label exists before gh pr create
- release.yml: make tag push idempotent for re-runs after partial
  failure
- bump-version.mjs: update workspace dependency ranges so major bumps
  don't leave examples pointing at the old major
- bump-version.mjs: run npm install --package-lock-only so npm ci
  on the release PR doesn't fail on lockfile mismatch
- npm-publish.yml: add npm-tag detection to publish-examples so beta
  example releases don't overwrite latest
- .github/release.yml: use [bot] suffix in author excludes so
  dependabot PRs are actually filtered from release notes
- CONTRIBUTING.md: document RELEASE_TOKEN setup; fix npm run -- syntax
---
 .github/release.yml               |  4 ++--
 .github/workflows/npm-publish.yml | 15 ++++++++++++++-
 .github/workflows/release.yml     | 18 +++++++++++++-----
 CONTRIBUTING.md                   |  8 +++++++-
 scripts/bump-version.mjs          | 12 ++++++++++++
 5 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/.github/release.yml b/.github/release.yml
index e57e2acdd..6a959506a 100644
--- a/.github/release.yml
+++ b/.github/release.yml
@@ -4,8 +4,8 @@ changelog:
       - ignore-for-release
       - release
     authors:
-      - github-actions
-      - dependabot
+      - github-actions[bot]
+      - dependabot[bot]
   categories:
     - title: Breaking Changes
       labels:
diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml
index 6358c2ce5..3a34ab9e8 100644
--- a/.github/workflows/npm-publish.yml
+++ b/.github/workflows/npm-publish.yml
@@ -138,8 +138,21 @@ jobs:
       - name: Build example
         run: npm run build --workspace examples/${{ matrix.example }}
 
+      - name: Determine npm tag
+        id: npm-tag
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          if [[ "$VERSION" == *"-beta"* ]]; then
+            echo "tag=--tag beta" >> $GITHUB_OUTPUT
+          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 example
-        run: npm publish --workspace examples/${{ matrix.example }} --provenance --access public
+        run: npm publish --workspace examples/${{ matrix.example }} --provenance --access public ${{ steps.npm-tag.outputs.tag }}
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_SECRET }}
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 0e51dfa45..a0dfe505b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -9,7 +9,8 @@ on:
         default: patch
       preid:
         description: "Prerelease identifier (only used with bump=prerelease)"
-        required: false
+        type: choice
+        options: [beta]
         default: beta
   pull_request:
     types: [closed]
@@ -30,6 +31,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: main
 
       - uses: actions/setup-node@v6
         with:
@@ -50,12 +53,13 @@ jobs:
           git checkout -b "$BRANCH"
           git add -u
           git commit -m "chore: release v$VERSION"
-          git push -f -u origin "$BRANCH"
+          git push -u origin "$BRANCH"
+          gh label create release --color B60205 --description "Release PR" 2>/dev/null || true
           gh pr create \
             --title "chore: release v$VERSION" \
             --body "Bumps all packages to \`$VERSION\`. Add release notes to \`RELEASES.md\` before merging. Merging this PR will automatically tag and create the GitHub Release, which triggers npm-publish." \
             --label release \
-            --base main || gh pr edit "$BRANCH" --title "chore: release v$VERSION"
+            --base main
 
   # When a release PR is merged, tag the commit and create the GitHub Release.
   # This triggers the npm-publish workflow.
@@ -68,9 +72,13 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: main
+          ref: ${{ github.event.pull_request.merge_commit_sha }}
 
       - name: Create tag and release
+        env:
+          # PAT so the `release: published` event triggers npm-publish
+          # (events from GITHUB_TOKEN don't cascade to other workflows)
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
         run: |
           VERSION=$(node -p "require('./package.json').version")
           TAG="v$VERSION"
@@ -79,7 +87,7 @@ jobs:
             exit 0
           fi
           git tag "$TAG"
-          git push origin "$TAG"
+          git push origin "$TAG" || echo "tag already on remote"
           PRERELEASE=""
           [[ "$VERSION" == *-* ]] && PRERELEASE="--prerelease"
           gh release create "$TAG" --title "$TAG" --generate-notes $PRERELEASE
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2fd49e12a..2c4518d76 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -537,6 +537,11 @@ Before publishing releases, ensure the following are configured:
    - Name it `Release`
    - Add required reviewers or other protection rules as needed
 
+3. **`RELEASE_TOKEN` secret**: The release workflow creates GitHub Releases that must trigger the npm-publish workflow. Events from the default `GITHUB_TOKEN` don't cascade to other workflows, so a separate token is needed.
+   - Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new) scoped to this repository with **Contents: write** permission
+   - Go to Settings > Secrets and variables > Actions > New repository secret
+   - Name: `RELEASE_TOKEN`, value: the PAT
+
 ### Publishing a Release
 
 Releases are automated via the [Release workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/release.yml).
@@ -552,6 +557,7 @@ Releases are automated via the [Release workflow](https://github.com/modelcontex
    - The workflow bumps the version across all packages and opens a PR labeled `release`
    - Add release notes to `RELEASES.md` in the PR
    - Approve and merge the PR
+   - _Note: re-running the workflow for the same version fails if the branch already exists. Delete the `release/vX.Y.Z` branch first if you need to redo the bump._
 
 3. **Done** — merging the PR automatically tags the commit and creates the GitHub Release (with auto-generated notes), which triggers the [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml). Approve the deployment once when prompted.
 
@@ -560,7 +566,7 @@ Releases are automated via the [Release workflow](https://github.com/modelcontex
 You can also bump versions locally:
 
 ```bash
-npm run bump patch   # or minor, major, prerelease --preid=beta
+npm run bump -- patch   # or: minor | major | prerelease --preid=beta
 ```
 
 Then commit, push, and create a GitHub Release manually — the npm-publish workflow triggers on release creation.
diff --git a/scripts/bump-version.mjs b/scripts/bump-version.mjs
index 3a618e62d..0dfcbf6dd 100644
--- a/scripts/bump-version.mjs
+++ b/scripts/bump-version.mjs
@@ -14,6 +14,7 @@
  */
 
 import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 
 const args = process.argv.slice(2);
 if (!args[0]) {
@@ -28,10 +29,21 @@ const exec = (cmd) =>
     .toString()
     .trim();
 
+const pkgName = JSON.parse(readFileSync("package.json", "utf-8")).name;
+
 const newVersion = exec(
   `npm version ${args.join(" ")} --no-git-tag-version`,
 ).replace(/^v/, "");
 exec(`npm pkg set version=${newVersion} --workspaces`);
 
+// Keep workspace dependency ranges compatible (needed on major bumps)
+const [major, minor] = newVersion.split(".");
+exec(
+  `npm pkg set "dependencies.${pkgName}=^${major}.${minor}.0" --workspaces`,
+);
+
+// Sync package-lock.json so `npm ci` doesn't reject the release PR
+exec("npm install --package-lock-only --ignore-scripts");
+
 console.error(`Bumped root + workspaces to ${newVersion}`);
 console.log(newVersion);

From f611aad02ac5e4ef867cfdc1214789617fcde923 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 26 Mar 2026 10:45:10 +0000
Subject: [PATCH 4/5] style: auto-fix prettier formatting

---
 scripts/bump-version.mjs | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/scripts/bump-version.mjs b/scripts/bump-version.mjs
index 0dfcbf6dd..65c878fd5 100644
--- a/scripts/bump-version.mjs
+++ b/scripts/bump-version.mjs
@@ -38,9 +38,7 @@ exec(`npm pkg set version=${newVersion} --workspaces`);
 
 // Keep workspace dependency ranges compatible (needed on major bumps)
 const [major, minor] = newVersion.split(".");
-exec(
-  `npm pkg set "dependencies.${pkgName}=^${major}.${minor}.0" --workspaces`,
-);
+exec(`npm pkg set "dependencies.${pkgName}=^${major}.${minor}.0" --workspaces`);
 
 // Sync package-lock.json so `npm ci` doesn't reject the release PR
 exec("npm install --package-lock-only --ignore-scripts");

From 6f8e30623b671f39e561d51ad8d7f4bfdfc8086e Mon Sep 17 00:00:00 2001
From: Olivier Chafik <ochafik@anthropic.com>
Date: Tue, 21 Apr 2026 15:57:28 +0100
Subject: [PATCH 5/5] build: add npm run bump; parallel npm-publish approval
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- scripts/bump-version.mjs (+ npm run bump): bumps root and all workspace
  package versions, updates examples' ^X.Y.0 dependency range on the root
  package (matters on major bumps), and refreshes package-lock so npm ci
  accepts the release PR.
- npm-publish.yml: all publish jobs now depend directly on [build, test]
  instead of chaining, so they enter "waiting for approval" together and a
  single Review-deployments click approves the lot. Prerelease versions
  (any X.Y.Z-…) publish under --tag beta so they don't take latest.
- CONTRIBUTING.md: release steps now use npm run bump.

Dropped from the original change: the workflow_dispatch release.yml
(required a long-lived PAT to cascade events), label-based
.github/release.yml auto-notes (PRs aren't labeled today), and the
release-X.Y npm-tag for non-main branches (no backport branches yet).
---
 .github/release.yml               | 31 -----------
 .github/workflows/npm-publish.yml |  6 +-
 .github/workflows/release.yml     | 93 -------------------------------
 CONTRIBUTING.md                   | 34 +++--------
 4 files changed, 9 insertions(+), 155 deletions(-)
 delete mode 100644 .github/release.yml
 delete mode 100644 .github/workflows/release.yml

diff --git a/.github/release.yml b/.github/release.yml
deleted file mode 100644
index 6a959506a..000000000
--- a/.github/release.yml
+++ /dev/null
@@ -1,31 +0,0 @@
-changelog:
-  exclude:
-    labels:
-      - ignore-for-release
-      - release
-    authors:
-      - github-actions[bot]
-      - dependabot[bot]
-  categories:
-    - title: Breaking Changes
-      labels:
-        - breaking-change
-        - breaking
-    - title: New Features
-      labels:
-        - feature
-        - enhancement
-    - title: New Examples
-      labels:
-        - examples
-    - title: Bug Fixes
-      labels:
-        - bug
-        - fix
-    - title: Documentation
-      labels:
-        - documentation
-        - docs
-    - title: Other Changes
-      labels:
-        - "*"
diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml
index 3a34ab9e8..0667bbddd 100644
--- a/.github/workflows/npm-publish.yml
+++ b/.github/workflows/npm-publish.yml
@@ -142,11 +142,8 @@ jobs:
         id: npm-tag
         run: |
           VERSION=$(node -p "require('./package.json').version")
-          if [[ "$VERSION" == *"-beta"* ]]; then
+          if [[ "$VERSION" == *"-"* ]]; then
             echo "tag=--tag beta" >> $GITHUB_OUTPUT
-          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
@@ -159,6 +156,7 @@ jobs:
   publish-mcpb:
     runs-on: ubuntu-latest
     if: github.event_name == 'release'
+    environment: Release
     needs: [build, test]
 
     permissions:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
deleted file mode 100644
index a0dfe505b..000000000
--- a/.github/workflows/release.yml
+++ /dev/null
@@ -1,93 +0,0 @@
-name: Release
-
-on:
-  workflow_dispatch:
-    inputs:
-      bump:
-        description: "patch | minor | major | prerelease | explicit version (e.g. 1.4.0)"
-        required: true
-        default: patch
-      preid:
-        description: "Prerelease identifier (only used with bump=prerelease)"
-        type: choice
-        options: [beta]
-        default: beta
-  pull_request:
-    types: [closed]
-    branches: [main]
-
-permissions:
-  contents: write
-  pull-requests: write
-
-env:
-  GH_TOKEN: ${{ github.token }}
-
-jobs:
-  # Opens a PR that bumps all package versions. Add release notes to
-  # RELEASES.md in the PR before merging.
-  prepare:
-    if: github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: main
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version: "22"
-
-      - name: Bump versions
-        id: bump
-        run: |
-          VERSION=$(node scripts/bump-version.mjs "${{ inputs.bump }}" --preid="${{ inputs.preid }}")
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-
-      - name: Create release PR
-        run: |
-          VERSION="${{ steps.bump.outputs.version }}"
-          BRANCH="release/v$VERSION"
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git checkout -b "$BRANCH"
-          git add -u
-          git commit -m "chore: release v$VERSION"
-          git push -u origin "$BRANCH"
-          gh label create release --color B60205 --description "Release PR" 2>/dev/null || true
-          gh pr create \
-            --title "chore: release v$VERSION" \
-            --body "Bumps all packages to \`$VERSION\`. Add release notes to \`RELEASES.md\` before merging. Merging this PR will automatically tag and create the GitHub Release, which triggers npm-publish." \
-            --label release \
-            --base main
-
-  # When a release PR is merged, tag the commit and create the GitHub Release.
-  # This triggers the npm-publish workflow.
-  tag:
-    if: >
-      github.event_name == 'pull_request' &&
-      github.event.pull_request.merged == true &&
-      contains(github.event.pull_request.labels.*.name, 'release')
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ github.event.pull_request.merge_commit_sha }}
-
-      - name: Create tag and release
-        env:
-          # PAT so the `release: published` event triggers npm-publish
-          # (events from GITHUB_TOKEN don't cascade to other workflows)
-          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
-        run: |
-          VERSION=$(node -p "require('./package.json').version")
-          TAG="v$VERSION"
-          if gh release view "$TAG" --repo ${{ github.repository }} >/dev/null 2>&1; then
-            echo "Release $TAG already exists, skipping"
-            exit 0
-          fi
-          git tag "$TAG"
-          git push origin "$TAG" || echo "tag already on remote"
-          PRERELEASE=""
-          [[ "$VERSION" == *-* ]] && PRERELEASE="--prerelease"
-          gh release create "$TAG" --title "$TAG" --generate-notes $PRERELEASE
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2c4518d76..6a3102bdb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -537,39 +537,19 @@ Before publishing releases, ensure the following are configured:
    - Name it `Release`
    - Add required reviewers or other protection rules as needed
 
-3. **`RELEASE_TOKEN` secret**: The release workflow creates GitHub Releases that must trigger the npm-publish workflow. Events from the default `GITHUB_TOKEN` don't cascade to other workflows, so a separate token is needed.
-   - Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new) scoped to this repository with **Contents: write** permission
-   - Go to Settings > Secrets and variables > Actions > New repository secret
-   - Name: `RELEASE_TOKEN`, value: the PAT
-
 ### Publishing a Release
 
-Releases are automated via the [Release workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/release.yml).
-
-#### Steps to publish:
-
-1. **Trigger the Release workflow**:
-   - Go to Actions → [Release](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/release.yml) → "Run workflow"
-   - Select the bump type (`patch`, `minor`, `major`, or `prerelease`)
-   - Click "Run workflow"
-
-2. **Review the release PR**:
-   - The workflow bumps the version across all packages and opens a PR labeled `release`
-   - Add release notes to `RELEASES.md` in the PR
-   - Approve and merge the PR
-   - _Note: re-running the workflow for the same version fails if the branch already exists. Delete the `release/vX.Y.Z` branch first if you need to redo the bump._
+1. **Bump the version** across the root and all workspace packages:
 
-3. **Done** — merging the PR automatically tags the commit and creates the GitHub Release (with auto-generated notes), which triggers the [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml). Approve the deployment once when prompted.
+   ```bash
+   npm run bump -- minor   # or: patch | major | prerelease --preid=beta | 1.7.0
+   ```
 
-#### Manual alternative
+   Commit and open a PR with a grouped changelog in the body (see prior `chore: bump …` PRs for the format).
 
-You can also bump versions locally:
-
-```bash
-npm run bump -- patch   # or: minor | major | prerelease --preid=beta
-```
+2. **Merge the PR**, then [draft a GitHub Release](https://github.com/modelcontextprotocol/ext-apps/releases/new) — create a `vX.Y.Z` tag on `main`, paste the changelog, publish.
 
-Then commit, push, and create a GitHub Release manually — the npm-publish workflow triggers on release creation.
+3. **Approve the deployment** — publishing the Release triggers the [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml); all publish jobs wait together for a single "Review deployments" approval.
 
 #### npm Tags