Metadata-Version: 2.4
Name: dhcckb-chinese-lit-ner
Version: 0.1.2
Summary: 中国古典文学命名实体识别 MCP Server - 支持13种实体类型、人工审核、模型适配层、外部资源集成与多格式导出。v0.1.2 修复 SQLite 数据库初始化与路径处理缺陷，新增 get_database_status 诊断工具和临时预览模式。
Author: Digital Humanities Platform
License: MIT
Keywords: chinese-classical-literature,digital-humanities,mcp-server,named-entity-recognition,ner
Classifier: Development Status :: 4 - Beta
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: huggingface
Requires-Dist: torch>=2.0.0; extra == 'huggingface'
Requires-Dist: transformers>=4.40.0; extra == 'huggingface'
Description-Content-Type: text/markdown

# dhcckb-chinese-lit-ner

中国古典文学命名实体识别 MCP Server。

支持 13 种实体类型识别、人工审核工作流、模型适配层（OpenAI/Ollama/HuggingFace）、4 项外部资源集成（Wikidata/汉典/CHisIEC/Chinese-Literature-NER-RE-Dataset）、多格式导出和完整错误降级策略。

## 版本

**v0.1.2** — 修复 SQLite 数据库初始化与路径处理缺陷，新增 `get_database_status` 诊断工具和 `allow_ephemeral_preview` 临时预览模式。

## 安装

```bash
pip install dhcckb-chinese-lit-ner
```

或使用 uvx 直接运行：

```bash
uvx dhcckb-chinese-lit-ner
```

## 环境变量配置

### 数据库路径（必读）

MCP Server 启动时需要访问 SQLite 数据库。数据库路径按以下优先级解析：

1. **`DATABASE_PATH`** — 直接指定数据库文件绝对路径（最高优先级）
2. **`DATA_DIR`** — 指定数据目录，数据库文件为 `${DATA_DIR}/annotations.db`
3. **平台默认路径** — 若以上均未设置，自动使用系统应用数据目录

**强烈建议在生产环境设置 `DATABASE_PATH` 为绝对路径。** 禁止使用类似 `./data/annotations.db` 的相对路径，因为 Cherry Studio 启动 MCP 时不保证工作目录。

#### 平台默认路径

| 平台 | 默认路径 |
|------|---------|
| Windows | `%LOCALAPPDATA%\classical-literature-mcp\annotations.db` |
| macOS | `~/Library/Application Support/classical-literature-mcp/annotations.db` |
| Linux | `~/.local/share/classical-literature-mcp/annotations.db` |

### 模型配置

| 环境变量 | 说明 | 可选值 |
|---------|------|--------|
| `MODEL_PROVIDER` | 模型提供方 | `openai`, `ollama`, `huggingface` |
| `MODEL_ENDPOINT` | 模型服务端点 | 如 `https://api.openai.com/v1` |
| `MODEL_NAME` | 模型名称 | 如 `gpt-4o` |
| `MODEL_API_KEY` | API 密钥 | 仅 OpenAI 模式需要 |

### 其他配置

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `MODEL_TIMEOUT` | 模型调用超时（秒） | `120` |
| `ENABLE_FALLBACK` | 模型不可用时启用词典+规则降级 | `true` |
| `MCP_TRANSPORT` | 传输模式：`stdio` 或 `sse` | `stdio` |
| `MCP_HOST` | SSE 监听地址 | `127.0.0.1` |
| `MCP_PORT` | SSE 监听端口 | `3000` |

## 支持的实体类型

| Key | 中文名称 |
|-----|---------|
| PERSON | 人物 |
| LOCATION | 地点 |
| ORGANIZATION | 组织 |
| OFFICE_TITLE | 官职、爵位、身份 |
| BOOK | 书名、典籍 |
| LITERARY_WORK | 文学作品 |
| TEXT_SECTION | 卷、篇、章、传、本纪等 |
| TIME | 朝代、年号、日期、节令 |
| EVENT | 历史事件 |
| OBJECT | 器物 |
| BIOLOGICAL_ENTITY | 动植物、药材 |
| ABSTRACT_CONCEPT | 制度、思想、品德、情感 |
| MEASURE | 数量和度量单位 |

## Cherry Studio 配置

在 Cherry Studio 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "chinese-lit-ner": {
      "command": "uvx",
      "args": ["dhcckb-chinese-lit-ner"],
      "env": {
        "DATABASE_PATH": "C:\\Users\\你的用户名\\AppData\\Local\\classical-literature-mcp\\annotations.db",
        "MODEL_PROVIDER": "openai",
        "MODEL_ENDPOINT": "https://api.openai.com/v1",
        "MODEL_NAME": "gpt-4o",
        "MODEL_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

> **注意**：Cherry Studio 通过 stdio 与 MCP 通信，stdout 仅用于 JSON-RPC 协议消息。所有日志均输出到 stderr，不会污染协议通道。

## 工具清单（15 个）

| 工具 | 说明 |
|------|------|
| `health_check` | 轻量级健康检查（不依赖任何外部资源） |
| `get_database_status` | 数据库状态诊断（v0.1.2 新增） |
| `recognize_entities` | 文本实体识别（支持持久化模式和临时预览模式） |
| `list_entities` | 列出文档中的实体（分页/筛选） |
| `get_entity` | 获取单个实体完整详情 |
| `add_entity` | 手动添加实体 |
| `update_entity` | 修改实体属性 |
| `delete_entity` | 软删除实体 |
| `link_entity` | 查询外部实体链接（Wikidata/汉典） |
| `accept_external_link` | 确认外部链接候选 |
| `reject_external_link` | 拒绝外部链接候选 |
| `export_entities` | 导出标注结果（json/jsonl/csv/bio） |
| `get_entity_types` | 获取支持的实体类型定义 |
| `get_status` | 获取系统状态 |
| `configure_resources` | 动态启用/禁用外部资源 |
| `get_model_config` | 获取模型配置信息 |

## 使用流程

### 1. 检查数据库状态

启动后先调用 `get_database_status`：

```json
// 正常响应
{
  "status": "ready",
  "database_path": "/home/user/.local/share/classical-literature-mcp/annotations.db",
  "database_exists": true,
  "schema_version": 1,
  "writable": true,
  "tables": ["documents", "segments", "entity_mentions", ...]
}
```

### 2. 实体识别

数据库就绪后调用 `recognize_entities`：

```json
{
  "entity_types": ["PERSON", "LOCATION"],
  "text": "韩非是战国末期法家代表人物，生于韩国。"
}
```

### 3. 外部链接

对已识别的实体调用 `link_entity` 查询 Wikidata：

```json
{
  "entity_id": "M001",
  "resources": ["wikidata"]
}
```

### 4. 审核与确认

人工审核实体后调用 `update_entity` 确认，然后调用 `accept_external_link` 确认外部链接。

### 5. 导出

```json
{
  "document_id": "D001",
  "format": "json",
  "status_filter": ["confirmed"]
}
```

## 故障排查

### 数据库不可用

1. 调用 `get_database_status` 查看具体错误信息
2. 检查 `DATABASE_PATH` 环境变量是否指向可写路径
3. 确认目标目录存在且有写入权限
4. 确认数据库路径不是目录

### 临时预览模式

若数据库暂时不可用但仍需测试实体识别，可设置 `allow_ephemeral_preview: true`：

```json
{
  "entity_types": ["PERSON"],
  "text": "韩非是战国末期法家代表人物。",
  "allow_ephemeral_preview": true
}
```

> 临时预览结果不会保存到数据库，无法审核、导出或建立外部链接。数据库恢复后需重新执行 `recognize_entities`。

### 日志查看

所有日志输出到 stderr。Cherry Studio 用户可在控制台或日志文件中查看 stderr 输出。

## 许可证

MIT