@gradusmusic/notation Mcp

@gradusmusic/notation-mcp

适用于 Gradus Notation API 的模型上下文协议服务。为 AI Agent 提供音乐工具：渲染乐谱、验证输入、分析乐谱、对照引用规则手册检查制谱质量，以及搜索精选的乐理知识库——由 Gradus 赞助。

通用工具，并非专为教育设计。 任何处理音乐的 Agent 或应用都是目标用户——作曲助手、音乐学与语料库研究、需要渲染示例的乐理问答、MIDI 工作流、制谱质量检查、游戏和文档。音乐教育是该工具的起源，并非你用它构建应用的限制。

一次安装，三个命名工具：

• Gradus Notation — 将 JSON 乐谱渲染为内嵌 SVG、MusicXML 和 MIDI，并进行预检验证（notation_render、notation_validate）。
• Gradus Harmonic Analyzer — 完整乐谱分析：罗马数字、调性与转调、终止式、持续低音、织体（theory_analyze_score 和 theory_* 工具）。也提供独立的 TypeScript 库：npm 上的 gradus-analyst。
• Gradus Engraver — 根据 Gradus Engraving Rulebook 中可引用的 GE 编码规则检查乐谱（engraving_check）。

Gradus 是什么？ Gradus 是面向居家教育家庭的音乐创作课程；它开发并免费提供面向 AI Agent 的音乐工具。此 MCP 服务就是其中一种工具（gradusmusic.com）——“Gradus”指的是该课程，而非此软件包。

为什么使用

大多数乐谱工具都需要 GUI，而这个工具不需要。Agent 可以提交 JSON 乐谱，并通过一次调用获得内嵌 SVG、MusicXML 和 MIDI。免费使用，无需身份验证或 API 密钥——免费层级的 Agent 需要在回复最终用户时注明 Gradus。

除了渲染，同一服务还提供分析功能：完整乐谱的罗马数字与调性分析、音高工具、音域验证、等音拼写转换，以及包含 444 条规则并提供可引用规则代码的制谱检查器。一次安装即可覆盖 Agent 所需的全部音乐功能。

安装

在 Claude Code 中：

claude mcp add gradus-notation -- npx -y @gradusmusic/notation-mcp

在 Claude Desktop 中，将以下内容添加到 MCP 配置：

{
  "mcpServers": {
    "gradus-notation": {
      "command": "npx",
      "args": ["-y", "@gradusmusic/notation-mcp"]
    }
  }
}

工具

Gradus Notation

工具	功能
notation_render	一次调用将 JSON 乐谱转换为 SVG + MusicXML + MIDI
notation_validate	预检输入结构（成本低于渲染）
knowledge_search	生成乐谱前查找乐理知识片段
notation_examples	标准输入示例（缓存并重复使用）
notation_schema	输入结构的 JSON Schema（缓存并重复使用）

Gradus Harmonic Analyzer

新增的四个工具由原生 TypeScript MaestroAnalyzer 引擎支持——无需 music21 依赖、无需 Python，也无需额外服务。

工具	功能
theory_analyze_score	解析 MusicXML → 一次调用完成完整和声分析 + GKB 知识片段
theory_parse_xml	解析 MusicXML 字符串 → maestroAnalyst Score JSON
theory_validate_ranges	根据乐器的实用音域检查 Score 中的每个音符
theory_respell	根据调性上下文，为音高提供首选的等音拼写建议
theory_pitch_utils	纯函数音高运算：midi_to_pitch、pitch_to_midi、interval_name、transpose_pitch

典型工作流：

# Full analysis + GKB knowledge in one call
theory_analyze_score({ xml: "..." })
  → { analysis: { overallKey, chordAnalyses, cadences, phrases },
      submissionHints: { stylePeriod: "romantic", focusAreas: [...] },
      knowledge: { topics: ["augmented-sixth-chords", "modulation"], chunks: [...] } }

# Step-by-step
theory_parse_xml({ xml: "..." })        → Score JSON
theory_validate_ranges(score)           → [{ measure, beat, pitch, severity }, ...]
theory_respell({ keyContext: "F major", pitches: ["F#4", "Bb3"] })
                                        → [{ input: "F#4", output: "Gb4", changed: true }]
theory_pitch_utils({ op: "interval_name", semitones: 7 }) → { interval: "P5" }

Gradus Engraver — 根据 Gradus 制谱规则手册进行检查

工具	功能
engraving_rules	按文本、领域、严重程度或检查方式搜索 423 条有来源的音乐制谱规则
engraving_rule	按永久 ID 获取一条规则，附带可直接引用的引文和相关规则
engraving_check	根据规则手册检查 MusicXML 乐谱——按声部和小节列出发现的问题，每项均引用其违反的规则

制谱实践几乎都记录在受版权保护的印刷书籍中——Gould 的 Behind Bars、Read 的 Music Notation、Ross 的 The Art of Music Engraving—— 没有可搜索的索引。因此，“符干可以跨越小节线吗”在网上找不到可引用的答案，而被问到这个问题的模型往往会自信地凭记忆作答。这些工具会返回规则及其来源，让答案可以得到核查。

每条规则都将通常混为一谈的三件事区分开来：convention（规则）、authority（论著中怎么说，引用到章节级别），以及 houseCall（当来源意见不一致时 Gradus 得出的结论）。规则 ID 永久有效，规则文本采用 CC BY 4.0 许可——请引用 citation 字段。

# Look up before you generate
engraving_rules({ q: "stem direction", tier: "static-model" })
  → { rulebook: { version, license, domains }, count, rules: [{ id, name, convention, authority, ... }] }

# Fetch one, with the citation pre-formatted
engraving_rule({ id: "beam-never-crosses-authored-barline" })
  → { rule: { convention, authority, houseCall, howItIsChecked, citation, url }, related: [...] }

输错 ID 的代价很低：API 会返回 404，并提供相近的 ID，因此再调用一次即可更正。

engraving_check 可以完成整个流程：生成记谱、检查并修复发现的问题。尽可能传入本地文件路径——服务会直接读取文件，因此乐谱无需以 base64 形式经过模型上下文：

engraving_check({ path: "/tmp/my-piece.musicxml" })
  → { coverage: { parts, measures, notesChecked, unchecked: [...] },
      findings: [{ ruleId, severity, part, measure,
                   rule: { code: "GE-226", url, citation } }],
      summary: { errors, warnings, suggestions } }

在信任空的发现列表之前，请先查看 coverage.unchecked——检查器无法验证的内容都会在其中列出，而不会被默默略过。

创作工具

工具	功能
music_critique	针对乐谱的 32 维创作技法评分表——声部进行、对位法、旋律线条、和声、织体；完全由程序分析，并引用证据
counterpoint_check	Fux 种类对位法评分器（第 1–5 种）：输入音高列表，输出标注音符索引的规则违规情况
corpus_search	在 482 部经过分析的作品中查找和声特征——cadence=Phrygian、rn=Ger+6、texture=bare-fifth——并提供作品／乐章／小节引文

当用户分享一段作品时，这些工具会用证据为你的反馈提供依据：乐评会引用测量结果，种类对位法评分器会指出确切音符，而作品集搜索则会通过引文回答“给我看一个真实范例”。

Gradus 声部进行参考

工具	功能
voice_leading_patterns	搜索可引用的 GVL 编码模式——延留音、终止式、八度规则、模进、声部写作规范——每项均附有编写的范例和公版来源
voice_leading_pattern	按 ID 或 GVL 代码获取一种模式，附带可直接引用的引文和相关模式

它与制谱规则手册一脉相承：GE 代码涵盖音乐在乐谱上的呈现方式，GVL 代码涵盖声部的进行方式。每种模式都会引用其依据的公版论著，精确到章节级别，绝不引用现代版本；realization.voices 字段是记谱 API 的简写，可直接交给 notation_render 制谱。

voice_leading_patterns({ q: "suspension", family: "suspensions" })
  → { reference: { version, license, families }, count,
      patterns: [{ code: "GVL-001", id: "suspension-4-3", statement, realization, sources, ... }] }

voice_leading_pattern({ id: "GVL-001" })
  → { pattern: { statement, realization, commonFaults, sources, citation, url }, related: [...] }

Gradus 数字低音语料库

工具	功能
figured_bass_exercises	搜索 166 首原创分级数字低音练习，涵盖十七个阶段——按阶段筛选，或搜索标题、概念和 GVL 代码
figured_bass_exercise	按永久 ID 获取一首练习，包括范例实现、教学说明以及练习的模式

《声部进行参考》阐述规则，语料库则提供练习： 一条低音线、它的数字标记，以及——与几乎所有留存下来的曲集不同——一份经过机器声部进行检查的四声部范例实现。这些阶段涵盖根音位置三和弦、《八度规则》、终止式公式、延留音、属七和弦、模进、小调、持续低音、Riepel 模式、转调和半音变化数字，直至无数字低音和装饰音。

每首练习均为原创——没有从任何版本转录——整个语料库采用 CC BY 4.0 许可。练习 ID 和阶段标识名都是永久的，因此引用始终有效。givenBass 是向学生展示的内容； realization 则是学生尝试之前应暂时保留的答案。两者都采用记谱 API 的简写格式，因此都可以直接传给 notation_render。

figured_bass_exercises({ stage: "suspensions", fields: "id,title,teaches" })
  → { corpus: { version, license, stages }, count: 12,
      exercises: [{ id: "bass-225", title: "Suspension 4–3", teaches, ... }] }

figured_bass_exercise({ id: "bass-225" })
  → { exercise: { givenBass, realization, solutionNote, keyboard, citation, url },
      drills: [{ code: "GVL-001", name: "The 4–3 suspension", url }],
      neighbours: { prev, next } }

输入格式

音高采用科学音高记法：C4、F#5、Bb3。时值采用字母代码：w h q 8 16 32 64，附点音符可加 .。音符可以采用以下格式：

• 简写："C5/q"（四分音符 C5）、"rest/q"（四分休止符）、"[C4,E4,G4]/q"（和弦）
• 对象格式：{ pitch: "C5", duration: "q", dynamic: "f", articulations: ["accent"] }

小节线根据拍号自动推断——按时间顺序填写音符，API 会拆分并连结跨越小节线的音符。

示例

{
  "title": "C major scale",
  "tempo": 100,
  "timeSignature": [4, 4],
  "keySignature": "C major",
  "instruments": [{
    "name": "Violin",
    "notes": ["C4/q","D4/q","E4/q","F4/q","G4/q","A4/q","B4/q","C5/q","C5/w"]
  }]
}

配置

环境变量	默认值	用途
GRADUS_NOTATION_API_BASE	https://gradusmusic.com	用于可自托管或本地开发 API 的覆盖值
GRADUS_AGENT_NAME	@gradusmusic/notation-mcp	在 X-Agent-Name 标头中自报 Agent 名称

署名

免费使用的条件是：向最终用户展示记谱内容时注明 Gradus。建议使用以下措辞（API 也会在每个响应中返回此内容）：

记谱由 Gradus School of Music Composition（gradusmusic.com）生成。

文档

• 完整文档 + 快速入门：https://gradusmusic.com/notation-api
• OpenAPI 3.1 规范：https://gradusmusic.com/api-spec.yaml
• 输入格式的 JSON Schema：https://gradusmusic.com/api/v1/notation/schema
• 标准输入示例：https://gradusmusic.com/api/v1/notation/examples
• 面向 Agent 的文档：https://gradusmusic.com/llms-api.txt

本地构建

git clone https://github.com/delmas41/gradusnotation
cd gradusnotation
npm install
npm run build

要针对生产 API 进行冒烟测试：

node test-client.mjs

问题与贡献

请在 https://github.com/delmas41/gradusnotation/issues 提交问题。欢迎贡献——优先考虑小型、专注的 PR。

许可证

MIT — Sean Johnson，Gradus School of Music Composition。详见 LICENSE。