structdiff MCP server

structdiff-mcp

An MCP server that tells an AI agent what actually changed between two JSON / YAML / TOML / CSV / .env / INI files, by path, ignoring key order and formatting. A line diff of two configs shows 400 changed lines because someone re-sorted the keys; this shows the one port that changed.

Why this one, when other diff MCP servers exist? Servers such as confdiff-mcp, diff-mcp and mcp-config-tools (Node/npm) already diff configs. This one is Python (uvx structdiff-mcp, no Node) and goes further on the cases that make diffs lie:

• Lists are matched by identity, not position. users[id=3] moved to the front is one moved entry, not a cascade of edits. Match by id/name/key (or your own field), by index, or as a set.
• A JSON Patch you can trust. as_json_patch returns an RFC 6902 patch that is verified by applying it before it is returned, and the test suite applies generated patches to thousands of random documents with two independent appliers (ours and jsonpatch).
• Honest about types. 1 vs "1" is a type_changed, null vs a missing key is an add/remove, big integers stay exact, NaN equals NaN, 0.1+0.2 vs 0.3 is equal with a tolerance.
• Warns about traps instead of silently picking one: duplicate JSON/YAML/.env keys, multi-document YAML, comments in JSON, mixed CSV delimiters or encodings.
• Keyed CSV diffing that streams the second file: added/removed/changed rows, per-cell changes, column additions, duplicate keys.
• Read-only and sandboxed to the folders you allow; YAML is parsed with the safe loader only.

Install

Claude Code:

claude mcp add structdiff -- uvx structdiff-mcp --dir "C:\path\to\your\projects"

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "structdiff": {
      "command": "uvx",
      "args": ["structdiff-mcp", "--dir", "C:\\path\\to\\your\\projects"]
    }
  }
}

--dir may be repeated. Without it the server can read only the folder it was started in. Relative file paths resolve against the first --dir.

Tools

Tool	What it does
diff_files	Semantic diff of two files (format auto-detected; a and b may differ in format)
diff_text	The same for two pasted strings (format required)
csv_diff	Row-level CSV/TSV diff using key_columns: added/removed/changed rows, cells, columns
as_json_patch	RFC 6902 patch turning a into b, verified before it is returned
apply_preview	Show what a JSON Patch does to a document (nothing is written)
inspect_file	How a file parses: format, encoding, shape, and warnings (duplicate keys, multi-doc, ...)

Example result of diff_text on two JSON documents (abs_tol=1e-9):

{
  "identical": false,
  "summary": {"added": 0, "removed": 0, "changed": 1, "type_changed": 1, "moved": 1, "total": 3},
  "changes": [
    {"op": "type_changed", "path": "$.port", "old": 8080, "new": "8080", "old_type": "number", "new_type": "string"},
    {"op": "changed", "path": "$.users[id=1].role", "old": "admin", "new": "owner"},
    {"op": "moved", "path": "$.users[id=3]", "from_index": 2, "to_index": 0}
  ]
}

Options shared by the diff tools

• array_match: auto (default: key field if one is present and unique in every item, else position), index, key (like auto, but warns when no key works), set (order-insensitive, duplicate-aware).
• array_keys: candidate key fields, default ["id", "name", "key"].
• ignore: paths to skip, e.g. ["$.metadata.updatedAt", "$.items[*].etag", "*.timestamp"]. * matches any text including dots and brackets; patterns must start with $ or *.
• abs_tol, rel_tol: numeric tolerance. 1 and 1.0 are always equal.
• strip_comments: allow //, /* */ and trailing commas in JSON (automatic for .jsonc).
• encoding: auto honours UTF-8/16/32 BOMs, otherwise UTF-8; pass cp1252 etc. explicitly for legacy files.
• max_changes, max_value_chars: caps on output. Summary counts are always complete.

Paths look like $.servers[id=3].port, $['odd.key'], $.tags[*] (set mode) or $[2] (by index).

Try asking

• "Diff deploy/prod.yaml and deploy/staging.yaml and ignore the replica counts."
• "What changed between package.json on main and this one I pasted? Only the dependencies matter."
• "Compare config.old.toml and config.new.toml; treat floats within 1e-6 as equal."
• "Compare these two exports on customer_id and tell me which cells changed, and which columns are new."
• "Give me a JSON Patch that turns a.json into b.json, and show me what applying it to c.json would do."
• "Does settings.json have duplicate keys or comments that would confuse a parser?"

Limits and behaviour worth knowing

• YAML documents are compared after loading: anchors, aliases and merge keys are resolved, dates become ISO strings, comments are ignored. Multi-document YAML is compared as a list of documents.
• A key 1 and a key true in one YAML mapping collide in Python; that is reported as a duplicate-key warning.
• INI values are strings and [DEFAULT] is treated as an ordinary section. .env values are strings.
• NaN and Infinity cannot appear in a JSON Patch (as_json_patch refuses); in diff output they are shown as strings.
• as_json_patch with ignore or tolerance options produces a patch whose result equals b only up to those options. A list containing ignored items is left unpatched, with a warning.
• Structured files are limited to 50 MB; csv_diff indexes file a in memory (limit 2 million rows) and streams file b.

Security

• Read-only. No tool writes, moves or deletes anything.
• Sandboxed. Files must resolve (symlinks followed) inside a --dir folder; anything else is refused. Only pass folders you are happy for the agent to read.
• Safe YAML. Only PyYAML's SafeLoader is used; !!python/... tags are rejected. Recursive aliases and alias bombs are detected and refused (5 million value budget, 100 levels of nesting).
• Pasted text is limited to 10 MB. File contents are returned in diff output (truncated per value), so do not point the server at secrets you do not want in the conversation; use ignore for sensitive paths.

Develop

uv sync --extra test
uv run pytest            # includes ~6000 property-test cases and a real stdio session
uv run ruff check src tests
uv run mypy --strict src

MIT licensed. A from-scratch tutorial that builds a minimal version of this server is in structdiff-mcp-the-hard-way.