# Release Mcp Version

> Cut and publish a NEW version of an MCP server that already has its distribution pipeline set up — lockstep version bump across package.json/server.json/manifest.json, land on main, tag, and let CI publish to npm + the official MCP registry + a GitHub release (.mcpb) + a container image. Use when asked to release/ship/publish a new version, cut a release, or "bump and publish" an MCP server. For…

- **Type:** Skill
- **Install:** `agentstack add skill-selic-skills-release-mcp-version`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [selic](https://agentstack.voostack.com/s/selic)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [selic](https://github.com/selic)
- **Source:** https://github.com/selic/skills/tree/main/skills/release-mcp-version

## Install

```sh
agentstack add skill-selic-skills-release-mcp-version
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 "/bump.mjs" …`, where `` 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///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 /` (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`.

```bash
node "/bump.mjs" 
node "/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  --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

```bash
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  --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.

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

## Phase 5 — verify

```bash
node "/check.mjs" --online   # npm + registry + tag all current
gh release view vX.Y.Z --json assets                       # .mcpb attached
(cd /tmp && npx -y @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 ` 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):

```bash
SUB=; RG=; APP=
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 //:latest             # or :X.Y.Z to pin
az webapp restart --subscription $SUB -g $RG -n $APP
# then poll https:///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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [selic](https://github.com/selic)
- **Source:** [selic/skills](https://github.com/selic/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-selic-skills-release-mcp-version
- Seller: https://agentstack.voostack.com/s/selic
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.