典故溯源与历代化用检索工具 (Allusion Tracer)

dhcckb-allusion-tracer 是一个 MCP (Model Context Protocol) Server，提供典故溯源、历代征引检索、语义变迁分析和群体时代分布统计功能。数据来源于 6 个中文古籍网站。

功能概览

数据源

默认使用 ctext + souyun + shidian（免登录），其余数据源需配置凭据后启用。

安装

# 通过 pip 安装
pip install dhcckb-allusion-tracer

# 或使用 uv
uv tool install dhcckb-allusion-tracer

# 开发安装
git clone <repo> && cd allusion-tracer
pip install -e ".[dev]"

要求：Python 3.11+

配置

环境变量 / .env 文件

在项目目录或 $HOME 下创建 .env 文件，或直接设置环境变量：

# 瀚堂典藏凭据（如需）
HYTUNG_USERNAME=your_username
HYTUNG_PASSWORD=your_password

# 中华经典古籍库凭据（如需）
ZHONGHUA_USERNAME=your_username
ZHONGHUA_PASSWORD=your_password

# 缓存目录（可选，默认 ~/.allusion_tracer/cache）
ALLUSION_TRACER_CACHE_DIR=/path/to/cache

自定义 .env 路径

ALLUSION_TRACER_ENV=/path/to/custom.env uv run allusion-tracer

使用方式

作为 MCP Server 运行（stdio）

# 直接启动
uvx dhcckb-allusion-tracer

# 或
python -m allusion_tracer

在 Claude Desktop 中配置

在 claude_desktop_config.json（或 mcp.json）中添加：

{
  "mcpServers": {
    "allusion-tracer": {
      "command": "uvx",
      "args": ["dhcckb-allusion-tracer"],
      "env": {
        "HYTUNG_USERNAME": "your_username",
        "HYTUNG_PASSWORD": "your_password"
      }
    }
  }
}

在 VS Code Copilot 中配置

在 .vscode/mcp.json 中添加：

{
  "servers": {
    "allusion-tracer": {
      "type": "stdio",
      "command": "uvx",
      "args": ["dhcckb-allusion-tracer"]
    }
  }
}

Tool 调用示例

1. 典故溯源

工具: allusion_source_trace
参数: { "keyword": "破釜沉舟", "max_results": 3 }

返回最早的典籍出处（如《史记·项羽本纪》），包含原文句段、释义和出处链接。

2. 历代征引检索

工具: allusion_diachronic_citations
参数: { "keyword": "高山流水", "dynasty_from": "隋唐", "dynasty_to": "清", "max_results": 20 }

返回隋唐至清代间使用"高山流水"典故的诗文引文列表，按时间排序。

3. 语义变迁分析

工具: allusion_semantic_change
参数: { "keyword": "望帝春心托杜鹃", "granularity": "dynasty", "include_raw_citations": true }

返回该典故从先秦到清的语义变化时间线，包括情感色彩、隐喻对象变化和突变节点。

4. 群体与时代分布

工具: allusion_demographic_distribution
参数: { "keyword": "杜鹃啼血", "group_by": "dynasty", "visualization_format": "markdown_table" }

返回各朝代使用频次、使用群体占比和流行高峰期。

返回结构

所有工具返回统一的 JSON 结构，包含：

{
  "keyword": "查询关键词",
  "... 工具特定字段 ...": "...",
  "unavailable_sources": ["数据源名称"],
  "error": "错误信息（如有）"
}

错误信息示例

{
  "keyword": "不存在关键词",
  "error": "未在任何数据源中找到相关结果。建议尝试更具体的表述或换用其他关键词。"
}

项目结构

allusion_tracer/
├── adapters/          # 6 个数据源适配器（ctext/souyun/hytung/shidian/zhonghua/nlc）
│   ├── base.py        # 基类：RateLimiter, BaseAdapter
│   ├── ctext.py       # ctext.org 适配器
│   ├── souyun.py      # 搜韵适配器
│   ├── hytung.py      # 瀚堂典藏适配器
│   ├── shidian.py     # 识典古籍适配器
│   ├── zhonghua.py    # 中华经典古籍库适配器
│   └── nlc.py         # 国家数字图书馆适配器
├── cache/             # 缓存层（SQLite/JSON 文件双后端）
├── tools/             # 4 个 MCP Tool 实现
├── aggregator.py      # 跨源去重/排序/冲突检测
├── config.py          # 全局配置与凭据管理
├── models.py          # Pydantic 数据模型
└── server.py          # MCP Server 入口（stdio）

缓存

• 默认使用 SQLite 缓存，位于 ~/.allusion_tracer/cache/cache.db
• 缓存 TTL：24 小时（可在 config 中调整）
• 可通过 ALLUSION_TRACER_CACHE_DIR 自定义缓存目录

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码检查
ruff check src/

许可证

MIT License