# unnipv/overleaf-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/unnipv/overleaf-mcp
- Repository: https://github.com/unnipv/overleaf-mcp

## Overview

##### Project type and purpose
- This is a Python-based MCP (Model Context Protocol) server for LaTeX document editing and Overleaf integration.
- It exposes a CLI entrypoint and a long-running server that AI assistants (e.g., Claude Desktop) connect to over MCP.
- Its core responsibilities are: parsing/generating LaTeX templates, invoking a LaTeX compiler and Pandoc for outputs, and handling Overleaf download/upload.

##### File structure
- Top level:
- cli.py: CLI bootstrap (“overleaf-mcp run”)
- server.py: MCP server implementation and request router
- latex/: subpackage with modules compiler, converter, generator, parser, template
- tools/: higher-level operations (document_tools, element_tools, format_tools, overleaf_tools)
- utils/: shared helpers (file I/O, LaTeX string utilities)
- examples/, tests/: demonstration and validation code
- Configuration: requirements.txt, pyproject.toml, pytest.ini
- Deployment scripts: activate_env.sh, run_latex_demo.sh

##### Extract insights from the README
- Key external dependencies: LaTeX compiler (e.g. TeX Live), Pandoc, Overleaf API
- Feature set: document creation, compilation, error-fixing, Overleaf sync
- Usage flow: start server → AI client sends commands → server uses tools → returns LaTeX/HTML/PDF

a. Main components
1. MCP Client (Claude Desktop or any MCP-compatible client)
2. overleaf-mcp CLI → starts MCP Server
3. MCP Server (overleaf_mcp/server.py)
4. LaTeX Engine (external process: pdflatex/xelatex)
5. Pandoc (external process for HTML conversion)
6. Overleaf Integration (overleaf_tools → external Overleaf API)
7. File System / Temp Storage
8. Internal Modules:
– Parser, Generator, Template (latex/parser.py, latex/generator.py, latex/template.py)
– Converter, Compiler (latex/converter.py, latex/compiler.py)
– Document & Element Tools (tools/document_tools.py, tools/element_tools.py)
– Utilities (utils/file_utils.py, utils/latex_utils.py)
b. Relationships & data flow
- Client → (MCP protocol) → Server request handler
- Server routes request → corresponding tool module
- Tool may:
– build or parse a LaTeX AST (parser, generator)
– write files to disk (file_utils)
– invoke external LaTeX compiler → PDF
– invoke Pandoc → HTML
– fetch/upload project ZIP via Overleaf API
- Server bundles outputs → responds over MCP to the client
c. Architectural patterns & principles
– Modular separation: CLI vs. Server vs. Tool modules
– Single responsibility: each latex/*.py and tools/*.py handles one domain
– Layering: server layer → domain tool layer → external process layer → storage
d. Key technologies & libraries
– Python 3.10+, click (CLI), asyncio or socket library (MCP)
– External: TeX Live / MiKTeX, Pandoc, Overleaf REST API
– Packaging: pyproject.toml, pip, virtualenv

##### Diagramming recommendations
- Components:
- Data flow:
– Client → Server
– Server → Parser/Generator/Converter/Compiler/Overleaf Tools
– Compiler → LaTeX Engine → PDF
– Converter → Pandoc → HTML
– Overleaf Tools ↔ Overleaf API
– All modules → File System
- Styling:
– Internal Python components (e.g. pastel blue)
– External processes/services (e.g. gray)
– Storage (e.g. green)
– Rectangles for compute modules
– Clouds for external services (Overleaf, LaTeX engine, Pandoc)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client and CLI
    Client["MCP Client"]:::external
    CLI["CLI Entrypoint\n(overleaf-mcp run)"]:::internal
    click CLI "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/cli.py"
    Client -->|"MCP Protocol"| Server

    %% Server
    Server["MCP Server\n(server.py)"]:::internal
    click Server "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/server.py"
    CLI -->|"starts"| Server

    %% Internal Modules
    subgraph "Internal Modules"
        direction TB
        Parser["Parser\n(parser.py)"]:::internal
        click Parser "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/latex/parser.py"
        Generator["Generator\n(generator.py)"]:::internal
        click Generator "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/latex/generator.py"
        Template["Template\n(template.py)"]:::internal
        click Template "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/latex/template.py"
        Converter["Converter\n(converter.py)"]:::internal
        click Converter "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/latex/converter.py"
        Compiler["Compiler\n(compiler.py)"]:::internal
        click Compiler "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/latex/compiler.py"
        DocumentTools["Document Tools\n(document_tools.py)"]:::internal
        click DocumentTools "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/tools/document_tools.py"
        ElementTools["Element Tools\n(element_tools.py)"]:::internal
        click ElementTools "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/tools/element_tools.py"
        FormatTools["Format Tools\n(format_tools.py)"]:::internal
        click FormatTools "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/tools/format_tools.py"
        OverleafTools["Overleaf Tools\n(overleaf_tools.py)"]:::internal
        click OverleafTools "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/tools/overleaf_tools.py"
        FileIO["File I/O Utils\n(file_utils.py)"]:::internal
        click FileIO "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/utils/file_utils.py"
        LatexUtils["LaTeX Utils\n(latex_utils.py)"]:::internal
        click LatexUtils "https://github.com/unnipv/overleaf-mcp/blob/main/overleaf_mcp/utils/latex_utils.py"
    end

    %% External Processes and Services
    LaTeXEngine[[LaTeX Engine]]:::external
    Pandoc[[Pandoc]]:::external
    OverleafAPI(("Overleaf API")):::external

    %% Storage
    FileSystem[(File System / Temp Storage)]:::storage

    %% Example and Demo
    ExampleUsage["Example Client\n(examples/client_usage_example.py)"]:::external
    click ExampleUsage "https://github.com/unnipv/overleaf-mcp/blob/main/examples/client_usage_example.py"
    DemoScript["Demo Script\n(run_latex_demo.sh)"]:::external
    click DemoScript "https://github.com/unnipv/overleaf-mcp/blob/main/run_latex_demo.sh"

    %% Connections: Server to modules
    Server --> Parser
    Server --> Generator
    Server --> Template
    Server --> Converter
    Server --> Compiler
    Server --> DocumentTools
    Server --> ElementTools
    Server --> FormatTools
    Server --> OverleafTools
    Server --> FileIO
    Server --> LatexUtils

    %% Modules to external or storage
    Parser --> FileSystem
    Generator --> FileSystem
    Template --> FileSystem
    DocumentTools --> FileSystem
    ElementTools --> FileSystem
    FormatTools --> FileSystem
    Converter --> Pandoc
    Converter --> FileSystem
    Compiler --> LaTeXEngine
    Compiler --> FileSystem
    OverleafTools --> OverleafAPI
    OverleafTools --> FileSystem
    FileIO --> FileSystem
    LatexUtils --> FileSystem

    %% Response flow
    FileSystem -->|"bundles outputs"| Server
    Server -->|"MCP Response"| Client

    %% Example flows
    ExampleUsage --> Client
    DemoScript --> FileSystem

    %% Styles
    classDef internal fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef storage fill:#d4edda,stroke:#333,stroke-width:1px
```
