Skip to main content
Glama
lizhuojunx86

chinese-history-mcp

by lizhuojunx86

chinese-history-mcp

CI PyPI License: MIT Data: CC BY 4.0 Python 3.9+ Dependencies: zero MCP Release

A traceable Chinese-history MCP server. Four Model Context Protocol tools over 9 classical Chinese texts (pre-Qin to Wei-Jin — 史记 / 汉书 / 后汉书 / 三国志 / 左传 / 论语 / 孟子 / 吕氏春秋 / 资治通鉴). Every result carries a 【book → chapter → paragraph】 citation, and honestly reports its review_status — the server never claims per-item human review it doesn't have.

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

Demo — every result is cited

  • Zero runtime dependencies — pure Python standard library. No pip install of a framework, no MCP SDK; the whole server is auditable in a few files.

  • Read-only — opens the corpus with mode=ro + PRAGMA query_only; never writes.

  • Honest by construction — machine-generated punctuation / translation and machine-adjudicated status are labeled in every response (AIGC-compliant).

Why this exists: as of mid-2026 the public MCP ecosystem has no classical Chinese / Chinese-history server. This fills that gap. Income expectation is zero; the goal is a useful public good.

Contents: The four tools · Install & run · The corpus database · Honesty · Data & provenance · Design notes


The four tools

tool

input

returns

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 anchorstime_label_source says which (manual vs derived; omitted on pre-0.2 data).

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).

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.

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.

Each tool call returns JSON. Multi-source events, person appraisals, and place/quality edges all carry the exact 【book → chapter → paragraph】 they came from — that is the point of the server.


Related MCP server: sacred-texts-mcp

Install & run

Requires Python 3.9+ (standard library only — nothing else is installed). The server speaks MCP over stdio (newline-delimited 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

Or run without installing, straight from a checkout:

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

Configure in an MCP client

Claude Desktop (claude_desktop_config.json), Cline, Continue, etc. — add one stdio server. After pip install 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"
    }
  }
}

Or zero-install with uv: uvx chinese-history-mcp --db /path/to/corpus.db.

Try one handshake by hand

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

Demo + hallucination comparison

python3 scripts/mcp_demo.py --db /path/to/corpus.db runs a scripted tour of all four tools (also a minimal MCP-client reference). See docs/MCP_DEMO.md for a side-by-side of a bare LLM (fabricated / uncitable) vs. this server (cited) on the same questions.


The corpus database

corpus.db is not in this repository (it is a ~90 MB binary). Download it from this repo's Releases and point --db at it, or set STORYEXTRACTOR_DB=/path/to/corpus.db.

The database is read-only at runtime. If you host it on a read-only medium, make sure the release artifact was produced with sqlite3 corpus.db "VACUUM INTO 'corpus_release.db'" (single file, no -wal/-shm sidecars).


Honesty (please read)

This server is designed for provenance, not to launder machine output as scholarship. Downstream clients and LLMs must not present its results as "individually human-reviewed." Every response labels what it is:

  • Events review_status='approved' — mostly machine bulk-approved credible inferences, not per-item human review.

  • Person profiles review_status='draft' — LLM-synthesized, not human-vetted.

  • Quality mappingsauto_approved = multi-LLM machine consensus, draft = pending review; evidence_quote is a real substring of the source, rationale is an LLM's reasoning.

  • Place mappings — mostly multi-LLM machine consensus (auto_approved), a few human-approved; confidence is bucketed high/medium/doubtful.

  • Text — original is public-domain 白文 with machine-generated punctuation/segmentation; vernacular translation is fully machine-generated.

The server also does not eliminate downstream hallucination: it gives you citable retrieval facts; an LLM built on top can still confabulate around them. The citations are anchors for human verification.

Scope is the 9 texts above — "not found" means "not in this corpus," not "did not happen."


Data & provenance

  • Original text: public-domain classical Chinese 白文 (unpunctuated base text from public-domain editions), with self-produced, machine-generated punctuation and segmentation (not copied from any modern annotated/collated edition).

  • Vernacular translation: machine-generated across the whole corpus.

  • Annotations (events / entities / places / qualities): machine-assisted, with human review gating on selected layers; status is reported per record.

License

  • Code (this repository): MIT — see LICENSE.

  • Corpus data (corpus.db, distributed via Releases): CC BY 4.0.

The text layer is self-produced (punctuation/segmentation) over public-domain base text, so it is distributed freely; machine-generated attributes are labeled throughout for AIGC compliance.


Design notes

  • Pure stdlib hand-written stdio JSON-RPC 2.0 (initialize / tools/list / tools/call + ping / notifications). No third-party MCP SDK.

  • Read-only DB access (src/storyextractor/mcp/db.py): mode=ro + PRAGMA query_only; the migration-running db.connect is never used at serve time.

  • Tests: python3 tests/test_mcp_server.py (read-only enforcement, protocol shapes/error codes, honest review_status, alias token-exact matching + disambiguation, LIKE-wildcard escaping) — builds a temporary fixture DB, so it runs without corpus.db.


Contributing & project meta

  • CONTRIBUTING.md — how to run tests/lint and the principles this project holds to.

  • CHANGELOG.md — release history.

  • SECURITY.md — threat surface (read-only, no network) and how to report issues.

Issues and pull requests are welcome. Please keep the constraints in mind: zero runtime dependencies, read-only, every result cited, honest review_status.

Available Tools

4 tools
get_personA

查人物画像 + 他者评价 + 参与事件 (逐条带出处)。画像 (profile) 为 LLM 综合生成、review_status=draft (未逐条人核); 他者评价 excerpt 是公版原文照抄可溯源; 附史料评为的品质。库内为先秦-汉魏人物。

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes人物本名或别名, 如 '曹操'、'项羽'、'淮阴侯'

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the full burden. It discloses that profiles are LLM-generated with draft review status, others' evaluations are verbatim from public editions and traceable, and appended historical evaluations. The database scope (pre-Qin to Han-Wei) is also stated. This provides good transparency about data quality and sourcing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (four sentences in Chinese) and front-loaded with the main function. Each sentence adds relevant detail (content types, source traceability, review status). No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one parameter and no output schema, the description adequately outlines what the tool returns (profile, evaluations, events with sources). It also notes data quality and historical scope. The description is sufficient for an agent to understand the tool's output and limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'name' has a schema description listing examples and acceptable formats. The tool description does not add additional parameter semantics beyond what the schema already provides. Since schema coverage is 100%, a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool retrieves person profiles, others' evaluations, and involved events with sources. It clearly specifies the verb '查' (query) and the resource (person). The tool name and description distinguish it from siblings like query_by_place (place query) and query_by_quality (quality query).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for comprehensive person lookup but does not explicitly state when to use versus alternatives such as search_events (event-only) or query_by_quality. No prerequisites or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_by_placeA

用今天的地名反查发生在这块土地上的古籍故事 + 出处。今地名可为省/地级市/区县 (如 '西安'、'陕西西安'、'洛阳')。古今映射多为多 LLM 机审共识 (auto_approved); 同名异地/古名多解时返回候选列表让你消歧, 绝不替你单选; 方向性泛称 (江东/关中) 不收录。

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo返回故事数 1-50, 默认 15
placeYes今天的地名, 如 '西安'、'洛阳'、'开封'

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behaviors: uses multi-LLM consensus ('auto_approved'), returns a candidate list for disambiguation, does not auto-select, and avoids directional terms. With no annotations provided, the description fully carries the burden of transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single focused paragraph. The first sentence immediately states the core purpose, followed by essential details and constraints. No extraneous wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 2 parameters, no output schema, and no annotations, the description covers all important aspects: purpose, input format, disambiguation behavior, exclusion criteria, and success logic. It leaves no significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how the 'place' parameter is resolved (disambiguation, accepted formats), which goes beyond the schema's single-line description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: using modern place names to lookup ancient stories and sources. It specifies the hierarchical levels supported (province/city/county) and distinguishes itself from siblings like get_person or query_by_quality by focusing on place-based queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to use (modern place name lookup), with examples ('西安', '陕西西安'). Clearly states what it does not do: it won't single-select ambiguous results and excludes directional terms like '江东'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_by_qualityA

按品质 (德性/才能/性情/为政…) 查代表性最强的事件/人物/故事 + 原文证据。品质取自 55 词受控词表 (如 忠/谋略/勇/仁/残暴/骄), 可用中文名或英文 slug。映射是【判断】非事实: auto_approved=机审高置信、draft=待人审; evidence_quote 是原文真子串; 默认只出机审通过。

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo事件/人物/故事各返回条数 1-30, 默认 10
qualityYes品质名或 slug, 如 '忠'、'谋略'、'yong'
include_draftNo是否含待人审(draft)映射, 默认 false 只返回机审通过

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the transparency burden. It discloses that the mapping is judgment-based, not factual, and distinguishes auto_approved vs. draft review states. It also clarifies that evidence_quote is a true substring of the original text. Missing details like error handling or authorization, but the core behavioral traits are well covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense sentence that packs purpose, vocabulary, review states, and defaults without fluff. It is front-loaded with the main action and resource. Slightly long, but each clause carries meaningful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description partially explains return content by mentioning evidence_quote and review statuses. It covers the key behavioral edge cases (draft filtering, controlled vocabulary). It does not fully specify the return structure or error behavior, but for a simple query tool with three parameters, it is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage, giving a baseline of 3. The description adds value by providing concrete examples of quality values (忠, 谋略, 勇, 仁, 残暴, 骄), explaining the controlled vocabulary and the review-state semantics for include_draft. This goes beyond the schema's parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool queries by quality (Chinese: 品质) and returns representative events, people, and stories with original-text evidence. It explicitly enumerates the controlled vocabulary and distinguishes itself from siblings like search_events, get_person, and query_by_place by the query dimension (quality).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use it: when searching by a quality from a 55-term controlled vocabulary, using either Chinese or English slugs. It also specifies default behavior (only machine-approved outputs) and the include_draft option. It does not explicitly state exclusions vs. alternatives, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_eventsA

查跨书融合历史事件 + 逐源出处。同一史事在史记/汉书/资治通鉴等多书的记载被合并为一条, 每个来源带【书·篇·段】与角色 (主叙/详述/简述/评论/旁证)。返回 review_status (approved=机审批量过审的可信推定, 非逐条人审); canonical_summary 为 LLM 融合的机器叙述。

ParametersJSON Schema
NameRequiredDescriptionDefault
bookNo限定来源书 slug (可选): shiji, hanshu, houhanshu, sanguozhi, zuozhuan, lunyu, mengzi, lushi-chunqiu, zizhitongjian
kindNo按事件类型过滤(可选): '事件'|'场景'|'评价'。不传默认返回全部类型, 含他者评价产出的'评价'事件。
limitNo返回条数 1-50, 默认 10
personNo限定涉及人物 (标题/叙述/摘录含此名), 如 '韩信'
keywordNo事件关键词, 匹配标题或融合叙述, 如 '鸿门宴'、'赤壁'、'七国之乱'

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that events are machine-merged and machine-reviewed, specifically noting that review_status is a batch machine approval, not per-item human review, and canonical_summary is an LLM-generated narrative. This is a valuable caveat beyond the basic operation, providing transparency about data reliability and provenance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two dense sentences that convey the purpose, the merging behavior, provenance formats, and reliability caveats. No filler or redundant information; every phrase adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description appropriately explains the key return fields (review_status, canonical_summary) and the per-source provenance structure. It also covers the source roles, making the tool's behavior sufficiently predictable for an agent to select and invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the baseline is 3. The description adds no extra meaning about parameter usage—it focuses on the result structure rather than how to filter the parameters. Thus it neither improves nor worsens the schema's already clear documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: searching cross-book fused historical events with per-source provenance. It specifies the merging of records from multiple history books and the output structure, distinguishing it from sibling tools like get_person or query_by_place which target other entity types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description establishes a clear context for when to use this tool—when you need an event synthesized from multiple historical sources. It does not explicitly name alternatives or exclusions, but its scope is sufficiently distinct that an agent can infer when to apply it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A4.3/5.0
Disambiguation5/5

Each tool targets a distinct search dimension: events, persons, places, and qualities. The descriptions clearly separate their use cases, leaving no ambiguity about which tool to select for a given query.

Naming Consistency4/5

Most tools follow a clear verb_noun pattern (search_events, get_person), while two use query_by_ (place, quality). This minor deviation is still readable and doesn't confuse the overall naming convention.

Tool Count5/5

With 4 tools, the server is well-scoped for its purpose. Each tool earns its place, covering different aspects of Chinese history knowledge without redundancy or bloat.

Completeness4/5

The toolset covers core search dimensions (event, person, place, quality), but lacks time-based or dynasty-specific queries and direct source text retrieval. These are minor gaps that agents can work around using the provided tools.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • F
    license
    A
    quality
    C
    maintenance
    A local MCP server for querying Chinese scientific literature from the CSL dataset, enabling paper search, detail retrieval, and dataset statistics via MCP clients.
    5
  • A
    license
    Not graded
    quality
    C
    maintenance
    A read-only MCP server that lets you search current and historical facts from a time-indexed knowledge graph derived from a folder of Markdown/text documents, with verification against original sources. It exposes tools for status, fact search, history search, and revision lookup while keeping document insertion and modification to the CLI.
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    A read-only MCP server for evidence retrieval in Yellow River Basin human–earth systems reviews, exposing PostgreSQL-backed tools for searching and comparing evidence, entities, and spatiotemporal data while preserving source provenance.
    9
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lizhuojunx86/chinese-history-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server