Skip to content

Releases

JOONS MCP Diff 0.1.0 Preview

Pre-release

Choose a tag to compare

@dbdefault dbdefault released this 12 Nov 07:23

First preview of JOONS MCP Diff: detect MCP tool and schema changes before they break your AI agents.

Highlights

  • snapshot: read-only capture of an MCP server's tools/list over stdio or Streamable HTTP into a versioned, canonical JSON snapshot (stable ordering, byte-identical for identical servers). Snapshots never store commands, paths, URLs, headers, environment values or tokens.
  • compare: diff two snapshots and classify every change as BREAKING, NON_BREAKING or UNKNOWN - tool added/removed, description changes, required arguments, type narrowing/widening, enum and const changes, additionalProperties, numeric/string/array bounds, nested properties and items.
  • Conservative by design: $ref, oneOf, anyOf, allOf and other constructs that cannot be proven safe are reported as UNKNOWN, never guessed as NON_BREAKING. Rename candidates are shown as hints only.
  • Reports in terminal, Markdown and JSON; CI-friendly --fail-on breaking|unknown|any|none and exit codes 0 / 1 / 2 / 3 / 4.
  • Safety: only initialize, notifications/initialized, tools/list and ping are ever sent; secrets passed with --secret-env or --header NAME=ENVVAR are masked everywhere including encoded forms; size, depth, tool-count and time limits; child processes are cleaned up on every path.

Status

Preview: snapshot and result formats are versioned (schemaVersion 1) and may change before 1.0. Node.js 20, 22 and 24 on Linux, macOS and Windows (CI). Not published on npm.

Install: npm install -g github:dbdefault/joons-mcp-diff#v0.1.0

Part of the JOONS ecosystem. Pairs with JOONS MCP Probe: Probe checks one server now, Diff compares two points in time. See CHANGELOG.md and docs/COMPATIBILITY.md.