# sacred-texts-mcp

[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![MCP server](https://img.shields.io/badge/MCP-server-6F42C1)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/Code%20license-MIT-green.svg)](LICENSE)

A local [Model Context Protocol](https://modelcontextprotocol.io/) server for
semantic search, close-reading, and cross-tradition comparison across sacred,
mythological, and foundational texts.

It turns heterogeneous source material into citable textual units, embeds them
in a filtered vector index, and gives AI clients seven focused tools for
retrieval and textual analysis.

## What you can do

- Search passages by meaning across multiple traditions and works.
- Find cross-cultural parallels starting from a known passage.
- Retrieve complete, citable passages instead of isolated search snippets.
- Search exact words, lemmas, and Strong numbers where lexical data exists.
- Inspect original-language tokens, morphology, and translation alignment.
- Discover which works are available and what kind of analysis each supports.

Example questions:

> Where do flood narratives appear across different traditions?

> Which creation passages resemble Genesis 1:1?

> How is a specific Hebrew or Greek lemma used across the indexed texts?

See [real tool output from three example sessions](examples/queries.md).

## How it works

```mermaid
flowchart LR
    A[Heterogeneous sources] --> B[Format-aware parsers]
    B --> C[Citable text units]
    C --> D[Gemini embeddings]
    D --> E[(SQLite + sqlite-vec)]
    E --> F[FastMCP server]
    F --> G[Codex, Claude Code, or another MCP client]
```

The index is local and distributed as a single SQLite file. No API key is
needed to search the prebuilt public index. A Gemini API key is required only
if you choose to rebuild its embeddings.

For implementation details, see [Architecture](docs/architecture.md) and
[Normalization](docs/normalization.md).

## MCP tools

| Tool | Purpose |
| --- | --- |
| `list_works` | List available works, traditions, unit counts, and original-language coverage |
| `semantic_search` | Search by meaning, optionally filtered by tradition or work |
| `similar_to` | Find passages semantically close to a known reference |
| `lexical_search` | Search exact terms, lemmas, or Strong numbers |
| `compare` | Inspect word-level apparatus for one passage |
| `passage` | Retrieve a passage with optional surrounding context |
| `passage_range` | Retrieve a continuous range within one work |

## Quick start

### 1. Install

Requirements: Git and Python 3.10 or newer.

```bash
git clone https://github.com/alessandrodalpozzo/sacred-texts-mcp.git
cd sacred-texts-mcp
python -m pip install -r requirements.txt
```

On Windows, use `py -3` instead of `python` if Python is installed through
the Windows launcher.

### 2. Download the prebuilt index

Download
[`index-open.db` from the latest release](https://github.com/alessandrodalpozzo/sacred-texts-mcp/releases/latest/download/index-open.db)
and save it locally as:

```text
data/index.db
```

The names differ intentionally: `index-open.db` is the downloadable release
asset; `data/index.db` is the path expected by the server.

PowerShell:

```powershell
Invoke-WebRequest `
  -Uri "https://github.com/alessandrodalpozzo/sacred-texts-mcp/releases/latest/download/index-open.db" `
  -OutFile "data/index.db"
```

macOS or Linux:

```bash
curl -L \
  https://github.com/alessandrodalpozzo/sacred-texts-mcp/releases/latest/download/index-open.db \
  -o data/index.db
```

### 3. Connect an MCP client

#### Codex

The project-scoped [`.codex/config.toml`](.codex/config.toml) registers the
server automatically. Open the repository as a trusted project, restart
Codex, and check **Settings > MCP servers** or run `/mcp`.

Codex reads the project instructions from [`AGENTS.md`](AGENTS.md).

#### Claude Code

Claude Code discovers the committed [`.mcp.json`](.mcp.json) automatically.
Its one-line [`CLAUDE.md`](CLAUDE.md) imports `AGENTS.md`, so Claude and
Codex follow the same project guidance.

You can also register the server manually:

```bash
claude mcp add sacred-texts -- python /absolute/path/to/sacred-texts-mcp/server/mcp_server.py
```

#### Other MCP clients

Configure a standard stdio server with:

```json
{
  "command": "python",
  "args": ["/absolute/path/to/sacred-texts-mcp/server/mcp_server.py"]
}
```

## Rebuilding the index

The repository includes the compressed open corpus, so a rebuild does not
require downloading the original source collection:

```bash
cp .env.example .env
# Add GEMINI_API_KEY to .env
python index/build_index.py
```

Rebuilding is optional. The released index is ready for local retrieval.

## Engineering highlights

- **Format-aware ingestion:** reusable parsers normalize TSV, TEI XML, JSON,
  HTML, OCR-derived text, PDFs, and Wikisource material.
- **Citation-preserving chunking:** retrieval units follow each work's own
  verse, section, chapter, or tablet structure rather than arbitrary character
  windows.
- **Incremental embedding pipeline:** unchanged units are detected and are not
  embedded again.
- **Native filtered vector search:** work and tradition metadata participate
  directly in SQLite vector retrieval.
- **Self-correcting tool interface:** ambiguous work or tradition names return
  candidates that an MCP client can use to refine its request.
- **License-aware publishing:** the public export is mechanically restricted to
  works approved for redistribution.
- **Automated verification:** tests cover corpus schemas, indexing, query
  behavior, vocabulary resolution, diffing, and public-export enforcement.

## Documentation

| Document | Contents |
| --- | --- |
| [Architecture](docs/architecture.md) | Pipeline, storage, retrieval, and design decisions |
| [Normalization](docs/normalization.md) | Source-format problems and normalization choices |
| [Data sources and licensing](docs/data-sources.md) | Included and excluded sources, licenses, and attribution |
| [Example sessions](examples/queries.md) | Real MCP calls and outputs |
| [Work license registry](data/work_licenses.tsv) | Authoritative per-work source and redistribution status |

## Scope and limitations

The public artifacts include only openly licensed or public-domain material.
They are a curated subset of the editions supported by the ingestion pipeline,
not a comprehensive library of every sacred or ancient text.

Semantic similarity is a retrieval aid, not a historical or theological
judgment. Results depend on the available edition, translation, and embedding
quality. Some works are translation-only and therefore do not support
word-level analysis.

This project applies the same neutral retrieval interface to every tradition
and does not endorse a theological interpretation. See
[Data sources and licensing](docs/data-sources.md) for the exact public scope.

## License

The source code is released under the [MIT License](LICENSE). Textual data
retains its original per-work license and attribution as recorded in
[`data/work_licenses.tsv`](data/work_licenses.tsv).