chinese-history-mcp

chinese-history-mcp

一个可溯源的中国历史 MCP 服务。通过 4 个模型上下文协议工具，查询9 部中国古典文献（先秦至魏晋——史记 / 汉书 / 后汉书 / 三国志 / 左传 / 论语 / 孟子 / 吕氏春秋 / 资治通鉴）。每条结果都附有【书名 → 篇章 → 段落】出处，并如实报告其 review_status——服务绝不会声称自己没有的逐条人工审核。

一个可溯源的中国历史故事 MCP 服务：按事件 / 人物 / 今地名 / 品质四轴查询 先秦-汉魏九部正史子书，每条返回都带原文出处，机器生成/机审内容如实标注。

• 运行时零依赖——仅使用 Python 标准库。不必 pip install 框架，也不需要 MCP SDK；整个服务只需审查少量文件。
• 只读——以 mode=ro 和 PRAGMA query_only 打开语料库；绝不写入。
• 从设计上保证诚实——每个响应都标注机器生成的标点 / 翻译和机器裁定的状态（符合 AIGC 规范）。

项目缘起：截至 2026 年年中，公开的 MCP 生态中没有中国古典文献 / 中国历史服务。本项目旨在填补这一空白。收入预期为零；目标是打造有用的公共产品。

目录：四个工具 · 安装与运行 · 语料库数据库 · 诚实性 · 数据与溯源 · 设计说明

四个工具

每次工具调用都会返回 JSON。多来源事件、人物评价和地点 / 品质关联都会附上其确切出处【书名 → 篇章 → 段落】——这正是此服务的意义所在。

安装与运行

需要 Python 3.9+（仅使用标准库——不会安装其他内容）。 服务通过 stdio 使用 MCP（以换行符分隔的 JSON-RPC 2.0）。

pip install chinese-history-mcp
# then (after downloading corpus.db from Releases — see below):
chinese-history-mcp --db /path/to/corpus.db

也可以不安装，直接从检出目录运行：

PYTHONPATH=src python3 -m storyextractor.mcp.server --db /path/to/corpus.db

在 MCP 客户端中配置

Claude Desktop（claude_desktop_config.json）、Cline、Continue 等——添加一个 stdio 服务。安装 chinese-history-mcp 后：

{
  "mcpServers": {
    "chinese-history": {
      "command": "chinese-history-mcp",
      "args": ["--db", "/path/to/corpus.db"]
    }
  }
}

{
  "mcpServers": {
    "chinese-history": {
      "command": "python3",
      "args": ["-m", "storyextractor.mcp.server", "--db", "/path/to/corpus.db"],
      "env": { "PYTHONPATH": "src" },
      "cwd": "/absolute/path/to/chinese-history-mcp"
    }
  }
}

手动尝试一次握手

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"query_by_quality","arguments":{"quality":"忠","limit":2}}}' \
  | chinese-history-mcp --db /path/to/corpus.db

演示与幻觉对比

运行 python3 scripts/mcp_demo.py --db /path/to/corpus.db，即可按脚本演示 全部四种工具（也是一个精简的 MCP 客户端参考示例）。有关同一组问题的**裸大模型 （捏造／无法引用）与本服务（可引用）**并排对比，请参阅 docs/MCP_DEMO.md。

语料库数据库

corpus.db 不在此仓库中（它是一个约 90 MB 的二进制文件）。请从此仓库的 发行版 下载，并将 --db 指向该文件，或设置 STORYEXTRACTOR_DB=/path/to/corpus.db。

数据库在运行时为只读。如果将其托管在只读介质上，请确保发行版文件是通过 sqlite3 corpus.db "VACUUM INTO 'corpus_release.db'" 生成的（单个文件，不带 -wal／-shm 辅助文件）。

诚信说明（请阅读）

此服务旨在保留来源信息，而非将机器输出包装成学术成果。**下游客户端和大模型不得将其结果表述为“经过逐条人工审核”。**每条响应都会标明其性质：

• 事件 review_status='approved' ——大多是经批量机器审核认可的可信推断，并非逐条人工审核。
• 人物档案 review_status='draft' ——由大模型合成，未经人工审定。
• 质量映射——auto_approved = 多个大模型达成的机器共识，draft = 待审核；evidence_quote 是源文本中的真实子串，rationale 是大模型的推理。
• 地点映射——大多来自多个大模型的机器共识（auto_approved），少数经过人工批准；置信度分为高／中／存疑。
• 文本——原文是公有领域的白文，标点和分段由机器生成；白话文译文完全由机器生成。

此服务也无法消除下游幻觉：它提供的是可引用的检索事实；基于这些事实构建的大模型仍可能围绕它们虚构内容。引用是供人工核验的依据。

范围仅限上述 9 部文本——“未找到”意为“不在此语料库中”，而非“没有发生”。

数据与来源

• 原文：公有领域的古典中文白文（来自公有领域版本的无标点底本文本），并附有自行制作、由机器生成的标点和分段（并非复制自任何现代标注／校勘版本）。
• 白话文译文：整个语料库均为机器生成。
• 标注（事件／实体／地点／品质）：借助机器完成，部分层级设有人审门槛；每条记录都会报告其状态。

许可证

• 代码（此仓库）：MIT——请参阅 许可证。
• 语料库数据（corpus.db，通过 Releases 分发）：CC BY 4.0。

文本层是在公有领域底本文本上自行制作的（添加标点／分段），因此可自由分发；机器生成的属性均已标注，以符合 AIGC 要求。

设计说明

• 纯标准库手写的 stdio JSON-RPC 2.0（initialize / tools/list / tools/call + ping / 通知）。不使用第三方 MCP SDK。
• 只读数据库访问（src/storyextractor/mcp/db.py）：mode=ro + PRAGMA query_only；运行迁移的 db.connect 在服务运行时不会被使用。
• 测试：python3 tests/test_mcp_server.py（强制只读、协议格式/错误代码、如实返回 review_status、别名令牌精确匹配 + 消歧、转义 LIKE 通配符）——构建临时测试数据库，因此无需 corpus.db 即可运行。

贡献与项目说明

• CONTRIBUTING.md — 如何运行测试/代码检查，以及本项目秉持的原则。
• CHANGELOG.md — 发布历史。
• SECURITY.md — 威胁面（只读、无网络）以及如何报告问题。

欢迎提交问题和拉取请求。请牢记以下约束： 运行时零依赖、只读、每项结果都有引用、如实返回 review_status。