PlayByKey Music Theory

@playbykey/theory-mcp

一个 MCP 服务，可将 @playbykey/theory 作为可由 AI 调用的乐理工具提供。

MCP 让 AI 助手可以直接将乐理引擎作为工具调用，而不必根据训练数据推理音阶、调式和调性关系。乐理关系通过固定的音程和音阶级数关系进行确定性解析。

如需相同的设置说明和完整的工具参考，请参阅 @playbykey/mcp 页面。

安装

无需全局安装——npx 会按需获取并运行此软件包。需要安装 Node.js（用于运行 npx）。

Claude Desktop

通过 Claude Desktop 的设置编辑 MCP 配置文件（claude_desktop_config.json）。

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

保存后重启 Claude Desktop，然后查看其设置，确认 theory 显示为已连接。

Cursor

配置文件位置：

• 全局（所有项目）： ~/.cursor/mcp.json
• 仅限项目： 项目根目录中的 .cursor/mcp.json

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

保存后重启 Cursor，然后查看其 MCP 设置，确认 theory 显示为已连接。

Claude Code

项目范围（推荐）——在仓库根目录提交一个 .mcp.json，这样每位贡献者在 git clone 后都可以使用此服务：

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

本地范围——仅为你自己在此项目中注册此服务，不提交任何内容：

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

全局范围——为你自己在此机器的所有项目中注册此服务：

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

运行 claude mcp list，确认 theory 显示为已连接。

工具

调式

get_mode_notes - 返回一个自然调式的 7 个音符。
输入：root（音符）、mode（调式名称）
示例：get_mode_notes("D", "dorian") → D、E、F、G、A、B、C

get_parent_scale_modes - 返回母调的全部 7 种调式旋转。
输入：root（音符）、mode（调式名称）
示例：get_parent_scale_modes("D", "dorian") → C ionian、D dorian、E phrygian、F lydian、G mixolydian、A aeolian、B locrian

get_modal_root - 返回某个大调中的指定调式的根音。
输入：parent_key（音符）、mode（调式名称）
示例：get_modal_root("C", "dorian") → D

get_relative_minor - 返回一个大调的关系小调根音。
输入：major_key（音符）
示例：get_relative_minor("C") → A

get_relative_major - 返回一个小调的关系大调根音。
输入：minor_key（音符）
示例：get_relative_major("A") → C

get_mode_info - 返回调式的显示元数据：名称、音阶级数和特征描述。
输入：mode（调式名称）
示例：get_mode_info("dorian") → Dorian、级数 2、“带升高第 6 级音的小调”

五度圈

get_circle_of_fifths - 按上行五度的顺序，返回从 C 开始的全部 12 个半音音符。
输入：无
示例 → C、G、D、A、E、B、F#、C#、G#、D#、A#、F

调号

get_key_signature - 返回指定调的升号或降号数量，并将其视为大调主音（此工具不提供小调调号）。结果会采用惯用的等音拼写——get_key_signature("A#") 返回 Bb 大调的 2 个降号，而非 A# 自身的调号。如需获取完全按指定拼写的根音所对应的数量，请将 get_root_letter 与 get_spelled_accidental_count 配合使用。
输入：key（音符）
示例：get_key_signature("D") → 2 个升号

音阶

get_scale_notes - 按类型返回音阶中的音符。
输入：root（音符）、scale_type（可选值：major、blues、pentatonic-major、pentatonic-minor、harmonic-minor、melodic-minor、chromatic）
示例：get_scale_notes("A", "blues") → A、C、D、D#、E、G

build_note_map - 返回结构化的逐音符数据：音符名称、音阶级数（从 1 开始）以及与根音的半音偏移。
输入：root（音符）、scale_type
示例：build_note_map("C", "major") → [{note:"C", scaleDegree:1, semitoneOffset:0}, {note:"D", scaleDegree:2, semitoneOffset:2}, ...]

get_scale_degree - 返回某个音符在音阶中的级数（从 1 开始）；如果该音符不属于此音阶，则返回 null。
输入：root（音符）、scale_type、note（音符）
示例：get_scale_degree("C", "major", "E") → 3

is_note_in_scale - 返回某个音符是否属于指定音阶。
输入：root（音符）、scale_type、note（音符）
示例：is_note_in_scale("C", "major", "F#") → false

get_melodic_minor_notes - 返回上行旋律小调音阶的七个音符。
输入：root（音符）
示例：get_melodic_minor_notes("C") → C、D、D#、F、G、A、B

get_melodic_minor_mode_notes - 返回旋律小调调式的七个音符。
输入：root（音符）、mode（可选值：melodic-minor、dorian-b2、lydian-augmented、lydian-dominant、mixolydian-b6、locrian-nat2、altered）
示例：get_melodic_minor_mode_notes("C", "altered") → C、C#、D#、E、F#、G#、A#

get_harmonic_minor_mode_notes - 返回和声小调调式的七个音符。
输入：root（音符）、mode（可选值：harmonic-minor、phrygian-dominant）
示例：get_harmonic_minor_mode_notes("C", "phrygian-dominant") → C、C#、E、F、G、G#、A#

get_bebop_scale_notes - 返回一种比波普音阶变体的八个音符，即一个自然音阶加上一个半音经过音。
输入：root（音符）、type（可选值：bebop-dominant、bebop-major、bebop-dorian）
示例：get_bebop_scale_notes("C", "bebop-dominant") → C、D、E、F、G、A、A#、B

音程

resolve_interval - 在给定根音的上下文中，返回指定音程的起始音和目标音。
输入：root（音符）、interval（音程 ID，例如 major_3rd、perfect_5th）
示例：resolve_interval("C", "major_3rd") → C 到 E（4 个半音）

get_semitone_distance - 返回两个音符之间上行的半音距离（0–11）。
输入：from（音符）、to（音符）
示例：get_semitone_distance("C", "E") → 4

音符拼写

get_sharps - 将音符列表重新拼写为标准升号拼写。大多数工具可直接接受降号拼写的输入，但 get_flats 和 get_enharmonic_labels 要求输入为升号拼写——调用这两个工具前，请先用此工具规范化降号拼写的音符。
输入：notes（升号或降号）
示例：get_sharps(["Db", "C#", "D"]) → C#, C#, D

get_flats - 将升号拼写的音符列表重新拼写为降号。自然音符不受影响。
输入：notes（必须为升号拼写）
示例：get_flats(["C#", "D"]) → Db, D

get_enharmonic_labels - 返回升号拼写的音符列表对应的升号/降号组合显示标签。自然音符不受影响。
输入：notes（必须为升号拼写）
示例：get_enharmonic_labels(["C#", "D"]) → Db/C#, D

get_root_letter - 根据升号或降号偏好，确定根音应拼写为何种字母（A-G）。供 spell_diatonic_scale 使用。
输入：root（音符），preference（sharp 或 flat）
示例：get_root_letter("F#", "flat") → G

spell_diatonic_scale - 重新拼写 7 音符自然音阶，确保 A-G 这 7 个字母各使用一次，涵盖普通音符无法单独表示的拼写（B#、E#、Cb、Fb、重升号、重降号）。
输入：notes（按音阶顺序排列的 7 个音符），root_letter（来自 get_root_letter）
示例：spell_diatonic_scale(["F#","G#","A#","B","C#","D#","F"], "F") → F#, G#, A#, B, C#, D#, E#

get_spelled_accidental_count - 返回正确拼写的 7 音符自然音阶中升号或降号的数量，以及其中重变音记号的数量。大调和自然小调音阶均可使用——一个调及其关系小调的数量相同。
输入：notes（按音阶顺序排列的 7 个音符），root_letter（来自 get_root_letter）
示例：get_spelled_accidental_count(["A#","C","D","D#","F","G","A"], "A") → 7 sharps（3 double sharps）

和弦

get_chord_notes - 根据根音和和弦类型返回和弦音符。
输入：root（音符），chord_type（22 种和弦类型之一，例如 major-triad、dominant-7th、major-13th）
示例：get_chord_notes("C", "major-triad") → C, E, G

get_diatonic_chords - 返回某个调式或调的 7 个自然和弦三和弦，每个音阶级数对应一个，按级数顺序排列。
输入：root（音符），mode（调式名称，可选——默认为 ionian）
示例：get_diatonic_chords("C", "ionian") → C major-triad, D minor-triad, E minor-triad, F major-triad, G major-triad, A minor-triad, B diminished-triad

get_chord_by_degree - 返回某个调式或调在指定音阶级数（1-7）上的自然和弦。
输入：degree（整数 1-7），root（音符），mode（调式名称，可选——默认为 ionian）
示例：get_chord_by_degree(5, "C", "ionian") → G major-triad

get_available_inversions - 根据和弦音符数量，返回某种和弦类型的有效转位编号。
输入：chord_type
示例：get_available_inversions("major-9th") → 0, 1, 2, 3, 4

get_chord_inversion - 重新排列和弦音符，使指定转位的和弦音成为最低音。
输入：root（音符），chord_type，inversion（整数，有效范围取决于和弦类型）
示例：get_chord_inversion("C", "major-triad", 1) → E, G, C

detect_chords - 识别一组音符中所有匹配的和弦（根音、类型），并按根音归类。
输入：notes（音符数组，顺序不限）
示例：detect_chords(["E", "C", "G"]) → { C: [major-triad] }

和弦进行

get_progression_in_key - 按顺序将指定的目录和弦进行呈现为指定调中的和弦。
输入：progression_id（以下之一：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（音符）
示例：get_progression_in_key("I-V-vi-IV", "C") → C 大三和弦、G 大三和弦、A 小三和弦、F 大三和弦

get_roman_numeral - 返回某调式中某个音级对应的罗马数字——大小写和后缀反映自然三和弦的性质。
输入：degree（整数 1-7）、mode（调式名称，可选；默认值为 ionian）
示例：get_roman_numeral(7, "ionian") → vii°

移调

transpose - 根据两个根音之间的半音距离，将一组音符从一个调移至另一个调。
输入：notes（音符数组）、from_root（音符）、to_root（音符）
示例：transpose(["C", "E", "G"], "C", "D") → D、F#、A

MIDI 与频率

note_to_midi - 使用科学音高记号返回指定八度中某个音符对应的 MIDI 音符编号（C4 = 中央 C = MIDI 60）。
输入：note（音符）、octave（整数）
示例：note_to_midi("C", 4) → 60

midi_to_note - 返回指定 MIDI 音符编号对应的音符和八度，是 note_to_midi 的逆操作。
输入：midi_number（整数 0-127）
示例：midi_to_note(69) → A4

note_to_frequency - 返回指定八度中某个音符的频率（Hz），采用十二平均律，A4 = 440 Hz。
输入：note（音符）、octave（整数）
示例：note_to_frequency("A", 4) → 440 Hz

许可证

MIT