Playbykey Music Theory

@playbykey/theory-mcp

Um servidor MCP que expõe @playbykey/theory como ferramentas de teoria musical chamáveis por IA.

O MCP permite que um assistente de IA chame o motor de teoria diretamente como ferramentas, em vez de raciocinar sobre escalas, modos e relações de tonalidade a partir de dados de treinamento. Relações de teoria musical, resolvidas deterministicamente por meio de relações fixas de intervalos e graus de escala.

Consulte a página @playbykey/mcp para obter as mesmas instruções de configuração e a referência completa das ferramentas.

Instalação

Nenhuma instalação global é necessária - npx busca e executa o pacote sob demanda. Requer Node.js (para npx).

Claude Desktop

Edite o arquivo de configuração do MCP (claude_desktop_config.json) por meio das configurações do Claude Desktop.

{
  "mcpServers": {
    "theory": {
      "command": "npx",
      "args": ["-y", "@playbykey/theory-mcp"]
    }
  }
}

Reinicie o Claude Desktop após salvar e verifique nas configurações se theory aparece como conectado.

Cursor

Localização do arquivo de configuração:

• Global (todos os projetos): ~/.cursor/mcp.json
• Somente projeto: .cursor/mcp.json na raiz do seu projeto

{
  "mcpServers": {
    "theory": {
      "command": "npx",
      "args": ["-y", "@playbykey/theory-mcp"]
    }
  }
}

Reinicie o Cursor após salvar e verifique nas configurações do MCP se theory aparece como conectado.

Claude Code

Escopo do projeto (recomendado) - envie um .mcp.json na raiz do seu repositório para que o servidor esteja disponível para todos os colaboradores após git clone:

{
  "mcpServers": {
    "theory": {
      "command": "npx",
      "args": ["-y", "@playbykey/theory-mcp"]
    }
  }
}

Escopo local - registre o servidor apenas para você neste projeto, sem enviar nada:

claude mcp add theory npx -y @playbykey/theory-mcp

Escopo global - registre o servidor para você em todos os projetos desta máquina:

claude mcp add theory npx -y @playbykey/theory-mcp --scope user

Execute claude mcp list para confirmar que theory aparece como conectado.

Ferramentas

Modos

get_mode_notes - Retorna as 7 notas de um modo diatônico.
Entrada: root (nota), mode (nome do modo)
Exemplo: get_mode_notes("D", "dorian") → D, E, F, G, A, B, C

get_parent_scale_modes - Retorna todas as 7 rotações modais da tonalidade principal.
Entrada: root (nota), mode (nome do modo)
Exemplo: get_parent_scale_modes("D", "dorian") → C jônio, D dórico, E frígio, F lídio, G mixolídio, A eólio, B lócrio

get_modal_root - Retorna a nota fundamental de um modo dentro de uma tonalidade principal (maior).
Entrada: parent_key (nota), mode (nome do modo)
Exemplo: get_modal_root("C", "dorian") → D

get_relative_minor - Retorna a fundamental do relativo menor para uma tonalidade maior.
Entrada: major_key (nota)
Exemplo: get_relative_minor("C") → A

get_relative_major - Retorna a fundamental do relativo maior para uma tonalidade menor.
Entrada: minor_key (nota)
Exemplo: get_relative_major("A") → C

get_mode_info - Retorna metadados de exibição para um modo: nome, grau da escala e descrição característica.
Entrada: mode (nome do modo)
Exemplo: get_mode_info("dorian") → Dórico, grau 2, "Menor com 6ª aumentada"

Círculo de Quintas

get_circle_of_fifths - Retorna todas as 12 notas cromáticas em ordem ascendente de quintas a partir de C.
Entrada: nenhuma
Exemplo → C, G, D, A, E, B, F#, C#, G#, D#, A#, F

Armaduras de Clave

get_key_signature - Retorna a quantidade de sustenidos ou bemóis para uma determinada tonalidade, tratada como tônica maior (armaduras de tom menor não são expostas por esta ferramenta). Resolve para a grafia enarmônica convencionalmente escrita - get_key_signature("A#") retorna os 2 bemóis de Si bemol maior, não os de Lá sustenido. Para a quantidade de uma fundamental exatamente como escrita, use get_spelled_accidental_count com get_root_letter.
Entrada: key (nota)
Exemplo: get_key_signature("D") → 2 sustenidos

Escalas

get_scale_notes - Retorna as notas de uma escala por tipo.
Entrada: root (nota), scale_type (um de: major, blues, pentatonic-major, pentatonic-minor, harmonic-minor, melodic-minor, chromatic)
Exemplo: get_scale_notes("A", "blues") → A, C, D, D#, E, G

build_note_map - Retorna dados estruturados por nota: nome da nota, grau da escala (baseado em 1) e deslocamento em semitons da fundamental.
Entrada: root (nota), scale_type
Exemplo: build_note_map("C", "major") → [{note:"C", scaleDegree:1, semitoneOffset:0}, {note:"D", scaleDegree:2, semitoneOffset:2}, ...]

get_scale_degree - Retorna o grau da escala (baseado em 1) de uma nota dentro de uma escala, ou nulo se a nota não estiver na escala.
Entrada: root (nota), scale_type, note (nota)
Exemplo: get_scale_degree("C", "major", "E") → 3

is_note_in_scale - Retorna se uma nota pertence a uma determinada escala.
Entrada: root (nota), scale_type, note (nota)
Exemplo: is_note_in_scale("C", "major", "F#") → falso

get_melodic_minor_notes - Retorna as sete notas da escala menor melódica ascendente.
Entrada: root (nota)
Exemplo: get_melodic_minor_notes("C") → C, D, D#, F, G, A, B

get_melodic_minor_mode_notes - Retorna as sete notas de um modo menor melódico.
Entrada: root (nota), mode (um de: melodic-minor, dorian-b2, lydian-augmented, lydian-dominant, mixolydian-b6, locrian-nat2, altered)
Exemplo: get_melodic_minor_mode_notes("C", "altered") → C, C#, D#, E, F#, G#, A#

get_harmonic_minor_mode_notes - Retorna as sete notas de um modo menor harmônico.
Entrada: root (nota), mode (um de: harmonic-minor, phrygian-dominant)
Exemplo: get_harmonic_minor_mode_notes("C", "phrygian-dominant") → C, C#, E, F, G, G#, A#

get_bebop_scale_notes - Retorna as oito notas de uma variante de escala bebop - uma escala diatônica mais uma nota de passagem cromática.
Entrada: root (nota), type (um de: bebop-dominant, bebop-major, bebop-dorian)
Exemplo: get_bebop_scale_notes("C", "bebop-dominant") → C, D, E, F, G, A, A#, B

Intervalos

resolve_interval - Retorna a nota de origem e a nota de destino para um intervalo nomeado dentro de um contexto de fundamental.
Entrada: root (nota), interval (ID do intervalo, ex.: major_3rd, perfect_5th)
Exemplo: resolve_interval("C", "major_3rd") → C para E (4 semitons)

get_semitone_distance - Retorna a distância ascendente em semitons entre duas notas (0-11).
Entrada: from (nota), to (nota)
Exemplo: get_semitone_distance("C", "E") → 4

Grafia de Notas

get_sharps - Reescreve uma lista de notas para a grafia canônica com sustenidos. A maioria das ferramentas aceita entrada com bemóis diretamente, mas get_flats e get_enharmonic_labels exigem entrada com sustenidos - use esta ferramenta para normalizar notas com bemóis antes de chamar essas duas.
Entrada: notes (sustenido ou bemol)
Exemplo: get_sharps(["Db", "C#", "D"]) → C#, C#, D

get_flats - Reescreve uma lista de notas com sustenidos como bemóis. Notas naturais não são afetadas.
Entrada: notes (deve estar com sustenidos)
Exemplo: get_flats(["C#", "D"]) → Db, D

get_enharmonic_labels - Retorna rótulos de exibição combinados de sustenido/bemol para uma lista de notas com sustenidos. Notas naturais não são afetadas.
Entrada: notes (deve estar com sustenidos)
Exemplo: get_enharmonic_labels(["C#", "D"]) → Db/C#, D

get_root_letter - Resolve qual letra (A-G) uma fundamental deve ser grafada sob uma preferência de sustenido ou bemol. Alimenta spell_diatonic_scale.
Entrada: root (nota), preference (sharp ou flat)
Exemplo: get_root_letter("F#", "flat") → G

spell_diatonic_scale - Reescreve uma escala diatônica de 7 notas para que cada uma das 7 letras A-G seja usada exatamente uma vez, cobrindo grafias que uma nota simples não pode representar sozinha (B#, E#, Cb, Fb, duplos sustenidos, duplos bemóis).
Entrada: notes (7 notas em ordem de escala), root_letter (de get_root_letter)
Exemplo: spell_diatonic_scale(["F#","G#","A#","B","C#","D#","F"], "F") → F#, G#, A#, B, C#, D#, E#

get_spelled_accidental_count - Retorna a quantidade de sustenidos ou bemóis para a grafia correta de uma escala diatônica de 7 notas, incluindo quantos são acidentes duplos. Funciona igualmente para escala maior ou menor natural - uma tonalidade e seu relativo menor compartilham a mesma quantidade.
Entrada: notes (7 notas em ordem de escala), root_letter (de get_root_letter)
Exemplo: get_spelled_accidental_count(["A#","C","D","D#","F","G","A"], "A") → 7 sustenidos (3 duplos sustenidos)

Acordes

get_chord_notes - Retorna as notas de um acorde dado uma fundamental e um tipo de acorde.
Entrada: root (nota), chord_type (um dos 22 tipos de acorde, ex.: major-triad, dominant-7th, major-13th)
Exemplo: get_chord_notes("C", "major-triad") → C, E, G

get_diatonic_chords - Retorna as 7 tríades diatônicas para uma tonalidade/modo, uma por grau da escala, em ordem de grau.
Entrada: root (nota), mode (nome do modo, opcional - padrão: jônio)
Exemplo: get_diatonic_chords("C", "ionian") → C tríade maior, D tríade menor, E tríade menor, F tríade maior, G tríade maior, A tríade menor, B tríade diminuta

get_chord_by_degree - Retorna o acorde diatônico em um grau específico da escala (1-7) para uma tonalidade/modo.
Entrada: degree (inteiro 1-7), root (nota), mode (nome do modo, opcional - padrão: jônio)
Exemplo: get_chord_by_degree(5, "C", "ionian") → G tríade maior

get_available_inversions - Retorna os números de inversão válidos para um tipo de acorde, com base na quantidade de notas.
Entrada: chord_type
Exemplo: get_available_inversions("major-9th") → 0, 1, 2, 3, 4

get_chord_inversion - Reordena as notas de um acorde para que a nota do acorde da inversão dada fique mais grave.
Entrada: root (nota), chord_type, inversion (inteiro, intervalo válido depende do tipo de acorde)
Exemplo: get_chord_inversion("C", "major-triad", 1) → E, G, C

detect_chords - Identifica cada correspondência de acorde (fundamental, tipo) para um conjunto de notas, agrupado por fundamental.
Entrada: notes (matriz de notas, qualquer ordem)
Exemplo: detect_chords(["E", "C", "G"]) → { C: [tríade maior] }

Progressões

get_progression_in_key - Renderiza uma progressão nomeada do catálogo como acordes em uma determinada tonalidade, em ordem.
Entrada: progression_id (um de I-V-vi-IV, ii-V-I, I-IV-V, vi-IV-I-V, 12-bar-blues, I-vi-IV-V, I-vi-ii-V), root (nota)
Exemplo: get_progression_in_key("I-V-vi-IV", "C") → C tríade maior, G tríade maior, A tríade menor, F tríade maior

get_roman_numeral - Retorna o numeral romano para um grau da escala em um modo - maiúsculas/minúsculas e sufixo refletem a qualidade da tríade diatônica.
Entrada: degree (inteiro 1-7), mode (nome do modo, opcional - padrão: jônio)
Exemplo: get_roman_numeral(7, "ionian") → vii°

Transposição

transpose - Transpõe um conjunto de notas de uma tonalidade para outra pela distância em semitons entre as duas fundamentais.
Entrada: notes (matriz de notas), from_root (nota), to_root (nota)
Exemplo: transpose(["C", "E", "G"], "C", "D") → D, F#, A

MIDI e Frequência

note_to_midi - Retorna o número da nota MIDI para uma nota em uma determinada oitava, usando notação científica de altura (C4 = dó central = MIDI 60).
Entrada: note (nota), octave (inteiro)
Exemplo: note_to_midi("C", 4) → 60

midi_to_note - Retorna a nota e a oitava para um determinado número de nota MIDI - o inverso de note_to_midi.
Entrada: midi_number (inteiro 0-127)
Exemplo: midi_to_note(69) → A4

note_to_frequency - Retorna a frequência em Hz para uma nota em uma determinada oitava, temperamento igual, A4 = 440Hz.
Entrada: note (nota), octave (inteiro)
Exemplo: note_to_frequency("A", 4) → 440 Hz

Licença

MIT