Overleaf Resume

Overleaf 웹사이트 대신 로컬에서 이력서를 편집하고 컴파일하세요. 필요할 때 Overleaf와 소스 파일을 동기화하는 MCP 서버를 사용합니다. 여러 Overleaf 프로젝트를 나란히 사용할 수 있습니다. 모든 동기화 도구는 명시적인 project_id를 받으므로 특정 단일 프로젝트에 고정되지 않습니다.

무료 플랜 Overleaf 계정(Git/API 접근 불가)을 위해 만들어졌습니다. 계정에 Git 통합(유료 플랜)이 있다면 git clone으로 프로젝트를 가져오면 됩니다. 이 도구는 필요 없습니다.

작동 방식

• 일상적인 편집: 프로젝트를 가져온 후(아래 참조) projects/<name>/ 아래에서 .tex 파일을 직접 편집하고 Tectonic으로 로컬에서 컴파일하세요. Overleaf를 거칠 필요가 없습니다.

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

  그러면 바로 옆에 PDF가 생성됩니다. (tools/tectonic.exe는 이 저장소에 이미 설정된 독립 실행형 바이너리입니다. 큰 다운로드 바이너리이므로 gitignore 처리되어 있습니다. 소스가 아닙니다.)

• Overleaf와 동기화: 무료 플랜 Overleaf 계정(Git/API 접근 불가)이므로 MCP 서버(overleaf_mcp/)가 Playwright로 실제 로그인된 Chromium 세션을 구동하여 프로젝트 소스를 다운로드하고 편집 내용을 온라인 편집기에 다시 푸시합니다. 브라우저에서 직접 수행하는 것과 동일한 작업입니다.

Related MCP server: LaTeX Resume MCP

프로젝트 구조

가져온 각 Overleaf 프로젝트는 자체 하위 폴더에 저장되므로 여러 이력서가 충돌 없이 공존할 수 있습니다.

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/는 gitignore 처리되어 있습니다. 실제 이력서 콘텐츠(Overleaf에서 가져온)를 보관하므로 로컬에 유지되며 커밋되지 않습니다.

일회성 설정

1-2단계는 이 저장소에 이미 완료되어 있습니다(.venv/에 의존성이 설치되어 있고 Playwright의 Chromium 브라우저가 다운로드되어 있으며 tools/tectonic.exe를 사용할 수 있습니다). 다른 머신이나 새 체크아웃 후 다시 수행해야 할 경우를 대비해 여기에 나열합니다.

1. 가상 환경을 만들고 의존성을 설치합니다.

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

2. Tectonic 받기: winget/choco는 항상 사용 가능한 관리자 권한이 필요할 수 있습니다. 관리자 권한 없이 안정적인 방법은 Windows 바이너리를 직접 다운로드하여 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

   tools/tectonic.exe --version으로 확인하세요.

3. MCP 서버가 세션을 재사용할 수 있도록 Overleaf에 한 번 로그인합니다.

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

   브라우저 창이 Overleaf 로그인 페이지로 열립니다. 이메일 + 비밀번호로 로그인하세요. "Google로 로그인"은 사용하지 마세요. Google은 자동화된 브라우저 내부의 로그인 양식을 차단하므로 Google 전용 계정은 먼저 Overleaf에서 비밀번호를 설정해야 합니다(계정 설정). 세션은 .auth/storage_state.json에 저장됩니다(gitignore 처리되어 있으므로 커밋하거나 공유하지 마세요). overleaf_login_status가 세션 만료를 보고할 때마다 이 스크립트를 다시 실행하세요.

4. 이 저장소의 .mcp.json은 서버를 Claude Code에 자동으로 등록합니다. Claude Code를 다시 시작하거나 /mcp를 실행하여 overleaf-resume 서버를 인식하세요.

5. overleaf_list_projects를 호출하여 모든 Overleaf 프로젝트와 ID를 확인한 다음 작업하려는 프로젝트에 대해 overleaf_pull(project_id)를 호출하세요. 파일은 projects/<name>/ 아래에 저장됩니다.

MCP 도구

• overleaf_login_status — 저장된 세션이 여전히 유효한지 확인합니다.

• overleaf_list_projects — 모든 Overleaf 프로젝트(이름 + ID)를 나열합니다.

• overleaf_pull(project_id, local_dir?) — 해당 프로젝트의 소스를 projects/<name>/(또는 지정된 local_dir)에 다운로드하고 기존 .tex/.cls/.sty/.bib 파일을 먼저 .backups/ 아래에 백업합니다.

• overleaf_push(project_id, file_path) — 로컬 파일의 현재 내용을 해당 Overleaf 프로젝트의 온라인 편집기에 다시 푸시합니다. file_path는 이 저장소 루트 기준 상대 경로입니다(예: projects/<your-project-name>/resume.tex).

project_id는 항상 필요합니다. 기본 프로젝트가 없으므로 이력서가 하나든 여러 개든 동일하게 작동합니다. ID를 조회해야 할 때마다 overleaf_list_projects를 사용하세요.

로컬 컴파일 문제 해결

Overleaf는 기본적으로 pdfLaTeX로 컴파일합니다. Tectonic은 XeTeX 기반 엔진을 사용합니다. 인기 있는 "Jake's Resume" 스타일 템플릿에서 이로 인해 발생한 두 가지 문제가 있습니다. 여러분도 겪을 수 있으니 참고하세요.

• \pdfglyphtounicode / \input{glyphtounicode} / \pdfgentounicode=1은 pdfTeX 전용 프리미티브입니다. 두 엔진 모두에서 작동하도록 보호하세요.

  \usepackage{iftex}
  \ifPDFTeX
    \input{glyphtounicode}
  \fi
  ...
  \ifPDFTeX
    \pdfgentounicode=1
  \fi

• enumitem의 \begin{itemize}...\end{itemize} 쌍(이 템플릿의 \resumeSubHeadingListStart/End 매크로를 통해)은 주석 처리된 섹션에서도 균형을 유지해야 합니다. 블록을 주석 처리한 후 남은 짝이 맞지 않는 \end{itemize}는 enumitem 내부(\enit@enditemize) 깊숙한 곳에서 난해한 Undefined control sequence 오류를 발생시킵니다. 이는 Tectonic/Overleaf 차이가 아닙니다. 오류 수를 보면 Overleaf 자체 컴파일러에서도 실패합니다.

주의 사항

• 이 도구는 실제 로그인된 세션으로 Overleaf의 실제 웹 UI를 자동화합니다. 무료 플랜 프로젝트에는 공개 API가 없습니다. Overleaf가 UI를 변경하면 중단될 수 있으며 저장된 세션은 가끔 만료됩니다(scripts/overleaf_login.py 다시 실행).

• 첫 번째 tectonic 컴파일은 LaTeX 패키지를 가져오기 위해 네트워크 접근이 필요합니다. 이후 컴파일은 캐시되어 오프라인에서 작동합니다.

• .auth/storage_state.json에는 활성 세션 쿠키가 들어 있습니다. 버전 관리에서 제외하세요.