Playbykey Music Theory

@playbykey/theory-mcp

Un servidor MCP que expone @playbykey/theory como herramientas de teoría musical invocables por IA.

MCP permite que un asistente de IA llame directamente al motor de teoría como herramientas, en lugar de razonar sobre escalas, modos y relaciones de tonalidades a partir de datos de entrenamiento. Las relaciones de teoría musical se resuelven de forma determinista mediante relaciones fijas de intervalos y grados de escala.

Consulta la página de @playbykey/mcp para las mismas instrucciones de configuración y la referencia completa de herramientas.

Instalación

No se necesita instalación global: npx descarga y ejecuta el paquete bajo demanda. Requiere Node.js (para npx).

Claude Desktop

Edita el archivo de configuración de MCP (claude_desktop_config.json) a través de la configuración de Claude Desktop.

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

Reinicia Claude Desktop después de guardar y luego revisa su configuración para confirmar que theory aparece como conectado.

Cursor

Ubicación del archivo de configuración:

• Global (todos los proyectos): ~/.cursor/mcp.json
• Solo proyecto: .cursor/mcp.json en la raíz de tu proyecto

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

Reinicia Cursor después de guardar y luego revisa su configuración de MCP para confirmar que theory aparece como conectado.

Claude Code

Alcance del proyecto (recomendado) - confirma un .mcp.json en la raíz de tu repositorio para que el servidor esté disponible para cada colaborador después de git clone:

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

Alcance local - registra el servidor solo para ti en este proyecto, sin confirmar nada:

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

Alcance global - registra el servidor para ti en todos los proyectos de esta máquina:

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

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

Herramientas

Modos

get_mode_notes - Devuelve las 7 notas de un modo diatónico.
Entrada: root (nota), mode (nombre del modo)
Ejemplo: get_mode_notes("D", "dorian") → D, E, F, G, A, B, C

get_parent_scale_modes - Devuelve las 7 rotaciones modales de la tonalidad principal.
Entrada: root (nota), mode (nombre del modo)
Ejemplo: get_parent_scale_modes("D", "dorian") → C jónico, D dórico, E frigio, F lidio, G mixolidio, A eólico, B locrio

get_modal_root - Devuelve la nota raíz de un modo dentro de una tonalidad principal (mayor).
Entrada: parent_key (nota), mode (nombre del modo)
Ejemplo: get_modal_root("C", "dorian") → D

get_relative_minor - Devuelve la raíz del relativo menor para una tonalidad mayor.
Entrada: major_key (nota)
Ejemplo: get_relative_minor("C") → A

get_relative_major - Devuelve la raíz del relativo mayor para una tonalidad menor.
Entrada: minor_key (nota)
Ejemplo: get_relative_major("A") → C

get_mode_info - Devuelve metadatos de visualización para un modo: nombre, grado de escala y descripción característica.
Entrada: mode (nombre del modo)
Ejemplo: get_mode_info("dorian") → Dórico, grado 2, "Menor con sexta elevada"

Círculo de Quintas

get_circle_of_fifths - Devuelve las 12 notas cromáticas en orden ascendente de quintas comenzando desde C.
Entrada: ninguna
Ejemplo → C, G, D, A, E, B, F#, C#, G#, D#, A#, F

Armaduras de Clave

get_key_signature - Devuelve el número de sostenidos o bemoles para una tonalidad dada, tratada como tónica mayor (las armaduras de tonalidades menores no se exponen con esta herramienta). Resuelve a la grafía enarmónica que se escribe convencionalmente: get_key_signature("A#") devuelve los 2 bemoles de Si bemol mayor, no los de La sostenido. Para el conteo de una raíz exactamente como se escribe, usa get_spelled_accidental_count con get_root_letter.
Entrada: key (nota)
Ejemplo: get_key_signature("D") → 2 sostenidos

Escalas

get_scale_notes - Devuelve las notas de una escala según su tipo.
Entrada: root (nota), scale_type (uno de: major, blues, pentatonic-major, pentatonic-minor, harmonic-minor, melodic-minor, chromatic)
Ejemplo: get_scale_notes("A", "blues") → A, C, D, D#, E, G

build_note_map - Devuelve datos estructurados por nota: nombre de la nota, grado de escala (basado en 1) y desplazamiento en semitonos desde la raíz.
Entrada: root (nota), scale_type
Ejemplo: build_note_map("C", "major") → [{note:"C", scaleDegree:1, semitoneOffset:0}, {note:"D", scaleDegree:2, semitoneOffset:2}, ...]

get_scale_degree - Devuelve el grado de escala (basado en 1) de una nota dentro de una escala, o null si la nota no está en la escala.
Entrada: root (nota), scale_type, note (nota)
Ejemplo: get_scale_degree("C", "major", "E") → 3

is_note_in_scale - Devuelve si una nota pertenece a una escala dada.
Entrada: root (nota), scale_type, note (nota)
Ejemplo: is_note_in_scale("C", "major", "F#") → false

get_melodic_minor_notes - Devuelve las siete notas de la escala menor melódica ascendente.
Entrada: root (nota)
Ejemplo: get_melodic_minor_notes("C") → C, D, D#, F, G, A, B

get_melodic_minor_mode_notes - Devuelve las siete notas de un modo menor melódico.
Entrada: root (nota), mode (uno de: melodic-minor, dorian-b2, lydian-augmented, lydian-dominant, mixolydian-b6, locrian-nat2, altered)
Ejemplo: get_melodic_minor_mode_notes("C", "altered") → C, C#, D#, E, F#, G#, A#

get_harmonic_minor_mode_notes - Devuelve las siete notas de un modo menor armónico.
Entrada: root (nota), mode (uno de: harmonic-minor, phrygian-dominant)
Ejemplo: get_harmonic_minor_mode_notes("C", "phrygian-dominant") → C, C#, E, F, G, G#, A#

get_bebop_scale_notes - Devuelve las ocho notas de una variante de escala bebop: una escala diatónica más un tono de paso cromático.
Entrada: root (nota), type (uno de: bebop-dominant, bebop-major, bebop-dorian)
Ejemplo: get_bebop_scale_notes("C", "bebop-dominant") → C, D, E, F, G, A, A#, B

Intervalos

resolve_interval - Devuelve la nota inicial y la nota final para un intervalo nombrado dentro de un contexto de raíz.
Entrada: root (nota), interval (ID de intervalo, p. ej. major_3rd, perfect_5th)
Ejemplo: resolve_interval("C", "major_3rd") → C a E (4 semitonos)

get_semitone_distance - Devuelve la distancia ascendente en semitonos entre dos notas (0-11).
Entrada: from (nota), to (nota)
Ejemplo: get_semitone_distance("C", "E") → 4

Ortografía de Notas

get_sharps - Reescribe una lista de notas a la ortografía canónica con sostenidos. La mayoría de las herramientas aceptan entrada con bemoles directamente, pero get_flats y get_enharmonic_labels requieren entrada con sostenidos: usa esto para normalizar notas con bemoles antes de llamar a esas dos.
Entrada: notes (sostenido o bemol)
Ejemplo: get_sharps(["Db", "C#", "D"]) → C#, C#, D

get_flats - Reescribe una lista de notas con sostenidos como bemoles. Las notas naturales no se ven afectadas.
Entrada: notes (debe estar escrita con sostenidos)
Ejemplo: get_flats(["C#", "D"]) → Db, D

get_enharmonic_labels - Devuelve etiquetas de visualización combinadas de sostenido/bemol para una lista de notas con sostenidos. Las notas naturales no se ven afectadas.
Entrada: notes (debe estar escrita con sostenidos)
Ejemplo: get_enharmonic_labels(["C#", "D"]) → Db/C#, D

get_root_letter - Resuelve qué letra (A-G) debe usarse para una raíz bajo una preferencia de sostenido o bemol. Alimenta a spell_diatonic_scale.
Entrada: root (nota), preference (sharp o flat)
Ejemplo: get_root_letter("F#", "flat") → G

spell_diatonic_scale - Reescribe una escala diatónica de 7 notas para que cada una de las 7 letras A-G se use exactamente una vez, cubriendo grafías que una nota simple no puede representar por sí sola (B#, E#, Cb, Fb, dobles sostenidos, dobles bemoles).
Entrada: notes (7 notas en orden de escala), root_letter (de get_root_letter)
Ejemplo: spell_diatonic_scale(["F#","G#","A#","B","C#","D#","F"], "F") → F#, G#, A#, B, C#, D#, E#

get_spelled_accidental_count - Devuelve el número de sostenidos o bemoles para la ortografía correcta de una escala diatónica de 7 notas, incluyendo cuántos son dobles alteraciones. Funciona indistintamente en una escala mayor o menor natural: una tonalidad y su relativo menor comparten el mismo conteo.
Entrada: notes (7 notas en orden de escala), root_letter (de get_root_letter)
Ejemplo: get_spelled_accidental_count(["A#","C","D","D#","F","G","A"], "A") → 7 sostenidos (3 dobles sostenidos)

Acordes

get_chord_notes - Devuelve las notas de un acorde dada una raíz y un tipo de acorde.
Entrada: root (nota), chord_type (uno de los 22 tipos de acorde, p. ej. major-triad, dominant-7th, major-13th)
Ejemplo: get_chord_notes("C", "major-triad") → C, E, G

get_diatonic_chords - Devuelve las 7 tríadas diatónicas para una tonalidad/modo, una por grado de escala, en orden de grado.
Entrada: root (nota), mode (nombre del modo, opcional: por defecto jónico)
Ejemplo: get_diatonic_chords("C", "ionian") → C tríada mayor, D tríada menor, E tríada menor, F tríada mayor, G tríada mayor, A tríada menor, B tríada disminuida

get_chord_by_degree - Devuelve el acorde diatónico en un grado de escala específico (1-7) para una tonalidad/modo.
Entrada: degree (entero 1-7), root (nota), mode (nombre del modo, opcional: por defecto jónico)
Ejemplo: get_chord_by_degree(5, "C", "ionian") → G tríada mayor

get_available_inversions - Devuelve los números de inversión válidos para un tipo de acorde, según su cantidad de notas.
Entrada: chord_type
Ejemplo: get_available_inversions("major-9th") → 0, 1, 2, 3, 4

get_chord_inversion - Reordena las notas de un acorde para que la nota del acorde de la inversión dada quede en la posición más baja.
Entrada: root (nota), chord_type, inversion (entero, el rango válido depende del tipo de acorde)
Ejemplo: get_chord_inversion("C", "major-triad", 1) → E, G, C

detect_chords - Identifica cada coincidencia de acorde (raíz, tipo) para un conjunto de notas, agrupadas por raíz.
Entrada: notes (arreglo de notas, en cualquier orden)
Ejemplo: detect_chords(["E", "C", "G"]) → { C: [tríada mayor] }

Progresiones

get_progression_in_key - Representa una progresión de catálogo nombrada como acordes en una tonalidad dada, en orden.
Entrada: progression_id (uno 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)
Ejemplo: get_progression_in_key("I-V-vi-IV", "C") → C tríada mayor, G tríada mayor, A tríada menor, F tríada mayor

get_roman_numeral - Devuelve el número romano para un grado de escala en un modo: mayúsculas/minúsculas y sufijo reflejan la calidad de la tríada diatónica.
Entrada: degree (entero 1-7), mode (nombre del modo, opcional: por defecto jónico)
Ejemplo: get_roman_numeral(7, "ionian") → vii°

Transposición

transpose - Transporta un conjunto de notas de una tonalidad a otra según la distancia en semitonos entre las dos raíces.
Entrada: notes (arreglo de notas), from_root (nota), to_root (nota)
Ejemplo: transpose(["C", "E", "G"], "C", "D") → D, F#, A

MIDI y Frecuencia

note_to_midi - Devuelve el número de nota MIDI para una nota en una octava dada, usando notación de tono científico (C4 = C central = MIDI 60).
Entrada: note (nota), octave (entero)
Ejemplo: note_to_midi("C", 4) → 60

midi_to_note - Devuelve la nota y la octava para un número de nota MIDI dado: el inverso de note_to_midi.
Entrada: midi_number (entero 0-127)
Ejemplo: midi_to_note(69) → A4

note_to_frequency - Devuelve la frecuencia en Hz para una nota en una octava dada, temperamento igual, A4 = 440 Hz.
Entrada: note (nota), octave (entero)
Ejemplo: note_to_frequency("A", 4) → 440 Hz

Licencia

MIT