book-archivar

Give an MCP-capable AI agent (Claude Desktop, Claude Code, your own agent) access to your own book library, fully local. The agent can search it by meaning and by exact words, look at a book's chapters, and read any chapter verbatim.

MCP tools:

Core: pure Python, EPUB, plain text and Markdown. Everything else is an opt-in add-on (see below).

Requirements

• Python 3.12+

• An OpenAI-compatible embeddings endpoint. The default is Ollama: ollama pull bge-m3

Related MCP server: mcp-ebook-server

Install

git clone https://github.com/sb32445/book-archivar && cd book-archivar
python3 -m venv venv
./venv/bin/pip install -e .            # add ".[pdf]" for PDF support

Use

./venv/bin/book-archivar doctor                  # is the embedding endpoint reachable?
./venv/bin/book-archivar import ~/Books          # files or folders; originals are never touched
./venv/bin/book-archivar serve                   # MCP server on stdio

Other commands: list, remove <slug>, reindex, watch, review (the last two are add-ons).

Claude Desktop (claude_desktop_config.json) / Claude Code (claude mcp add):

{
  "mcpServers": {
    "books": { "command": "/path/to/venv/bin/book-archivar", "args": ["serve"] }
  }
}

For a network service use serve --transport streamable-http --host 127.0.0.1 --port 8000. There is no authentication: keep it on loopback or put an authenticating proxy in front.

Using it with an agent

example/SKILL.md is a template skill that tells an agent when and how to use the five tools (searching, quoting, reading long chapters). Copy it into your agent's skills folder and adapt it.

Configuration

Everything has a default; see config.example.yaml. Pass --config FILE, set BOOK_ARCHIVAR_CONFIG, or place a config.yaml in the working directory. Data lives in ~/.local/share/book-archivar: library/<slug>/{book.md,chapters.json,metadata.json}, chroma/ (vectors), keyword.db (full-text index).

Changing the embedding model

Vectors from different models are not comparable. The index remembers which model built it; importing with another model fails with a clear message. Run

./venv/bin/book-archivar reindex

to rebuild both indexes from library/ (no original files needed). The old index is kept as chroma.old-<timestamp> until you delete it. Stop serve first. The same command repairs a damaged index, and applies new chunk_size settings.

How it works

Book → Markdown plus chapter byte ranges → overlapping chunks that end at paragraph/sentence boundaries → embeddings → Chroma, and the same chunks into an SQLite FTS5 index. Hybrid search fuses both rankings (reciprocal rank fusion): meaning finds paraphrases, keywords find names and quotes. EPUB chapters come from the table of contents, including anchors inside a file; without one, each document becomes a chapter. The same file (SHA-256) is never imported twice.

Add-ons

All off by default; enable each under addons: in config.yaml.

Inbox watcher (addons.inbox) – drop books into a folder and they are imported: book-archivar watch ~/inbox, or with serve when enabled. Files are never deleted; they move to processed/, duplicates/, review/ or failed/. If the embedding endpoint is down, books simply wait. deploy/book-archivar.service is a systemd example.

Duplicate review (addons.duplicates) – a book whose author and title match an existing one but whose file differs is parked in review/ instead of imported. Decide with book-archivar review list|keep-both|replace|discard <entry>. replace imports first and removes the old copy only afterwards. Stop serve while resolving.

JSON log file (addons.logging) – rotating JSON-lines log of imports, review decisions and every tool call. Metadata only, never queries or book text.

PDF (addons.pdf, pip install "book-archivar[pdf]") – chapters from the PDF's bookmarks; without them "Chapter N" lines, else blocks of 20 pages. Uses poppler's pdftotext if installed (about 10x faster), otherwise pypdf. Scanned PDFs have no text; run OCR (ocrmypdf) first.

Calibre fallback (addons.calibre) – MOBI, AZW3, FB2, DOCX, ODT, RTF via Calibre's ebook-convert (must be installed). The file is converted to a temporary EPUB and imported normally.

Limitations

• The conversion is deliberately simple: tables, footnotes and images are reduced to text. PDF layouts with columns can read oddly.

• Chapter quality depends on the book's table of contents.

• Only use it with books you are allowed to use; do not publish the generated library.

Tests

./venv/bin/pip install -e ".[dev]" && ./venv/bin/pytest

Dual-licensed under MIT or Apache-2.0, at your option.