Upgrading a server
Covers FrontMCP 1.12.2 as of
Upgrade the FrontMCP packages together, then compare the client contract you depend on. The SDK release, the MCP protocol revision and the client version are three separate values. Documentation hashes show which pages changed.
Identify the installed release
Read the resolved SDK package in your project, or use the docs server's resolve_version. In a monorepo with several installations, pass the npm/pnpm workspace path or an exact installedVersion. When a lockfile is ambiguous, the resolver returns an error. It doesn't pick the first package record. A manifest range lists the versions allowed, not the one installed.
{ "workspace": "packages/api", "packageJson": "<file text>", "lockfile": "<file text>" }
Keep lockfiles local, unless you choose to share the parts that matter. The resolver needs no credentials, and not your whole repository.
Read the changes and establish a baseline
Pin a docs endpoint to the installed version. Call whats_changed with the old and the target release. Then read the reference pages for the APIs that changed. Check companion plugins and adapters too. Before you change dependencies, run your existing contract, access and deployment checks. Save their output with secrets and private data removed, along with the versions and the date.
How often releases ship doesn't tell you whether an API changed. So for each change that affects your server, record four things: the old behavior, the new behavior, whether application or client code must change, and the migration check that covers it. Keep additions, fixes and intended breaking changes apart. The production evaluation explains what release and adoption signals can and can't tell you.
Reproduce a bounded upgrade
The repository's upgrade check uses the reporting download as its fixture. It installs FrontMCP 1.9.2, runs the fixture's tests and captures its tool contracts. Then it installs the documented release and runs the same checks again. It keeps the output from before and after, and reports any differences.
node scripts/check-upgrade.mjsThe check installs dependencies in a temporary project. It needs network access to npm, and Node.js 24 or later. Its README and script are in the evaluation download.
Inspect the recorded contract
The before/after record names both releases. It lists the actual schemas, a successful result and an expected refusal. It also records whether the selected contract changed. The same fixture code is installed separately with each set of dependencies.
Upgrade and roll back deliberately
Update the SDK, CLI, testing and companion packages to releases that work together. Regenerate the lockfile, run the contract and auth checks, and build for your target. In preview, try real client connections and widget behavior. Keep the previous build artifact, configuration and lockfile at hand. Database migrations need their own plan to roll back or recover forward.
If you change a contract on purpose, record the result before and after, and update the affected clients yourself. See Versions and release notes.