snapgaugesnapgauge

record · diff · gate

A tool vanished from the contract. CI exits 1.

Snapshot an MCP server's schema and behavior, then fail CI when the next version moves. Fixture servers are in the repo, so it runs offline.

Run the offline demoCheck a live server

✓ fixtures in the repo✓ runs offline✓ no LLM anywhere

clean@v1 → drift-breaking@v2build-time run
1exit code

gate fail-on=risky

This build would be blocked.

6 findings in this diff

2breaking
1risky
1compatible
2cosmetic
breakingtool.removedtools.archive_note

tool "archive_note" was removed — a client holding the old contract will fail

A real diff from the committed fixtures. Run this pair yourself — same engine, in your browser, offline.

2breakinga consumer will break
1riskythe routing surface moved
37diff rulesone catalog, generated
0network callsthe demo runs offline

the mechanism

How a diff gets a tier

snapgauge record writes a snapshot of a server's schema and observed behavior. snapgauge check records again and sorts every difference onto one of four rungs. The four rungs above are the clean@v1 → drift-breaking@v2 diff, read four ways.

generated from the real rule registryCI regenerates and diffs it on every push
The four diff tiers, as a ladder A ladder with four rungs, breaking at top through cosmetic at bottom. Each rung names one real rule id from the registry: breaking carries tool.removed, risky carries tool.description.changed, compatible carries tool.input.optional.added, cosmetic carries tool.icons.changed. All four are findings from the same clean@v1 versus drift-breaking@v2 fixture diff shown elsewhere on this page. The risky rung is the only amber rung: description and title text is the surface a model routes on, so a description change is classified risky, not cosmetic. A dashed line between the risky and compatible rungs marks the default CI gate — breaking and risky fail the build, compatible and cosmetic pass it. default gate — fail-on: riskyabove: fails CI · below: passesbreakingtool.removedA tool present in the old contract is gone— clients holding the old contract fail.riskytool.description.changedDescription text changed— the trigger surface a model routes on (never cosmetic).compatibletool.input.optional.addedA new optional input appeared— old calls remain valid.cosmetictool.icons.changedTool icons changed.

risky is the rung most diff tools would call cosmetic: description and title text is the surface a model routes on, so a rewrite is treated as a behavior change. Full catalog (37 rules): /docs.

watch it run

Not a mockup.

Recorded against the deployed site at snapgauge.vercel.app/demo. It picks the clean@v1 → drift-breaking@v2 pair shown above, runs it, and shows the same tiered findings table and exit code.

Text alternative: the recording opens /demo, selects the drift-breaking@v2 fixture pair, presses Run, and shows the resulting findings table — 2 breaking and 1 risky findings, exit code 1. No audio.

not a replacement

Complementary to the official conformance suite

The official MCP conformance suite answers whether a server obeys the spec today. snapgauge does not re-implement it — it answers a different, narrower question.

Question

official suite

Does this server obey the spec, right now?

snapgauge

Did THIS server change vs. its own recorded contract — and how does it behave one client-version back?

Method

official suite

Scenario-based, wire-schema validated, run fresh every time.

snapgauge

Recorded snapshot diff (self-vs-self over time) + degradation profiles across client capability sets.

Output

official suite

Pass/fail against the 2026-07-28 revision.

snapgauge

Tiered findings (breaking/risky/compatible/cosmetic) with an exit code CI can gate on.

When it runs

official suite

Any time, against any server, no history required.

snapgauge

After the first `snapgauge record` — it needs a prior snapshot to compare against.

what CI reads

Exit codes

1 vs 3 is deliberate: different owner, different fix.

codemeaningwho fixes it
0Clean — no findings at/above the gate.Nobody — nothing to do.
1Drift at/above the gate (--fail-on, default risky).The consumer: review the diff, then either --update the stored snapshot (drift was intentional) or fix/pin the server.
2Probe/connection failure (unreachable, auth, timeout, malformed response).The consumer's environment/config — check the target URL, credentials, and network reachability.
3Compat/degradation violation — the server is wrong, not merely different.The server's maintainer — it violates the 2026-07-28 revision's degradation contract.
4Usage/config/snapshot-format error (incl. probe-spec mismatch: re-record).The consumer — fix the CLI invocation or config, or re-run snapgauge record.
5Internal error — a bug in snapgauge itself.snapgauge's maintainer — please report it (SECURITY.md).

one command

Install

bash
npx snapgauge@1 check

the shape of it

A sharp tool: one job, done deterministically. No dashboard, no accounts, no LLM anywhere in the product. Five-minute quickstart, the snapshot format, failure modes, and limitations are in the docs.