Metadata-Version: 2.4
Name: dhcckb-ancient-music-mcp
Version: 0.1.1
Summary: 古代音乐文献研究 MCP Server — 检索先秦至明清音乐典籍、释义律吕宫调术语、转换工尺谱与减字谱、分析律制体系
Author: Digital Humanities Platform
License: MIT
License-File: LICENSE
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: mcp==2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
Requires-Dist: pytest==9.1.1; 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_config.json` 中添加：

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

## 工具说明

### search_music_literature

在古代音乐文献语料库中按关键词、朝代、作者、体裁进行全文检索。支持中/英/日多语言检索，自动扩展同义词。

### lookup_musicology_term

查阅音乐学专业术语的释义、最早出处、同义/关联术语及相关原始文献引文。覆盖音律、乐谱、乐制、乐器四类核心术语。

### convert_gongche_to_staff

将工尺谱字符串转换为现代记谱法。同时输出科学音高记号（如 C4/D4）、简谱（数字谱）、ABC Notation 文本（可用于 LilyPond/abc2svg 渲染五线谱）及 MIDI 音高编号。

### convert_jianzipu_to_modern

解析古琴减字谱字符，提取右手弹奏指法、左手按弦指法、弦序、徽位及特殊技法。

### analyze_tuning_system

分析指定律制体系的数学比例与音高关系。支持三分损益法、十二平均律、京房六十律、钱乐之三百六十律、何承天新律五种律制。

### get_instrument_info

查询中国传统乐器的基本信息，包括八音类别、起源朝代、形制描述、代表性曲目与演奏家、关联文献出处。

## 许可

MIT License
