Versioning

mpak uses semantic versioning (semver) for all packages. Understanding how versions work helps you publish reliably and consume safely.

Semantic Versioning

Every package version follows MAJOR.MINOR.PATCH:

Bump	When	Example
MAJOR	Breaking changes (removed tools, changed behavior)	1.0.0 -> 2.0.0
MINOR	New features (added tools, new capabilities)	1.0.0 -> 1.1.0
PATCH	Bug fixes (no behavior change)	1.0.0 -> 1.0.1

For MCP servers, a “breaking change” means: tools were removed, tool schemas changed incompatibly, or required configuration changed.

Version Resolution

When you run a package without specifying a version, mpak resolves to the latest published version:

# Gets the latest version
mpak bundle run @org/server

# Gets a specific version
mpak bundle run @org/server@1.2.0

Note

If a version is already cached locally, mpak bundle run uses the cache. Use mpak bundle run @org/server --update to check for newer versions.

Version Pinning

Pin to a specific version in your MCP client configuration to ensure reproducible behavior:

{
  "mcpServers": {
    "postgres": {
      "command": "mpak",
      "args": ["bundle", "run", "@nimblebraininc/postgres-mcp@1.2.0"]
    }
  }
}

This guarantees the same version runs every time, regardless of newer releases.

When to pin:

• Production environments where stability matters
• CI/CD pipelines where reproducibility is critical
• When a specific version is known to work with your setup

When not to pin:

• Development environments where you want the latest features
• When you’re evaluating a package for the first time

Pre-release Versions

Note

Pre-release version support is planned. Check the CLI changelog for updates.

Version Immutability

Once a version is published, it cannot be overwritten. Publishing @org/server@1.0.0 a second time will be rejected by the registry.

This is critical for supply chain security: if you’ve verified that @org/server@1.0.0 is safe, you can trust that it won’t change.

To fix a bug in a published version, publish a new version:

1.0.0  <- published, immutable
1.0.1  <- bug fix

Deprecation

Deprecation marks a version or package as no longer recommended. Deprecated packages still work (they can be downloaded and run) but display a warning.

Note

The deprecation mechanism is being finalized. Currently, document deprecation in your package README and publish a new version with updated guidance.

Unpublishing

Note

Unpublishing policy is being finalized. Since bundles are hosted on GitHub Releases, deleting the release asset effectively removes the download. The registry metadata may persist to prevent name reuse.

Next Steps

Publishing How to publish your bundle

How the Registry Works Architecture and data flow

run CLI command for running bundles