MusicXML Comparer

io.github.raulkivi由 GitHub 帳號 raulkivi 發布v0.2.1更新於 Nov 3, 2026

Music-aware, multi-level comparison of two MusicXML files

已驗證STDIO僅桌面資料與分析媒體與設計

概覽

AI 產生的概覽

對兩份 MusicXML 樂譜進行音樂感知的多層級比較，從整體相似度一路細到單一音符的差異。

可以做什麼
  • 以內嵌文字或檔案路徑比較兩份樂譜，回傳結構化差異結果
  • 快速給出相似度分數與彙總統計，不含逐音符細節
  • 依聲部名稱與小節範圍篩選列出音符層級變更
  • 產生可讀的比較報告，涵蓋聲部、小節、調號與拍號變化
  • 匯出帶逐音符顏色標註的 MusicXML，可內嵌回傳或寫入檔案
  • 描述樂譜的標題、調號、拍號、速度、聲部、小節與長度
適用情境
適合比較同一作品的不同版本或改編、將 OMR 或轉換結果與可信的參考譜對照、驗證往返轉換的保真度、在模型或轉換邏輯變更後做回歸測試，以及確認編輯只動到預期的元素。
執行需求
以 Python 套件 comparer-mcp 透過 uvx 在本機執行；需要 Python 3.11+ 以及 music21 與 mcp 函式庫，不需系統函式庫。檔案路徑必須位於輸出資料夾（SHEET_MUSIC_OUTPUT_ROOT，預設為工作目錄）、用戶端根目錄，或 SHEET_MUSIC_INPUT_ROOTS 中列出的資料夾內。僅支援桌面用戶端。
安裝前請注意
結果較大時，標註匯出會把 MusicXML 檔案寫入磁碟。路徑輸入被限制在已設定的資料夾內，伺服器會讀取這些根目錄下的本機樂譜檔案。未宣告任何驗證或憑證。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 MusicXML Comparer，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

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
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

ToolDescription
compare_musicxmlFull diff of two scores, inline or by path → structured ComparisonResult JSON
compare_musicxml_filesFull diff of two MusicXML file paths (.musicxml, .xml, or .mxl) inside the allowed folders → structured ComparisonResult JSON
quick_similaritySimilarity score (0.0–1.0) + summary statistics only, no per-note detail
list_changesNote-level diffs (operation != MATCH), optionally filtered by part name and/or measure range
generate_comparison_reportHuman-readable version comparison report — similarity headline, missing/extra parts and measures, key/time signature changes, note-level differences grouped by measure range (e.g. "transposed by 3 semitones in measures 17-24")
export_annotated_musicxmlMusicXML with per-note color annotations marking the diff. Small results come back inline (reference_annotated_musicxml + target_annotated_musicxml); large ones are written to files and returned as *_path fields plus a score_summary (return: auto/path/inline). Pass the paths to render-mcp's render_to_pdf/render_to_image as musicxml_path
describe_scoreTitle, key, time, tempo, parts (IDs, names, clefs, ranges), measures and duration of a score, without returning the score
health_checkServer status — verifies music21 is importable and runs a self-comparison smoke test
list_capabilitiesServer metadata per project conventions

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.

json
// Compare two MusicXML strings{  "tool": "compare_musicxml",  "arguments": {    "reference_xml": "<score-partwise>...</score-partwise>",    "target_xml": "<score-partwise>...</score-partwise>"  }}
// 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": "<score-partwise>...</score-partwise>",    "target_xml": "<score-partwise>...</score-partwise>"  }}// → {"similarity_score": 0.87, "summary": {...}}
// Filtered changes, e.g. "what changed in the Alto, measures 17-24?"{  "tool": "list_changes",  "arguments": {    "reference_xml": "<score-partwise>...</score-partwise>",    "target_xml": "<score-partwise>...</score-partwise>",    "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": "<score-partwise>...</score-partwise>",    "target_xml": "<score-partwise>...</score-partwise>"  }}// → {"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": "<score-partwise>...</score-partwise>",    "target_xml": "<score-partwise>...</score-partwise>"  }}// → {"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:

json
{  "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:

bash
cd comparer-mcpuv sync
python
from comparer_mcp.engine import compare, compare_files
# Compare two MusicXML stringsresult = 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.0print(result.summary)            # ComparisonSummary: parts/measures/notes matched, missing, changedprint(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

bash
# Unit testsVIRTUAL_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 dependenciesuv 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

PhaseStatus
Phase 1 — Core comparison (MVP)Complete — 45/45 tests passing (43 unit + 2 integration)
Phase 2 — Rich detail (key/time signature diffs, voice-aware alignment, articulations)Complete — 67/67 tests passing (65 unit + 2 integration)
Phase 3 — MCP server & integration (server.py, all 6 tools, install.sh, SETUP.md, client config examples)Complete — 94/94 tests passing (90 unit + 4 integration)
Phase 4 — Advanced features (options wiring, generate_comparison_report, export_annotated_musicxml)Complete — 134/134 tests passing (127 unit + 7 integration)
UX Wave 2 — Score references (reference_path/target_path, return for the annotated export, describe_score)Complete — 239 unit tests passing (+7 integration)

來源：comparer-mcp/README.md，提交 5fcea5d

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.2.1最新Sep 26, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分