Release

Release @mcp-b packages

Use the existing Release workflow. CI publishes from main using npm OIDC, not an NPM_TOKEN secret. Do not publish, dispatch, push, or change remote settings without authorization.

Stable releases

1. Validate the changes:

   pnpm build && pnpm typecheck && vp check && pnpm test:unit && pnpm release:check
   

2. Run pnpm changeset. Select only packages with actual changes and describe the consumer-facing effect. Separate summaries when packages need different release notes.

3. Commit the changeset with the implementation and submit the PR.

4. After merge, CI creates or updates chore(release): version packages.

5. Review that PR's versions, changelogs, relay manifest and global CDN test pin. Merging it lets CI publish the release.

The version PR uses GITHUB_TOKEN. GitHub can hold workflows from bot-created or updated PRs for approval: a maintainer with write access selects Approve workflows to run in the PR merge box, then waits for all required checks. Do not bypass checks or add a PAT to work around an approval prompt. See GitHub's workflow trigger rules.

Never hand-edit package versions or use pnpm version: this bypasses changelogs and fixed-group coordination. All 12 published packages belong to one Changesets fixed group; private workspace apps and examples are not released.

pnpm changeset:version applies versions and synchronizes checked-in metadata through scripts/release-metadata.mjs --write. Normally the workflow runs it. Use it locally only when preparing an explicitly requested version commit.

ci:publish validates metadata, publishes unpublished package versions in dependency order, then runs changeset tag. The pinned Changesets action reads those new-tag messages to create GitHub releases and trigger SBOM, MCPB and signing steps. Keep the tag command after a successful publish; plain pnpm publish does not emit Changesets release events.

npm trusted publishing

Each public package must configure the same trusted publisher on npm:

• Organization: WebMCP-org
• Repository: npm-packages
• Workflow filename: changesets.yml
• Environment: npm-publish
• Allowed action: npm publish

The workflow uses GitHub-hosted runners and job-level id-token: write. Node 24 and the pinned npm CLI meet npm's OIDC requirements. pnpm packs the workspace, resolving workspace: and catalog: protocols, then delegates publication to npm. Keep the npm CLI setup. Provenance is enabled; no long-lived npm publish token is needed.

Configure npm-publish environment reviewers and restrict deployment branches to main in GitHub settings. Naming an environment in YAML does not configure these protections. Verify OIDC publishing works before disabling legacy token access in npm settings. The workflow's canonical-repository and branch checks are additional safeguards.

See npm trusted publishing and pnpm publish.

Snapshots

For one temporary build from main, dispatch only when requested:

gh workflow run "Release" --ref main -f tag=beta

This publishes <next>-beta.<datetime> under beta, without committing temporary versions or consuming the changesets on main. Dispatch before merging the version PR: snapshots need pending changesets. The workflow rejects an empty release, latest, unsafe tag text, and existing pre-mode state. It publishes only snapshot packages and signs the registry artifact in each prerelease GitHub release.

A snapshot is independent of the accumulating prerelease flow below. Never restore an entire working tree with git checkout . to discard snapshot versions. Prefer the workflow; if a local snapshot is explicitly needed, prepare it in a disposable clean checkout.

Accumulating prereleases

pnpm changeset pre enter beta

Commit .changeset/pre.json. Normal version PRs now produce X.Y.Z-beta.0, then beta.1, and so on. scripts/npm-dist-tag.mjs selects the active prerelease tag for ci:publish and publish:all; invalid state must stop publication rather than defaulting to latest.

To graduate, run pnpm changeset pre exit and commit the change. The next version PR removes the prerelease suffix and publishes to latest.

Local publishing and recovery

Use local publishing only when explicitly requested. Authenticate with npm login through the user's approved interactive flow; do not read, print, or shell-evaluate .env files. Then use pnpm publish:all, which builds, checks release metadata, and selects the dist-tag. Do not publish a source directory with npm: it cannot resolve pnpm dependency protocols.

Publication is not atomic across packages. pnpm skips versions already on npm, so rerun the same release after fixing the cause of a partial publish. Never overwrite or silently bump an already published version. If npm publishing succeeded but a later GitHub artifact step failed, recover those missing artifacts explicitly: existing tags can make Changesets report no new publication on a rerun. A rerun of snapshot versioning creates a new timestamp.

If only signing failed after stable GitHub releases were created, recover signatures with:

gh workflow run "Release" --ref main -f recover_signatures_version=5.0.3

Use the affected stable version. This checks out its usewebmcp@<version> tag, validates every public package's version, tag commit and existing release, then signs source archives with Sigstore bundles. It never publishes npm packages or replaces SBOM/MCPB/R2 artifacts.

Verify exact versions (npm view <name>@<version> version) and dist-tags, including unscoped usewebmcp and nested @mcp-b/smart-dom-reader-server. Do not use the default npm view version as a prerelease check: it reads latest.

See publishing references for MCPB artifact recovery.