MusicXML Comparer

comparer-mcp

MCP server for music-aware comparison of MusicXML files. Provides structured, multi-level diffs that report what changed between two scores — from global similarity down to individual notes.

What it does

• Version / arrangement comparison — Compare different editions, arrangements, or simplifications of the same piece
• OMR quality evaluation — Compare omr-mcp output against a known-good reference
• Round-trip fidelity — Verify MusicXML → ABC → MusicXML through musicxml-abc-mcp
• Regression testing — Detect regressions when OMR models or conversion logic change
• Score editing validation — Confirm LLM-driven edits only changed intended elements

Installation

bash install.sh

See SETUP.md for client config snippets (Claude Desktop, Cursor, Windsurf, Continue, Zed) and TROUBLESHOOTING.md if something doesn't work.

MCP Tools

Each score can be passed inline (reference_xml, target_xml) or as a file path (reference_path, target_path; .musicxml, .xml or .mxl), exactly one of each pair. Paths save copying whole scores through the conversation. They must be inside the output folder (SHEET_MUSIC_OUTPUT_ROOT, default the working directory), one of the client's roots, or a folder listed in SHEET_MUSIC_INPUT_ROOTS.

// Compare two MusicXML strings

{ "tool": "compare_musicxml", "arguments": { "reference_xml": " ... ", "target_xml": " ... " } }

// Compare two files { "tool": "compare_musicxml_files", "arguments": { "reference_path": "/path/to/reference.musicxml", "target_path": "/path/to/omr_output.musicxml" } }

// Quick similarity check { "tool": "quick_similarity", "arguments": { "reference_xml": " ... ", "target_xml": " ... " } } // → {"similarity_score": 0.87, "summary": {...}}

// Filtered changes, e.g. "what changed in the Alto, measures 17-24?" { "tool": "list_changes", "arguments": { "reference_xml": " ... ", "target_xml": " ... ", "part": "Alto", "measures": [17, 24] } } // → {"changes": [{"measure_number": 18, "operation": "PITCH_CHANGE", "part_name": "Alto", ...}], "count": 1}

// Human-readable report { "tool": "generate_comparison_report", "arguments": { "reference_xml": " ... ", "target_xml": " ... " } } // → {"report": "Overall similarity: 87% (minor differences)\n...", "similarity_score": 0.87}

// Colored MusicXML diff export — chain straight into render-mcp to visualize { "tool": "export_annotated_musicxml", "arguments": { "reference_xml": " ... ", "target_xml": " ... " } } // → {"reference_annotated_musicxml": "...", "target_annotated_musicxml": "...", // "similarity_score": 0.87, "legend": {"PITCH_CHANGE": "#FF8800", ...}} // For scores over 8 KB (return: "auto", the default): // → {"reference_annotated_musicxml_path": ".../scores/annotated-reference_annotated_musicxml-....musicxml", // "target_annotated_musicxml_path": "...", "similarity_score": 0.87, "legend": {...}, // "score_summary": {"reference_annotated_musicxml": {...}, "target_annotated_musicxml": {...}}}

// Paths instead of inline text { "tool": "quick_similarity", "arguments": { "reference_path": "scores/reference.musicxml", "target_path": "scores/omr_output.mxl" } }

compare_musicxml, compare_musicxml_files, generate_comparison_report, and export_annotated_musicxml all accept an optional options object:

{

"expand_repeats": false, // unfold repeats before comparing (default: false — opt-in) "normalize_pitch": false, // transpose transposing instruments to concert/sounding pitch "ignore_articulations": false, // exclude articulations from NoteInfo/diffs "parts": ["Soprano"], // compare only these parts: IDs, names or voices ("P1", "S"); // part_filter is a deprecated alias "measures": [1, 32] // only differences in measures 1-32, inclusive (scores are not // cut); measure_range is a deprecated alias }

Using the engine directly

The comparison engine (src/comparer_mcp/engine.py) has no MCP dependency and is fully usable as a plain Python library, independent of the MCP server:

cd comparer-mcp

uv sync

from comparer_mcp.engine import compare, compare_files

Compare two MusicXML strings

result = compare(reference_xml, target_xml)

Compare two files (.musicxml, .xml, or compressed .mxl)

result = compare_files("reference.musicxml", "omr_output.mxl")

print(result.similarity_score) # float, 0.0-1.0 print(result.summary) # ComparisonSummary: parts/measures/notes matched, missing, changed print(result.part_diffs) # list[PartDiff] -> list[MeasureDiff] -> list[NoteDiff]

Errors are raised as comparer_mcp.engine.ProcessingError (e.g. for a missing file or invalid MusicXML), carrying a .error_code attribute (FILE_NOT_FOUND, INVALID_INPUT, etc.) matching the format the MCP tools return.

Testing

# Unit tests

VIRTUAL_ENV= .venv/bin/pytest tests/ -v -m "not integration"

Integration tests (real .mxl SATB fixtures shared with omr-mcp)

VIRTUAL_ENV= .venv/bin/pytest tests/ -v -m integration

Install dependencies

uv sync

Dependencies

• music21 — MusicXML parsing, score object model, stream alignment
• numpy — distance matrix for note alignment (transitive via music21)
• mcp — MCP protocol

System requirements

• Python 3.11+
• No system libraries required

Phase status