📋 Table of Contents

• ⚡ Feature Parity Matrix
• 📊 Conversion Benchmarks
• 🛡️ Battle-Tested Resilience & Continuous Fuzzing
• 📦 Installation
• 🚀 Quick Start (Rust)
• 🐍 Python Bindings
• 🤖 Model Context Protocol (MCP) Server
• 💻 CLI Usage
• 📚 Complete API Reference
• 🏗️ Architecture Overview
• 🤝 Contributing
• 🙏 Acknowledgments
• 📜 License

⚡ Feature Parity Matrix

📂 Format Support

🧭 Navigation, Rendering & Security

🔍 Search, Analytics & AI RAG

🌐 Interoperability, Exporters & Performance

⚡ 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:

🛡️ Battle-Tested Resilience & Continuous Fuzzing

ebook-rs is built to be the most resilient eBook engine in existence, specifically engineered to withstand the dirty long tail of corrupted, malformed, and non-spec files found across Project Gutenberg, Archive.org, and legacy digital archives:

• Graceful Error Handling: Every format boundary validates lengths and magic bytes and returns Result<Book, EbookError> instead of panicking. This is enforced by CI (cargo test) and a scheduled fuzz/chaos workflow, and regression-tested in tests/test_security_regressions.rs. See SECURITY.md for the threat model and the known residual risks (notably slow-loris, which tiny_http cannot fully mitigate).
• Continuous Coverage-Guided Fuzzing: Continuous LLVM libFuzzer (cargo-fuzz) runs mutate raw byte streams over millions of iterations against Book::from_bytes and CFI locators.
• Mass Corpus Stress Testing: A dedicated chaos-testing runner (examples/corpus_stress.rs) evaluates real-world books across all 14 supported formats, injecting byte truncations (10% to 90%), zeroed headers, and bit-flipped noise.

📊 Real-World Resilience Scorecard

These figures are snapshots from the runs described above, not a standing guarantee — they are regression-tested in tests/test_security_regressions.rs and re-measured by the scheduled fuzz/chaos workflow.

Run the Automated Gutenberg Stress Test:

# 1. Automatically fetch 25 Project Gutenberg classics:
./scripts/fetch_gutenberg.sh 25 corpus/gutenberg      # Linux / macOS
pwsh scripts/fetch_gutenberg.ps1 -Count 25           # Windows

# 2. Run parallel resilience & chaos stress test:
cargo run --release --all-features --example corpus_stress -- corpus/gutenberg

# Or stress-test any local library directory:
cargo run --release --all-features --example corpus_stress -- /path/to/your/ebooks

📦 Installation

Add ebook-rs to your Cargo.toml:

[dependencies]
ebook-rs = "0.17.3"

Or install via cargo:

cargo add ebook-rs

For Python projects:

pip install ebook-rs

🚀 Quick Start (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

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 2.0 server, available over stdio or as an HTTP POST endpoint (/api/mcp) on the reader server. Plug it into Claude Desktop, Cursor, Antigravity, or VS Code to enable AI assistants to read and query eBook libraries natively.

Run Server:

ebook-rs mcp

The stdio server is sandboxed to the current working directory by default. To grant access to a specific library, pass --sandbox-root <dir>:

ebook-rs mcp --sandbox-root /path/to/ebooks

Security: MCP tools that read or write files (get_metadata, read_section, convert_ebook, ...) are refused unless a sandbox root is configured, and convert_ebook can only write inside it. See SECURITY.md.

Claude Desktop / Cursor Setup (claude_desktop_config.json):

{
  "mcpServers": {
    "ebook-rs": {
      "command": "ebook-rs",
      "args": ["mcp"]
    }
  }
}

See detailed MCP documentation in docs/MCP_SERVER.md.

💻 CLI Usage

The ebook-rs executable provides several utility sub-commands:

# 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 via $PORT, default 8080)
ebook-rs serve sample.epub

# Protect the HTTP API with a bearer token (required for anything beyond localhost)
ebook-rs serve sample.epub --auth-token "$EBOOK_RS_AUTH_TOKEN"

# Confine MCP filesystem tools to a directory (defaults to the working directory)
ebook-rs serve sample.epub --sandbox-root /path/to/ebooks

Both flags also read from the environment: EBOOK_RS_AUTH_TOKEN and EBOOK_RS_SANDBOX_ROOT. ebook-rs serve binds to 127.0.0.1 only and prints a warning if no auth token is set.

📚 Complete API Reference

For detailed function signatures, struct documentation, and module guides, refer to:

• API.md: Full API reference guide.
• docs/MCP_SERVER.md: Model Context Protocol (MCP) server specification.
• Docs.rs Documentation: 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: Lazy on-demand 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:

   git clone https://github.com/SV-stark/ebook-rs.git
   cd ebook-rs
   cargo build --all-features
   

2. Run Test Suite:

   cargo test --all-features
   

3. Check Code Formatting & Lints:

   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 and foliate-js.
• Compliant with W3C EPUB 3.3 Specifications and Readium Foundation Architecture.

📜 License

Distributed under the MIT License. See LICENSE for more information.