ModalJazz

Recipes

A recipe gives an agent the steps of a larger job, for example the copy of a PDF score. The guide tool of the MCP server gives the agent the same text as this page.

Use a recipe

Name the recipe in your request, for example: "Use the transcribe-pdf recipe to copy ~/Downloads/minuet.pdf to ~/Scores/minuet.mj." The agent then gets the steps from guide.

In Claude Code, each recipe is also a slash command: /mcp__modaljazz__transcribe-pdf, and so on.

  • transcribe-pdf: Copy the music of a PDF score into a ModalJazz score.
  • import-musicxml: Make a ModalJazz score from a MusicXML file, and check it.
  • fix-measures: Read, change, and check a range of measures.

Programs that a recipe can use

Some recipes use other programs if they are installed. The guide tool tells the agent which of them are on your Mac. You do not need them, but a recipe works better with them.

ProgramForInstall with Homebrew
pdftoppm (poppler)Pictures of the pages of a PDFbrew install poppler
gs (Ghostscript)Pictures of the pages of a PDF, if pdftoppm is not installedbrew install ghostscript

An agent does not install a program without your permission.

transcribe-pdf

Copy the music of a PDF score into a ModalJazz score.

Can use: pdftoppm, gs

  1. Ask the user if the program that made the PDF can export MusicXML. If it can, use that file and follow the import-musicxml recipe. MusicXML is more exact than a picture of the page.

  2. Make a PNG image of each page at about 150 dpi:

    • With pdftoppm (poppler): pdftoppm -png -r 150 score.pdf page.
    • With gs (Ghostscript), if pdftoppm is not installed: gs -dNOPAUSE -dBATCH -sDEVICE=png16m -r150 -sOutputFile=page-%d.png score.pdf.
    • If neither program is installed, tell the user. Do not install software without asking the user.

  3. Look at the first page. Find the title, the composer, the parts, the key, the time, and the tempo.

  4. Make the score:

    • new_score with a new path and the nearest template, for example piano. The new score has eight empty measures.
    • run_command with :instrument to add, remove, move, or rename parts. Put the label of the part in front, as score_summary shows it: :P3 instrument rename "Tenor", :P5 instrument brace off. With no label, :instrument acts on P1. In a name, | starts a new line: :P1 instrument rename "S|A" stacks "S" over "A".
    • run_command with :title, :composer, :key, :time, and :tempo.
    • run_command with :bars +N to get the number of measures of the PDF.

    Then call score_summary to see the staff labels.

  5. Call text_format once and read it before you write.

  6. Write one page, or one system, with each write_measures call. Large writes are fast and correct, so do not cut the music into small steps of a few measures.

  7. After each write, read the same measures back with read_measures. Compare the text with the page image: the notes, the rhythm, the ties, the accidentals, the dynamics, and the marks. Fix each error before you write the next page. This check is the most important step.

  8. At the end, call score_summary, and compare the number of measures with the PDF. Call check_collisions: for each line, look at the measure in the page image, and write the measure again with the mark where the PDF has it (another side, as !p:above, or another time). Call save.

import-musicxml

Make a ModalJazz score from a MusicXML file, and check it.

  1. Call score_summary with the MusicXML file (.musicxml, .xml, or .mxl). The tools read the file. The reply shows the import warnings, if there are any.
  2. Read the measures that the warnings name with read_measures. Fix them with write_measures or run_command.
  3. Read some measures from the start, the middle, and the end of the score. Compare them with the original, if the user can show it.
  4. Call save with to set to a path that ends in .mj. The MusicXML file does not change.

fix-measures

Read, change, and check a range of measures.

  1. Call score_summary to see the staff labels and the number of measures.
  2. Read the measures with read_measures. Give staves to read only some staves.
  3. Make the change:
    • Use run_command for a change that a : command can make, for example :5-8 transpose +P8 or :5 key D. list_commands shows the commands.
    • Use write_measures for other changes. Write all the lines of a staff for each measure in the range. A staff with no line in the text does not change.
  4. Read the same measures again, and check that the change is correct. If it is not correct, call undo and try again.
  5. Call save when the user wants the change in the file.