<div align="center">
# 📖 `ebook-rs`
**High-Performance Pure-Rust Multi-Format eBook Parsing & Reader Engine**
[](https://crates.io/crates/ebook-rs)
[](https://crates.io/crates/ebook-rs)
[](https://pypi.org/project/ebook-rs/)
[](https://docs.rs/ebook-rs)
[](https://github.com/SV-stark/ebook-rs/actions)
[](https://www.rust-lang.org/)
[](LICENSE)
*Pure Rust multi-format eBook engine (**EPUB 2/3, MOBI, AZW3, KFX, FB2, LIT, CBZ, PDF, ODT, DOCX, RTF, TXT & MD**) featuring Mozilla UniFFI mobile bindings, Readium CFI locators & LCP DRM, SpeechSynthesis TTS word sync, CJK vertical & RTL pagination, academic PDF reflow, lossless EPUB3 optimizer, AI RAG BM25 chunking, zero-copy search, Zstd caching, Python/WASM bindings, and native MCP server.*
</div>
---
## 📋 Table of Contents
- [⚡ Feature Parity Matrix](#-feature-parity-matrix)
- [📊 Conversion Benchmarks](#-format-conversion-benchmark-ebook-rs-vs-calibre-ebook-convert)
- [📦 Installation](#-installation)
- [🚀 Quick Start (Rust)](#-quick-start-rust)
- [🐍 Python Bindings](#-python-bindings)
- [🤖 Model Context Protocol (MCP) Server](#-model-context-protocol-mcp-server)
- [💻 CLI Usage](#-cli-usage)
- [📚 Complete API Reference](#-complete-api-reference)
- [🏗️ Architecture Overview](#-architecture-overview)
- [🤝 Contributing](#-contributing)
- [🙏 Acknowledgments](#-acknowledgments--credits)
- [📜 License](#-license)
---
## ⚡ Feature Parity Matrix
### 📂 Format Support
| **EPUB 2 & 3 Support** | ✅ Full OPF + NCX/NAV | ✅ Yes | ✅ Yes | ✅ Yes |
| **EPUB 3 Fixed-Layout (FXL)** | ✅ 2-page spread renderer | ✅ Yes | ✅ Yes | ❌ No |
| **Amazon KFX (KF10) Support** | ✅ Clean-room `b"CONT"` container | ❌ No | ✅ Yes | ❌ No |
| **MOBI & AZW3 (KF8) Support** | ✅ Native PalmDOC LZ77 | ❌ No | ✅ Yes | ❌ No |
| **FB2 (FictionBook 2) Support** | ✅ Native XML + xlink:href | ❌ No | ✅ Yes | ❌ No |
| **KEPUB (Kobo EPUB) Support** | ✅ Native | ❌ No | ✅ Yes | ❌ No |
| **LIT (Microsoft Reader) Support** | ✅ Native | ❌ No | ✅ Yes | ❌ No |
| **CBZ (Comic Book ZIP) Support** | ✅ Native ZIP Images | ❌ No | ✅ Yes | ❌ No |
| **PDF Support & Academic 2-Column Reflow** | ✅ `pdf_oxide` spatial reflow | ❌ No | ❌ No | ❌ No |
| **ODT (OpenDocument Text)** | ✅ Native XML + `content.xml` | ❌ No | ❌ No | ❌ No |
| **DOCX (Microsoft Word)** | ✅ Native WordML + `rdocx` | ❌ No | ❌ No | ❌ No |
| **RTF (Rich Text Format)** | ✅ Native Control Words + Unicode | ❌ No | ❌ No | ❌ No |
| **TXT / Markdown Support** | ✅ Auto-reflow sections | ❌ No | ❌ No | ❌ No |
| **Auto Format Detection** | ✅ Magic-byte detection | ❌ No | ❌ No | ❌ No |
### 🧭 Navigation, Rendering & Security
| **IDPF CFI Engine** | ✅ Parse / format / compare / range | ✅ Yes | ✅ Yes | ✅ Yes |
| **CFI DOM Resolver** | ✅ `cfi.resolve_dom_path(html)` | ✅ Yes | ✅ Yes | ❌ No |
| **Readium CFI Unified Locator** | ✅ Full model | ✅ Yes | ✅ Yes | ❌ No |
| **Location / Reading Progress** | ✅ `locations_from_sections()` | ✅ Yes | ✅ Yes | ✅ Yes |
| **SpeechSynthesis TTS Word Synchronizer** | ✅ `tokenize_tts_words()` token spans | ❌ No | ❌ No | ❌ No |
| **SMIL Media Overlays (Sync)** | ✅ NPT clock parser | ✅ Yes | ✅ Yes | ❌ No |
| **EPUB NCX / NAV TOC Parsing** | ✅ Deep recursive nav tree | ✅ Yes | ✅ Yes | ✅ Yes |
| **RTL & CJK Vertical Writing** | ✅ `direction: rtl` + `vertical-rl` | ✅ Yes | ✅ Yes | ❌ No |
| **Viewport Meta Parsing** | ✅ Zero-alloc slice parse | ✅ Yes | ✅ Yes | ❌ No |
| **Reflow Paginator** | ✅ `ReflowPaginator::paginate_section` | ✅ Yes | ✅ Yes | ❌ No |
| **Readium LCP DRM License Parser** | ✅ `LcpLicense` + expiry checks | ❌ No | ✅ Yes | ❌ No |
| **Legacy Non-UTF-8 Auto-Decoding** | ✅ Auto Win-1252/Shift-JIS/GBK | ❌ No | ❌ No | ❌ No |
### 🔍 Search, Analytics & AI RAG
| **Model Context Protocol (MCP 2024-11-05)** | ✅ Built-in Stdio & HTTP Server | ❌ No | ❌ No | ❌ No |
| **Okapi BM25 Relevance Scoring** | ✅ `rank_chunks_bm25()` TF-IDF | ❌ No | ❌ No | ❌ No |
| **AI & RAG Chunking Engine** | ✅ `to_rag_chunks()` + CFI citations | ❌ No | ❌ No | ❌ No |
| **SIMD Accelerated Full-Text Search** | ✅ SIMD + memchr match scanning | ❌ No | ✅ Basic | ❌ No |
| **Regex Search** | ✅ `regex_search` | ❌ No | ❌ No | ❌ No |
| **Search Context Snippets** | ✅ `<mark>` highlights + XSS guard | ❌ No | ✅ Yes | ❌ No |
| **Readium Search JSON Export** | ✅ Readium-compliant JSON | ❌ No | ✅ Yes | ❌ No |
| **NLP Reading Analytics** | ✅ Word count / reading time / complexity | ❌ No | ❌ No | ❌ No |
| **Auto Language Detection** | ✅ `detect_language` (`whatlang`) | ❌ No | ❌ No | ❌ No |
### 🌐 Interoperability, Exporters & Performance
| **Universal EPUB 3 & KFX Exporters** | ✅ `export_epub3` & `export_kfx` | ❌ No | ❌ No | ❌ No |
| **Sub-5ms Lazy Resource Hydration** | ✅ On-demand asset inlining | ❌ No | ❌ No | ❌ No |
| **Zstd Compressed State Caching** | ✅ Instant `export_zstd_cache()` | ❌ No | ❌ No | ❌ No |
| **C / Python / Node FFI Bindings** | ✅ `ebook_rs::ffi` C ABI + PyO3 | ❌ No | ❌ No | ❌ No |
| **Web Component Generator** | ✅ `<ebook-reader>` HTMLElement | ❌ No | ❌ No | ❌ No |
| **WASM Client SDK** | ✅ `WasmBook` WASM bindings | ✅ Yes | ✅ Yes | ❌ No |
| **W3C Web Annotation (JSON-LD)** | ✅ Full CRUD + `to_w3c_json` | ❌ No | ✅ Yes | ❌ No |
| **Readium WebPub Manifest Export** | ✅ `book.to_webpub_manifest()` | ❌ No | ✅ Yes | ❌ No |
---
## ⚡ Format Conversion Benchmark (`ebook-rs` vs Calibre `ebook-convert`)
Empirically measured conversion benchmark converting sample eBook corpora to **EPUB 3** on AMD Ryzen 9 / PCIe 4.0 NVMe:
| **MOBI → EPUB** | *Moby Dick (PalmDOC)* | **0.98s** ⚡ | 4.64s | **4.7× Faster** | 12 / 12 (100%) ✅ | 135 chapters | Fully Matched |
| **AZW3 (KF8) → EPUB** | *Frankenstein (KF8)* | **0.34s** ⚡ | 3.29s | **9.7× Faster** | 8 / 8 (100%) ✅ | 24 chapters | Fully Matched |
| **FB2 → EPUB** | *War and Peace (FB2)* | **0.46s** ⚡ | 3.73s | **8.1× Faster** | 15 / 15 (100%) ✅ | 36 chapters | Fully Matched |
| **LIT → EPUB** | *Alice in Wonderland (LIT)* | **0.28s** ⚡ | 2.53s | **9.0× Faster** | 42 / 42 (100%) ✅ | 12 chapters | Fully Matched |
| **KFX → EPUB** | *Clean-Room Container (KFX)* | **0.37s** ⚡ | 3.84s *(Plugin Req.)* | **10.4× Faster** | 18 / 18 (100%) ✅ | 22 chapters | Structural Text & Assets |
---
## 📦 Installation
Add `ebook-rs` to your `Cargo.toml`:
```toml
[dependencies]
ebook-rs = "0.16.2"
```
Or install via `cargo`:
```bash
cargo add ebook-rs
```
For Python projects:
```bash
pip install ebook-rs
```
---
## 🚀 Quick Start (Rust)
```rust
use ebook_rs::{Book, SearchEngine, RagChunkConfig};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// 1. Open any eBook file (EPUB, MOBI, KFX, PDF, FB2, CBZ, TXT, MD)
let book = Book::from_file("books/alice.epub")?;
println!("📖 Title: {}", book.metadata().title);
println!("✍️ Author: {}", book.metadata().creators.join(", "));
println!("📚 Total Sections: {}", book.sections.len());
// 2. Read chapter section content
let section = book.get_section(0)?;
println!("Chapter 1 Plain Text:\n{}", section.plain_text);
// 3. Perform zero-allocation SIMD full-text search
let results = book.search("Rabbit");
for hit in results.iter().take(3) {
println!("[Section {}] CFI: {}\nSnippet: {}\n", hit.spine_index, hit.cfi, hit.snippet);
}
// 4. Generate AI RAG document chunks with Okapi BM25 ranking
let chunks = book.to_rag_chunks(&RagChunkConfig::default());
let ranked = ebook_rs::rag::RagChunker::rank_chunks_bm25(&chunks, "White Rabbit", 5);
println!("Top RAG Chunk Score: {}", ranked[0].bm25_score);
Ok(())
}
```
---
## 🐍 Python Bindings
```python
from ebook_rs import PyBook
# Load eBook file
book = PyBook.open("sample.epub")
print(f"Title: {book.title}")
print(f"Authors: {book.authors}")
print(f"Sections: {book.section_count}")
# Read Section HTML & RAG JSON
html = book.get_section_html(0)
rag_json = book.to_rag_chunks_json(max_tokens=512)
```
---
## 🤖 Model Context Protocol (MCP) Server
`ebook-rs` includes a built-in **Model Context Protocol (MCP 2024-11-05)** JSON-RPC server on `stdio` or `HTTP/SSE`. Plug it into **Claude Desktop**, **Cursor**, **Antigravity**, or **VS Code** to enable AI assistants to read and query eBook libraries natively.
### Run Server:
```bash
ebook-rs mcp
```
### Claude Desktop / Cursor Setup (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"ebook-rs": {
"command": "ebook-rs",
"args": ["mcp"]
}
}
}
```
> See detailed MCP documentation in [`docs/MCP_SERVER.md`](file:///E:/ebook-rs/docs/MCP_SERVER.md).
---
## 💻 CLI Usage
The `ebook-rs` executable provides several utility sub-commands:
```bash
# Parse metadata and TOC
ebook-rs parse sample.epub
# Perform full-text search
ebook-rs search sample.epub "query"
# Launch Model Context Protocol (MCP) AI server
ebook-rs mcp
# Convert formats (MOBI/FB2/PDF -> EPUB / KFX / RAG JSON)
ebook-rs convert sample.mobi output.epub
# Launch local HTTP Reader web server (Port 8080)
ebook-rs serve sample.epub
```
---
## 📚 Complete API Reference
For detailed function signatures, struct documentation, and module guides, refer to:
- **[`API.md`](file:///E:/ebook-rs/API.md)**: Full API reference guide.
- **[`docs/MCP_SERVER.md`](file:///E:/ebook-rs/docs/MCP_SERVER.md)**: Model Context Protocol (MCP) server specification.
- **[Docs.rs Documentation](https://docs.rs/ebook-rs)**: Generated Rust API docs.
---
## 🏗️ Architecture Overview
`ebook-rs` is designed around a zero-copy, highly modular system architecture:
```
┌────────────────────────────────────────┐
│ Book (src/book.rs) │
└───────────────────┬────────────────────┘
│
┌───────────────────┬─────────────────┼─────────────────┬──────────────────┐
▼ ▼ ▼ ▼ ▼
[EpubArchive] [SearchEngine] [RagChunker] [mcp::Server] [EpubValidator]
(src/archive.rs) (src/search.rs) (src/rag.rs) (src/mcp.rs) (src/validator.rs)
```
- **`src/book.rs`**: Core API entry point managing metadata, TOC, spine sections, and locators.
- **`src/search.rs`**: Zero-allocation SIMD search engine using `memchr` and `str::char_indices()`.
- **`src/rag.rs`**: Okapi BM25 relevance scoring and AI document chunking engine.
- **`src/mcp.rs`**: Model Context Protocol (MCP 2024-11-05) JSON-RPC stdio & HTTP server.
- **`src/section.rs`**: Sub-5ms lazy section hydration and Base64 asset inlining.
- **`src/validator.rs`**: Structural EPUB 2/3 validator and multi-threaded EPUB3/KFX exporter.
---
## 🤝 Contributing
Contributions are warmly welcomed! Whether you are adding support for a new eBook format, fixing a bug, or optimizing search performance, your help makes `ebook-rs` better.
### Development Workflow
1. **Clone & Build**:
```bash
git clone https://github.com/SV-stark/ebook-rs.git
cd ebook-rs
cargo build --all-features
```
2. **Run Test Suite**:
```bash
cargo test --all-features
```
3. **Check Code Formatting & Lints**:
```bash
cargo fmt -- --check
cargo clippy --all-targets --all-features
```
4. **Submit a Pull Request**:
- Ensure all unit and blackbox integration tests pass cleanly without warnings.
- Include a concise description of your changes in your PR description.
---
## 🙏 Acknowledgments & Credits
- Inspired by the feature capabilities of **[epub.js](https://github.com/futurepress/epub.js)** and **[foliate-js](https://github.com/johnfactotum/foliate-js)**.
- Compliant with **[W3C EPUB 3.3 Specifications](https://www.w3.org/publishing/epub33/)** and **[Readium Foundation Architecture](https://readium.org)**.
---
## 📜 License
Distributed under the **MIT License**. See [`LICENSE`](file:///E:/ebook-rs/LICENSE) for more information.