Evaluate release-please for automated versioning and changelog

[dangrondahl]

Description

Consider adopting release-please to automate version bumps, generate a CHANGELOG, and cut releases from Conventional Commits.

The repo is a good fit on paper: commit messages and PR titles already follow Conventional Commits, and squash-merging means PR titles become the commit messages release-please reads.

What we'd gain

• A CHANGELOG. We have none. Releases currently rely on generate_release_notes in release.yml, which produces a raw commit list.
• No manual bump/tag sequence. Today: npm version → PR → merge → tag → push. release-please opens a release PR; merging it creates the tag and Release.
• src/version.ts upkeep. extra-files with an x-release-please-version annotation can maintain it, overlapping with scripts/sync-version.mjs. Worth keeping the script regardless, since it also covers local npm version bumps.

Three things that must be handled, or releases break

1. Tag-triggered publishing stops firing.
release.yml runs on: push: tags: ['v*']. release-please creates that tag using GITHUB_TOKEN, and events triggered by GITHUB_TOKEN do not start new workflow runs. The tag and Release would appear and npm publish would silently never run. Fix: publish inside the release-please workflow gated on its release_created output, or drive the tag with a PAT / GitHub App token.

2. That collides with the npm trusted publisher.
The trusted publisher is bound to kosli-dev/mcp-server → release.yml. If publishing moves to a different workflow file, the OIDC binding no longer matches and publishing fails until it's updated on npmjs.com. Provenance depends on this, so it needs coordinating across both systems (see #4, #35).

3. Catalog updates would never trigger a release.
update-catalog.yml hardcodes chore: regenerate catalog from OpenAPI spec, and chore doesn't bump anything. But a catalog change is exactly what shipped as 0.5.0 — new list_flows filters, a removed action. Those would accumulate unreleased. Retitling that commit feat: is arguably more honest anyway.

To verify before committing to it

• Signed commits. main requires them. release-please commits via the GitHub API, so its commits should be signed as github-actions[bot] — the same mechanism that fixed ci: sign catalog update commits so they satisfy the main ruleset #19 — but confirm on a test PR rather than assuming.
• Pre-1.0 behaviour. We're on 0.x; check how it treats breaking changes (conventionally a minor bump below 1.0) and that it matches our intent.
• Interaction with the pull_request ruleset — the release PR needs the same approval as any other, which is fine, just one more PR to review.

Assessment

Five releases in three months, and the manual flow works and is documented in CLAUDE.md. The honest gain is the changelog plus never forgetting a step — real but modest against a publish-path restructure and an npm binding change. Worth doing if release cadence picks up or we want a user-readable changelog; otherwise the current setup is cheaper than the migration.

Filed so that whoever picks it up doesn't discover point 1 by shipping a release that never reaches npm.