Zayit MCP Server

An MCP (Model Context Protocol) server that exposes the Zayit Jewish texts library to AI assistants. Wraps Zayit's SQLite database and Lucene search indices — no network required, fully offline.

Prerequisites

Zayit installed on the same machine (provides the database and Lucene indices)
Java 21+ — required by Lucene 10.x

Installing Java 21

| Platform | Command | |----------|---------| | Windows | winget install EclipseAdoptium.Temurin.21.JDK | | macOS | brew install --cask temurin@21 | | Ubuntu/Debian | sudo apt install temurin-21-jdk (add Adoptium repo first) | | Fedora/RHEL | sudo dnf install temurin-21-jdk |

Building

The Gradle wrapper is included — no separate Gradle installation needed.

# Linux / macOS
chmod +x gradlew
./gradlew shadowJar

# Windows
gradlew.bat shadowJar

Output: build/libs/zayit-mcp.jar (~35 MB, self-contained)

Running

stdio mode (for Claude Desktop / MCP clients)

# Linux / macOS
chmod +x run-stdio.sh
./run-stdio.sh

# Windows
run-stdio.bat

HTTP / SSE mode (for testing or remote access)

# Linux / macOS
./run-http.sh 3001

# Windows
run-http.bat 3001

The MCP endpoint is at http://localhost:3001/mcp.

Custom data directory

If Zayit stores its data somewhere non-standard, set ZAYIT_DATA_DIR:

ZAYIT_DATA_DIR=/path/to/databases ./run-stdio.sh

Data paths (auto-detected per OS)

| Platform | Path | |----------|------| | Windows | %APPDATA%\io.github.kdroidfilter.seforimapp\databases | | macOS | ~/Library/Application Support/io.github.kdroidfilter.seforimapp/databases | | Linux | ~/.local/share/io.github.kdroidfilter.seforimapp/databases (XDG) |

Claude Desktop configuration

Windows

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "zayit": {
      "command": "C:\\path\\to\\zayit-mcp\\run-stdio.bat"
    }
  }
}

macOS / Linux

~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
~/.config/Claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "zayit": {
      "command": "/path/to/zayit-mcp/run-stdio.sh"
    }
  }
}

Tools

`search_books`

Search for books by title using SQLite LIKE.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | required | Hebrew or partial title | | limit | integer | 20 | Max results |

Returns: id | title | category | lines=N [primary]

Example: query="בראשית" → בראשית, בראשית רבה, אגדת בראשית …

`search_ref`

Fast prefix lookup via the Lucene reference index.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | required | Title prefix (Hebrew) | | limit | integer | 10 | Max results |

Returns: book_id=N | title

`get_text`

Retrieve lines from a book by numeric ID with pagination.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | book_id | integer | required | From search_books or search_ref | | offset | integer | 0 | Line offset | | limit | integer | 50 | Lines to return (max 200) |

`get_text_by_ref`

Retrieve text by Hebrew reference string — the ergonomic alternative to get_text.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | ref | string | required | e.g. בראשית א, א or ברכות ב | | context | integer | 2 | Lines of context before/after each hit | | limit | integer | 10 | Max hits |

Returns: Matched line (marked ►) with surrounding context, across all books containing that reference.

Example: ref="בראשית א, א" finds Genesis 1:1 in the base text plus every commentary quoting it.

`get_book_toc`

Get the hierarchical chapter/section table of contents for a book.

| Parameter | Type | Description | |-----------|------|-------------| | book_id | integer | Book ID |

Returns: Indented TOC with line_id pointers per section. Use the line_id values as offset in get_text.

Example output:

▸ בראשית → line_id=1
  • פרק א → line_id=2
  • פרק ב → line_id=34
  ...

`get_links`

Cross-references for a book or specific line, from the link table.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | book_id | integer | required | Book to find links for | | line_id | integer | — | Restrict to a specific line | | connection_type | string | — | Commentary, Targum, Reference, Source, Other | | limit | integer | 30 | Max links |

Returns: Source and target refs with 120-char text snippets and connection type.

`text_search`

Full-text search across all ~6,000 books using Lucene. Nikud and teamim are stripped automatically; final letters (ך→כ, ם→מ, ן→נ, ף→פ, ץ→צ) are normalized.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | required | Lucene query (see syntax below) | | book_id | integer | — | Restrict to one book | | limit | integer | 20 | Max results | | offset | integer | 0 | Pagination offset |

Lucene query syntax:

| Syntax | Example | Meaning | |--------|---------|---------| | Terms (AND by default) | תורה משה | both words must appear | | Explicit OR | אברהם OR יצחק | either word | | Exclude | תורה -משנה | תורה without משנה | | Phrase | "ואהבת לרעך כמוך" | exact phrase | | Prefix wildcard | ברא* | ברא, בראשית, בראה … | | Single-char wildcard | ב?אשית | | | Fuzzy | שלום~ | similar spelling | | Proximity | "תורה משה"~5 | within 5 words of each other | | Grouping | (אברהם OR יצחק) שרה | |

Architecture

AI client
    │  MCP JSON-RPC (stdio or HTTP/SSE)
    ▼
zayit-mcp.jar
    ├── SQLite (seforim.db)          → search_books, get_text, get_text_by_ref,
    │                                   get_book_toc, get_links
    └── Lucene (seforim.db.lucene,   → text_search, search_ref
                seforim.db.lookup.lucene)

Stack: Kotlin 2.3 · MCP SDK 0.12.0 · Lucene 10.3.2 · SQLite JDBC 3.49 · Ktor 3.1 (HTTP mode)

MCP Servers