{
  "markdown": "<!-- mcp-name: io.github.Terobyte/librarian -->\n# 📚 librarian\n\n[![CI](https://github.com/Terobyte/librarian-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Terobyte/librarian-cli/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/librarian-cli)](https://pypi.org/project/librarian-cli/)\n[![Python versions](https://img.shields.io/pypi/pyversions/librarian-cli)](https://pypi.org/project/librarian-cli/)\n[![License](https://img.shields.io/pypi/l/librarian-cli)](LICENSE)\n[![MCP registry](https://img.shields.io/badge/MCP_registry-io.github.Terobyte%2Flibrarian-6A5ACD)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Terobyte/librarian)\n\nTurn any ebook into clean, token-counted Markdown chapters — let Claude read your\nbookshelf over MCP and catch it misquoting your books. Deterministic RAG: no embeddings,\nno network, no API keys.\n\n![demo](docs/assets/demo.gif)\n\nAny input format — FB2, EPUB, DOCX, HTML, TXT/MD, text-layer PDF — becomes a directory of\nclean chapters with token counts. No network, no LLM, no randomness: the same input always\nproduces byte-identical output.\n\n## Install\n\n```\nuv tool install librarian-cli\n# or: pipx install librarian-cli\n```\n\nOffline contract: install and runtime need no network (the tokenizer's vocabulary is\nvendored in the package).\n\n## Quick start\n\n```\nlib ingest examples/*.epub\nlib list\nlib find curiouser\nlib get <book-id> --budget 3000\n```\n\n## Commands\n\n| Command | Purpose |\n|---------|---------|\n| `lib ingest <files…> [--force] [--no-keep-source] [--config cfg.toml] [--verbose]` | Process books into the library; prints a file · id · status · score table. |\n| `lib list [<book-id>]` | No argument — all books; with an id — that book's chapters (n, title, tokens, summary). |\n| `lib get <book-id> <spec>` | Print chapters by range (`1-3,7`) to stdout. |\n| `lib get <book-id> --budget N [--from K]` | Greedily print consecutive chapters from K while the token sum stays ≤ N. |\n| `lib find <query> [--limit 10] [--book <id>] [--reindex] [--json]` | Full-text search across chapters and titles/authors library-wide (bm25, snippets, RU/EN stemming). |\n| `lib info <book-id>` | JSON: book metadata + quality metrics. |\n| `lib doctor [<book-id>]` | No id — books in review and broken directories; with id — that book's report. |\n| `lib reingest --all [--config cfg.toml] [--verbose]` | Rebuild the library from `source/` with the current code/config. |\n| `lib rm <book-id>` | Delete a book and rebuild the index. |\n| `lib serve [--library <path>]` | Stdio MCP server over the library. |\n| `lib verify \"quote\" [--book ID] [--json] [--limit N]` | Check a quote against one book or attribute it across the library. |\n\nLibrary root: `--library <path>` (or the `LIB_HOME` env var, default `./library`). Data goes\nto stdout, diagnostics to stderr. Exit codes: `0` success, `1` runtime error, `2` usage error.\n\n## Give Claude your bookshelf\n\n`librarian-cli` ships a built-in stdio MCP server with 6 read-only tools — `list_books`,\n`list_chapters`, `find`, `get_chapters`, `book_info`, `verify_quote` — so Claude can browse\nthe catalog, search it, pull chapters under a token budget, and check its own quotes against\nthe source on its own: deterministic RAG with no embeddings, no network, and no API keys.\n\nClaude Code:\n\n```\nclaude mcp add librarian --env LIB_HOME=$HOME/books -- uvx librarian-cli\n```\n\nClaude Desktop (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"librarian\": {\n      \"command\": \"uvx\",\n      \"args\": [\"librarian-cli\"],\n      \"env\": { \"LIB_HOME\": \"/path/to/books\" }\n    }\n  }\n}\n```\n\n## Verify quotes\n\n*An MCP server that catches Claude misquoting your books.*\n\n`lib verify \"quote\"` checks whether a quote actually appears in your library, verbatim —\npunctuation, case, ё/е, and markdown formatting don't count. Two modes:\n\n- **Book mode** (`--book <id>`): full scan of one book — \"does this book actually say\n  this?\" Works without the search index.\n- **Shelf mode** (no `--book`): attribution across the whole library via FTS5 candidates —\n  \"which book is this from?\" The quote needs at least 5 significant words (stop words\n  don't count), or the check is skipped with `verdict: null`.\n\n```\nlib verify \"Рукописи не горят\" --book bulgakov-master-i-margarita\nlib verify \"рукописи не горят никогда\"\n```\n\n| verdict | meaning |\n|---------|---------|\n| `exact` | matches after normalization (punctuation/case/ё/typography don't count) |\n| `close` | similarity ≥ 0.95 — near-exact, differences shown as a word-diff |\n| `distorted` | similarity ≥ 0.75 — the right place, but the quote is misremembered |\n| `not_found` | similarity < 0.75 — nothing like it in the book/library |\n| `null` | check wasn't run: empty quote, or a short quote without `--book` |\n\nExit codes (grep-style semantics, a deliberate departure from the project's usual\n\"`1` = runtime error\" — see `docs/MILESTONES.md` deviation 38):\n\n| exit | case | stdout |\n|------|------|--------|\n| 0 | `exact` / `close` — quote confirmed | full report / JSON |\n| 1 | `distorted` / `not_found` — not confirmed | full report / JSON |\n| 1 | runtime error (unknown book id, no search index, locked index) | empty |\n| 2 | usage error: empty/short quote (`verdict: null`), `--limit < 1` | empty (message on stderr) |\n\nScript discriminator: exit `1` with non-empty stdout means \"checked, not confirmed\"; exit\n`1` with empty stdout means an error (diagnostics went to stderr instead). **Exit `0`\nincludes `close`** — a strict CI gate must check `verdict == \"exact\"` in the `--json`\noutput, not the exit code alone.\n\n## Quality\n\nEvery book gets a score from five metrics (coverage, structure, garbage, encoding,\ndehyphenation): `ok` (score ≥ 0.90, no hard triggers) — saved silently; `review`\n(0.60 ≤ score < 0.90, or triggers present) — saved with a warning, details via\n`lib doctor <id>`; `failed` (score < 0.60) — not saved. Scans and password-protected PDFs\nhonestly fail (OCR and DRM removal are out of scope).\n\n## Determinism\n\nThe pipeline has no network access, no LLM calls, and no randomness — the same input file\nalways produces byte-identical output. That makes ingestion reproducible and cacheable, and\nit's what makes `lib serve`'s RAG deterministic: no embeddings to drift, no model calls to\nvary between runs.\n\n## Limitations\n\n- PDF: works well on typographically normal books; complex layouts may land in `review`.\n- DRM is not circumvented; source legality is the user's responsibility.\n- Networked filesystems (NFS/SMB) are not supported (the advisory lock isn't reliable there).\n- MOBI/DJVU and text-less scans are not supported (v3 candidates: OCR, calibre).\n- CLI messages are currently in Russian; English output is planned.\n- `lib verify`: quotes spanning a chapter boundary are not supported (v1) — the best you'll\n  get is `distorted` on one half.\n- `lib verify`: `close` on a single-word replacement is realistic from ~150 characters of\n  quote; shorter quotes with a replaced word honestly land in `distorted` — a third of a\n  three-word quote really is a distortion.\n- `lib verify` shelf mode (no `--book`) needs the FTS5 search index; book mode\n  (`--book <id>`) works without it in the CLI. `lib serve` as a whole still requires FTS5 —\n  it syncs the index at startup regardless of which tool gets called.\n- `lib verify` in book mode scans the whole chapter text in pure Python; a long book can\n  take a few seconds of CPU. The MCP tool runs it in a worker thread so it doesn't block\n  the rest of the server.\n\n## Русская версия\n\nSee [README.ru.md](README.ru.md) for the Russian documentation.\n",
  "bytes": 7588,
  "sha": "e991cbbb2ad0e028c27f683dd73052cad36c852025020b06d5e7307cfac41057",
  "repo_slug": "terobyte/librarian-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_terobyte_librarian_708a121f/readme"
}