jsondiff

jsondiff

Compare two JSON documents deeply, without worrying about key or array order. jsondiff walks both documents at every level and reports each difference it finds — a key that exists on one side only, a value that differs, or a value whose JSON type differs — with the exact dotted path of the difference, a per-kind summary, and an overall identical / different status.

It is pure local computation: no upstream API, no account, no API key, no configuration.

CLI

npx @reneturcios/jsondiff compare '<json1>' '<json2>'
npx @reneturcios/jsondiff compare --file1 a.json --file2 b.json
npx @reneturcios/jsondiff --version

Both inputs are JSON strings; with --file1 / --file2 they are read from files instead. Output is the comparison report as JSON:

{
  "status": "different",
  "total_differences": 2,
  "differences": [
    {
      "type": "missing_key",
      "path": "root.user.settings.language",
      "key": "language",
      "file1_value": "tr",
      "message": "Key 'language' exists in file1 but missing in file2"
    },
    {
      "type": "value_mismatch",
      "path": "root.user.name",
      "file1_value": "Ahmet Yılmaz",
      "file2_value": "Mehmet Demir",
      "message": "Value mismatch at 'root.user.name'"
    }
  ],
  "summary": {
    "missing_keys": 1,
    "extra_keys": 0,
    "value_mismatches": 1,
    "type_mismatches": 0
  }
}

Exit codes: 0 on success, 1 on a runtime error (including an input that is not valid JSON — the error names the input), 2 on a usage error.

MCP server

The same bin serves a stdio MCP server:

npx -y @reneturcios/jsondiff mcp

MCP client config:

{
  "mcpServers": {
    "jsondiff": {
      "command": "npx",
      "args": ["-y", "@reneturcios/jsondiff", "mcp"]
    }
  }
}

Tools

• compare_json — Compare two JSON strings deeply and order-independently, and report every difference (missing keys, extra keys, value mismatches, type mismatches) with full path tracking.
  • json1 (string, required) — the first JSON document, as a JSON string
  • json2 (string, required) — the second JSON document, as a JSON string

Difference kinds: missing_key (in the first document only), extra_key (in the second only), value_mismatch (same JSON type, different content), type_mismatch (different JSON types). Arrays are compared order-independently: an element with no deep-equal partner on the other side is reported as a value mismatch.

Docker

docker run -i ghcr.io/cloudcorprecords/jsondiff            # stdio MCP server
docker run --rm ghcr.io/cloudcorprecords/jsondiff compare '{"a":1}' '{"a":2}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios