compare-xml
A toolkit for structured XML comparison — find what changed between two XML documents, with control over how keys, values, and arrays are matched.
Online playground: comparexml.com
Why
Most XML diff tools either output unstructured text or hide the parts that matter (where an element was added, whether an array differs in order or in content). compare-xml parses XML into a structured representation and returns a list of differences — every entry carries a path, the side it belongs to (base / contrast / both), and the kind of change (added, deleted, valueChanged) — so you can render, filter, or program against it.
Features
- Deep comparison of XML elements, attributes, arrays, and text values.
- Three array comparison strategies:
byIndex(default),lcs(minimal diff via Longest Common Subsequence), andunordered(multiset match). - Case-insensitive key and/or value matching.
- Path tracking with both segment-array and dot-notation forms.
- CLI with table or JSON output, reading from inline strings or files.
- MCP server built in — drop the CLI into any MCP-aware AI assistant.
- Agent Skill — a single skill that works in Claude Code, OpenAI Codex CLI, and OpenCode.
- Full TypeScript types.
Packages
This is a pnpm workspace:
| Package | Description |
|---|---|
@compare-xml/core | Core comparison library (programmatic API). |
@compare-xml/cli | Command-line tool & MCP server, built on top of core. |
Quick Start
Library
npm install @compare-xml/core
import { compareXML } from '@compare-xml/core';
const differences = compareXML({
baseXML: '<user><name>Alice</name><age>30</age></user>',
contrastXML: '<user><name>Bob</name><age>30</age><email>bob@test.com</email></user>',
});
// [
// { pathString: 'user.name', pathBelongsTo: 'both', diffType: 'valueChanged', ... },
// { pathString: 'user.email', pathBelongsTo: 'contrast', diffType: 'added', ... },
// ]
See the core README for the full API.
CLI
npm install -g @compare-xml/cli
compare-xml base.xml contrast.xml
┌──────────────┬──────────────┐
│ Key │ Change Type │
├──────────────┼──────────────┤
│ (Base) a │ valueChanged │
│ (Base) b │ deleted │
│ (Contrast) c │ added │
└──────────────┴──────────────┘
Use --json-export for machine-readable output, or --mcp to launch as an MCP server. See the CLI README for all flags and the MCP tool schema.
MCP
{
"mcpServers": {
"compare-xml": {
"command": "npx",
"args": ["@compare-xml/cli@latest", "--mcp"]
}
}
}
Skill
A single SKILL.md teaches AI coding assistants how to invoke the CLI on demand. The file follows the open Agent Skills format and works across Claude Code, OpenAI Codex CLI, OpenCode, Cursor, and 50+ others.
The fastest install is npx skills — it auto-detects every agent you have installed and drops the skill into each one:
npx skills add unitstack/compare-xml
Development
Requires Node.js ≥ 20 and pnpm.
# install dependencies
pnpm install
# build all packages
pnpm -r build
# run tests across the workspace
pnpm -r test
# lint
pnpm -r lint
The repo layout:
packages/
├── compare-xml-core/ # @compare-xml/core — library
├── compare-xml-cli/ # @compare-xml/cli — CLI + MCP server
└── internal/ # shared eslint/tsconfig (not published)
skills/
└── compare-xml/ # SKILL.md for Claude Code / Codex CLI / OpenCode
License
MIT
Server Config
{
"mcpServers": {
"compare-xml": {
"command": "npx",
"args": [
"@compare-xml/cli@latest",
"--mcp"
]
}
}
}Recommend Servers
View Alltest