Metadata-Version: 2.4
Name: dhcckb-poetry-tone-mcp
Version: 0.3.0
Summary: MCP server for annotating classical Chinese poetry with four tones and pingze.
Author: 陆泉宇
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: mcp==2.0.0
Requires-Dist: opencc-python-reimplemented<0.2,>=0.1.7
Requires-Dist: openpyxl<4,>=3.1
Requires-Dist: pydantic<3,>=2.11
Provides-Extra: test
Requires-Dist: pytest<9,>=8.3; extra == 'test'
Description-Content-Type: text/markdown

# 诗歌四声平仄标引 MCP

这是一个为古典诗歌逐字标引四声和平仄的 MCP Server，并保留数据来源、候选读音和人工复核状态。

项目支持两种运行模式：

- 本地完整研究版读取陆泉宇现有的私有 Excel 字表，提供较完整的证据字段；
- 公开安装版读取最小化衍生 SQLite 数据库，不包含原始 Excel、无关字段、整理备注、负责人信息或本机路径。

公开衍生数据库仍可被安装者提取和分析，因此它解决的是“不公开原始工作文件”，不是数据内容的密码学保密。

## 已实现的能力

### `lookup_character_tones`

查询一个汉字的四声和平仄，可选传入诗句或词组作为上下文。定音优先级固定为：

1. 《平水韵》
2. 《广韵》
3. 数据库字表
4. 多音字词表“表1定音”
5. 多音字词表“表2多音词组”
6. 《广韵》未收字补充表（校订1.0）

同一级字表只有在四声唯一时才直接定音。若存在多个声调，工具保留全部记录并继续查询下一优先级。

### `annotate_poem_tones`

标引一首诗的逐字四声和平仄。参数：

- `text`：诗歌原文。
- `unresolved_strategy`：`exclude` 或 `prosody_assisted`。
- `expected_chars_per_line`：可选的预期句长，如 5 或 7；只用于检查，不会截断原文。

两种“多”处理方式：

- `exclude`：保留“多”，并按被检验规则的单位排除样本：二四异声按句，联内“对”按联，跨联“粘”按相邻句组。结果中的 `rule_sample_eligibility` 会分别列出可用与排除单位。
- `prosody_assisted`：按照旧代码的随韵、二四异声、粘对和对式逻辑，选择合律度最高的读音。所有此类结果均标记为 `prosody_inferred`，不会伪装成字书定音。

首句入韵允许按内置邻韵组通押；若多个最高合律方案并列且某位置仍不能唯一，保守地保留“多”。

### `get_annotation_method`

返回当前服务版本、算法优先级、策略说明和五个私有数据文件的 SHA-256 指纹。结果不包含本机绝对路径，可用于论文方法记录和结果复算。

## 输出形式

MCP 工具返回结构化 JSON，同时提供便于阅读的三行式文本。例如：

```text
白　日　依　山　盡
入　入　平　平　上
仄　仄　平　平　仄
```

逐字结果还包括：

- 原字与内部检索用规范字形；
- 最终四声和平仄；
- 候选四声、候选平仄和韵部；
- 每一级字表的查询记录；
- 定音来源与证据；
- 是否为格律推断；
- 是否需要人工复核；
- 该诗是否可用于完整四声或平仄统计。
- 二四异声、联内相对、跨联相粘各自应排除的句、联或相邻句组。

## 本机安装

当前电脑已完成安装。需要重建环境时，在 PowerShell 中运行：

```powershell
cd "<项目目录>"
.\setup_local.ps1
```

启动 stdio MCP Server：

```powershell
.\run_server.ps1
```

stdio 服务启动后不会出现普通交互界面；它等待 MCP 客户端通过标准输入输出调用。

## 公开安装包模式

在没有 `config.local.toml` 时，程序自动使用随包分发的精简衍生数据库。发布到 PyPI 后，用户可以运行：

```powershell
uvx dhcckb-poetry-tone-mcp
```

当前只构建了本地待审 wheel，尚未上传璇琮或 PyPI。

从私有字表重新生成衍生数据库：

```powershell
.\.venv\Scripts\python.exe .\scripts\build_public_bundle.py --config .\config.local.toml
```

构建并检查发行包：

```powershell
.\.venv\Scripts\python.exe -m pip wheel . --no-deps --wheel-dir .\dist
.\.venv\Scripts\python.exe .\scripts\verify_distribution.py .\dist\dhcckb_poetry_tone_mcp-0.3.0-py3-none-any.whl
```

## 客户端配置

可直接参考 [mcp-client-config.json](mcp-client-config.json)。其中已经写入当前电脑的 Python、项目和本地配置路径。

## 不通过 MCP 的快速演示

```powershell
$env:POETRY_TONE_MCP_CONFIG=(Resolve-Path '.\config.local.toml').Path
.\.venv\Scripts\python.exe .\scripts\demo.py "白日依山盡，黃河入海流。" --line-length 5
```

测试“排除样本”策略：

```powershell
.\.venv\Scripts\python.exe .\scripts\demo.py "東丆東東東，東東東東東。" --strategy exclude --line-length 5
```

测试“随韵而协”策略：

```powershell
.\.venv\Scripts\python.exe .\scripts\demo.py "東丆東東東，東東東東東。" --strategy prosody_assisted --line-length 5
```

需要完整 JSON 时追加 `--json`。

## 验证

运行全部自动测试：

```powershell
$env:POETRY_TONE_MCP_CONFIG=(Resolve-Path '.\config.local.toml').Path
.\.venv\Scripts\python.exe -m pytest
```

目前测试覆盖：

- 六级证据链优先级；
- 《平水韵》多调时回退《广韵》；
- 数据库字表补充；
- 多音字固定定音与词组定音；
- `exclude` 与 `prosody_assisted`；
- 原文和繁简字形保留；
- 标准 MCP stdio 初始化、工具发现、工具调用和资源读取。
- 本地完整字表与公开衍生数据库的核心结果一致性；
- wheel 不包含原始工作簿、本机绝对路径或本地配置文件。

既有 Excel 回归对照：

```powershell
.\.venv\Scripts\python.exe .\scripts\compare_existing.py --limit 200
```

报告位于 `verification/旧版标引对照报告.json`。它只用于观察新旧流程差异，不代替人工金标准准确率评测。

本地完整研究版与公开衍生包的对照：

```powershell
.\.venv\Scripts\python.exe .\scripts\compare_bundle.py --limit 200
```

报告位于 `verification/完整字表与公开衍生包对照报告.json`。

## 当前未纳入

- 格律合规检测与病犯统计；
- Excel/CSV 批量导出；
- 词律、曲律与赋律；
- 远程 HTTP 部署。

## 数据范围与暂行许可

公开发行包只包含运行标引所需的最小化衍生 SQLite 数据库，不包含原始 Excel
工作簿、本地路径、释义、反切、声母、等第、整理备注或负责人信息。

本版本采用“保留所有权利”的暂行研究与演示条款。允许为个人学术研究、教
学、评估和演示目的下载、安装并运行未经修改的版本；不得未经书面许可重新
分发、商业使用、修改，或抽取并独立利用所附衍生数据库。详见 `LICENSE`。
