TypeScript music theory engine | Theory EngineSkip to content

TypeScript music theory engine

@playbykey/theory is a zero-dependency TypeScript music theory engine for computing scale notes, resolving diatonic modes, navigating key relationships, and building note display maps.

The music theory engine powering PlayByKey, a free interactive music theory learning tool.

Using this with an AI assistant?<br>MCP tools<br>Context prompt

Add @playbykey/theory-mcp to your Claude Desktop config and call the theory engine directly as tools - no copy-paste needed:

"mcpServers": {

"theory": {

"command": "npx",

"args": ["-y", "@playbykey/theory-mcp"]

Paste this into any agent or LLM to give it context about this package:<br>I'm using @playbykey/theory for music theory computation. Docs: https://theory-engine.docs.playbykey.com. Key functions: getModeNotes, getParentScaleModes, getModalRoot (modes); getRelativeMinorKey, getRelativeMajorKey, getKeySignatureCount, getCircleOfFifthsOrder (key relationships); getSemitoneDistance (note utilities); getScaleNotes, getScaleDegrees, getScaleDegree, isNoteInScale, buildNoteMap (scales); resolveIntervalEndpoints, getIntervalSemitones, INTERVAL_DEFINITIONS (intervals - half_step/whole_step are scale motion, minor_2nd/major_2nd are from root); parseNote, parseModeName, isNote, isModeName (type guards, case-insensitive); getBluesNotes, getHarmonicMinorNotes, getPentatonicNotes (derived scales). Zero dependencies, TypeScript-first, sharps-only notation (C# not Db).

Installation<br>Section titled “Installation”

npm<br>pnpm<br>yarn<br>bun<br>agent

Terminal windownpm install @playbykey/theory

Terminal windowpnpm add @playbykey/theory

Terminal windowyarn add @playbykey/theory

Terminal windowbun add @playbykey/theory

Install @playbykey/theory from npm and add it to my project. Docs: https://theory-engine.docs.playbykey.com. Functions: getModeNotes, getParentScaleModes, getModalRoot (modes); getRelativeMinorKey, getRelativeMajorKey, getKeySignatureCount, getCircleOfFifthsOrder (key relationships); getSemitoneDistance (note utilities); getScaleNotes, getScaleDegrees, getScaleDegree, isNoteInScale, buildNoteMap (scales); resolveIntervalEndpoints, getIntervalSemitones, INTERVAL_DEFINITIONS (intervals - half_step/whole_step are scale motion, minor_2nd/major_2nd are from root); parseNote, parseModeName, isNote, isModeName (type guards, case-insensitive); getBluesNotes, getHarmonicMinorNotes, getPentatonicNotes (derived scales). Zero dependencies, TypeScript-first, sharps-only notation (C# not Db). Or use @playbykey/theory-mcp for MCP tool calling.

Quickstart<br>Section titled “Quickstart”

import { getModeNotes, getParentScaleModes } from '@playbykey/theory';

// Get all notes in D Dorian

const notes = getModeNotes('D', 'dorian');

console.log(notes); // ['D', 'E', 'F', 'G', 'A', 'B', 'C']

// Find the parent major key

const parentModes = getParentScaleModes('D', 'dorian');

const parent = parentModes.find((m) => m.mode === 'ionian');

console.log(parent?.root); // 'C'

m.mode === 'ionian');console.log(parent?.root); // 'C'">

What’s in the package<br>Section titled “What’s in the package”

Category<br>What it covers<br>Page

Keys & Modes<br>Scales, modes, key relationships, note utilities<br>Keys & Modes

Intervals<br>Interval catalog, semitone lookup, endpoint resolution<br>Intervals

Scales<br>Blues, harmonic minor, pentatonic, derived scales<br>Scales

Constants<br>All exported constants and their values<br>Constants

TypeScript<br>Section titled “TypeScript”

The package is written in TypeScript with strict mode. All exported functions are fully typed. No any. Import types directly:

import type { Note, ModeName } from '@playbykey/theory';

Note notation<br>Section titled “Note notation”

The package uses sharps-only notation (C#, not Db). Reference ENHARMONIC_LABELS for display-friendly flat/sharp labels.