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 临时预览模式。

安装

pip install dhcckb-chinese-lit-ner

或使用 uvx 直接运行：

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 配置中添加：

{
  "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：

// 正常响应
{
  "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：

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

3. 外部链接

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

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

4. 审核与确认

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

5. 导出

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

故障排查

数据库不可用

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

临时预览模式

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

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

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

日志查看

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

许可证

MIT