Ship to
Change tools without breaking published CLIs
Tool contractsRename, remove or reshape your MCP server's tools while every CLI already installed keeps working.
Available in Framework 0.18.0. Claude, ChatGPT and other assistants read your tools fresh every time, so they adapt to a change. A CLI you published keeps calling the server it was built against for months. A contract is what a CLI was built against: the tools’ names, inputs and outputs. Your server keeps only the current tools, and serves each older contract through a small adapter over them.
Is the change breaking?
Section titled “Is the change breaking?”| Breaking: bump the contract | Not breaking: nothing to do |
|---|---|
| A tool removed or renamed | A new tool |
| An input removed, renamed, retyped or newly required | A new optional input |
| An output reshaped: a field removed, renamed, retyped or moved | A new field in a result |
| A changed description, title, annotation or formatted text |
When unsure, make the change and run the snapshot tests: they fail on a break and pass on an addition.
Bump the contract
Section titled “Bump the contract”Change the tools
Change the tools to what you want now. Never keep a second copy of a tool.
Add an adapter for the old contract
Increase current by one. Under supported, describe what the old contract called each
current tool, took and answered:
import { tool, z } from "@flow-engineer/flow";import type { McpContracts } from "@flow-engineer/flow/mcp";
export const contracts: McpContracts = { current: 2, supported: { 1: { tools: { // By the current tool's name: what contract 1 called it, took and answered. get_order: { name: "order_status", input: z.object({ id: z.string() }), mapInput: ({ id }) => ({ order_id: id }), output: z.object({ order: orderSchema, ok: z.boolean() }), mapOutput: (order) => ({ order, ok: true }), }, }, // A tool contract 1 had and the current one does not. legacy: [tool({ name: "ping", description: "Check the server", input: z.object({}), run: () => "pong" })], }, }, // CLIs published before they named a contract, told apart by their clientInfo. pick: ({ name, version }) => (name === "acme-cli" && version.startsWith("0.1.") ? 1 : undefined),};Every adapter maps from the current tools. When you bump again, update each older adapter for the change too; the snapshot tests show which.
Serve the contracts and name one in the CLI
mcpServer({ name: "acme", version, tools, contracts });export const cli = defineCli({ name: "acme", contract: contracts.current, /* ... */ });Keep the number in one module both files import, so they never disagree.
Release the server, then the CLI
A CLI that names a contract the server does not know yet is refused.
A request is answered in the contract its client names (Flow’s CLI sends defineCli’s contract
in _meta["flow.engineer/contract"]), else the one pick chooses, else the current one. MCP hosts
name none, so they always get the current tools. tools/list says which contract it answered in,
and traces’ tool events carry it.
An adapter changes data, not words: an older contract’s tool answers with the current tool’s formatted text and descriptions, so those can change freely.
Expected result: an installed acme 0.1.x still runs acme order-status --id ord_1 and gets
{ order, ok: true }, while the new CLI and every assistant see get_order.
Snapshot every contract in your tests
Section titled “Snapshot every contract in your tests”Keep one saved file per contract served: its tools and a few sample calls against fixed backend answers. Cover each result shape: a read, a write, a preview and an error.
import assert from "node:assert/strict";import { readFileSync, writeFileSync } from "node:fs";import test from "node:test";import { contractProblems, contractSnapshot } from "@flow-engineer/flow/mcp";
for (const n of [1, 2]) test(`contract ${n} still holds`, async () => { const now = await contractSnapshot(server, { contract: n, token, calls }); const file = new URL(`../contracts/${n}.json`, import.meta.url); if (process.env.UPDATE_CONTRACTS === String(n)) writeFileSync(file, `${JSON.stringify(now, null, 2)}\n`); assert.deepEqual(contractProblems(JSON.parse(readFileSync(file, "utf8")), now), []);});For a contract that published CLIs reach through pick, take its snapshot with their client
({ name: "acme-cli", version: "0.1.4" }) instead of contract, so the rule is tested too.
Expected result: contractProblems returns [] for an addition, and lists each break (a
removed tool, a renamed field) otherwise. Never rewrite an old contract’s snapshot to make a test
pass: fix its adapter. Write a snapshot only for a new contract, before its first CLI release.
Drop an old contract
Section titled “Drop an old contract”Drop a contract only when no CLI that needs it is still in use: check that traces’ tool.end
events have not carried that contract for a while. Then remove its adapter, snapshot and test.
A CLI still on it gets one line and exit code 1:
This acme (0.1.4) is too old for acme. Run `acme update` to get the newest version.Thanks, we read every comment.