Publishing and Release

This document explains the automated release and publication process for simap-mcp. Starting with version 1.2.2, the project migrated to a changesets-driven release flow. This process automates version bumping, changelog generation, and dual-registry publication to npm (general JavaScript ecosystem) and the MCP Registry (Claude-specific discoverability).

Changeset-Driven Release Flow

The project uses changesets to manage versioning and changelogs. This ensures that version numbers across package.json and server.json stay in lockstep and that releases are documented automatically.

The Changeset Lifecycle

1. Opt-in Changesets: Developers add a changeset file to their PR if it contains user-visible changes .
2. Automated PR Comments: The changeset-bot (referenced in .changeset/README.md) comments on every PR to show the current release status .
3. Version Packages PR: When a PR is merged to main, the release.yml workflow triggers changesets/action. If changesets are pending, it opens (or updates) a "Version Packages" PR. This PR consumes the changesets, updates versions, and populates CHANGELOG.md , .
4. Tag and Release: Merging the "Version Packages" PR triggers the final publication to npm and the MCP Registry via the release.yml workflow , .

Adding a Changeset

To record a change, run:

The CLI prompts for the bump level (patch, minor, or major) and a summary of the change . This creates a markdown file in the .changeset/ directory (e.g., .changeset/quiet-foxes-spin.md) which should be committed with the code changes .

Sources: , ,

Version Consistency

The simap-mcp project maintains version consistency across multiple files. Because changesets only natively manages package.json, a synchronization script is used to update the MCP Registry manifest.

Version Sync Script

The scripts/sync-server-json.mjs utility ensures that server.json never drifts from package.json . It reads the version from package.json and updates both the root version and the packages[0].version in server.json . It is invoked during the versioning step of the release workflow via npm run version-packages .

File	Version Field	Purpose
package.json	version	npm package version
server.json	version	MCP Registry server version
server.json	packages[0].version	npm package reference version

Diagram: Version Synchronization Flow

Sources: , ,

Release Workflow Architecture

The Release workflow executes on ubuntu-latest using Node.js version 24 and handles the entire CI/CD pipeline from linting to final publication , .

Workflow Execution Flow

Diagram: Release Workflow Pipeline

The workflow uses GitHub OIDC (OpenID Connect) for secure authentication to npm and the MCP Registry by requesting id-token: write permissions .

Sources:

Dual-Registry Publication

The system publishes to two distinct registries:

1. npm Registry:

   • Triggered by npm run release within the changesets action .
   • Uses NPM_CONFIG_PROVENANCE: "true" to establish a verifiable link between the package and the source repository .
   • Registry URL is set to https://registry.npmjs.org .

2. MCP Registry:

   • Triggered if steps.changesets.outputs.published == 'true' .
   • Dynamically installs mcp-publisher (version 1.7.9) and verifies its SHA-256 checksum .
   • Authenticates via github-oidc using the ./mcp-publisher login github-oidc command .
   • Publishes the server definition using the metadata defined in server.json, which includes the package identifier @digilac/simap-mcp and transport type stdio , .

Sources: ,

Release Permissions

The workflow operates with a strict permission set to ensure security and prevent recursive actions:

• contents: write: Required to create git tags and GitHub Releases .
• pull-requests: write: Required for the action to open the "Version Packages" PR .
• id-token: write: Required for OIDC authentication to npm and the MCP Registry .

A Personal Access Token (RELEASE_PAT) is used for checkout and the changesets action instead of the default GITHUB_TOKEN. This allows pushes to the changeset-release/main branch to trigger downstream pull_request workflows, which GitHub otherwise suppresses to prevent recursion , .

Sources: , ,