dhcckb-ancient-music-mcp 0.1.0

古代音乐文献研究 MCP Server — 检索先秦至明清音乐典籍、释义律吕宫调术语、转换工尺谱与减字谱、分析律制体系

古代音乐文献研究 MCP Server

dhcckb-ancient-music-mcp 是一个面向古代音乐文献研究的 MCP (Model Context Protocol) Server，让 AI Agent 能通过标准化工具检索先秦至明清的音乐典籍、释义专业术语（律吕/宫调/谱式）、转换传统乐谱（工尺谱/减字谱）、分析律制体系（三分损益/十二平均律/京房六十律）、以及查询中国传统乐器信息。

功能概览

工具	功能
search_music_literature	古代音乐文献全文检索（支持中/英/日多语言）
lookup_musicology_term	音乐学专业术语释义与文献引文查询
convert_gongche_to_staff	工尺谱转科学音高/简谱/ABC Notation
convert_jianzipu_to_modern	减字谱字符解析（指法/弦位/徽位提取）
analyze_tuning_system	律制体系数学分析（三分损益/十二平均律/京房六十律等）
get_instrument_info	中国传统乐器信息查询（八音分类/形制/曲目）

安装

从 PyPI 安装

pip install dhcckb-ancient-music-mcp

从源码安装（开发模式）

git clone <repo-url>
cd dhcckb-ancient-music-mcp
pip install -e .

要求 Python 3.10 或更高版本。

Claude Desktop 接入

在 Claude Desktop 的配置文件中添加：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ancient-music": {
      "command": "uvx",
      "args": ["dhcckb-ancient-music-mcp"]
    }
  }
}

或者使用 pip 安装后的方式：

{
  "mcpServers": {
    "ancient-music": {
      "command": "python",
      "args": ["-m", "dhcckb_ancient_music_mcp"]
    }
  }
}

配置完成后重启 Claude Desktop，即可在对话中使用古代音乐文献研究工具。

使用自定义语料数据目录

如果需要扩展或替换内置语料，可在启动时指定自定义数据目录：

{
  "mcpServers": {
    "ancient-music": {
      "command": "python",
      "args": ["-m", "dhcckb_ancient_music_mcp", "--data-dir", "/path/to/your/data"]
    }
  }
}

自定义数据目录需包含与 data/ 相同结构的 JSON 文件（literature.json、terms.json、instruments.json、cross_language.json、jianzipu_data.json）。

工具详解

1. search_music_literature

在古代音乐文献语料库中按关键词、朝代、作者、体裁进行全文检索。

参数：

• query (必填): 检索关键词（支持中文、英文、日文，自动扩展跨语言同义词）
• period (可选): 朝代过滤 — pre_qin / han / weijin / tang / song / yuan / ming / qing / all
• genre (可选): 体裁过滤 — yuelun / notated_score / qin_treatise / instrument_book / poetry / all
• author (可选): 按作者/编撰者过滤
• max_results (可选): 最大返回条数，默认 10

示例：

search_music_literature(query="琴", period="pre_qin", max_results=5)
search_music_literature(query="temperament", genre="yuelun")  # 自动映射到中文"律制"
search_music_literature(query="gongche", max_results=10)

2. lookup_musicology_term

查阅音乐学专业术语的释义、最早出处、同义/关联术语及相关原始文献引文。

参数：

• term (必填): 待查询的音乐学术语
• category (可选): 术语类别 — pitch_tuning / notation / mode_tonality / instrument / all

示例：

lookup_musicology_term(term="黄钟")
lookup_musicology_term(term="Huangzhong")  # 英文自动匹配
lookup_musicology_term(term="sanfen sunyi")
lookup_musicology_term(term="jianzipu", category="notation")

3. convert_gongche_to_staff

将工尺谱字符串转换为现代记谱法。

参数：

• gongche_string (必填): 工尺谱字符串，如 上尺工凡六五乙
• key_mode (可选): 工尺七调之一，默认 xiaogong_diao（小工调 D）
  • xiaogong_diao 小工调 (D) | zhenggong_diao 正宫调 (G) | yizi_diao 乙字调 (A) | shangzi_diao 上字调 (Bb) | chizi_diao 尺字调 (C) | fanzi_diao 凡字调 (E) | liuzi_diao 六字调 (F)
• output_format (可选): scientific_pitch / abc_notation / jianpu / all，默认 all

输出包含：

• scientific_pitch: 科学音高记号 (如 C4, D4, E4…)
• jianpu: 简谱（数字谱）记法
• abc_notation: ABC Notation 文本（可用于 LilyPond/abc2svg 渲染五线谱）
• midi_sequence: MIDI 音高编号列表
• warnings: 无法识别的字符提示

示例：

convert_gongche_to_staff(gongche_string="上尺工凡六五乙", key_mode="xiaogong_diao")
# → D4 E4 F#4 G4 A4 B4 C#5

convert_gongche_to_staff(gongche_string="合四一上尺工凡", key_mode="zhenggong_diao", output_format="jianpu")
# → 简谱数字序列

4. convert_jianzipu_to_modern

解析古琴减字谱字符，提取指法、弦位、徽位等信息。

参数：

• jianzipu_character (必填): 减字谱字符（单个复合汉字）

输出包含：

• right_hand: 右手弹奏指法（擘/托/抹/挑/勾/剔/打/摘等）
• left_hand: 左手按弦指法（大指/食指/中指/名指）
• string: 弦序（1-7）
• hui: 徽位（1-13 或 徽外）
• additional_techniques: 附加技法（吟/猱/绰/注/撞等）
• is_open_string: 是否散音（空弦）
• explanation: 中文解释文本

5. analyze_tuning_system

分析指定律制体系的数学比例与音高关系。

参数：

• method (必填): 律制方法
  • sanfen_sunyi — 三分损益法
  • twelve_tone_equal — 朱载堉新法密率/十二平均律
  • jingfang_sixty — 京房六十律
  • qianlezhi_360 — 钱乐之三百六十律
  • hechengtian_new_law — 何承天新律
• huangzhong_frequency (可选): 黄钟参考频率，默认 261.63 Hz (C4)

输出包含：

• 每律的振动体长度比 (string_length_ratio)
• 频率比 (frequency_ratio, 以黄钟为 1.0)
• 计算频率 (frequency_hz)
• 音分值 (cents_from_huangzhong)
• 对应的现代音名近似值
• 文字说明与历史背景

6. get_instrument_info

查询中国传统乐器的基本信息。

参数：

• instrument_name (必填): 乐器名称（支持中/英/日）

输出包含：

• 所属八音类别（金/石/土/革/丝/木/匏/竹）
• 起源朝代与历史沿革
• 形制描述（尺寸/弦数/品数/材质）
• 代表性曲目与演奏家
• 关联文献出处
• 专用记谱法

示例：

get_instrument_info(instrument_name="琴")
get_instrument_info(instrument_name="pipa")
get_instrument_info(instrument_name="bianzhong")

数据语料

内置语料涵盖：

• 音乐文献 25+ 条核心文本条目，覆盖先秦至清代，包含《乐记》《乐书》《律历志》《琴操》《碧鸡漫志》《律吕正义》《溪山琴况》《神奇秘谱》《燕乐考原》《乐律全书》等
• 音乐学术语 18+ 条，覆盖音律（十二律/三分损益/新法密率）、乐谱（工尺谱/减字谱/俗字谱/律吕谱）、乐制（旋宫转调/燕乐二十八调/板眼）、乐器（八音/琴/琵琶）
• 乐器数据 12+ 种传统乐器（琴、瑟、琵琶、笛、箫、钟、磬、笙、埙、鼓、箜篌、排箫、胡笳）
• 跨语言映射 中/英/日三语检索支持
• 减字谱数据 右手/左手基本指法与常见减字谱例

语料数据以 JSON 文件存放在 src/dhcckb_ancient_music_mcp/data/ 目录下，可通过 --data-dir 参数扩展或替换。

命令行使用

安装后可直接通过命令行启动 MCP Server：

# 使用 uvx (推荐)
uvx dhcckb-ancient-music-mcp

# 使用 python -m
python -m dhcckb_ancient_music_mcp

# 指定自定义数据目录
python -m dhcckb_ancient_music_mcp --data-dir /path/to/custom/data

也可以使用 mcp dev 进行开发调试：

pip install mcp
mcp dev src/dhcckb_ancient_music_mcp/server.py

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

许可证

MIT License

相关资源

• MCP (Model Context Protocol) 官方文档
• Claude Desktop MCP 接入指南