convez.ai
PluginIntegração & APIsIntermediário
delmas41

Gradus Notation MCP

delmas41/gradusnotation

Notação musical sem GUI para agentes IA: JSON → SVG, MusicXML, MIDI

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para renderizar notação musical em SVG, MusicXML e MIDI a partir de JSON. Inclui análise harmônica, validação de ranges instrumentais, busca em base de conhecimento de teoria musical e utilitários de pitch. Sem GUI, sem autenticação — ideal para agentes IA gerarem partituras programaticamente.

Instalação

$npx convez-ai delmas41/gradusnotation

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
v0.1.1
Issues abertas
0
Contribuidores
2

Casos de uso

  • Gerar partituras por script para composição assistida por IA
  • Analisar harmonia e estrutura de peças MusicXML
  • Validar notas contra ranges práticos de instrumentos
  • Sugerir enarmonia e transposição em contexto tonal
  • Integrar notação musical em fluxos de agentes Claude

Veredito

Ferramenta sólida e sem dependências externas (TypeScript puro) para automatizar notação musical em pipelines de IA. Ideal para compositores e desenvolvedores que precisam gerar ou analisar partituras programaticamente, com suporte robusto a teoria musical.

README

A tradução para o português deste README ainda está na fila.

@gradusmusic/notation-mcp

Model Context Protocol server for the Gradus Notation API. Lets AI agents render music notation, validate input, and search a curated music-theory knowledge base — sponsored by Gradus School of Music Composition.

Why

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

Install

In Claude Code:

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

In Claude Desktop, add to your MCP config:

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

Tools

Notation (v1 — unchanged)

ToolWhat it does
notation_renderJSON score → SVG + MusicXML + MIDI in one call
notation_validatePre-flight validate input shape (cheaper than render)
knowledge_searchLook up music-theory chunks before generating notation
notation_examplesCanonical input examples (cache and reuse)
notation_schemaJSON Schema for the input shape (cache and reuse)

Theory / MaestroAnalyzer (v2 — replaces music21)

Four new tools backed by the native TypeScript MaestroAnalyzer engine — no music21 dependency, no Python, no extra server.

ToolWhat it does
theory_analyze_scoreParse MusicXML → full harmonic analysis + GKB knowledge chunks in one call
theory_parse_xmlParse a MusicXML string → maestroAnalyst Score JSON
theory_validate_rangesCheck every note in a Score against its instrument's practical range
theory_respellSuggest preferred enharmonic spelling for pitches in a key context
theory_pitch_utilsPure-function pitch arithmetic: midi_to_pitch, pitch_to_midi, interval_name, transpose_pitch

Typical workflows:

# 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" }

Input format

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

  • Shorthand: "C5/q" (quarter C5), "rest/q" (quarter rest), "[C4,E4,G4]/q" (chord)
  • Object form: { pitch: "C5", duration: "q", dynamic: "f", articulations: ["accent"] }

Bar lines are inferred from the time signature — write notes in time order and the API splits and ties anything that crosses a bar line.

Example

{
  "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"]
  }]
}

Configuration

Env varDefaultPurpose
GRADUS_NOTATION_API_BASEhttps://gradusmusic.comOverride for self-hosted or local-dev API
GRADUS_AGENT_NAME@gradusmusic/notation-mcpSelf-report your agent name in X-Agent-Name header

Attribution

Free 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):

Notation rendered by Gradus School of Music Composition (gradusmusic.com).

Documentation

Building locally

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

To smoke-test against the production API:

node test-client.mjs

Issues + contributions

Open an issue at https://github.com/delmas41/gradusnotation/issues. Contributions welcome — small, focused PRs preferred.

License

MIT — Sean Johnson, Gradus School of Music Composition. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados