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 分