Metadata-Version: 2.4
Name: dhcckb-ancient-music-mcp
Version: 0.1.0
Summary: 古代音乐文献研究 MCP Server — 检索先秦至明清音乐典籍、释义律吕宫调术语、转换工尺谱与减字谱、分析律制体系
Author: Digital Humanities Platform
License: MIT
Keywords: ancient-music,chinese-musicology,gongche,jianzipu,mcp,tuning-system
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: lilypond
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 古代音乐文献研究 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 安装

```bash
pip install dhcckb-ancient-music-mcp
```

### 从源码安装（开发模式）

```bash
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`

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

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

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

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

### 使用自定义语料数据目录

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

```json
{
  "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：

```bash
# 使用 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` 进行开发调试：

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

## 开发

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

# 运行测试
pytest
```

## 许可证

MIT License

## 相关资源

- [MCP (Model Context Protocol) 官方文档](https://modelcontextprotocol.io)
- [Claude Desktop MCP 接入指南](https://docs.anthropic.com/en/docs/claude-desktop)
