delmas41/gradusnotation

Выполняет поиск в базе знаний Gradus по теории музыки для получения авторитетных исходных материалов. Корпус включает авторские учебные тексты, анализ хоралов Баха (408 хоралов), комментарии к партитурам более чем 50 оркестровых произведений, а также первоисточники от Фукса (1725) до Буланже. КОГДА ИСПОЛЬЗОВАТЬ: перед генерацией нотной записи, если нужно уточнить конкретный теоретический факт — типовое голосоведение при разрешении неаполитанского аккорда в доминанту, idiomatic генерал-бас для определённой каденции, чем хроматическая медианта в стиле одного композитора отличается от другого. Обращение к этому инструменту в первую очередь предотвращает выдумывание агентом стилистически неверных аккордовых последовательностей. КОГДА НЕ ИСПОЛЬЗОВАТЬ: для общих музыкальных понятий («что такое аккорд?»), которые любой LLM уже знает; для запросов, не связанных с теорией, например биографий композиторов, рекомендаций по исполнению или исторических дат — они выходят за рамки; для получения собственно нотной записи (используйте вместо этого notation_render или notation_examples). ВХОДНЫЕ ДАННЫЕ: укажите ЛИБО `topics` (теги в kebab-case), ЛИБО `step` (шаг учебного плана, 1-49). `topics` предпочтительнее; `step` — запасной вариант, если вы не знаете канонический тег темы. Если оба пусты, возвращается ошибка MISSING_QUERY. ВЫХОДНЫЕ ДАННЫЕ (JSON): { ok: true, requestId, chunks: [{ id, sourceType, sourceId, title, content, composer?, era?, topics: string[], curriculumSteps: number[], tokenEstimate }], meta: { query, returnedCount, totalTokens, responseTimeMs }, attribution }. `sourceType` — одно из: kg_concept, score_analysis, score_commentary, bach_chorale_analysis, composer, dictionary, curriculum, lesson_content, practicum, voice_leading, fugue, chorale_exercise и т.д. Пустой `chunks: []` означает, что по темам ничего не найдено — агенту следует опереться на собственные знания или попробовать другой тег. ПРИМЕР ВХОДНЫХ ДАННЫХ: { "topics": ["voice-leading", "deceptive-cadence"], "limit": 3 } ТИПИЧНАЯ ЗАДЕРЖКА: 200-700 мс (один вызов эмбеддинга Voyage 3 + RPC Supabase pgvector).

Получает шесть канонических примеров входных данных, покрывающих наиболее распространённые сценарии использования notation_render: одноголосная мелодия, двухголосный контрапункт (cantus firmus + контрапункт), аккордовая последовательность (каденция), смешанные ритмы с динамикой и артикуляцией, струнный квартет из четырёх инструментов и ноты, связанные лигой через тактовую черту. КОГДА ИСПОЛЬЗОВАТЬ: при первом знакомстве с этим MCP — получает примеры для изучения формата входных данных на конкретных отработанных шаблонах; перед вызовом notation_render, если вы не уверены, как выразить определённую музыкальную структуру (аккорд, многоголосный нотоносец, связанную лигой ноту); чтобы показать конечному пользователю, какие виды нотации возможны. КОГДА НЕ ИСПОЛЬЗОВАТЬ: после кэширования ответа (примеры стабильны во всех версиях v1 API; получайте один раз и используйте повторно вечно); когда вам нужны только формальные определения типов (используйте notation_schema для JSON Schema). ВХОДНЫЕ ДАННЫЕ: нет. Передайте пустой объект `{}`. ВЫХОДНЫЕ ДАННЫЕ (JSON): { ok: true, examples: [{ id, title, description, use_when, input: NotationInput }], docs: { schema, render, validate }, attribution }. Шесть примеров со стабильными id: single-melody, two-voice-counterpoint, chord-progression, mixed-rhythms, string-quartet-snippet, tied-across-bar. Каждый `input` — это полная полезная нагрузка, которую можно передать напрямую в notation_render. ПРИМЕР ВХОДНЫХ ДАННЫХ: {} (без параметров) ТИПИЧНАЯ ЗАДЕРЖКА: 30–200 мс. Ответ кэшируется на CDN с длинным TTL - последующие вызовы практически бесплатны.

Преобразует нотную запись из JSON-оценки в три выходных формата за один вызов: встраиваемый SVG (гравировка через Verovio со шрифтом Bravura SMuFL — тот же движок, что у IMSLP и Music Encoding Initiative), MusicXML с круговой совместимостью (чисто открывается в Sibelius, Finale, MuseScore, Dorico) и MIDI в формате SMF Type-1, закодированный в base64. КОГДА ИСПОЛЬЗОВАТЬ: когда агенту нужно показать пользователю гравированную нотацию (композитору, демонстрирующему идею, учителю, создающему рабочий лист, создателю контента, встраивающему пример нотации), или при конвертации JSON-оценки в форматы файлов, которые могут читать другие агенты или инструменты (MusicXML для настольных нотных редакторов, MIDI для секвенсоров). КОГДА НЕ ИСПОЛЬЗОВАТЬ: если вы не уверены, что входные данные корректны → сначала вызовите notation_validate (гораздо дешевле, без отрисовки); если вы еще не знаете формат входных данных → вызовите notation_examples или notation_schema; если вам нужны теоретические факты перед сочинением → сначала вызовите knowledge_search. ВХОДНЫЕ ДАННЫЕ: требуется `instruments` (непустой массив). Каждый инструмент имеет `name` (обязательно; ключ выводится из названия: "Cello" → басовый, "Viola" → альтовый, "Timpani" → ударный — можно переопределить через `clef`) и либо `notes` (сокращение для одного голоса), либо `voices` (несколько голосов). Высоты нот задаются в научной нотации ("C4", "F#5", "Bb3"); длительности — буквенными кодами ("w", "h", "q", "8", "16", "32", "64" с необязательным "." для пунктирной, ".." для двойной пунктирной). Тактовые черты выводятся из `timeSignature` (по умолчанию [4,4]); ноты, пересекающие тактовую черту, автоматически разбиваются и связываются — агентам не нужно считать доли. ВЫХОДНЫЕ ДАННЫЕ (JSON, успех): { ok: true, requestId, outputs: { svg: string, musicxml: string, midiBase64: string }, meta: { measureCount, instrumentCount, voiceCount, durationBeats, renderTimeMs }, warnings?: ValidationIssue[], attribution }. ValidationIssue = { path, code, message, fix?, severity: "error"|"warning" }. Обычно SVG занимает 60-100 КБ со встроенным шрифтом Bravura; MusicXML — несколько КБ; MIDI — менее 1 КБ. ВЫХОДНЫЕ ДАННЫЕ (JSON, ошибка валидации): { ok: false, requestId, errors:… }

Получает JSON-схему (Draft 2020-12), описывающую входную структуру notation_render. Включает все поля, их типы, значения по умолчанию, правила валидации (включая регулярное выражение для shorthand-string) и `$defs` для Instrument, VoiceLine, Note и NoteObject. КОГДА ИСПОЛЬЗОВАТЬ: при первом знакомстве с этим MCP, когда нужны машиночитаемые определения типов; при создании клиента, который валидирует входные данные на стороне клиента перед вызовом notation_render; при генерации кода (типы TypeScript, схемы Zod и т.д.), который использует этот формат. КОГДА НЕ ИСПОЛЬЗОВАТЬ: после кэширования ответа (стабильный во всём v1 API); когда нужно обучение на примерах (используйте notation_examples — рабочие полезные нагрузки легче читать, чем определения схем). ВХОДНЫЕ ДАННЫЕ: нет. Передайте пустой объект `{}`. ВЫХОДНЫЕ ДАННЫЕ (JSON): { ok: true, schema: { $schema: "https://json-schema.org/draft/2020-12/schema", $id, title, type: "object", required: ["instruments"], properties, $defs: { Instrument, VoiceLine, Note, NoteObject } }, docs: { examples, render, validate }, attribution }. Поле `schema` — это полный документ JSON-схемы. ПРИМЕР ВХОДНЫХ ДАННЫХ: {} (без параметров) ТИПИЧНАЯ ЗАДЕРЖКА: 30-200 мс. Ответ кэшируется на CDN с большим TTL — последующие вызовы практически бесплатны.

Выполняет предварительную проверку ввода notation_render без рендеринга. Возвращает ошибки с конкретным полем `fix`, которое сообщает агенту, как именно исправить повреждённый ввод. Значительно дешевле, чем notation_render, поскольку полностью пропускает этап гравировки Verovio. КОГДА ИСПОЛЬЗОВАТЬ: когда повторяете форму ввода и не уверены, что она корректна; когда ввод получен от пользователя или от LLM и может быть повреждён; когда нужно показать точные ошибки валидации конечному пользователю до полноценного рендеринга; когда изучаете формат ввода (используйте вместе с notation_examples для просмотра канонических примеров). КОГДА НЕ ИСПОЛЬЗОВАТЬ: если ввод заведомо корректен (просто вызовите notation_render — он тоже проверяет внутри); если вы ещё не изучили схему (сначала вызовите notation_schema или notation_examples, чтобы увидеть формат). ВВОД: форма идентична notation_render. Массив `instruments` обязателен (каждый элемент содержит `name` и `notes` или `voices`). ВЫВОД (JSON, валидный): { ok: true, requestId, valid: true, warnings: ValidationIssue[], meta: { measureCount, instrumentCount, voiceCount, durationBeats }, attribution }. Warnings — неблокирующие уведомления (например, нестандартная обработка размера). ВЫВОД (JSON, невалидный): { ok: false, requestId, valid: false, errors: ValidationIssue[], warnings, attribution }. Каждый ValidationIssue: { path: "instruments[0].voices[0].notes[3]", code: "BAD_PITCH"|"BAD_DURATION"|"MISSING_FIELD"|"BAD_KEY_SIG"|..., message, fix: "Use scientific notation: letter A-G + optional # or b + octave number, e.g. C4, F#5, Bb3.", severity: "error"|"warning" }. Покажите `fix` пользователю или используйте его для автоматического исправления. ПРИМЕР ВВОДА: { "instruments": [{ "name": "Violin", "notes": ["C5/q","D5/q","E5/q","F5/q"] }] } ТИПИЧНАЯ ЗАДЕРЖКА: 30-100 мс (без рендеринга Verovio; чистое преобразование JSON в Score + расчёт тактовых линий).

Эндпоинт для однократного вызова: разбирает MusicXML → запускает полный конвейер гармонического анализа MaestroAnalyzer → запрашивает в Gradus Knowledge Base (GKB) подготовленные фрагменты теории, соответствующие обнаруженным характеристикам партитуры. Возвращает как алгоритмический анализ, так и релевантные знания, написанные вручную, за один вызов. КОГДА ИСПОЛЬЗОВАТЬ: когда у агента есть партитура MusicXML и он хочет узнать, что в ней интересного с точки зрения гармоники: тональность, траекторию локальных тональностей, анализ аккордов с римскими цифрами, каденции, фразовую структуру, стилистический период И релевантный теоретический контекст из GKB (правила голосоведения, гармонический словарь, оркестровые примечания, исторический контекст). Это самый насыщенный анализ за один вызов из доступных. КОГДА НЕ ИСПОЛЬЗОВАТЬ: если вам нужна только проверка диапазонов (theory_validate_ranges); если вам нужна только перезапись (theory_respell); если вы хотите выполнить прямой поиск по GKB без анализа партитуры (knowledge_search). ВХОДНЫЕ ДАННЫЕ: { xml: string, maxKnowledgeTokens?: number (по умолчанию 1500), includeKnowledge?: boolean (по умолчанию true) } ВЫХОДНЫЕ ДАННЫЕ: { meta: { partCount, noteCount, measureCount }, analysis: { overallKey: { key, mode, confidence }, localKeys: [{ measure, key, confidence }], chordAnalyses: [{ measure, beat, primary, readings: [{ rn, rnAscii, inversion, localKey, confidence }], tendencyTones }], cadences: [{ type: "PAC"|"IAC"|"HC"|"DC"|"Plagal"|"Phrygian"|"unclear", ... }], phrases: [{ index, measureStart, measureEnd, fermataMeasures }], }, submissionHints: { stylePeriod, focusAreas, rationale }, // выведенная стилистическая эвристика knowledge: { topics: string[], // теги GKB, полученные из анализа chunks: [{ title, content, sourceType, era, composer, curriculumSteps }], totalTokens: number, }, } ТИПИЧНАЯ ЗАДЕРЖКА: 200–600 мс (анализ выполняется на чистом JS; GKB добавляет один вызов эмбеддинга Voyage ~100–200 мс).

Преобразует строку MusicXML в объект Score библиотеки maestroAnalyst. Score — входной тип для theory_validate_ranges, его можно передать в любую аналитическую функцию maestroAnalyst. КОГДА ИСПОЛЬЗОВАТЬ: когда у вас есть MusicXML-файл (например, экспортированный из Sibelius, Finale, MuseScore, Dorico или созданный с помощью notation_render) и вы хотите его проанализировать — определить тональность, проверить диапазоны, переписать знаки альтерации. Это точка входа для нативного конвейера анализа, который заменяет music21. ОГРАНИЧЕНИЯ: принимает текст MusicXML в формате score-partwise. НЕ принимает ZIP-архивы .mxl — при необходимости распакуйте их. Score-timewise и другие не-partwise форматы не поддерживаются. ВХОДНЫЕ ДАННЫЕ: { xml: string } — полный текст документа MusicXML. ВЫХОДНЫЕ ДАННЫЕ: { ok, requestId, score: Score, meta: { partCount, noteCount, measureCount }, attribution }. Полученный JSON объекта Score затем можно передать в theory_validate_ranges или любой другой инструмент теории. ТИПИЧНЫЙ РАЗМЕР: хорал Баха (4 партии, 32 такта) создает Score примерно с 512 нотами. Часть симфонии Бетховена (12 партий, 400 тактов) может дать более 8 000 нот. Уложитесь в лимит контекста или обрабатывайте частями.

Набор быстрых чистых утилит для работы с высотой тона, заменяющих наиболее используемые функции music21 без сетевых задержек. ОПЕРАЦИИ: midi_to_pitch - MIDI-номер → строковое представление ноты. midi=60 → "C4". preferFlats=true → обозначения "Db". pitch_to_midi - строковое представление ноты → MIDI-номер. "C4"→60, "F#5"→78, "Bb3"→46. Возвращает null для пауз. interval_name - количество полутонов → строка качества интервала. 0→"P1" 3→"m3" 4→"M3" 7→"P5" 12→"P8". Составные интервалы: 14→"M2+8". transpose_pitch - сдвигает ноту на заданное количество полутонов. "C4"+7→"G4", "E5"+-2→"D5". preferFlats управляет обозначением чёрных клавиш. КОГДА ИСПОЛЬЗОВАТЬ: быстрая арифметика при генерации или анализе партитуры без запуска полного конвейера анализа; заполнение таблиц MIDI-вывода; маркировка интервалов в учебных целях; транспонирование отдельных нот во время сочинения. ВХОДНЫЕ ДАННЫЕ: { op: string, ...params }, где op — одна из указанных операций. ПРИМЕРЫ: { op: "midi_to_pitch", midi: 60 } → { pitch: "C4" } { op: "pitch_to_midi", pitch: "F#5" } → { midi: 78 } { op: "interval_name", semitones: 7 } → { interval: "P5" } { op: "transpose_pitch", pitch: "C4", semitones: 7 } → { pitch: "G4" } { op: "transpose_pitch", pitch: "E4", semitones: 1, preferFlats: true } → { pitch: "F4" }

Предлагает предпочтительное энгармоническое написание для одного или нескольких тонов в заданном тональном контексте. Выбирает написание, диатоническое для тональности (например, F# в G major, Gb в F major). Использует предпочтение знаков альтерации тональности (диезы/бемоли) как критерий разрешения для хроматических проходящих тонов. КОГДА ИСПОЛЬЗОВАТЬ: после OMR (оптического распознавания музыки) для исправления неправильно написанных знаков альтерации; при создании нотной записи, когда не уверены, написать F# или Gb; при транспонировании — переписать после полутонового сдвига для сохранения диатонического написания; перед вызовом notation_render для очистки знаков альтерации. ВХОДНЫЕ ДАННЫЕ: { keyContext: string, pitches: string[] } ИЛИ { keyContext: string, pitch: string }. Строки тонов используют научную нотацию: "F#4", "Bb3", "C5", "Eb4". ВЫХОДНЫЕ ДАННЫЕ: { ok, requestId, keyContext, results: [{ input, output, changed }], attribution }. `changed` принимает значение true, если написание было скорректировано. ПРИМЕРЫ: { keyContext: "F major", pitches: ["F#4", "Bb4", "E4"] } → F#4→Gb4 (Gb диатоничен для F major), Bb4 без изменений, E4 без изменений. { keyContext: "G major", pitch: "Gb4" } → Gb4→F#4 (F# диатоничен для G major).

Проверяет каждую ноту в Score JSON на соответствие стандартному практическому диапазону инструмента. Возвращает предупреждения о выходящих за диапазон высотах с указанием такта, доли, MIDI-номера и уровня серьезности. КОГДА ИСПОЛЬЗОВАТЬ: после разбора файла MusicXML с помощью theory_parse_xml и перед анализом — чтобы выявить неисполнимые или экстремальные ноты на раннем этапе; при программном создании или редактировании партитуры и необходимости проверить соответствие инструментальному диапазону; когда студент представляет сочинение для рецензии и нужно отметить ошибки диапазона. УРОВНИ СЕРЬЕЗНОСТИ: "error" — нота находится более чем на 1 полутон вне практического диапазона; "warn" — нота находится на границе (в пределах 1 полутона). ПОДДЕРЖИВАЕМЫЕ ИНСТРУМЕНТЫ (частичное совпадение имени, без учета регистра): Violin, Viola, Cello, Double Bass, Harp, Flute, Piccolo, Oboe, English Horn, Clarinet, Bass Clarinet, Bassoon, Contrabassoon, Soprano/Alto/Tenor/Baritone Sax, Horn, Trumpet, Trombone, Tuba, Piano, Organ, Marimba, Xylophone, Vibraphone, Glockenspiel, Timpani, Soprano/Mezzo/Alto/Tenor/Baritone/Bass (voice). ВХОДНЫЕ ДАННЫЕ: объект maestroAnalyst Score — получите его, вызвав theory_parse_xml с текстом MusicXML. ВЫХОДНЫЕ ДАННЫЕ: { ok, requestId, warnings: [{ measure, beat, pitch, midi, partId, instrumentName, min, max, severity }], attribution }. Пустой массив warnings означает, что все ноты в диапазоне. ПРИМЕР: передайте Score с партией скрипки, содержащей ноту A7 (MIDI 105) — он вернет уровень серьезности "error", поскольку диапазон скрипки заканчивается около B7/MIDI 107, но A7 выходит за пределы практического диапазона.