calibremcp

# calibre-mcp — llms-full.txt

**Fleet manifest pair:** index → `llms.txt` · full corpus → this file.
**Packaging / MCPB:** [mcp-central-docs — MCPB_PACKAGING_STANDARDS.md](https://github.com/sandraschi/mcp-central-docs/blob/master/standards/MCPB_PACKAGING_STANDARDS.md) · [PACKAGING_STANDARDS.md §5](https://github.com/sandraschi/mcp-central-docs/blob/master/standards/PACKAGING_STANDARDS.md#5-python-mcp-repo-uv-justfile-llmstxt-glama-mcpb-pack)

---

## Tools (representative)

Portmanteau-first server (FastMCP 3.1+). Names match MCP registration:

- **manage_libraries** — libraries list/switch, stats, connection
- **query_books** — search/list with filters, optional auto_open
- **manage_books** — book CRUD / bulk
- **search_fulltext** — Calibre FTS; optional `resolve_locations` (PDF/EPUB/viewer hints)
- **calibre_metadata_index_build** / **calibre_metadata_search** / **calibre_metadata_export_json** — LanceDB metadata RAG + JSON export
- **rag_index_build** / **rag_retrieve** — chunk RAG from FTS text
- **calibre_rag** — portmanteau neural / full-text RAG
- **manage_analysis** — duplicates, health, stats
- **manage_files** / **export_books** / **manage_library_operations**
- **manage_import** — from local path, download from URL, Anna's Archive (search/MD5 download), Project Gutenberg (search/ID import), arXiv (search/ID import)
- **manage_system** / **manage_viewer**
- **help_tool** — bundled help
- **calibre_ocr** — optional OCR backends
- **show_book_prefab_card** / **show_libraries_prefab_card** — optional MCP Apps (install **`uv sync --extra apps`**); rich **book** card and **Our Calibre** (all libraries + basic stats); **`CALIBRE_PREFAB_APPS=0`** disables

**Prompts:** `@mcp.prompt()` templates in `src/calibre_mcp/prompts.py` — see `docs/PROMPTS.md`.
**Skill:** `skill://calibre-expert/SKILL.md` (bundled under `src/calibre_mcp/skills/`).

---

## Environment

| Variable | Role |
|----------|------|
| `CALIBRE_LIBRARY_PATH` | Primary library folder (`metadata.db`) |
| `CALIBRE_METADATA_COMMENT_MAX_CHARS` | Metadata RAG: max chars per book **Comments** field in embedding text (default **20480** = 20 KiB; max 16 MiB) |
| `CALIBRE_METADATA_STRIP_HTML` | Metadata RAG: `1` (default) strip HTML in comments; `0`/`false` keep raw |
| `CALIBRE_RAG_CHUNK_EXCLUDE_FORMATS` | **Chunk RAG only** (`rag_index_build`): comma-separated formats to skip. **Unset → excludes PDF**. Metadata RAG is unaffected (same for PDF/EPUB). Set **empty** to index PDFs in chunk RAG |
| `CALIBRE_RAG_MAX_BOOK_TEXT_CHARS` | Chunk RAG: skip `books_text` rows longer than this (optional; huge textbooks) |
| `CALIBRE_BETA_TOOLS` | Set `true` to load extra/beta tool modules |
| `CALIBRE_PREFAB_APPS` | Set **`0`** / **`false`** to skip Prefab tool registration (**`show_book_prefab_card`**, **`show_libraries_prefab_card`**) when **`prefab-ui`** is installed |
| `CALIBRE_ANNAS_MIRRORS` | Comma-separated list of Anna's Archive mirrors |
| `CALIBRE_GUTENBERG_MIRROR` | Base URL for Project Gutenberg (default `https://www.gutenberg.org`) |
| `LLM_PROVIDER` / `LLM_BASE_URL` / `LLM_API_KEY` | HTTP chat proxy when using `--http` |

See root `README.md` and `docs/AGENTIC_AND_RAG.md` for RAG/FTS env and LanceDB paths.

---

## Run

- **stdio MCP:** `uv run python -m calibre_mcp` (or `calibre-mcp` console script)
- **HTTP:** `uv run python -m calibre_mcp` with transport flags per `README.md`
- **Webapp:** `webapp/start.ps1` — backend **10720**, frontend **10721** (fleet adjacent ports)

---

## Architecture

- **FastMCP** app in `src/calibre_mcp/server.py` · tools under `src/calibre_mcp/tools/`
- **RAG:** `src/calibre_mcp/rag/` — LanceDB / fastembed; library-scoped indexes beside `metadata.db`
- **MCPB bundle:** `mcpb/` pack root — `mcpb pack . ../dist/calibre-mcp.mcpb` after syncing `src/calibre_mcp` into `mcpb/src/` (see `scripts/build-mcpb-package.ps1`)

---

## Troubleshooting

1. **Missing library path** — set `CALIBRE_LIBRARY_PATH` or user_config in Claude Desktop after MCPB install.
2. **Dependencies** — MCPB ships **source only** per fleet standard; run `uv sync` from a **git clone** or install the PyPI wheel; do not expect deps inside `.mcpb`.
3. **FTS / RAG** — build indexes first (`calibre_metadata_index_build`, `rag_index_build`) — see `docs/COOKBOOK.md`.
4. **MCPB validate fails** — run `npm install -g @anthropic-ai/mcpb` and `mcpb validate mcpb/manifest.json`.

---

*Last updated: 2026-07-05 — SOTA compliance sweep: health diagnostics, webapp backend merge, CORS, NSIS, chat rewrite. Added `/api/v1/diagnostics`, `/api/health` endpoints.*