MCP server release automation

semantic-release vs changesets

Option A: semantic-release

semantic-release reads commit messages since the last release, determines the version bump (patch/minor/major), generates a CHANGELOG entry, creates a GitHub release, and publishes to npm — all on every merge to main.

// .releaserc.json
{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/changelog", {
      "changelogFile": "CHANGELOG.md"
    }],
    ["@semantic-release/npm", {
      "npmPublish": true
    }],
    ["@semantic-release/github", {
      "assets": []
    }],
    ["@semantic-release/git", {
      "assets": ["CHANGELOG.md", "package.json"],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }]
  ]
}

name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write       # Create tags and releases
      issues: write         # Comment on issues when closed by release
      pull-requests: write  # Comment on PRs
      id-token: write       # npm provenance

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0     # Full history required by semantic-release
          persist-credentials: false

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          registry-url: 'https://registry.npmjs.org'

      - run: npm ci

      - name: Run tests before release
        run: npm test

      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

Conventional commits for MCP server changes

semantic-release maps commit message prefixes to version bumps. Here's how to use them for MCP tool changes:

Breaking changes require the BREAKING CHANGE: footer in the commit body (not just the subject line):

feat!: rename get_document to fetch_document

BREAKING CHANGE: The tool name `get_document` has been renamed to
`fetch_document` to align with the new naming convention across all
MCP servers. Update your AI client configurations to use the new name.
Clients using `get_document` will receive a MethodNotFound error.

Closes #47

The ! after the type is shorthand for a breaking change and triggers a major bump. The BREAKING CHANGE: footer provides the migration message that ends up in CHANGELOG.md and the GitHub release notes.

Option B: changesets

Changesets is better suited for monorepos with multiple packages. Developers add a changeset file to each PR that describes what changed and at what severity level. A periodic "version" PR batches all changesets into version bumps and CHANGELOG entries.

# Install changesets
npm install -D @changesets/cli

# Initialize (creates .changeset/config.json)
npx changeset init

// .changeset/config.json
{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Developer workflow for each PR:

# 1. Make your changes
# 2. Add a changeset describing what changed
npx changeset add

# This prompts:
# ? Which packages would you like to include?
#   ◉ @yourscope/mcp-server-documents
# ? What kind of change is this for mcp-server-documents?
#   minor
# ? Please enter a summary for this change:
#   Add delete_document tool with 30-day soft-delete and undo_delete tool

# Creates .changeset/purple-tigers-sing.md with your summary
git add .changeset/
git commit -m "feat: add delete_document and undo_delete tools"

The changeset file sits in the PR alongside the code change:

---
"@yourscope/mcp-server-documents": minor
---

Add `delete_document` tool that soft-deletes documents with a 30-day recovery window,
and `undo_delete` tool that restores documents within that window. Both tools require
the `documents:write` scope. See the README for the updated tool schema.

When you're ready to release, run changeset version (usually via a bot PR) and then changeset publish:

name: Changesets release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          registry-url: 'https://registry.npmjs.org'

      - run: npm ci

      - name: Create release PR or publish
        uses: changesets/action@v1
        with:
          publish: npm run release  # Your script running changeset publish
          version: npm run version  # Your script running changeset version
          commit: "chore: version packages"
          title: "chore: release packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

The changesets GitHub Action creates a "Version packages" PR that accumulates all pending changesets. Merging that PR triggers the actual publish.

CHANGELOG format for MCP servers

Whether you use semantic-release or changesets, write CHANGELOG entries that communicate tool-level changes clearly — your users are developers who care about tool names and schema changes, not internal code changes:

## [2.0.0] - 2026-06-27

### BREAKING CHANGES
- **`get_document` renamed to `fetch_document`** — Update your AI client MCP config and any
  code that references this tool name. The inputSchema is unchanged.
- **`document_id` parameter type changed from `string` to `string (UUID format)`** — The
  server now validates UUID format and returns `isError: true` for non-UUID values.
  Previously any string was accepted.

## [1.3.0] - 2026-06-15

### New Tools
- **`delete_document`** — Soft-delete a document with a 30-day recovery window.
- **`undo_delete`** — Restore a soft-deleted document within its recovery window.

## [1.2.1] - 2026-06-10

### Bug Fixes
- **`search_documents`** — Fixed: tool returned `isError: true` when the query contained
  apostrophes. The query is now properly parameterized. (#52)

Deployed services (not npm packages)

If your MCP server is a deployed service (not an npm package), release automation is simpler. You don't need npm publish — you just need tagging and deployment:

name: Tag and deploy

on:
  workflow_dispatch:
    inputs:
      version_bump:
        description: 'Version bump type'
        required: true
        type: choice
        options: [patch, minor, major]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Bump version
        run: |
          npm version ${{ inputs.version_bump }} -m "chore(release): %s"

      - name: Push tag
        run: git push && git push --tags

      - name: Deploy
        run: |
          # Your deployment command
          # e.g., fly deploy
          # e.g., railway deploy

For deployed services, the key release artifact is the deployment itself — the version in package.json is informational. Use CI/CD to automate the deploy, and use the git tag for rollback (check out the previous tag and redeploy).

Snapshot testing as the release gate

Wire your tool schema snapshot tests as a required check before any release. If a tool name, description, or inputSchema changes unexpectedly, the snapshot test fails and blocks the release. This prevents accidental breaking changes from shipping without a major version bump:

// tool-schema.snapshot.test.ts
import { describe, it, expect } from 'vitest';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
import { createServer } from './index.js';

describe('Tool schema snapshot', () => {
  it('tools/list output matches snapshot', async () => {
    const [st, ct] = InMemoryTransport.createLinkedPair();
    const server = createServer({ db: mockDb });
    await server.connect(st);
    const client = new Client({ name: 'snap', version: '1' }, { capabilities: {} });
    await client.connect(ct);
    const { tools } = await client.listTools();
    // Snapshot fails if any tool name, description, or inputSchema changes
    expect(tools).toMatchSnapshot();
    await client.close();
  });
});

If the snapshot fails, the developer must run vitest --update-snapshots to accept the new schema — a deliberate action that forces them to think about whether the change is a patch, minor, or major version bump before committing.

Related pages

• Publishing MCP servers to npm
• MCP server monorepo patterns
• MCP server versioning and schema evolution
• MCP server CI/CD pipeline
• Snapshot testing MCP tool schemas
• MCP server schema evolution