release

Releasing

package.json is the single source of truth for the version. The npm version lifecycle hook runs scripts/sync-version.mjs, which propagates it to src/version.ts, manifest.json and server.json (incl. the .mcpb release-asset URL), and moves CHANGELOG.md's [Unreleased] notes under a new ## [x.y.z] - <date> heading (leaving [Unreleased] empty); version.test.ts guards that the version files never drift and that a heading for the current version exists. This used to be a manual "docs: move Unreleased notes under X.Y.Z" step that had to happen before npm version — easy to forget, or easy to do in the wrong order (a v0.9.0 release once shipped tagged with CHANGELOG.md still saying "Unreleased", caught by nothing). It's now atomic with the version bump itself, so there's no ordering to get wrong. sync-version.mjs and preversion-check.mjs locate the repo root via fileURLToPath(import.meta.url) + dirname() — no Node-version floor above the package's own engines.node (≥ 20.11) applies to running npm version yourself.

A preversion hook (scripts/preversion-check.mjs) runs first, with two checks:

• Unpushed-tag race: if the current package.json version already has a local git tag, it blocks unless that tag is also on origin — this is the exact race that once orphaned a version in a sibling repo (npm version run twice within minutes, the first tag/commit never pushed, silently buried under the second). Push the dangling tag (git push origin vX.Y.Z) or delete it if it was a mistake (git tag -d vX.Y.Z), then retry.
• Empty [Unreleased]: presence-only safety net, not a substitute for actually running the skill below as a real judgment step. Run the changelog-style skill against the commits since the last tag first — it's what actually makes the entries short, self-describing, free of implementation detail, and linked to their commits; the hook only confirms something is there, not that it follows that style. (Or re-run with CONFIRM_EMPTY_CHANGELOG=1 if this release genuinely has no user-facing changes, e.g. a pure dependency bump.)

When invoked as this skill, run these as explicit steps, not optional — don't rely on the preversion hook alone to catch a skipped one:

1. Invoke the changelog-style skill against the commits since the last tag; write/fix the [Unreleased] entries per its style rules. Leave them under [Unreleased] — do not hand-rename that heading to the target version; npm version (step 4) does that automatically now.
2. Run the docs-consistency-check skill — none of this is version-bump mechanics, so sync-version.mjs/version.test.ts don't catch drift here, and it accumulates silently across several PRs (manifest.json's tools/prompts arrays, server.json's environmentVariables/ description length, README's tool table, AGENTS.md's src/ tree). Note top_by_entity's text branches on media_type/genre, so re-check it whenever that branching logic changes, not just when its wording does.
3. Commit all of the above.
4. npm version <patch|minor|major> — preversion gate, then bumps + syncs every file + commits "release: vX.Y.Z" + tags vX.Y.Z.
5. git push --follow-tags — pushing the tag triggers .github/workflows/release.yml.

The tag push (v*) runs the Release workflow: build → test → pack .mcpb → extract CHANGELOG.md's section for this version (fails loudly, not silently, if that section is empty — the workflow's own safety net for whatever slipped past sync-version.mjs/preversion-check.mjs) → GitHub Release → npm publish (OIDC trusted publishing, with provenance, pinned to an exact verified-good npm version — no token; skipped without failing the job if this version is already on npm, so a re-run after a partial failure doesn't abort) → inject the just-packed .mcpb's SHA-256 into server.json (fails loudly if the injection didn't actually match a package, instead of silently leaving a stale hash) → publish to the official MCP Registry (mcp-publisher, pinned to an exact version + verified SHA-256 rather than latest — it runs with live OIDC publishing credentials, so it gets the same pin discipline as everything else in this job — GitHub OIDC). Never hand-edit the version in the derived files; bump package.json via npm version and let the hook sync the rest.