{
  "markdown": "# chinese-history-mcp\n\n<!-- mcp-name: io.github.lizhuojunx86/chinese-history-mcp -->\n\n[![CI](https://github.com/lizhuojunx86/chinese-history-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/lizhuojunx86/chinese-history-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/chinese-history-mcp.svg)](https://pypi.org/project/chinese-history-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Data: CC BY 4.0](https://img.shields.io/badge/Data-CC%20BY%204.0-blue.svg)](DATA_LICENSE.md)\n[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776ab.svg)](https://www.python.org/)\n[![Dependencies: zero](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#)\n[![MCP](https://img.shields.io/badge/MCP-server-000000.svg)](https://modelcontextprotocol.io)\n[![Release](https://img.shields.io/github/v/release/lizhuojunx86/chinese-history-mcp)](https://github.com/lizhuojunx86/chinese-history-mcp/releases)\n\nA **traceable Chinese-history MCP server**. Four [Model Context\nProtocol](https://modelcontextprotocol.io) tools over **9 classical Chinese\ntexts** (pre-Qin to Wei-Jin — 史记 / 汉书 / 后汉书 / 三国志 / 左传 / 论语 / 孟子 /\n吕氏春秋 / 资治通鉴). **Every result carries a 【book → chapter → paragraph】\ncitation**, and honestly reports its `review_status` — the server never claims\nper-item human review it doesn't have.\n\n> 一个**可溯源的中国历史故事** MCP server：按事件 / 人物 / 今地名 / 品质四轴查询\n> 先秦-汉魏九部正史子书，每条返回都带原文出处，机器生成/机审内容如实标注。\n\n![Demo — every result is cited](assets/demo.svg)\n\n- **Zero runtime dependencies** — pure Python standard library. No `pip install`\n  of a framework, no MCP SDK; the whole server is auditable in a few files.\n- **Read-only** — opens the corpus with `mode=ro` + `PRAGMA query_only`; never\n  writes.\n- **Honest by construction** — machine-generated punctuation / translation and\n  machine-adjudicated status are labeled in every response (AIGC-compliant).\n\nWhy this exists: as of mid-2026 the public MCP ecosystem has **no classical\nChinese / Chinese-history server**. This fills that gap. Income expectation is\nzero; the goal is a useful public good.\n\n**Contents**: [The four tools](#the-four-tools) · [Install & run](#install--run) ·\n[The corpus database](#the-corpus-database) · [Honesty](#honesty-please-read) ·\n[Data & provenance](#data--provenance) · [Design notes](#design-notes)\n\n---\n\n## The four tools\n\n| tool | input | returns |\n|---|---|---|\n| `search_events` | `keyword` / `book` / `person` / `kind` / `limit` | Cross-book fused historical events with **per-source provenance** (book · chapter · paragraph + role: primary/detailed/brief/comment/corroborating). `canonical_summary` is an LLM-fused machine narrative. Optional `kind` filter (事件/场景/评价; unset = all, including appraisal events). `time_label` may be **derived from reviewed time anchors** — `time_label_source` says which (manual vs derived; omitted on pre-0.2 data). |\n| `get_person` | `name` (given name or alias) | Person profile (LLM-synthesized, `draft`) + others' appraisals (verbatim source quotes, each cited) + attributed qualities + events mentioning them + **person-to-person relations** (closed 26-type vocabulary — kinship/ruler-minister/mentorship/alliance/enmity; machine-reviewed, only `approved`/`auto_approved` exposed, no temporal bounds; empty on pre-0.2 data). |\n| `query_by_place` | `place` (today's place name) / `limit` | Ancient stories set on the land of a modern place, with citations. Same-name-different-place returns candidates for you to disambiguate — **it never silently picks one**. Directional/regional generic names are excluded. |\n| `query_by_quality` | `quality` (from a 55-term controlled vocabulary, e.g. 忠 loyalty, 谋略 strategy) / `limit` / `include_draft` | Representative events, people, and stories for a quality, each with an **original-text `evidence_quote`** and rationale. |\n\nEach tool call returns JSON. Multi-source events, person appraisals, and\nplace/quality edges all carry the exact 【book → chapter → paragraph】 they came\nfrom — that is the point of the server.\n\n---\n\n## Install & run\n\nRequires **Python 3.9+** (standard library only — nothing else is installed).\nThe server speaks MCP over stdio (newline-delimited JSON-RPC 2.0).\n\n```bash\npip install chinese-history-mcp\n# then (after downloading corpus.db from Releases — see below):\nchinese-history-mcp --db /path/to/corpus.db\n```\n\nOr run without installing, straight from a checkout:\n\n```bash\nPYTHONPATH=src python3 -m storyextractor.mcp.server --db /path/to/corpus.db\n```\n\n### Configure in an MCP client\n\nClaude Desktop (`claude_desktop_config.json`), Cline, Continue, etc. — add one\nstdio server. After `pip install chinese-history-mcp`:\n\n```json\n{\n  \"mcpServers\": {\n    \"chinese-history\": {\n      \"command\": \"chinese-history-mcp\",\n      \"args\": [\"--db\", \"/path/to/corpus.db\"]\n    }\n  }\n}\n```\n\n<details><summary>Alternative: run from a checkout (no install), or with <code>uvx</code></summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"chinese-history\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"storyextractor.mcp.server\", \"--db\", \"/path/to/corpus.db\"],\n      \"env\": { \"PYTHONPATH\": \"src\" },\n      \"cwd\": \"/absolute/path/to/chinese-history-mcp\"\n    }\n  }\n}\n```\n\nOr zero-install with [uv](https://docs.astral.sh/uv/):\n`uvx chinese-history-mcp --db /path/to/corpus.db`.\n\n</details>\n\n### Try one handshake by hand\n\n```bash\nprintf '%s\\n' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{}}}' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"query_by_quality\",\"arguments\":{\"quality\":\"忠\",\"limit\":2}}}' \\\n  | chinese-history-mcp --db /path/to/corpus.db\n```\n\n### Demo + hallucination comparison\n\n`python3 scripts/mcp_demo.py --db /path/to/corpus.db` runs a scripted tour of\nall four tools (also a minimal MCP-client reference). See\n[docs/MCP_DEMO.md](docs/MCP_DEMO.md) for a side-by-side of **a bare LLM\n(fabricated / uncitable) vs. this server (cited)** on the same questions.\n\n---\n\n## The corpus database\n\n`corpus.db` is **not** in this repository (it is a ~90 MB binary). Download it\nfrom this repo's **[Releases](../../releases)** and point `--db` at it, or set\n`STORYEXTRACTOR_DB=/path/to/corpus.db`.\n\nThe database is read-only at runtime. If you host it on a read-only medium,\nmake sure the release artifact was produced with\n`sqlite3 corpus.db \"VACUUM INTO 'corpus_release.db'\"` (single file, no\n`-wal`/`-shm` sidecars).\n\n---\n\n## Honesty (please read)\n\nThis server is designed for provenance, not to launder machine output as\nscholarship. **Downstream clients and LLMs must not present its results as\n\"individually human-reviewed.\"** Every response labels what it is:\n\n- **Events** `review_status='approved'` — mostly **machine bulk-approved**\n  credible inferences, **not** per-item human review.\n- **Person profiles** `review_status='draft'` — LLM-synthesized, not human-vetted.\n- **Quality mappings** — `auto_approved` = multi-LLM machine consensus, `draft`\n  = pending review; `evidence_quote` is a real substring of the source,\n  `rationale` is an LLM's reasoning.\n- **Place mappings** — mostly multi-LLM machine consensus (`auto_approved`),\n  a few human-approved; confidence is bucketed high/medium/doubtful.\n- **Text** — original is public-domain 白文 with **machine-generated\n  punctuation/segmentation**; vernacular translation is **fully\n  machine-generated**.\n\nThe server also does not eliminate downstream hallucination: it gives you\n**citable retrieval facts**; an LLM built on top can still confabulate around\nthem. The citations are anchors for *human* verification.\n\nScope is the 9 texts above — \"not found\" means \"not in this corpus,\" not \"did\nnot happen.\"\n\n---\n\n## Data & provenance\n\n- **Original text**: public-domain classical Chinese 白文 (unpunctuated base\n  text from public-domain editions), with **self-produced, machine-generated\n  punctuation and segmentation** (not copied from any modern annotated/collated\n  edition).\n- **Vernacular translation**: **machine-generated** across the whole corpus.\n- **Annotations** (events / entities / places / qualities): machine-assisted,\n  with human review gating on selected layers; status is reported per record.\n\n### License\n\n- **Code** (this repository): **MIT** — see [LICENSE](LICENSE).\n- **Corpus data** (`corpus.db`, distributed via Releases): **CC BY 4.0**.\n\nThe text layer is self-produced (punctuation/segmentation) over public-domain\nbase text, so it is distributed freely; machine-generated attributes are\nlabeled throughout for AIGC compliance.\n\n---\n\n## Design notes\n\n- Pure stdlib hand-written stdio JSON-RPC 2.0 (`initialize` / `tools/list` /\n  `tools/call` + `ping` / notifications). No third-party MCP SDK.\n- Read-only DB access (`src/storyextractor/mcp/db.py`): `mode=ro` +\n  `PRAGMA query_only`; the migration-running `db.connect` is never used at\n  serve time.\n- Tests: `python3 tests/test_mcp_server.py` (read-only enforcement, protocol\n  shapes/error codes, honest `review_status`, alias token-exact matching +\n  disambiguation, LIKE-wildcard escaping) — builds a temporary fixture DB, so\n  it runs without `corpus.db`.\n\n---\n\n## Contributing & project meta\n\n- [CONTRIBUTING.md](CONTRIBUTING.md) — how to run tests/lint and the principles\n  this project holds to.\n- [CHANGELOG.md](CHANGELOG.md) — release history.\n- [SECURITY.md](SECURITY.md) — threat surface (read-only, no network) and how to\n  report issues.\n\nIssues and pull requests are welcome. Please keep the constraints in mind:\nzero runtime dependencies, read-only, every result cited, honest `review_status`.\n",
  "bytes": 9632,
  "sha": "e98145438746d67cb2c38c6fd75c976ff47d26e9a135b694fc5a24c588f545e3",
  "repo_slug": "lizhuojunx86/chinese-history-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lizhuojunx86_chinese_history_m_97a7bdae/readme"
}