# Overleaf Resume

Edit and compile your resume(s) locally instead of on the Overleaf website,
with an MCP server that syncs source files with Overleaf when needed. Works
with any number of Overleaf projects side by side — every sync tool takes an
explicit `project_id`, so nothing is pinned to a single "the" project.

Built for **free-plan Overleaf accounts** (no Git/API access). If your
account has Git integration (paid plan), just `git clone` your project
instead — you don't need this.

## How it works

- **Day-to-day editing:** once a project is pulled (see below), edit its
  `.tex` file directly under `projects/<name>/`, then compile locally with
  [Tectonic](https://tectonic-typesetting.github.io/) — no Overleaf round
  trip needed:

  ```
  tools/tectonic.exe projects/<name>/<main file>.tex
  ```

  This produces a PDF right next to it. (`tools/tectonic.exe` is a
  standalone binary already set up in this repo — gitignored since it's a
  large downloaded binary, not source.)

- **Syncing with Overleaf:** since this is a free-plan Overleaf account
  (no Git/API access), an MCP server (`overleaf_mcp/`) drives a real,
  logged-in Chromium session with Playwright to download a project's
  source and push edits back into its online editor — the same actions
  you'd take by hand in the browser.

## Project layout

Each Overleaf project you pull lands in its own subfolder, so multiple
resumes can coexist without collisions:

```
projects/
  <your-project-name>/
    resume.tex (or whatever the project's main file is named)
    ...other pulled files (.cls, .sty, images)
    .backups/            # timestamped backups made before each re-pull
  <another-project-name>/
    ...
```

`projects/` is gitignored — it holds your actual resume content (pulled
from Overleaf), so it stays local and never gets committed.

## One-time setup

Steps 1-2 are already done in this repo (`.venv/` has the dependencies
installed and Playwright's Chromium browser downloaded; `tools/tectonic.exe`
is ready to use). They're listed here in case you need to redo them on
another machine or after a clean checkout.

1. Create a virtual environment and install dependencies:

   ```
   python -m venv .venv
   .venv\Scripts\activate
   pip install -r requirements.txt
   playwright install chromium
   ```

2. Get Tectonic: `winget`/`choco` may need admin rights that aren't always
   available. The reliable no-admin option is to download the Windows
   binary directly and drop it in `tools/`:

   ```
   gh release download tectonic@0.17.0 --repo tectonic-typesetting/tectonic \
     --pattern "tectonic-0.17.0-x86_64-pc-windows-msvc.zip" --dir tools
   # then unzip it so tools/tectonic.exe exists
   ```

   Verify with `tools/tectonic.exe --version`.

3. Log in to Overleaf once so the MCP server can reuse the session:

   ```
   .venv/Scripts/python.exe scripts/overleaf_login.py
   ```

   A browser window opens to Overleaf's login page. **Log in with email +
   password**, not "Sign in with Google" — Google blocks its sign-in form
   inside any automated browser, so Google-only accounts need a password
   set on Overleaf first (Account Settings). The session is then saved to
   `.auth/storage_state.json` (gitignored — never commit or share it).
   Re-run this script whenever `overleaf_login_status` reports the session
   has expired.

4. This repo's `.mcp.json` registers the server with Claude Code
   automatically. Restart Claude Code (or run `/mcp`) so it picks up the
   `overleaf-resume` server.

5. Call `overleaf_list_projects` to see all your Overleaf projects and
   their ids, then `overleaf_pull(project_id)` for whichever one(s) you
   want to work on. Files land under `projects/<name>/`.

## MCP tools

- `overleaf_login_status` — check whether the saved session is still valid.
- `overleaf_list_projects` — list every Overleaf project (name + id).
- `overleaf_pull(project_id, local_dir?)` — download that project's
  source into `projects/<name>/` (or `local_dir` if given), backing up
  any existing `.tex`/`.cls`/`.sty`/`.bib` files there under `.backups/`
  first.
- `overleaf_push(project_id, file_path)` — push a local file's current
  content back into that Overleaf project's online editor. `file_path` is
  relative to this repo root, e.g. `projects/<your-project-name>/resume.tex`.

`project_id` is always required — there's no single default project, so
this works the same whether you have one resume or several. Use
`overleaf_list_projects` whenever you need to look one up.

## Troubleshooting local compiles

Overleaf compiles with pdfLaTeX by default; Tectonic uses a XeTeX-based
engine. Two issues this surfaced on the popular ["Jake's Resume"](https://github.com/sb2nov/resume)-style
templates, in case you hit them too:

- `\pdfglyphtounicode` / `\input{glyphtounicode}` / `\pdfgentounicode=1` are
  pdfTeX-only primitives. Guard them so both engines work:
  ```latex
  \usepackage{iftex}
  \ifPDFTeX
    \input{glyphtounicode}
  \fi
  ...
  \ifPDFTeX
    \pdfgentounicode=1
  \fi
  ```
- `enumitem`'s `\begin{itemize}...\end{itemize}` pairs (via this
  template's `\resumeSubHeadingListStart`/`End` macros) must stay
  balanced even across commented-out sections — a stray, unmatched
  `\end{itemize}` left behind after commenting out a block produces a
  cryptic `Undefined control sequence` deep inside `enumitem` internals
  (`\enit@enditemize`). This isn't a Tectonic/Overleaf difference — it'll
  fail on Overleaf's own compiler too if you look at the error count.

## Caveats

- This automates Overleaf's actual web UI with your own logged-in
  session — there's no public API for free-plan projects. It can break
  if Overleaf changes its UI, and the saved session will occasionally
  expire (re-run `scripts/overleaf_login.py`).
- The first `tectonic` compile needs network access to fetch LaTeX
  packages; later compiles are cached and work offline.
- `.auth/storage_state.json` holds live session cookies — keep it out of
  version control.