dhcckb-poetry-tone-mcp 0.3.0

MCP server for annotating classical Chinese poetry with four tones and pingze.

诗歌四声平仄标引 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，同时提供便于阅读的三行式文本。例如：

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

逐字结果还包括：

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

本机安装

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

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

启动 stdio MCP Server：

.\run_server.ps1

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

公开安装包模式

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

uvx dhcckb-poetry-tone-mcp

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

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

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

构建并检查发行包：

.\.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。其中已经写入当前电脑的 Python、项目和本地配置路径。

不通过 MCP 的快速演示

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

测试“排除样本”策略：

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

测试“随韵而协”策略：

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

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

验证

运行全部自动测试：

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

目前测试覆盖：

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

既有 Excel 回归对照：

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

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

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

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

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

当前未纳入

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

数据范围与暂行许可

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

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