Release mcp version

Release a new MCP-server version

Incremental-release runbook for a repo that already has the distribution pipeline in place (npm package, server.json, optional manifest.json, a tag-triggered release.yml, and — if containerised — a docker-publish.yml). Publish-only: npm + the official MCP registry + a GitHub release. Container redeploy is the optional appendix, not part of a normal release.

Auto-detect the target from the repo in the cwd: read package.json for name, mcpName, and the current version.

Bundled resource: bump.mjs sits next to this file — invoke it as node "<skill-dir>/bump.mjs" …, where <skill-dir> is wherever this skill lives (~/.claude/skills/release-mcp-version/, or as a plugin $CLAUDE_PLUGIN_ROOT/skills/release-mcp-version/). The lockstep/online validator is check.mjs from the companion publish-mcp-server skill.

⚠️ Steps that need the user's explicit go-ahead

The harness will (correctly) block these; do not retry silently — pause and ask:

1. Landing on main — a direct push to the default branch, or merging a PR you authored yourself. Ask the user to confirm, or have them merge in the GitHub UI.
2. (Appendix only) a production container redeploy.

Everything else runs unattended, except the registry device-flow, where you surface a code + URL and the user approves in a browser.

Phase 0 — preflight

• Confirm the cwd is the intended repo (node -p "require('./package.json').name").
• Working tree clean (git status --short); on main or the release branch/PR.
• Green locally: npm ci && npm run build && npm test.
• Choose the semver bump from what changed: patch (fixes), minor (additive, backward-compatible), major (breaking). On 0.x, treat breaking as a minor.
• Confirm the npm token is in THIS repo's Actions secrets — it's per-repo: gh api repos/<owner>/<repo>/actions/secrets --jq '.secrets[].name' should list NPM_TOKEN. A token in another repo does not apply and can't be copied (secrets are write-only). If missing: gh secret set NPM_TOKEN --repo <owner>/<repo> (paste at the prompt), or plan to npm publish by hand.

Phase 1 — bump the version (lockstep)

The version must match in every place the pipeline reads it: package.json, server.json (top-level and packages[0].version), and manifest.json.

node "<skill-dir>/bump.mjs" <patch|minor|major|X.Y.Z>
node "<publish-mcp-server skill-dir>/check.mjs"      # confirms lockstep + packaging
git add -A && git commit -m "Release vX.Y.Z"

bump.mjs edits all locations, skips a missing manifest.json, and refuses a downgrade.

Phase 2 — land on main ⚠️ (authorization gate)

• Direct on main: git push origin main — ask first (default-branch push).
• Via a PR: gh pr merge <n> --merge --delete-branch — ask first (self-merge is blocked). Or the user clicks Merge; then git checkout main && git pull.

Phase 3 — tag & push → CI publishes

git tag vX.Y.Z && git push origin vX.Y.Z

The tag push (not git tag alone) fires:

• release.yml → build/test → npm publish --provenance (uses NPM_TOKEN; no-ops if the version is already live or the token is unset) → .mcpb bundle → GitHub release.
• docker-publish.yml (if present) → container image (:X.Y.Z, :X.Y, :latest from main).

Watch: gh run watch "$(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')" --exit-status --compact. Confirm the "Publish to npm" step's conclusion is success (not skipped) via gh run view <id> --json jobs.

Phase 4 — MCP registry (device-flow)

The mcp-publisher login token expires in well under an hour — log in immediately before publishing. Run login in the background, read its output, and give the user the code + URL; it completes when they authorize.

mcp-publisher login github     # → "enter code XXXX-XXXX at https://github.com/login/device"
mcp-publisher publish          # reads ./server.json

Phase 5 — verify

node "<publish-mcp-server skill-dir>/check.mjs" --online   # npm + registry + tag all current
gh release view vX.Y.Z --json assets                       # .mcpb attached
(cd /tmp && npx -y <pkg>@X.Y.Z --help)                     # from OUTSIDE the repo

Gotchas (each cost real time once)

• NPM_TOKEN is per-repo and write-only — a token in another repo doesn't count and can't be read/copied; add it to the repo you're releasing.
• The mcp-publisher login token dies fast — always log in right before publish.
• Run the npx smoke test from outside the repo (npx -y <name> inside the repo resolves the local package and fails).
• A release fires on tag push, not git tag. A tag on a commit predating the workflow file runs nothing.
• If git tag vX.Y.Z says "already exists" it aborts a chained && git push — push the existing tag explicitly.

---

Appendix — container redeploy (optional, not a normal release step)

If the server runs as a container pulled from a registry (e.g. an Azure App Service or any host), the image is already built by docker-publish.yml; redeploy = repoint the tag and restart. ⚠️ Production change — get an explicit go-ahead. Prefer enabling the host's continuous-deployment webhook so a tag push auto-rolls; otherwise repoint + restart by hand.

Azure App Service example (fill in your own coordinates):

SUB=<subscription-id>; RG=<resource-group>; APP=<app-name>
az webapp config container show --subscription $SUB -g $RG -n $APP \
  --query "[?name=='DOCKER_CUSTOM_IMAGE_NAME'].value" -o tsv          # current image:tag
az webapp config container set  --subscription $SUB -g $RG -n $APP \
  --container-image-name <registry>/<owner>/<repo>:latest             # or :X.Y.Z to pin
az webapp restart --subscription $SUB -g $RG -n $APP
# then poll https://<host>/health until "version" == X.Y.Z

az may need brew reinstall azure-cli then az login --use-device-code (surface the code like the registry flow). Rollback: rerun container set with the previous tag.