@zevruna/diff

Classified schema diffs for MCP tool contracts.

The diff engine behind Zevruna, as a standalone library. Give it two contract snapshots and it tells you what changed and whether the change breaks your callers. Pure functions, zero I/O.

Install

npm i @zevruna/diff

Usage

import { diffSnapshots, worstSeverity } from "@zevruna/diff";

const changes = diffSnapshots(before, after);

worstSeverity(changes); // "breaking" | "risky" | "safe"

changes.filter((c) => c.severity === "breaking");
// [{ kind: "input_property_removed", severity: "breaking", tool: "create_contact",
//    path: "inputSchema.properties.customer_id",
//    detail: "Field `customer_id` was removed from `create_contact` input — consumers still
//             sending it may be rejected or silently ignored." }]

Severity

breaking — a call that used to be valid can now fail, or a value your code reads is gone: tool removed or renamed, input field removed or renamed, a new required field, a field that became required, a type change, an enum value removed or narrowed, a resource or prompt removed.

risky — legal, but it changes what the model sees or does: a new optional field, a new enum value, a changed default, a substantially rewritten description (≥25% word delta).

safe — a tool, resource, prompt or optional field added, a requirement dropped, a cosmetic description edit. Description changes below a 2% word delta aren't reported at all.

Thresholds are exported as DESCRIPTION_RISKY_THRESHOLD and DESCRIPTION_NOISE_FLOOR.

Also exported

canonicalize, contentHash, schemaHash, stableStringify, resolveImpacts, checkManifest, wordDelta, plus the Snapshot, Change, Severity, ChangeKind, Manifest and Impact types.

In your terminal

The same classification from the CLI, exiting 1 on any breaking change:

npx zevruna diff before.json after.json

License

MIT