librarian-cli is a tool that converts e-books into clean, token-counted Markdown chapters. It supports multiple input formats, including FB2, EPUB, DOCX, HTML, TXT/MD, and text-layer PDF. The conversion process involves no network, no LLM, and no randomness; the same input file always produces byte-identical output, so the ingestion process is reproducible and cacheable.
Main capabilities:
- Convert any e-book into a table of contents containing clean chapters and token counts.
- Built-in stdio MCP server providing 6 read-only tools: list_books, list_chapters, find, get_chapters, book_info, verify_quote. Through these tools, Claude can browse the library catalog, search, extract chapters within a token budget, and independently check whether quotations match the original text.
- Deterministic RAG: no embeddings, no network, no API keys.
- lib verify command: checks whether a quotation appears verbatim in the library. Supports book mode (--book <id>) and shelf mode (no --book). Book mode can perform a full scan of a single book without a search index; shelf mode performs library-wide attribution via FTS5 candidates and requires the quotation to contain at least 5 content words (stop words do not count); otherwise it skips and returns verdict: null.
- Scoring system: each book receives a score from five metrics (coverage, structure, junk, encoding, dehyphenation). ok (score ≥ 0.90, no hard triggers) is saved silently; review (0.60 ≤ score < 0.90, or a trigger is present) is saved with a warning, and details can be viewed via lib doctor <id>; failed (score < 0.60) is not saved.
Usage:
- Specify the library root directory via --library <path>, or use the LIB_HOME environment variable; the default is ./library.
- Data is output to stdout, and diagnostics are output to stderr.
- Exit codes: 0 success, 1 runtime error, 2 usage error. lib verify uses grep-style semantics (unlike the project's usual "1 = runtime error"): exit code 1 with non-empty stdout means "checked, not confirmed"; exit code 1 with empty stdout means an error (diagnosticson stderr). Exit code 0 includes the close case; strict CI gates should check verdict == "exact" in the --json output, not just the exit code.
- Claude Desktop configuration: configure the MCP server in claude_desktop_config.json.
Use cases:
- Need to have Claude read a local e-book library and ensure quotations are accurate.
- Build an offline, deterministic RAG system without embeddings or network.
- Verify in CI whether quotations appear verbatim in e-books.
Limitations:
- PDF: performs well on normally typeset books; complex layouts may fall into review.
- Does not bypass DRM; responsibility for the legality of sources lies with the user.
- Does not support network file systems (NFS/SMB), because advisory locks are unreliable.
- Does not support MOBI/DJVU or scanned versions without text (v3 candidates: OCR, calibre).
- CLI messages are currently in Russian; English output is planned.
- lib verify: does not support quotations crossing chapter boundaries (v1); a close determination for a single-word substitution is more realistic starting from quotations of about 150 characters; shorter quotations, if one word is substituted, are faithfully classified as distorted.
- Shelf mode (no --book) requires an FTS5 search index; book mode (--book <id>) does not require an index in the CLI. lib serve as a whole still requires FTS5, and synchronizes the index at startup.
- Book mode scans the full text of all chapters of a book using pure Python; long books may take a few seconds of CPU; MCP tools run in worker threads and do not block the server.
