How unnipv/overleaf-mcp works
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)