# onebirdrocks/ebook-mcp architecture

> Architecture diagram of the GitHub repository onebirdrocks/ebook-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/onebirdrocks/ebook-mcp
- Repository: https://github.com/onebirdrocks/ebook-mcp

## Overview

##### Project type and purpose
- Ebook-MCP is an open-source Model Context Protocol (MCP) server written in Python.
- It exposes standardized APIs allowing LLM-powered clients (e.g., Cursor, Claude, custom scripts) to process and interact with EPUB/PDF e-books.

##### File structure
- Top-level:
- .github/workflows/cli.yml – CI for tests or release
- pyproject.toml / requirements.txt – build & dependencies
- README.md – project overview & architecture sketch
- src/ebook_mcp/
- main.py – entrypoint launching the FastMCP server
- mcp-client-example/ – sample clients demonstrating calls to the running MCP server (Anthropic, DeepSeek, OpenAI)
- tools/ – core modules for EPUB/PDF processing (epub_helper.py, pdf_helper.py), plus logger setup
- tests/ – unit tests for file format support (e.g., test_azw.py, test_epub_helper.py)

##### README for additional insights
- It defines three logical layers:
- Agent Layer – strategy, LLM calls, conversation orchestration
- MCP Tool Layer – individual “tool” handlers such as extract_chapter, get_metadata
- System Base Layer – low-level file I/O, parsing via ebooklib/PyPDF2/PyMuPDF, HTML→Markdown conversion

##### Diagramming best-practices
Client → Server.Agent → Server.Tools → System.IO/Parsing → back up
- Clients & external services (e.g., green)
- Server layers (e.g., blue for Agent, yellow for Tool, gray for System)
- File system / persistent store (e.g., brown)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients & IDE Plugins" 
        anthropic_example["Anthropic Example"]:::clients
        deepseek_example["DeepSeek Example"]:::clients
        openai_example["OpenAI Example"]:::clients
        cli_clients["CLI / IDE Plugins / Scripts"]:::clients
    end

    %% External LLM Services
    subgraph "External LLM Services"
        AnthropicAPI["Anthropic API"]:::ext
        DeepSeekAPI["DeepSeek API"]:::ext
        OpenAIAPI["OpenAI API"]:::ext
    end

    %% MCP Server Layered Architecture
    subgraph "MCP Server (FastMCP / Uvicorn)"
        Main["main.py\n(Entrypoint & Agent Layer)"]:::agent
        subgraph "MCP Tool Layer"
            EPUB["epub_helper.py"]:::tool
            PDF["pdf_helper.py"]:::tool
        end
        subgraph "System Base Layer"
            Logger["logger_config.py"]:::system
            Parsing["Parsing Libraries\n(ebooklib, PyPDF2, PyMuPDF,\nBeautifulSoup, html2text)"]:::system
            FS["Filesystem\n(EPUB/PDF Store)"]:::storage
        end
    end

    %% Project Configurations
    subgraph "Project Configs"
        README["README.md"]:::system
        CI[".github/workflows/cli.yml"]:::system
        Metadata["pyproject.toml\nrequirements.txt"]:::system
    end

    %% Data Flows
    anthropic_example -->|"MCP RPC/REST"| Main
    deepseek_example -->|"MCP RPC/REST"| Main
    openai_example -->|"MCP RPC/REST"| Main
    cli_clients -->|"MCP RPC/REST"| Main

    Main -->|"dispatch to tool"| EPUB
    Main -->|"dispatch to tool"| PDF

    EPUB -->|"read files"| FS
    PDF -->|"read files"| FS

    EPUB -->|"use parsing libs"| Parsing
    PDF -->|"use parsing libs"| Parsing

    Main -->|"calls"| AnthropicAPI
    Main -->|"calls"| DeepSeekAPI
    Main -->|"calls"| OpenAIAPI

    %% Click Events
    click Main "https://github.com/onebirdrocks/ebook-mcp/blob/main/src/ebook_mcp/main.py"
    click EPUB "https://github.com/onebirdrocks/ebook-mcp/blob/main/src/ebook_mcp/tools/epub_helper.py"
    click PDF "https://github.com/onebirdrocks/ebook-mcp/blob/main/src/ebook_mcp/tools/pdf_helper.py"
    click Logger "https://github.com/onebirdrocks/ebook-mcp/blob/main/src/ebook_mcp/tools/logger_config.py"
    click anthropic_example "https://github.com/onebirdrocks/ebook-mcp/blob/main/src/ebook_mcp/mcp-client-example/anthropic_example.py"
    click deepseek_example "https://github.com/onebirdrocks/ebook-mcp/blob/main/src/ebook_mcp/mcp-client-example/deepseek_example.py"
    click openai_example "https://github.com/onebirdrocks/ebook-mcp/blob/main/src/ebook_mcp/mcp-client-example/openai_example_with_history.py"
    click CI "https://github.com/onebirdrocks/ebook-mcp/blob/main/.github/workflows/cli.yml"
    click Metadata "https://github.com/onebirdrocks/ebook-mcp/blob/main/pyproject.toml"
    click Metadata "https://github.com/onebirdrocks/ebook-mcp/blob/main/requirements.txt"
    click README "https://github.com/onebirdrocks/ebook-mcp/blob/main/README.md"
    click testAZW "https://github.com/onebirdrocks/ebook-mcp/blob/main/src/ebook_mcp/tests/test_azw.py"
    click testEPUB "https://github.com/onebirdrocks/ebook-mcp/blob/main/src/ebook_mcp/tools/test_epub_helper.py"

    %% Styles
    classDef clients fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef ext fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef agent fill:#add8e6,stroke:#333,stroke-width:1px
    classDef tool fill:#ffff99,stroke:#333,stroke-width:1px
    classDef system fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef storage fill:#d2b48c,stroke:#333,stroke-width:1px
    class testAZW,testEPUB system
    class CI,Metadata,README system
```
