📋 Table of Contents

• ⚡ Feature Parity Matrix
• 📊 Conversion Benchmarks
• 📦 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:

📦 Installation

Add ebook-rs to your Cargo.toml:

[dependencies]
ebook-rs = "0.16.4"

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

ebook-rs mcp

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)
ebook-rs serve sample.epub

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

   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.