> ## Documentation Index
> Fetch the complete documentation index at: https://flow.engineer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Change tools without breaking published CLIs

> Rename, 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](https://flow.engineer/docs/cli.md) 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?

| 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](#snapshot-every-contract-in-your-tests):
they fail on a break and pass on an addition.

## Bump the contract

**1. Change the tools**

Change the tools to what you want now. Never keep a second copy of a tool.

**2. 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:

```ts src/contracts.ts
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.

**3. Serve the contracts and name one in the CLI**

```ts src/mcp.ts
mcpServer({ name: "acme", version, tools, contracts });
```

```ts src/cli.ts
export const cli = defineCli({ name: "acme", contract: contracts.current, /* ... */ });
```

Keep the number in one module both files import, so they never disagree.

**4. 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

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.

```ts test/contracts.test.ts
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

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:

```text
This acme (0.1.4) is too old for acme. Run `acme update` to get the newest version.
```

> [!TIP]
>
> Coding agents get this procedure as the `flow-framework-contracts` skill, installed by `flow new`.
