史典古籍 MCP Server

为 AI 助理（Claude Desktop）提供史典古籍网站的智能采集能力，通过 MCP（Model Context Protocol）协议暴露为可调用工具。

✨ v0.3.0 重大更新

📦 百万字长文本智能分块系统

• 500字/块：对应古籍一页，支持百万字级别文本处理
• 三种模式：默认模式、关键词搜索、精确获取
• 高性能缓存：首次3-4秒，缓存命中0ms，LRU策略1小时TTL
• LLM友好：<书籍信息>、<块N>标签清晰结构化输出

🚀 核心特性

1. 智能分块：自动检测长文本并分块处理
2. 关键词检索：精准定位相关块，无需加载全文
3. 精确获取：按块号直接读取指定内容
4. 内存安全：按需返回，避免百万字内存溢出

🚀 快速开始

安装方式

推荐使用 npx 方式（无需安装）：

npx -y shidianguji-mcp

或全局安装：

npm install -g shidianguji-mcp

Claude Desktop 配置

编辑配置文件：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "shidianguji": {
      "command": "npx",
      "args": ["-y", "shidianguji-mcp"]
    }
  }
}

重启 Claude Desktop 即可使用。

📖 工具使用

1. search_guji - 搜索古籍

支持原字/模糊搜索，可按分类、朝代、书名、作者筛选。

示例：

{
  "keyword": "关羽",
  "search_mode": "original",
  "pages": 1
}

高级筛选：

{
  "keyword": "天朝",
  "category_filter": "史部",
  "dynasty_filter": "明",
  "book_name": "明史"
}

2. get_library - 分类浏览

获取古籍四部分类（经史子集）信息。

示例：

{
  "library_id": "20000"
}

3. get_book - 获取书籍内容（⭐ 支持百万字长文本）

核心特性：

• 自动分块：超过500字自动分块处理
• 关键词检索：只返回包含关键词的块
• 精确获取：按块号直接读取

基本用法（获取概览）：

{
  "book_id": "YW00001",
  "chapter_id": "1l5o2xukw2q07"
}

关键词搜索（推荐用法）：

{
  "book_id": "YW00001",
  "chapter_id": "1l5o2xukw2q07",
  "keyword": "天朝"
}

精确获取指定块：

{
  "book_id": "YW00001",
  "chapter_id": "1l5o2xukw2q07",
  "chunks": [7, 15, 20]
}

返回格式示例：

<书籍信息>
书籍: 朝鲜王朝实录
总块数：69
总字数：34,084
关键字：天朝
匹配块：[1, 9, 20, 23, 24]
</书籍信息>

<块1>
...奉使天朝，请建国本...
</块1>

<块9>
...贻怒于天朝，见非于人议...
</块9>

<系统提醒>
- 使用 chunks=[块号] 直接读取目标块
- 使用 keyword="关键词" 检索包含关键词的块
- 总共69块，每块约500字
</系统提醒>

4. get_reference_links - 生成引用链接

批量生成古籍引用URL。

示例：

{
  "references": [
    {"book_id": "SBCK001", "chapter_id": "SBCK001_1"},
    {"book_id": "SBCK002"}
  ]
}

5. install_browsers - 安装浏览器

诊断并修复 Playwright 浏览器依赖问题。

示例：

{
  "install_system_deps": false
}

🔧 性能优化

缓存机制

• LRU缓存：1小时TTL，访问即续期
• 自动清理：10分钟一次，移除过期条目
• 高速响应：缓存命中0ms，极致性能

内存管理

• 延迟初始化：按需创建浏览器
• 自动释放：60秒闲置后释放浏览器
• 内存优化：闲置50MB，工作300MB

📊 使用场景

1. 历史研究

通过关键词快速定位史料：

{
  "book_id": "HISTORICAL_BOOK",
  "chapter_id": "CHAPTER_1",
  "keyword": "天启"
}

2. 古籍阅读

分块阅读长篇文献：

{
  "book_id": "LONG_BOOK",
  "chapter_id": "CHAPTER_1",
  "chunks": [1, 2, 3]
}

3. 文献检索

搜索特定主题的古籍：

{
  "keyword": "海运",
  "category_filter": "史部",
  "dynasty_filter": "明"
}

🛠️ 开发指南

本地开发

# 克隆仓库
git clone https://github.com/yokami618/history.git
cd history

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 运行测试
npm test

项目结构

src-ts/
├── cli/          # CLI 命令实现
├── core/         # 核心调度器和浏览器管理
├── mcp/          # MCP Server 实现
├── parsers/      # 页面解析器（搜索/分类/书籍）
├── types/        # TypeScript 类型定义
└── utils/        # 工具类（格式化器等）

📦 发布流程

准备发布

1. 更新版本号：

npm version patch  # 0.3.0 → 0.3.1
npm version minor  # 0.3.0 → 0.4.0
npm version major  # 0.3.0 → 1.0.0

2. 编译代码：

npm run build

3. 测试验证：

npm test
node test-chunking.js  # 测试分块功能

发布到 npm

# 登录 npm（首次）
npm login

# 发布
npm publish

# 查看发布结果
npm info shidianguji-mcp

发布检查清单

• [ ] 版本号已更新
• [ ] 代码已编译（dist/ 目录存在）
• [ ] 测试全部通过
• [ ] package.json 描述信息最新
• [ ] README.md 文档完整

🐛 故障排除

浏览器启动失败

运行浏览器安装工具：

npx shidianguji-mcp  # 会提示安装浏览器

或使用 install_browsers 工具。

内存占用高

• 检查缓存：缓存会在1小时后自动清理
• 重启服务：关闭 Claude Desktop 后重新打开

📄 许可证

MIT License - 详见 LICENSE

🙏 致谢

• 史典古籍 - 提供古籍数字化资源
• Model Context Protocol - AI工具标准化协议
• Playwright - 强大的浏览器自动化框架

📮 联系方式

• GitHub: @yokami618
• Issues: 提交问题

🎯 v0.3.0 - 百万字长文本智能分块系统，让古籍研究更高效！