Docs

Install

npx snapgauge@1 init --url https://mcp.example.com/mcp   # or --command / --fixture
npx snapgauge@1 record                                    # writes .snapgauge/<target>.snapshot.json
npx snapgauge@1 check                                      # probe live -> diff vs stored -> gate -> exit code

As a GitHub Action, against a snapshot already committed to your repo:

- uses: jamessuuu/snapgauge@v1
  with:
    config: snapgauge.config.json   # default
    fail-on: risky                  # default (SPEC §5)

Five-minute quickstart

The fastest way to see the engine work with nothing installed: /demo runs the real engine against fixture servers bundled into the page, entirely offline, in a Web Worker.

To run it on your own machine against a real MCP server, clone the repo — the CLI is not yet published (see the README status banner) — and record twice, then diff:

git clone https://github.com/jamessuuu/snapgauge
cd snapgauge && pnpm install && pnpm --filter snapgauge build

# record a baseline against a bundled fixture server (no MCP server of your own required)
node packages/snapgauge/dist/cli/index.js record demo --fixture clean@v1 --dir /tmp/snapgauge-demo

# record a "next release" of the same server — one tool removed, one new required argument
node packages/snapgauge/dist/cli/index.js record demo-v2 --fixture drift-breaking@v2 --dir /tmp/snapgauge-demo

# diff them — offline, no network
node packages/snapgauge/dist/cli/index.js diff /tmp/snapgauge-demo/demo.snapshot.json /tmp/snapgauge-demo/demo-v2.snapshot.json

This is the actual, verified output of that last command:

breaking   tool.input.required.added          tools.get_weather.inputSchema.required.date — input "date" is now required — a client recorded against the old contract does not send it
breaking   tool.removed                       tools.archive_note — tool "archive_note" was removed — a client holding the old contract will fail
risky      tool.description.changed           tools.get_weather.description — description changed — the trigger surface a model routes on (SPEC §5: risky, not cosmetic)
compatible tool.input.optional.added          tools.list_notes.inputSchema.properties.cursor — optional input "cursor" was added
cosmetic   serverInfo.version.changed         discover.serverInfo.version — serverInfo.version changed
cosmetic   tool.icons.changed                 tools.get_weather.icons — icons changed
6 findings (2 breaking, 1 risky, 1 compatible, 2 cosmetic); gate fail-on=risky -> DRIFT (exit 1)

Exit code 1: two findings (breaking and risky) are at or above the default gate. Fixing this means one of two things — the consumer decides the drift was intentional and runs check --update to accept the new snapshot, or the server owner reverts the change. See failure modes below for the full exit-code table.

Once published, replace the fixture shortcut above with a real target: npx snapgauge@1 init --url https://your-server/mcp writes snapgauge.config.json, then record and check run the identical pipeline against it.

Snapshot format

One file per target, committed to your repo: .snapgauge/<target>.snapshot.json. It records discover (supported versions, capabilities, serverInfo, instructions, cache hints), every tool (schema, annotations, icons, x-mcp-header bindings), resources, prompts, the observed behavior of any probes you declared, and the T-group transport assertion results.

Shape, not values, by default. A probed call's response is stored as a recursive type sketch — keys sorted, array element types unioned — not the actual values. Text content is stored as { type: "text", sha256 }. This is deliberate: shape-capture is what makes a snapshot safe to commit (it cannot leak a real customer's data out of a tool response) and stable against servers that return live data — weather, timestamps, ids. capture: "values" is opt-in per probe, for fixtures and for tools you know are deterministic.

Canonicalization is part of the format: keys sorted lexicographically, 2-space indent, a trailing newline — chosen for git-diff legibility over byte-canonical JCS (hashes are computed separately, over JCS bytes, for comparison). A snapshot is only ever comparable to itself: probeSpecHash (a hash of the target's declared probes) must match between two snapshots being diffed, or the run exits 4 rather than producing a silent partial comparison.

Diff taxonomy

Every difference between two snapshots is classified into exactly one of four tiers, direction-aware (old → new). The default gate is fail-on: risky — breaking and risky findings fail CI; compatible and cosmetic ones do not.

Descriptions and titles are risky, not cosmetic. Most diff tools would call a text rewrite cosmetic. This one does not: a tool's description and title are the trigger surface a model routes on when deciding which tool to call — rewrite the wording and an agent's behavior can change even though the schema did not move a single byte.

Compat + degradation checks

The official conformance suite answers whether a server obeys the 2026-07-28 revision right now. It does not check whether the server still works with a client one version back, whether it degrades correctly when a client declares fewer capabilities, or whether it is honest about which protocol versions it actually supports. That surface is what the compat engine covers.

A profile is (protocol version, client capabilities, extensions, header behavior). Built-ins include modern-full, modern-minimal (no extensions declared — the critical one), and legacy/no-capability variants. Every declared probe is replayed under every profile, and the response is scored per (tool × profile): ok | declined-correctly | degraded-reported | degraded-silent | violation. Any violation exits 3 — the server is wrong, not merely different, which is a different owner and a different fix than exit 1.

Full T-group (transport framing) and X-group (x-mcp-header validity) catalogs — 20 and 9 rule ids respectively — are in docs/RULES.md.

The board

/board publishes a refreshed, public read of 8–12 named MCP servers: era (modern-only / dual / legacy), advertised protocol versions, the T-group framing assertions, cache-hint presence, x-mcp-header validity, and the D-group checks reachable without tools/call. Unauthenticated and read-only — a server that requires auth is a row marked not tested (auth required), never guessed. A GitHub Actions job refreshes it weekly and commits boards/<date>.json; the commit history is the durable, un-fakeable record.

Disclosure policy. For any MUST-level violation, an upstream issue is filed first and the row records reportedAt; publication follows at least 7 days later (publishedAt). Findings are stated as neutral observations — "returns 200 on GET; the revision says 405" — never as scores, grades, or security claims.

boards/roster.json ships empty on purpose: which public servers belong on the board is a decision, not a default, so the page shows the honest empty state until that decision is made.

CI integration

action.yml is a composite GitHub Action. It runs snapgauge check --json against your committed config and snapshot, then reuses snapgauge report — the same pure reformatter the CLI itself uses — to turn the saved result into GitHub Actions annotations (::error:: / ::warning:: per finding) and a job-summary markdown table. No second live check runs to build the summary.

- uses: jamessuuu/snapgauge@v1
  with:
    config: snapgauge.config.json   # default
    fail-on: risky                  # default
    # target: my-server             # only needed when the config has more than one

Output: exit-code, the same value snapgauge check would exit with locally. A finding's location is a JSON path into the target's schema (e.g. tools.get_weather.description), never a source file position — the action does not fabricate one.

Failure modes

Exit codes:

The ugly paths, by situation: