Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Releases and versioning

This page explains what the crate’s version numbers promise, which Rust versions it supports, how a release is made and published, how this site is published, and which versions receive fixes. What changed in each version is in the changelog.

Versioning

mcp-server-core follows Semantic Versioning, and its changelog follows Keep a Changelog.

Version changeBefore 1.0Example
MinorMay change the API0.1.0 to 0.2.0
PatchDoes not change the API in a way that breaks your code0.1.0 to 0.1.1

From 1.0, only a major version may break the API. Until then, depend on a minor version and read the changelog before moving to the next:

[dependencies]
mcp-server-core = "0.4"

Cargo reads "0.4" as >=0.4.0, <0.5.0: you get patch releases with cargo update, and never a new minor version without changing the requirement.

An upgrade can affect a running server as well as your code. The 0.1.0 entry, for example, says that tokens issued by the servers’ earlier copies of this code lack the new claims, so everyone signs in once more after upgrading. Read the Changed section before upgrading a deployed server.

Lower-level API lists the #[non_exhaustive] types, which later versions can extend without a breaking change.

rmcp and axum

The crate’s API includes types from rmcp and axum, re-exported as mcp_server_core::rmcp and mcp_server_core::axum. Their versions are part of this crate’s compatibility:

DependencyRequirement in Cargo.tomlAccepts
rmcp~3.9.03.9.0 and later 3.9 patch releases, never 3.10
axum0.8.90.8.9 and later 0.8 releases, never 0.9

rmcp is held to one minor version on purpose. The policy wrapper forwards every method of rmcp’s ServerHandler trait to your handler, so a new rmcp minor version, which may add or change methods, needs a release of this crate that forwards them too. This crate therefore follows rmcp’s minor versions: moving to a new one is a new minor version here. Use rmcp through the re-export rather than adding it to your own Cargo.toml, so the versions always match.

Minimum supported Rust version

The minimum supported Rust version (MSRV) is 1.88, set as rust-version in Cargo.toml. The crate uses the 2024 edition, which needs Rust 1.85, and let chains (if let ... && let ...), which need Rust 1.88.

The msrv CI job runs on every pull request and every push to main. It reads rust-version from Cargo.toml, installs that toolchain and runs, with RUSTUP_TOOLCHAIN set to it:

cargo check --lib --all-features --locked
cargo check --lib --no-default-features --locked

Inside the repository, rust-toolchain.toml pins Rust 1.99.1 and takes precedence over rustup’s default toolchain, which is why the job sets RUSTUP_TOOLCHAIN. To check the library on the minimum supported version yourself, name the toolchain, which also takes precedence over the file:

rustup toolchain install 1.88
cargo +1.88 check --lib --all-features --locked
cargo +1.88 check --lib --no-default-features --locked

Only the library is meant to build at the MSRV. Tests, examples and the development tools use the toolchain pinned in rust-toolchain.toml, currently Rust 1.99.1, which rustup installs when you build in the repository.

Supported versions

Until 1.0, only the latest minor version receives security fixes. Fixes are released as patch versions and announced in a GitHub security advisory once a fixed version is available.

VersionSupported
0.4.xYes

To report a vulnerability, see Security model.

The release process

A release is a version bump merged to main. The steps, from the repository’s CONTRIBUTING.md:

  1. Move the entries under ## [Unreleased] in CHANGELOG.md to a new heading ## [X.Y.Z] - YYYY-MM-DD with today’s date (and, as for [0.1.0], a link for it at the bottom), and set version in Cargo.toml to X.Y.Z.
  2. Merge the change to main. The release workflow tags the merge commit vX.Y.Z and releases it.

Pushing a vX.Y.Z tag by hand also starts a release, for example to release a commit other than the head of main:

git tag v0.1.1
git push origin v0.1.1

What the release workflow does

The release workflow (.github/workflows/release.yml) starts on a push to main that changes Cargo.toml, on a pushed tag that matches v*.*.*, and by hand from the Actions tab (Run workflow on main), for example to retry a failed release. On Ubuntu with Rust 1.99.1, it:

StepWhat happensFails with
Version to releaseThe tag is v followed by version from Cargo.toml. On main, when the GitHub release and the crates.io version both exist, the workflow stops here: <tag> is already released: nothing to do. On a pushed tag, the tag must match.tag <tag> does not match Cargo.toml version <version>, or releases run only from main or a tag for a manual run on another branch
Testscargo test --all-features --locked.Any failing test
Release notesTakes the section of CHANGELOG.md under ## [X.Y.Z], up to the next ## [ heading or the link definitions at the bottom.no CHANGELOG.md section for <tag> when the section is missing or empty
GitHub releasegh release create titled with the tag, with those notes. On a push to main this also creates the tag on the merge commit. When a release for the tag already exists, for example on a re-run, it says so and goes on.A gh error
crates.ioGets a short-lived token through trusted publishing (rust-lang/crates-io-auth-action), then cargo publish --locked.An auth error when the crate has no trusted publisher for this workflow

The crates.io steps skip themselves when crates.io already has the version (X.Y.Z is already on crates.io: skipping). If the workflow fails after the GitHub release was created, re-run it: the release step and, once the version is on crates.io, the publish step both skip what is already done.

The package contains src/, examples/, the pages of this site, the README, changelog, security policy and both licences, as listed under include in Cargo.toml. CI runs cargo package --locked on every pull request and push to main, so a packaging problem shows up before a release is tagged.

After publishing

docs.rs builds the API documentation for the new version by itself, with every feature on ([package.metadata.docs.rs] in Cargo.toml). Each version stays available at https://docs.rs/mcp-server-core/<version>/.

This site

This site is built from docs/ with mdBook and published to GitHub Pages at https://trozz.github.io/mcp-server-core-rs/ by the docs workflow (.github/workflows/docs.yml):

  • It runs on every push to main, and can be started by hand; it builds only from main.
  • It installs the pinned tools with scripts/install-docs-tools.sh, builds with scripts/build-docs.sh, which also checks every internal link and anchor, and deploys docs/book to the github-pages environment.
  • A run in progress is never cancelled: a newer push waits for it, and GitHub keeps only the newest waiting run, so the last push to main is the one published.

The site therefore describes main, which can be ahead of the latest release on crates.io. For the exact API of the version you depend on, use its docs.rs page. Contributing explains how to build the site locally.

Repository setup (maintainers)

  • crates.io: in the crate’s settings on crates.io, add a trusted publisher for GitHub with owner Trozz, repository mcp-server-core-rs and workflow release.yml. No token secret is needed.
  • Workflow permissions: every workflow defaults to contents: read. The release job requests contents: write to create the tag and GitHub release, id-token: write for trusted publishing, and the docs deploy job pages: write and id-token: write.
  • GitHub Pages: under Settings > Pages, the source must be GitHub Actions for the docs workflow to publish.