MCP Server Trello Release

mcp-server-trello-release

The release rules for @delorenj/mcp-server-trello. This repo publishes to two registries off automation triggered by a PR merge — so a release is not "run publish", it is "get main correct and merge the PR". Get the version parity or the trigger semantics wrong and you desync npm from the MCP registry, or ship a server that lies about its own version.

Every fact below was VERIFIED on 2026-07-16 against this repo. The maintainer pivots fast — re-check the workflow files and versionbump.js before leaning on any of it. llr is the recency compass.

The one thing that breaks every time: version parity

There are four version literals in this repo, not one, plus the changelog. They must all read the same X.Y.Z before you open the release PR:

The trap: bun run versionbump:{patch,minor,major} (scripts/versionbump.js) only edits #1. It silently leaves #2, #3, #4 behind. That is exactly how server.json drifted to 1.5.6 while npm was on 1.7.1, and how the McpServer literal sat at 1.7.1 into a 1.8.0 cut. Never trust versionbump alone.

Use the bundled helper instead — it sets all four literals at once and flips the changelog heading:

.agents/skills/mcp-server-trello-release/scripts/set-version.sh 1.8.0

Then always confirm parity before committing:

.agents/skills/mcp-server-trello-release/scripts/parity-check.sh

parity-check.sh exits non-zero if any of the five disagree. It is safe to wire into CI as a release gate.

The trigger map — what publishes, and when (VERIFIED from .github/workflows/)

Publishing is tokenless (Trusted Publishing / OIDC), since 2026-07. npm's package settings list delorenj / mcp-server-trello / publish-npm.yml as a trusted publisher, so CI mints a short-lived OIDC token per run instead of a stored secret. This replaced the NPM_TOKEN path, which npm is deprecating: 2FA-bypass tokens lose sensitive actions ~Aug 2026 and direct publish ~Jan 2027. Requirements the workflow must keep satisfying: id-token: write, npm CLI ≥ 11.5.1 (we npm install -g npm@latest), Node ≥ 22.14.0, and no NODE_AUTH_TOKEN. The trusted-publisher config fields are case-sensitive and exact — org delorenj, repo mcp-server-trello, workflow filename publish-npm.yml (no path, keep the .yml), environment blank.

Read the consequences carefully — they define the whole procedure:

• Merging the release PR is the publish event. The merge closes the PR (→ npm publish) and pushes the version files to main (→ registry publish). There is no separate "publish" step and no local npm publish.
• workflow_dispatch is the re-publish escape hatch. If the npm job fails for an infra reason (a bad CI run, a first-time trusted-publisher config), fix it and re-run publish-npm.yml directly on main — gh workflow run publish-npm.yml — instead of re-merging. It publishes whatever version package.json on main currently declares. (npm rejects a re-publish of an already-published version, so this is safe to retry.)
• Release only through a PR merge — never direct-push a bump to main. A direct push fires the registry publish (paths match) but not the npm publish (needs a PR-close event). That desyncs the two registries. Always PR.
• A raw annotated git tag is side-effect-free. No workflow triggers on tag pushes — only on a GitHub Release object. So you can (and must) push vX.Y.Z after merge with zero risk of a double-publish.
• Do NOT gh release create under the current config. A GitHub Release emits release: published, which re-runs publish-registry.yml for a version already pushed via main → a red, duplicate publish. Push the raw tag instead. (To make GitHub Releases safe, see Recommended hardening below.)

Semver rules for this repo

• patch (x.y.Z) — bug fix, no surface change.
• minor (x.Y.0) — new tool, new optional param, additive behavior. Most releases here.
• major (X.0.0) — a breaking change to the published tool surface: removing/renaming a tool that shipped, or making a previously-optional param required. Removing a tool that never shipped to npm is not breaking (that was the 1.8.0 dead-tool cleanup — minor, not major).
• Tool count is a moat concern (selection accuracy degrades past ~20 tools). A release that removes a tool is healthy; note it in the changelog Removed.

The procedure

Phase 0 — Preflight (on a release branch, never on main)

git branch --show-current            # must NOT be main
git status --short                   # must be clean

Phase 1 — Set the version everywhere

scripts/set-version.sh <X.Y.Z>       # writes literals 1–4 and flips the changelog heading

Or by hand: edit package.json, both server.json fields, the McpServer literal in src/index.ts, and the changelog heading. Then run parity-check.

Phase 2 — Finish the changelog

set-version.sh turns ## [Unreleased] into ## [X.Y.Z] - <today>. Fill in the Added / Changed / Fixed / Removed bullets (Keep a Changelog format). Get today's date from date +%F.

Phase 3 — Gates (mirror CI locally, in order)

scripts/parity-check.sh              # all 5 versions agree
npm run typecheck                    # 0 errors (guards the zod v4 / SDK types path)
npm run test:coverage                # green; autoUpdate may ratchet vitest.config.ts — COMMIT that bump
npm run build                        # bun build succeeds
# stdio smoke: server boots and lists the expected tool count

Phase 4 — Commit

git add -A && git commit -m "chore(release): <X.Y.Z>"

Keep the version files + the ratcheted vitest.config.ts in this commit.

Phase 5 — Open the PR

git push -u origin <branch>
gh pr create --base main --title "Release <X.Y.Z>: <headline>" --body-file <notes>

State in the PR body that merging publishes (npm + registry). Wait for ci.yml (the coverage gate) to go green.

Phase 6 — Merge = publish

Merge the PR. This auto-fires publish-npm.yml and publish-registry.yml. Watch both Actions runs to green before declaring the release done.

Phase 7 — Tag (after merge, on main)

git checkout main && git pull
git tag -a v<X.Y.Z> -m "v<X.Y.Z>"    # annotated; message can carry the changelog highlights
git push origin v<X.Y.Z>             # raw tag push — no workflow side effects

This repo's tags stopped at v1.6.1 (1.7.0/1.7.1 shipped untagged). From now on, every release gets an annotated vX.Y.Z tag.

Phase 8 — Verify

npm view @delorenj/mcp-server-trello version            # == X.Y.Z
git ls-remote --tags origin | grep v<X.Y.Z>             # tag present
gh run list --workflow=publish-npm.yml --limit 1        # green
gh run list --workflow=publish-registry.yml --limit 1   # green

Optionally confirm the MCP registry entry updated at https://registry.modelcontextprotocol.io for io.github.delorenj/mcp-server-trello.