← Back to Blog
tutorialpublishingversioningmaintenance

Publishing Updates to Your MCP Tool on mcpm

How to version, publish updates, write changelogs, and communicate changes to your MCP tool users.

·3 min read·xapable

Publishing Updates to Your MCP Tool on mcpm

Your tool is live. Now users depend on it. This guide covers updating responsibly.

Before You Publish an Update

1. Determine the Bump Type

Change Version Command
Bug fix Patch (1.0.0 → 1.0.1) mcpm-dev publish
New feature Minor (1.0.0 → 1.1.0) mcpm-dev publish --minor
Breaking change Major (1.0.0 → 2.0.0) mcpm-dev publish --major

2. Update package.json

<span class="hljs-punctuation">{</span>
  <span class="hljs-attr">&quot;name&quot;</span><span class="hljs-punctuation">:</span> <span class="hljs-string">&quot;weather-mcp&quot;</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">&quot;version&quot;</span><span class="hljs-punctuation">:</span> <span class="hljs-string">&quot;1.1.0&quot;</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">&quot;description&quot;</span><span class="hljs-punctuation">:</span> <span class="hljs-string">&quot;Get weather data — now with severe weather alerts&quot;</span>
<span class="hljs-punctuation">}</span>

3. Write a Changelog

Create CHANGELOG.md:

<span class="hljs-section"># Changelog</span>

<span class="hljs-section">## 1.1.0 (2026-07-07)</span>

<span class="hljs-section">### Added</span>
<span class="hljs-bullet">-</span> New <span class="hljs-code">`get_alerts`</span> tool for severe weather alerts
<span class="hljs-bullet">-</span> Support for airport weather codes (ICAO)
<span class="hljs-bullet">-</span> Celsius/Fahrenheit conversion in all tools

<span class="hljs-section">### Fixed</span>
<span class="hljs-bullet">-</span> City names with special characters now work correctly
<span class="hljs-bullet">-</span> Improved error messages for invalid API keys

<span class="hljs-section">### Changed</span>
<span class="hljs-bullet">-</span> Default forecast days reduced from 5 to 3 (less API usage)

4. Update README

Add new tools, update examples, refresh the description. mcpm reads your README on every publish.

Publishing

<span class="hljs-comment"># Patch (bug fix)</span>
mcpm-dev publish
<span class="hljs-comment"># → 1.0.0 → 1.0.1</span>

<span class="hljs-comment"># Minor (new feature)</span>
mcpm-dev publish --minor
<span class="hljs-comment"># → 1.0.0 → 1.1.0</span>

<span class="hljs-comment"># Major (breaking change)</span>
mcpm-dev publish --major
<span class="hljs-comment"># → 1.0.0 → 2.0.0</span>

What Happens on Publish

  1. CLI reads your package.json and README.md
  2. New version is pushed to mcpm.dev
  3. Old versions remain available (users can pin to them)
  4. Users see update notifications: mcpm-dev outdated

Communicating with Users

For Patch Updates

No communication needed. Users get the fix automatically on next update.

For Minor Updates

Update your README. Consider a short post on your tool's mcpm page.

For Major Updates

Warn users before breaking changes:

  1. Add deprecation notices in the previous minor version

    <span class="hljs-comment">// In your tool handler</span>
<span class="hljs-keyword">if</span> (args.<span class="hljs-property">oldParam</span>) {
  <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">&quot;⚠️ &#x27;oldParam&#x27; is deprecated. Use &#x27;newParam&#x27; instead.&quot;</span>);
}

  2. Write a migration guide

    <span class="hljs-section">## Migrating from v1 to v2</span>

<span class="hljs-section">### Parameter changes</span>
<span class="hljs-bullet">-</span> <span class="hljs-code">`oldParam`</span> → renamed to <span class="hljs-code">`newParam`</span>
<span class="hljs-bullet">-</span> <span class="hljs-code">`city`</span> is now <span class="hljs-code">`location`</span> (supports city names AND coordinates)

<span class="hljs-section">### New required config</span>
<span class="hljs-bullet">-</span> <span class="hljs-code">`API_VERSION=2`</span> must be set in env vars

  3. Keep old versions available
    Users can stay on v1: mcpm-dev add weather-mcp@1.9.0

Release Checklist

Before every publish:

  • package.json version updated
  • CHANGELOG.md has this version's entries
  • README.md reflects current features
  • All tests pass: npm test
  • Manual test with real MCP client
  • Breaking changes have migration guide
  • Deprecated features logged with warnings

Rollback Plan

If an update causes issues:

<span class="hljs-comment"># Revert to previous version</span>
mcpm-dev publish --version 1.0.0

This republishes the old version as the latest. Users can then:

mcpm-dev update weather-mcp

Automating with GitHub Actions

<span class="hljs-comment"># .github/workflows/publish.yml</span>
<span class="hljs-attr">name:</span> <span class="hljs-string">Publish</span> <span class="hljs-string">to</span> <span class="hljs-string">mcpm</span>
<span class="hljs-attr">on:</span>
  <span class="hljs-attr">push:</span>
    <span class="hljs-attr">tags:</span>
      <span class="hljs-bullet">-</span> <span class="hljs-string">&#x27;v*&#x27;</span>

<span class="hljs-attr">jobs:</span>
  <span class="hljs-attr">publish:</span>
    <span class="hljs-attr">runs-on:</span> <span class="hljs-string">ubuntu-latest</span>
    <span class="hljs-attr">steps:</span>
      <span class="hljs-bullet">-</span> <span class="hljs-attr">uses:</span> <span class="hljs-string">actions/checkout@v4</span>
      <span class="hljs-bullet">-</span> <span class="hljs-attr">uses:</span> <span class="hljs-string">actions/setup-node@v4</span>
      <span class="hljs-bullet">-</span> <span class="hljs-attr">run:</span> <span class="hljs-string">npm</span> <span class="hljs-string">ci</span>
      <span class="hljs-bullet">-</span> <span class="hljs-attr">run:</span> <span class="hljs-string">npm</span> <span class="hljs-string">test</span>
      <span class="hljs-bullet">-</span> <span class="hljs-attr">run:</span> <span class="hljs-string">npx</span> <span class="hljs-string">mcpm-dev</span> <span class="hljs-string">publish</span>
        <span class="hljs-attr">env:</span>
          <span class="hljs-attr">MCPM_TOKEN:</span> <span class="hljs-string">${{</span> <span class="hljs-string">secrets.MCPM_TOKEN</span> <span class="hljs-string">}}</span>

Tag a release on GitHub, and it auto-publishes to mcpm.

Publishing is a conversation with your users. Be thoughtful, be transparent, and keep your changelog honest.

#MCP #Tutorial #Publishing #Versioning #mcpm

← Back to all posts