Tools for agents: JSON diff and patch generator

Compare two JSON states and get an ordered JSON Patch plus explicit old and new values for agent review.

Connect with MCP

{
  "mcpServers": {
    "super-agent-tools": {
      "url": "https://app.getsupers.com/sites/agent-json-diff/mcp"
    }
  }
}
Streamable HTTP · No API key · Stateless

Use this URL in any client supporting remote Streamable HTTP MCP. Calls return structured JSON; inputs are processed without persistence.

Call diff_json

Returns RFC 6902 add/remove/replace operations using RFC 6901 JSON Pointer paths. The empty path denotes the document root; ~ and / in keys are escaped. Arrays are compared by position, with tail removals in descending order; this is not a minimal edit script or move detector. Object key order is ignored. Numerically equal JSON numbers compare equal, but booleans and numbers are distinct. Null is a value, distinct from a missing field. Apply patch operations in order to the exact before document; no concurrency precondition is included. This tool only computes a patch and never applies changes to your data.

Input and output schemas
{
  "name": "diff_json",
  "title": "JSON diff and patch generator",
  "description": "Compare JSON documents and return ordered RFC 6902 add/remove/replace operations, old-value change records and counts. Does not apply changes or access external data.",
  "inputSchema": {
    "$defs": {
      "JsonValue": {}
    },
    "properties": {
      "before": {
        "$ref": "#/$defs/JsonValue"
      },
      "after": {
        "$ref": "#/$defs/JsonValue"
      }
    },
    "required": [
      "before",
      "after"
    ],
    "title": "diff_jsonArguments",
    "type": "object"
  },
  "outputSchema": {
    "additionalProperties": true,
    "title": "diff_jsonDictOutput",
    "type": "object"
  },
  "icons": null,
  "annotations": {
    "title": null,
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "meta": null,
  "execution": null
}

Run the example to see the actual result.

HTTP alternative

POST https://app.getsupers.com/sites/agent-json-diff/call
Content-Type: application/json

{
  "before": {
    "task": {
      "status": "queued",
      "owner": null
    },
    "steps": [
      "fetch",
      "draft",
      "obsolete"
    ]
  },
  "after": {
    "task": {
      "status": "ready",
      "owner": "worker-a"
    },
    "steps": [
      "fetch",
      "verify"
    ],
    "verified": true
  }
}

The HTTP and MCP interfaces execute the same implementation. Validation errors are returned explicitly. See the tool notes above for its supported inputs and behavior.

Ordered JSON operations preserve positional meaning

Read the explanation

The source example changes steps from fetch, draft, obsolete to fetch, verify. The first entry matches. Index one changes from draft to verify and becomes a replace operation. The final entry at index two is removed. This is positional comparison, not move detection or a minimal edit script. When several tail entries are removed, operations run in descending index order so earlier removals do not shift the remaining targets. The nested status changes from queued to ready. Owner changes from null to worker a: null is an existing value, so that is replacement, not addition. Steps at index one gives the third replacement. Removing steps at index two and adding verified true gives five total operations. Old and new values are exposed for review. Object key order does not matter; equal numeric values compare equal, but booleans and numbers remain different. For a four entry array reduced to its first two entries, remove index three before index two. Removing the lower index first would shift the last value away from its original address. Paths escape slash as tilde one and tilde as tilde zero; an empty path means the root document. Apply operations in returned order to the exact before state. No concurrency precondition is included, and the tool computes rather than applies changes. These examples follow the published contract; no remote HTTP or MCP execution was tested.

JSON Pointer Differencing and RFC 6902 Patch Generation

How does diff_json compute RFC 6902 patch operations and track structural state transformations across objects and arrays?

The diff_json tool analyzes structural differences between two JSON documents and outputs an ordered RFC 6902 patch alongside detailed before-and-after audit records. Locations are referenced via RFC 6901 JSON Pointers, encoding '~' as '~0' and '/' as '~1'. Object keys are evaluated across sorted sets, while arrays are compared strictly by positional index with trailing removals executed in descending order.

Array comparisons use one-to-one positional matching rather than an edit-distance or Myers diff algorithm; shifting an element alters all downstream array indices into replacements rather than move operations. Key ordering within objects is ignored. The tool generates operations but does not execute them or append optimistic concurrency checks such as test operations.

Try a worked example

Submit the default form by clicking 'Run tool'. The service evaluates the state transformation and populates the structured result with operation_count: 5. The generated patch contains exactly five operations: adding '/verified' with true, removing the trailing element at '/steps/2', replacing '/steps/1' with 'verify', replacing '/task/owner' with 'worker-a', and replacing '/task/status' with 'ready'.

RFC 6901 JSON Pointer Addressing

JSON Pointers identify target values using slash-separated reference tokens starting from the root document. Special characters in keys require specific escaping: any occurrence of '~' must be encoded as '~0' and '/' as '~1', ensuring unique path resolution across deeply nested objects. RFC 6901: JavaScript Object Notation (JSON) Pointer

RFC 6902 Patch Semantics and Array Traversal

An RFC 6902 JSON Patch document is an ordered sequence of discrete operations applied consecutively to a target document. In diff_json, array differences are emitted strictly by index: truncated array elements are pruned in descending order from the tail so that preceding array indexes remain stable during sequential patch application. RFC 6902: JavaScript Object Notation (JSON) Patch

Sources and further reading