Metadata-Version: 2.4
Name: dhcckb-deep-parse-music-literature
Version: 1.0.1
Summary: 唐宋音乐文献深度解析 MCP Server——整合智能实体标引、人事传播网络溯源、歌辞异文比对与杂言化分析三层深度解析能力
License: MIT
Requires-Python: >=3.10
Requires-Dist: mcp<2.0.0,>=1.13.1
Provides-Extra: paddlenlp
Requires-Dist: paddlenlp>=3.0; extra == 'paddlenlp'
Provides-Extra: sse
Requires-Dist: starlette>=0.38; extra == 'sse'
Requires-Dist: uvicorn>=0.30; extra == 'sse'
Description-Content-Type: text/markdown

# 唐宋音乐文献深度解析 MCP Server

`dhcckb-deep-parse-music-literature` 是一个面向数字人文研究的 MCP Server，整合三大核心能力：

1. **智能实体标引** — Person/Tune/Structure/Instrument/Location 五类实体识别（词典 MMSeg 正则匹配为先、可选 PaddleNLP 后补），输出 entities（含 char_offset、confidence）和 key_sentences
2. **人事传播网络溯源** — 内置 20+ 位核心乐人/进献使臣基础信息（含身份等级、行为操作、朝代时间轴），女性乐人条件触发"被遮蔽的乐人群体"标签及社会学背景说明
3. **歌辞异文比对与杂言化分析** — 字数句式统计、杂言化指数 Mixed-verse Index 计算、版本异文高亮含字符偏移量、入破/急遍结构推断，所有结论附带精确到卷数与原始引文的 citations

## 依赖版本约束

本 Server 要求 **MCP SDK >= 1.13.1 且 < 2.0.0**，以确保与 Cherry Studio 等主流 MCP 客户端兼容。此约束已在 `pyproject.toml` 中声明：

```
"mcp>=1.13.1,<2.0.0"
```

## 安装与启动

### 方式一：uvx 一行启动（推荐）

```bash
uvx dhcckb-deep-parse-music-literature
```

uvx 会自动从 PyPI 拉取最新版本并解析依赖约束。

### 方式二：uvx 显式声明 MCP 版本（Cherry Studio 推荐）

在 Cherry Studio 的 MCP 配置中使用如下 JSON：

```json
{
  "mcpServers": {
    "deep-parse-music-literature": {
      "command": "uvx",
      "args": ["dhcckb-deep-parse-music-literature"]
    }
  }
}
```

如果遇到 SDK 版本不兼容问题，可改用 `uv run --with` 显式声明：

```json
{
  "mcpServers": {
    "deep-parse-music-literature": {
      "command": "uv",
      "args": ["run", "--with", "mcp>=1.13.1,<2.0.0", "--with", "dhcckb-deep-parse-music-literature", "dhcckb-deep-parse-music-literature"]
    }
  }
}
```

### 方式三：pip 安装

```bash
pip install 'mcp>=1.13.1,<2.0.0' dhcckb-deep-parse-music-literature
dhcckb-deep-parse-music-literature
```

### 方式四：uv tool install 全局安装

```bash
uv tool install --with 'mcp>=1.13.1,<2.0.0' dhcckb-deep-parse-music-literature
dhcckb-deep-parse-music-literature
```

### SSE 模式启动

```bash
# 安装 SSE 可选依赖
uvx --with 'dhcckb-deep-parse-music-literature[sse]' dhcckb-deep-parse-music-literature --transport sse --port 8000

# 或 pip 方式
pip install 'dhcckb-deep-parse-music-literature[sse]'
dhcckb-deep-parse-music-literature --transport sse --port 8000
```

## 工具说明

### `deep_parse_music_literature`

对输入的唐宋音乐文献全文进行三层深度解析。必填参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `input_text` | string | ✅ | 用户输入的原始文献全文，支持简体/繁体/混合 |
| `target_work` | string | ❌ | 指定研究的核心曲目或诗题，如"凉州"、"梁州令" |
| `compare_versions` | string[] | ❌ | 需要比对的版本库列表，默认 ["乐府诗集","敦煌写本","全唐诗","全宋词"] |
| `external_verse_paths` | string[] | ❌ | 用户本地版本库文件路径列表（UTF-8/GBK/GB2312 自动检测编码） |
| `research_focus` | enum | ❌ | `structural_shift` / `person_network` / `syntax_change`，支持层级剪枝 |
| `ner_mode` | enum | ❌ | `dict_mmseg`（默认，快速）或 `paddle_nlp`（需要 `[paddlenlp]` 额外依赖） |

## 支持的 Python 版本

- Python 3.10+
- Python 3.11
- Python 3.12
- Python 3.13

## 许可证

MIT
