# How to verify an SDK, CLI and MCP server share one model version

> Fail a release when its SDK, CLI and MCP server came from different specs or models, with a check that reads each surface's generated code, not only a checksum.

Source: https://voxgig.com/howto/verify-surfaces-share-one-model-version

- Audience: agent-builder
- Level: intermediate
- Languages: typescript, go
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

Record the spec hash each surface was generated from, and also read the entity list each generated surface carries and compare it with the committed model. A spec checksum catches a surface built from an older spec, but passes one rebuilt after a local model edit. sdkgen's `doctor` exits 0 on both, `check-drift` fails both, and Hey API and openapi-typescript need a header stamp or `--check`.

---
## You will need

Node 22 or later, Go 1.24 or later to build the MCP server, and a project that generates more than
one surface. Verified 2026-11-21 against Node 22.23.5, Go 1.24.7, `@voxgig/create-sdkgen` 0.31.9,
`@voxgig/sdkgen` 4.44.3, `@voxgig/apidef` 8.32.4, `@hey-api/openapi-ts` 0.99.0 and
openapi-typescript 7.13.0. The sample holds a Bookshelf document in two versions: `api-v1.json`
with books, and `api-v2.json`, which adds `/authors`.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [A checksum recorded in CI artifacts](https://docs.github.com/en/actions/tutorials/store-and-share-data) | Any generator, with each surface built by its own job | It sees the spec alone, so a model or guide edit passes, and it names no cause | The generator reads files beside the spec |
| [Hey API output header stamp](https://heyapi.dev/docs/openapi/typescript/configuration/output) | A Hey API client, where `output.header` writes a line into every file | A stamp you design and a script you keep, and it records only what you hash | The spec is the only input, and openapi-typescript is already in use |
| [openapi-typescript --check](https://openapi-ts.dev/cli) | Types from openapi-typescript, checked against the spec in CI | Covers its own output alone, and answers yes or no with no reason | Several generators feed one release |
| [sdkgen check-drift](https://github.com/voxgig/sdkgen) | An sdkgen project, before a release | Deletes and regenerates every target, and needs the `.sdk` toolchain installed | You need a check that runs in seconds on every push |
| [voxgig-sdkgen doctor](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md) | Checking the `.sdk` copies against the scaffold | It never reads generated output, so it passed every release here | The question is which model a surface came from |

Voxgig maintains sdkgen. This page compares two of its commands with a checksum and the checks
of two other generators, and sdkgen is not the recommendation.

The checksum works for every generator and says nothing about why a surface differs. The two
generator-aware rows know their own output: openapi-typescript compares its types, and
`check-drift` compares every sdkgen target. Neither looks across tools, so the model check below
reads the surfaces directly.

## Build three releases from one project

`generate.sh` scaffolds one project from `api-v2.json` with four targets and commits it as
`release`:

```bash title="generate.sh"
cp "$here/api-v2.json" api.json
npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target ts --target go --target go-cli --target go-mcp > scaffold.log 2>&1
(cd bookshelf-sdk/.sdk && npm run generate > ../../generate.log 2>&1)
```

Two copies of it then regenerate every target, and the script puts back only their
`go-mcp/tools.go`.
`old-spec` swaps in `api-v1.json` first. `model-only` appends `guide-edit.aontu`, which switches
the `author` entity off, and leaves that edit out of the commit. For each surface the script
writes the artifact its CI job would: the sha256 of the spec it generated from.

No surface carries a version on its own. The model holds `main.kit.info.version`, `1.1.0`, but a
search of `ts/`, `go/`, `go-cli/` and `go-mcp/` found that version and the spec's hash in no file.
A check therefore has to read the surfaces themselves.

## Run four checks on each release

`verify.mjs` runs the checksum and the model check on each release and reads the `doctor` and
`check-drift` runs that `generate.sh` recorded:

```bash
node verify.mjs
```

```text output
release     doctor  spec checksum  surfaces vs model  check-drift
release     exit 0  ok             ok                 exit 0
old-spec    exit 0  FAIL go-mcp    FAIL go-mcp        exit 1 go-mcp/tools.go
model-only  exit 0  ok             FAIL go-mcp        exit 1 go-mcp/tools.go
```

The checksum caught the older spec and passed the model edit, which is the pitfall in one row.
`doctor` passed all three, because it compares the copies under `.sdk/` with the scaffold and
never opens `go-mcp/`. `check-drift` failed both bad releases and named the file.
`@voxgig/sdkgen` 4.45.0 with `@voxgig/apidef` 8.33.1 gave the same `doctor` and `check-drift`
results on all three releases.

## Read the entity list out of each surface

`checks.mjs` reads three files: the `entity` block in the SDK's `ts/src/Config.ts`, the
`case` lines in `go-cli/words.go`, and the enum each tool in `go-mcp/tools.go` passes to
`entitySchema`. A reader that finds nothing throws, so a changed template fails the check
instead of passing it.

```js title="checks.mjs"
  'go-mcp': (dir) => {
    const lists = [...read(dir, 'go-mcp/tools.go').matchAll(/InputSchema: entitySchema\[\w+\]\(([^)]*)\)/g)]
    if (lists.length === 0) throw new Error('no tool schemas in go-mcp/tools.go')
    const sets = lists.map((m) => sorted([...m[1].matchAll(/"([a-z0-9_]+)"/g)].map((x) => x[1])).join(' '))
    if (new Set(sets).size !== 1) throw new Error(`go-mcp tools disagree with each other: ${sets.join(' | ')}`)
    return found(sets[0].split(' ').filter(Boolean), 'go-mcp/tools.go')
  },
```

```bash
node verify.mjs generated/model-only
```

```text output
generated/model-only: model has author, book
  ts SDK  ok    author, book
  go-cli  ok    author, book
  go-mcp  FAIL  book
```

The command exits 1. `generate.sh` also built each MCP server and sent it `tools/list` over stdio;
both of its tools answered with an `entity` enum of `book` alone, and a test holds the reader to
those answers.[^1]

## Stamp the Hey API and openapi-typescript clients

Hey API and openapi-typescript generate from the spec alone, so the spec hash is the whole
question for them. Hey API's [`output.header`](https://heyapi.dev/docs/openapi/typescript/configuration/output)
option takes a function of the default header, and this configuration adds the hash:

```js title="openapi-ts.config.mjs"
export default {
  input: spec,
  output: {
    path: process.env.OUT ?? 'client',
    header: (ctx) => [...ctx.defaultValue, `// openapi-sha256: ${sha256}`],
  },
}
```

openapi-typescript needs no stamp: its [`--check`](https://openapi-ts.dev/cli) flag regenerates in
memory, compares with the file, and exits 1 when they differ, writing nothing. `stamps.mjs` runs
both against the release spec, with a client from each document:

```bash
node stamps.mjs
```

```text output
release spec api-v2.json, sha256 be941341ba80
  Hey API from api-v2.json             ok    4 files, be941341ba80
  openapi-typescript from api-v2.json  ok    --check exit 0
  Hey API from api-v1.json             FAIL  stamp 554e49a1d327, spec be941341ba80
  openapi-typescript from api-v1.json  FAIL  --check exit 1
```

## Check it worked

Ten tests cover the table, the readers, the recorded `tools/list` answers and both stamps:

```bash
node --test verify.test.mjs
```

```text output
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

Four of them break copies of `Config.ts`, `tools.go`, the artifacts and the Hey API files, and
expect each check to throw or fail. One drops the `old-spec` server into the good release on
purpose, and the model check names `go-mcp`.

## When it goes wrong

`doctor` reports `.sdk matches the scaffold` and the MCP server is still wrong. It compares only
the copies `target add` wrote under `.sdk/`. Gate the release on `check-drift`, or on a check that
reads the output.

`check-drift` reports `M go-mcp/tools.go` without saying why the file changed. It names the file, not the cause.
The model check names the surface and the missing entity, and the artifact hash says whether the
spec moved.

A release passes the checksum with a surface's artifact missing. A check that compares only the
artifacts it finds cannot see the one that is absent. `checksum()` names the surfaces a release
ships, and fails one with no artifact, a hash that is empty or malformed, or a file that names
another surface.

A Hey API file has no stamp. A file written by hand, or by an older configuration, has no header
line. `stamps.mjs` reads every file under the output, subdirectories included, and fails an
unstamped one rather than skipping it.

## When not to do this

Do not rely on a spec checksum alone for a generator that reads anything beside the spec. sdkgen
reads the guide and the project overlay, so a model edit leaves the hash unchanged.

Do not run `check-drift` on every push in a large project. It deletes and regenerates every target,
work the script's own comment puts at minutes. Run it before a release, and run the
model check on every push.

Do not take `doctor`'s exit 0 as evidence about generated output. Hey API is the better choice when
the release is one TypeScript client: one header option and a short script cover it.
openapi-typescript's `--check` suits a team that ships types only, because it needs no script at all.

## Related how-tos

- [Block a release when generated SDK files have drifted](/howto/block-a-release-when-generated-sdk-files-drift)

- [Find hand edits in a generated SDK before you regenerate](/howto/find-hand-edits-before-regenerating)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Rename a generated SDK method without editing the output](/howto/rename-generated-methods-without-editing-output)

- [Diff two semantic models from successive spec versions](/howto/diff-two-semantic-models-across-versions)

## Last verified

Verified 2026-11-21 against Node 22.23.5, Go 1.24.7, `@voxgig/create-sdkgen` 0.31.9,
`@voxgig/sdkgen` 4.44.3, `@voxgig/apidef` 8.32.4, `@hey-api/openapi-ts` 0.99.0, openapi-typescript
7.13.0 and TypeScript 5.9.3. Every output block is what the command preceding it printed. The
scaffold, the three generations, `doctor`, `check-drift` on 4.44.3 and 4.45.0, the MCP server
builds and the Hey API runs happened once, in `generate.sh`, and their output is committed. The commands here read that
output, and `stamps.mjs` runs openapi-typescript's `--check` live.

[^1]: The enum is plain [JSON Schema](https://json-schema.org/draft/2020-12/json-schema-validation#section-6.1.2):
the value must be an array, should have at least one element, and its elements should be unique. A
server with one entity fewer still satisfies all three, so validating the tool schemas cannot find
the gap.