sacred-texts-mcp

Semantic search and comparative retrieval over a multi-tradition corpus of sacred and foundational texts, exposed as an MCP server.

What it does

Ancient texts live in hostile formats: interlinear TSV with Strong numbers, TEI XML, decades-old HTML, OCR'd PDFs, wikisource dumps. This project parses them into one normalized corpus of citable units (verse / section / tablet), embeds it, and serves it through the Model Context Protocol — so any MCP client (Claude Code, IDEs, your own app) can search scripture by meaning, compare passages across traditions, and read word-level apparatus where it exists.

Architecture

flowchart LR
    A[Heterogeneous sources] --> B[Format-family parsers]
    B --> C[corpus.jsonl]
    C --> D[Gemini batch embeddings]
    D --> E[(sqlite-vec index)]
    E --> F[MCP server — 7 tools]
    F --> G[Any MCP client]

Details in docs/architecture.md; the data problems (and how they were beaten) in docs/normalization.md.

The MCP tools

Tool	What it answers
list_works	What's in the corpus, per tradition, with per-work capabilities
passage / passage_range	Read a unit or a span, translation and original
compare	Word-level apparatus for one unit (tokens, Strong, morphology)
lexical_search	Exact-word and Strong-number search
semantic_search	Meaning-based search, filterable by tradition/work
similar_to	Nearest neighbours of a given passage across the corpus

tradition and work filter to a single value each (a string); to leave several traditions or works out of a search, exclude_tradition and exclude_work accept either a single value or a list — passing a list to tradition/work themselves is rejected as invalid input.

Example sessions with real outputs: examples/queries.md.

Quick start

git clone https://github.com/<you>/sacred-texts-mcp
cd sacred-texts-mcp
pip install -r requirements.txt

Then get an index (pick one):

1. Download index-open.db from the latest GitHub Release and save it as data/index.db. Done — no API key needed.
2. Rebuild it yourself: copy .env.example to .env, add a Gemini API key, and run python index/build_index.py — it reads the committed data/corpus-open.jsonl.gz directly.

Register the server with your MCP client, e.g. for Claude Code:

claude mcp add ancient-texts -- python /path/to/sacred-texts-mcp/server/mcp_server.py

Data and licensing

The committed corpus contains only openly licensed or public-domain texts — the per-work registry is data/work_licenses.tsv, enforced mechanically by tools/export_open_corpus.py. Copyrighted editions (ANET, Nag Hammadi, the Vermes Dead Sea Scrolls…) are not redistributed; docs/data-sources.md documents how to obtain them legally and plug them into the pipeline yourself. Code is MIT.

Scope and limitations

• Retrieval finds semantically similar passages, not truth: results depend on the edition indexed and on embedding quality. Several works are 19th-century translations with known limitations; some are translation-only, with no original-language apparatus.
• This is a text retrieval tool. It advances no theological or historical thesis, endorses no interpretation, and presents all traditions through the same neutral interface.