{
  "markdown": "# @gradusmusic/notation-mcp\n\nModel Context Protocol server for the [Gradus Notation API](https://gradusmusic.com/notation-api). Gives AI agents music tools: render notation, validate input, analyze scores, check engraving against a cited rulebook, and search a curated music-theory knowledge base — sponsored by Gradus.\n\n**General-purpose, not education-specific.** Any agent or application that works with music is the audience — composition assistants, musicology and corpus research, theory Q&A that wants rendered examples, MIDI pipelines, engraving quality checks, games, documentation. Music education is where the tool comes from, not a restriction on what you build with it.\n\n**One install, three named tools:**\n\n- **Gradus Notation** — render a JSON score to inline SVG, MusicXML, and MIDI, with pre-flight validation (`notation_render`, `notation_validate`).\n- **Gradus Harmonic Analyzer** — full-score analysis: Roman numerals, keys and modulations, cadences, pedal points, texture (`theory_analyze_score` and the `theory_*` tools). Also a standalone TypeScript library: [`gradus-analyst`](https://www.npmjs.com/package/gradus-analyst) on npm.\n- **Gradus Engraver** — checks a score against the [Gradus Engraving Rulebook](https://gradusmusic.com/engraving)'s citable GE-coded rules (`engraving_check`).\n\n> **What is Gradus?** Gradus is a music-composition curriculum for homeschool families; it builds and gives away free music tools for AI agents. This MCP server is one of those tools ([gradusmusic.com](https://gradusmusic.com)) — \"Gradus\" refers to the curriculum, never to this package.\n\n## Why\n\nMost music-notation tools require a GUI. This one doesn't. An agent can submit a JSON score and get back inline SVG, MusicXML, and MIDI in a single call. Free to use, no auth, no API key — agents on the free tier are asked to credit Gradus in their response to the end user.\n\nBeyond rendering, the same server exposes the analysis side: Roman-numeral and key analysis of a full score, pitch utilities, range validation, enharmonic respelling, and a 444-rule engraving checker with citable rule codes. One install covers the whole music surface an agent needs.\n\n## Install\n\nIn Claude Code:\n\n```bash\nclaude mcp add gradus-notation -- npx -y @gradusmusic/notation-mcp\n```\n\nIn Claude Desktop, add to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"gradus-notation\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@gradusmusic/notation-mcp\"]\n    }\n  }\n}\n```\n\n## Tools\n\n### Gradus Notation\n\n| Tool | What it does |\n|---|---|\n| `notation_render` | JSON score → SVG + MusicXML + MIDI in one call |\n| `notation_validate` | Pre-flight validate input shape (cheaper than render) |\n| `knowledge_search` | Look up music-theory chunks before generating notation |\n| `notation_examples` | Canonical input examples (cache and reuse) |\n| `notation_schema` | JSON Schema for the input shape (cache and reuse) |\n\n### Gradus Harmonic Analyzer\n\nFour new tools backed by the native TypeScript MaestroAnalyzer engine — no music21 dependency, no Python, no extra server.\n\n| Tool | What it does |\n|---|---|\n| `theory_analyze_score` | Parse MusicXML → full harmonic analysis + GKB knowledge chunks in one call |\n| `theory_parse_xml` | Parse a MusicXML string → maestroAnalyst `Score` JSON |\n| `theory_validate_ranges` | Check every note in a Score against its instrument's practical range |\n| `theory_respell` | Suggest preferred enharmonic spelling for pitches in a key context |\n| `theory_pitch_utils` | Pure-function pitch arithmetic: `midi_to_pitch`, `pitch_to_midi`, `interval_name`, `transpose_pitch` |\n\n**Typical workflows:**\n\n```\n# Full analysis + GKB knowledge in one call\ntheory_analyze_score({ xml: \"...\" })\n  → { analysis: { overallKey, chordAnalyses, cadences, phrases },\n      submissionHints: { stylePeriod: \"romantic\", focusAreas: [...] },\n      knowledge: { topics: [\"augmented-sixth-chords\", \"modulation\"], chunks: [...] } }\n\n# Step-by-step\ntheory_parse_xml({ xml: \"...\" })        → Score JSON\ntheory_validate_ranges(score)           → [{ measure, beat, pitch, severity }, ...]\ntheory_respell({ keyContext: \"F major\", pitches: [\"F#4\", \"Bb3\"] })\n                                        → [{ input: \"F#4\", output: \"Gb4\", changed: true }]\ntheory_pitch_utils({ op: \"interval_name\", semitones: 7 }) → { interval: \"P5\" }\n```\n\n### Gradus Engraver — checks against the Gradus Engraving Rulebook\n\n| Tool | What it does |\n|---|---|\n| `engraving_rules` | Search 423 sourced music-engraving rules by text, domain, severity, or how they are checked |\n| `engraving_rule` | Fetch one rule by its permanent id, with a ready-to-quote citation and related rules |\n| `engraving_check` | Check a MusicXML score against the rulebook — findings by part and measure, each citing the rule it breaks |\n\nEngraving practice is documented almost entirely in copyrighted print — Gould's\n*Behind Bars*, Read's *Music Notation*, Ross's *The Art of Music Engraving* —\nwith no searchable index. So \"may a beam cross a barline\" has no citable answer\nonline, and a model asked that question answers confidently from memory. These\ntools return the rule **with its source**, so the answer can be checked.\n\nEach rule separates three things that are usually mashed together: `convention`\n(the rule), `authority` (what the treatises say, cited at chapter level), and\n`houseCall` (where Gradus came down when the sources disagree). Rule ids are\npermanent and rule text is CC BY 4.0 — quote the `citation` field.\n\n```\n# Look up before you generate\nengraving_rules({ q: \"stem direction\", tier: \"static-model\" })\n  → { rulebook: { version, license, domains }, count, rules: [{ id, name, convention, authority, ... }] }\n\n# Fetch one, with the citation pre-formatted\nengraving_rule({ id: \"beam-never-crosses-authored-barline\" })\n  → { rule: { convention, authority, houseCall, howItIsChecked, citation, url }, related: [...] }\n```\n\nA wrong id is cheap: the API answers 404 with near-matching ids, so you can\ncorrect in one more call.\n\n`engraving_check` closes the loop: generate notation, check it, fix what it\nfinds. Pass a local file path when you can — the server reads it directly, so\nthe score never has to travel through the model's context as base64:\n\n```\nengraving_check({ path: \"/tmp/my-piece.musicxml\" })\n  → { coverage: { parts, measures, notesChecked, unchecked: [...] },\n      findings: [{ ruleId, severity, part, measure,\n                   rule: { code: \"GE-226\", url, citation } }],\n      summary: { errors, warnings, suggestions } }\n```\n\nRead `coverage.unchecked` before trusting an empty findings list — anything the\nchecker could not verify is named there rather than silently passed.\n\n### Craft tools\n\n| Tool | What it does |\n|---|---|\n| `music_critique` | 32-dimension craft scorecard for a score — voice leading, counterpoint, contour, harmony, texture; purely programmatic, evidence-cited |\n| `counterpoint_check` | Fux species grader (species 1–5): pitch lists in, note-indexed rule violations out |\n| `corpus_search` | Find harmonic features in 482 analyzed works — `cadence=Phrygian`, `rn=Ger+6`, `texture=bare-fifth` — with work/movement/measure citations |\n\nWhen a user shares a piece, these ground your feedback in evidence: the critique\ncites what it measured, the species grader points at the exact note, and the\ncorpus search answers \"show me a real example\" with a citation.\n\n### The Gradus Voice-Leading Reference\n\n| Tool | What it does |\n|---|---|\n| `voice_leading_patterns` | Search the citable GVL-coded patterns — suspensions, cadences, the Rule of the Octave, sequences, part-writing norms — each with an authored realization and public-domain sources |\n| `voice_leading_pattern` | Fetch one pattern by id or GVL code, with a ready-to-quote citation and related patterns |\n\nThe sibling of the Engraving Rulebook: where GE codes cover how music should\nlook on the page, GVL codes cover how voices should move. Every pattern cites\nthe public-domain treatise it rests on — Fux, Rameau, Kirnberger, Fenaroli,\nRiepel, Prout — at chapter level, never through a modern edition, and the\n`realization.voices` field is notation-API shorthand you can hand straight to\n`notation_render` to engrave.\n\n```\nvoice_leading_patterns({ q: \"suspension\", family: \"suspensions\" })\n  → { reference: { version, license, families }, count,\n      patterns: [{ code: \"GVL-001\", id: \"suspension-4-3\", statement, realization, sources, ... }] }\n\nvoice_leading_pattern({ id: \"GVL-001\" })\n  → { pattern: { statement, realization, commonFaults, sources, citation, url }, related: [...] }\n```\n\n### The Gradus Figured-Bass Corpus\n\n| Tool | What it does |\n|---|---|\n| `figured_bass_exercises` | Search 166 original graded figured-bass exercises across seventeen stages — filter by stage, or search titles, concepts and GVL codes |\n| `figured_bass_exercise` | Fetch one exercise by its permanent id, with the model realization, its teaching note, and the patterns it drills |\n\nWhere the Voice-Leading Reference states the rule, the corpus is the practice:\na bass, its figures, and — unlike almost every surviving collection — a\nfour-part **model realization**, machine-checked for voice leading. The stages\nrun from root-position triads through the Rule of the Octave, cadence formulas,\nsuspensions, the dominant seventh, sequences, minor mode, pedal point, the\nRiepel schemata, modulation and chromatic figures to unfigured bass and\ndiminution.\n\nEvery exercise is original — nothing is transcribed from any edition — and the\nwhole corpus is CC BY 4.0. Exercise ids and stage slugs are permanent, so a\ncitation keeps resolving. `givenBass` is what you show the student;\n`realization` is the answer to hold back until they have tried. Both are\nnotation-API shorthand, so either goes straight to `notation_render`.\n\n```\nfigured_bass_exercises({ stage: \"suspensions\", fields: \"id,title,teaches\" })\n  → { corpus: { version, license, stages }, count: 12,\n      exercises: [{ id: \"bass-225\", title: \"Suspension 4–3\", teaches, ... }] }\n\nfigured_bass_exercise({ id: \"bass-225\" })\n  → { exercise: { givenBass, realization, solutionNote, keyboard, citation, url },\n      drills: [{ code: \"GVL-001\", name: \"The 4–3 suspension\", url }],\n      neighbours: { prev, next } }\n```\n\n\n## Input format\n\nPitches use scientific notation: `C4`, `F#5`, `Bb3`. Durations use letter codes: `w h q 8 16 32 64` with optional `.` for dotted notes. Notes can be:\n\n- Shorthand: `\"C5/q\"` (quarter C5), `\"rest/q\"` (quarter rest), `\"[C4,E4,G4]/q\"` (chord)\n- Object form: `{ pitch: \"C5\", duration: \"q\", dynamic: \"f\", articulations: [\"accent\"] }`\n\nBar lines are **inferred** from the time signature — write notes in time order and the API splits and ties anything that crosses a bar line.\n\n## Example\n\n```json\n{\n  \"title\": \"C major scale\",\n  \"tempo\": 100,\n  \"timeSignature\": [4, 4],\n  \"keySignature\": \"C major\",\n  \"instruments\": [{\n    \"name\": \"Violin\",\n    \"notes\": [\"C4/q\",\"D4/q\",\"E4/q\",\"F4/q\",\"G4/q\",\"A4/q\",\"B4/q\",\"C5/q\",\"C5/w\"]\n  }]\n}\n```\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `GRADUS_NOTATION_API_BASE` | `https://gradusmusic.com` | Override for self-hosted or local-dev API |\n| `GRADUS_AGENT_NAME` | `@gradusmusic/notation-mcp` | Self-report your agent name in `X-Agent-Name` header |\n\n## Attribution\n\nFree use is offered in exchange for crediting Gradus when you surface notation to your end user. Suggested wording (the API also returns this in every response):\n\n> Notation rendered by Gradus School of Music Composition (gradusmusic.com).\n\n## Documentation\n\n- Full docs + Quick Start: https://gradusmusic.com/notation-api\n- OpenAPI 3.1 spec: https://gradusmusic.com/api-spec.yaml\n- JSON Schema for the input format: https://gradusmusic.com/api/v1/notation/schema\n- Canonical input examples: https://gradusmusic.com/api/v1/notation/examples\n- Agent-focused doc: https://gradusmusic.com/llms-api.txt\n\n## Building locally\n\n```bash\ngit clone https://github.com/delmas41/gradusnotation\ncd gradusnotation\nnpm install\nnpm run build\n```\n\nTo smoke-test against the production API:\n\n```bash\nnode test-client.mjs\n```\n\n## Issues + contributions\n\nOpen an issue at https://github.com/delmas41/gradusnotation/issues. Contributions welcome — small, focused PRs preferred.\n\n## License\n\nMIT — Sean Johnson, Gradus School of Music Composition. See [LICENSE](LICENSE).\n",
  "bytes": 12316,
  "sha": "6fdbc395218be1d920b7d198653aeb47ce149f3427fb21dc737ef41721c616da",
  "repo_slug": "delmas41/gradusnotation",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_gradusmusic_notation_d4ebc0ec/readme"
}