chinese-history-mcp

Purpose

chinese-history-mcp aims to fill the gap in the public MCP ecosystem for a Chinese classical history / Chinese history server. It targets scenarios that need to retrieve citable facts from classic texts spanning the pre-Qin through Han-Wei periods, enabling downstream LLMs or applications to answer based on sourced original text rather than generating from nothing. The project is positioned as a public-benefit initiative, with expected revenue of zero.

Main Capabilities

The server provides four MCP tools, covering nine classic texts (pre-Qin through Han-Wei): Shiji, Hanshu, Hou Hanshu, Sanguozhi, Zuozhuan, Lunyu, Mengzi, Lüshi Chunqiu, and Zizhi Tongjian. It supports queries along the following four axes:

• Events
• Figures
• Modern place names
• Qualities

Each tool call returns JSON. Multi-source events, figure evaluations, and place/quality associations all carry precise [book → chapter → passage] citations.

Usage

Requires Python 3.9+ (standard library only; no other dependencies installed). The server communicates via the MCP protocol over stdio (newline-delimited JSON-RPC 2.0).

Installation

pip install chinese-history-mcp

Or run directly from the checkout directory without installation.

Configuration in an MCP client

Claude Desktop (claude_desktop_config.json), Cline, Continue, etc.: add a stdio server. After installation, configure as follows:

（配置内容见官方仓库文档）

Zero-install method:uvx chinese-history-mcp --db /path/to/corpus.db

Manual handshake test

python3 scripts/mcp_demo.py --db /path/to/corpus.db

Run a scripted demo of the four tools, which can also serve as a minimal MCP client reference.

Corpus database

corpus.db is not in the repository (approximately a 90 MB binary file). Download it from the repository's Releases and point to it via --db , or set the environment variable STORYEXTRACTOR_DB=/path/to/corpus.db. The runtime database is read-only.

Honesty Statement

The server is designed to provide provenance, not to disguise machine output as scholarly work. Downstream clients and LLMs must not present its results as "reviewed item by item by humans." Every response is labeled with the nature of its content:

• Events with review_status='approved': mostly reliable inferences batch-approved by machines, not item-by-item human review.
• Person profiles with review_status='draft': synthesized by LLMs, not human-reviewed.
• Quality mappings: auto_approved = multi-LLM machine consensus, draft = pending review; evidence_quote is a real substring from the source, and rationale is the LLM's reasoning.
• Place mappings: mostly multi-LLM machine consensus (auto_approved), with a few human-approved; confidence is divided into three levels: high/medium/doubtful.
• Text: the original text is public-domain unpunctuated text, with machine-generated punctuation/word segmentation; the vernacular translation is entirely machine-generated.

The server cannot eliminate downstream hallucination: it provides citable retrieval facts, but LLMs built on top of it may still fabricate around these facts. Citations are anchors for human verification.

Scope is limited to the nine texts above—"not found" means "not in this corpus," not "did not happen historically."

Data and Sources

• Original text: public-domain classical Chinese unpunctuated text (unpunctuated base text from a public-domain version); punctuation and word segmentation are self-generated and machine-produced (not copied from any modern annotated edition).
• Vernacular translation: machine-generated for the entire corpus.
• Annotations (events/entities/places/qualities): machine-assisted, with human review gating at some levels; each record reports its status.
• Code (this repository): MIT, see LICENSE.
• Corpus data (corpus.db, distributed via Releases): CC BY 4.0.

The text layer is self-generated based on public-domain base text (punctuation/word segmentation), so it can be freely distributed; machine-generated attributes are labeled throughout to comply with AIGC compliance requirements.

Design Notes

• Pure standard-library hand-written stdio JSON-RPC 2.0 (initialize / tools/list / tools/call + ping / notifications), no third-party MCP SDK.
• Read-only datalibrary access (src/storyextractor/mcp/db.py): mode=ro + PRAGMA query_only; db.connect, which runs migrations, is not used during serving.
• Tests:python3 tests/test_mcp_server.py(read-only enforcement, protocol shape/error codes, honest review_status, exact alias matching + disambiguation, LIKE wildcard escaping)—builds a temporary test database, so it can run without corpus.db.

Limitations

• The corpus scope is only the nine texts and does not cover other historical materials.
• Some content is machine-generated or machine-reviewed, not reviewed item by item by humans.
• The server itself does not eliminate downstream hallucination.
• The runtime database is read-only and performs no writes.
• Revenue expectation is zero; the goal is public benefit.
• Contributions must follow constraints: zero runtime dependencies, read-only, every result with citations, honest review_status.