Metadata-Version: 2.4
Name: dhcckb-mingqing-narrative
Version: 0.1.1
Summary: 明清小说与戏曲叙事检索、事件分析及标注辅助 MCP Server
Author: Digital Humanities Platform
License: MIT
License-File: LICENSE
Keywords: annotation,chinese-literature,digital-humanities,mcp,ming-qing,narrative-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.11
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: mcp<2.0.0,>=1.12.0
Description-Content-Type: text/markdown

# 明清小说与戏曲叙事研究 MCP Server

这是一个可运行的 **本地原型**：它提供标注规范查询、样例语料检索、规则型
事件抽取、母题候选、事件对齐和标注草稿工具。它不将“相似”表述为影响、改写
或来源关系，也不会改写人工精标数据。

## 当前边界

- 随包仅有 10 部作品的元数据和 6 段演示文本，不是完整明清小说语料库。
- 事件抽取、母题分类、重排序均为规则型基线，不是 HanLP、向量检索或 LLM Judge。
- CBDB、CHGIS 和《红楼梦》标注库默认使用内置演示数据；未默认访问任何外部网站。
- 《红楼梦》远程 API 需要先取得授权、确认接口，再通过环境变量显式配置。

## 安装

需要 Python 3.11 或更高版本。解压后在项目目录执行：

```bash
python -m venv .venv
.venv/Scripts/python -m pip install .
```

安装会使用受限版本的 `mcp>=1.12,<2.0`。不要直接使用 `uvx
dhcckb-mingqing-narrative`，除非你已将本包发布到受控的软件源。

## 客户端配置

以 stdio 方式接入 MCP 客户端：

```json
{
  "mcpServers": {
    "mingqing-narrative": {
      "command": "C:/path/to/project/.venv/Scripts/dhcckb-mingqing-narrative.exe",
      "args": []
    }
  }
}
```

默认 transport 是 stdio。开发期 HTTP 模式只监听本机：

```bash
.venv/Scripts/dhcckb-mingqing-narrative --http --host 127.0.0.1 --port 8000
```

未配置 HTTPS 和认证时，程序会拒绝绑定到公网地址。

## 工具

| 工具 | 当前能力 |
| --- | --- |
| `get_annotation_schema` | 读取本地标注规范 |
| `search_corpus` / `get_source_passage` | 查询注册的本地样例语料；支持题名别名如 `hongloumeng` |
| `extract_narrative_units` | 规则型实体、事件和 realis 候选 |
| `classify_motifs` | 基于母题词表的候选与关键词证据 |
| `search_annotation_examples` | 内置精标参考样例的关键词查询 |
| `search_similar_passages` | 字符 TF-IDF、n-gram 和规则事件特征召回 |
| `align_event_sequences` | 阈值或 Needleman-Wunsch 规则对齐 |
| `verify_person_and_place` | 内置演示人物、地名表查询 |
| `rerank_narrative_matches` | 规则型重排，不调用 LLM Judge |
| `create_annotation_draft` | 不落库的待审核标注草稿 |

## 外部《红楼梦》标注库

参照 `.env.example` 设置本机环境变量后，才能显式启用远程适配器。请先取得
数据库维护方许可，并确认搜索端点、参数和返回 JSON 格式；本项目不会抓取网页。

```text
HLM_API_BASE_URL=https://example.org
HLM_ANNOTATION_SEARCH_PATH=/api/annotations/search
HLM_API_TOKEN=replace-with-authorized-token
```

远程接口需要返回 `{ "results": [...] }` 或 `{ "data": [...] }`。请求失败时服务会
回退到内置样例，并在 provenance 中标记为 `embedded_demo`。

## 验证

安装依赖后执行：

```bash
.venv/Scripts/python scripts/smoke_test.py
```

该测试会通过 stdio 完成初始化、列工具并调用 schema、原文、事件和母题工具。

## 下一步

生产化前应接入有授权的正式语料、稳定段落 ID、版本溯源、真实检索索引、古汉语
事件模型和人工金标准测试集；当前输出只能作为人工审核与研究线索发现的起点。
