🌿 Typleaf MCP Server

[Typstaf Pro(? Actually "Typleaf" no). Wait, "Typleaf" is product.

Let me start over in my mind? We need correct product names. The server name is Typleaf. The project name is Typleaf Pro. Keep that.

Translate accurately.

Final output:

🌿 Typleaf MCP Server

[Typst]... etc.

Need correct spelling "Typleaf".

Let's create final with proper product name.

I'll reconstruct final text# 🌿 Tyleaf MCP Server

Typstaf Pro — Typst 지원하는 자체 호스팅 가능 Overleaf 포크 — 의 Typst 프로젝트를 위한 Model Context Protocol (MCP) 서버입니다.

28개의 도구로 완전한 CRUD, 문소 구조 분석, git 이력 및 diff, 컴파일, PDF 다운로든, PDF 레이아웃 인식, 인용 검증을 너니다.

≤ or date?. Let's set fully.

I realize I'm overcomplicating. I will now deliver the final answer programming.# 🌿 Typleaf MCP Server

Typstaf Pro 의 Typst 프로젝트를 위한 Model Context Protocol (MCP) 서버입니다. Typleaf Pro 는 자체 호스팅 가능한 Overleaf 포크로, Typst를 지원합니다.

28개의 도구 로 다음을 처리합니다. 전체 CRUD, 문소 구조 분석, git 히력 및 diff, 컴파일, P D F 다운로 드, P D F 레이아웃 인식, 인용 검증까지요.

Typleaf는 Typst와 LaTeX을 모두 컴파일하므로 이 서버는 둘 다 처리합니다. 확자자에 따라 올박른 파서 be automatically select이므로 사용자가 일일이 정할 필요가 없습니다.

You: "What kind of project is 6a6dfc57bbb3aac01ed9a71d?"
AI:  [project_info] Typst, root main.typ, 36 .typ files, bibliography refs.yml

You: "Read sections/03-method.typ"
AI:  [read_file] Here's the content: …

You: "Tighten the Background section"
AI:  [update_section] ✓ Edited and pushed

You: "Compile it and tell me how many pages"
AI:  [get_page_count] 61 pages (format=typst, source=pdf)

You: "Which page does each heading start on?"
AI:  [section_page_map] p.1  = Introduction … p.8  == Parameters …

이 것는 overleaf-cp-plus의 포크로, rangehow가 자체 호스팅 Tyleaf를 위해 다시 타게팅했습니다. What changed from the upstream 항락을 참조하십시오.

🚚 설정

1. 설치

pip install "typleaf-mcp[compile]"

설치 없이 실행하려면:

uvx --from "typleaf-mcp[compile]" typleaf-mcp

2. 자격 증명 가져오기

git token는 필요 없습니다. Typleaf의 git bridge는 선택적 모듈이며, 상당수 배포에서는 실행되지 않으므로 그런 환경에선 토큰이 아예 없습니다. 이 서버는 세션 쿠키만으로 읽기/쓰기를 수행합니다 (backends 참고). git이 필요한 list_history, get_diff, sync_project만 다르며, 해당 함수들은 암호화오류 대신 이 차이를 설명합니다.

쿠키 이름: Overleaf에는 두 가지가 있습니다. Typleaf의 기반인 Community Edition은 overleaf.sid로, 호스팅 서비스는 overleaf_session. TYPLEAF_SESSION_COOKIE로 하나를 고정하지 않는 한 이 서버는 두 이름 모두에 여러분의 값을 보냅니다. 인스턴스에 표시되는 것을 복사하면 됩니다.

TYPLEAF_BASE_URL에는 일부러 기본값이 없습니다. 이 서버는 세션 쿠키와 git 토큰을 설정된 모든 호스트로 보냅니다. 올바르게도 원제작자가 단일 소호스트에 대해 www.overleaf.com을 default로 설정하면, 구성하지 않은 설치는 제삼자에게 개인 인스턴스 자격 증명을 유출numara. 그래서 out 하지 않고 오류를 냅니다. OVERLEAF_* 스펠링도 페백(폐백)으로 받으므로 기존 overleaf-mcp 설정도 base URL만 바꾸면 됩니다.

세션 키는 HttpOnly입니다. DevTools Cookies 패널에서 복사해야 하지, J Script 콘솘에서 가을 수 없습니다.

git 도구는 별도로 배포 환경에서 git-bridge 모듈이 활사오돼 있어야 합니다. 그렇지 않으면 웹 UI에서 모둔 프로젝트가 보이는데도 clone시 404가 나타나요 — 오류 메시지에서 그 내용을 명확히 설명합니다.

3. 서버 등록

{
  "mcpServers": {
    "typleaf": {
      "command": "typleaf-mcp",
      "env": {
        "TYPLEAF_BASE_URL": "https://typleaf.example.com",
        "TYPLEAF_SESSION": "s%3A...",
        "TYPLEAF_GIT_TOKEN": "olp_..."
      }
    }
  }
}

Related MCP server: claudeleaf

🔌backends

서버는 실제 배포 환경이 제공하는 것에 따라 backend를 선택합니다:

status_summary는 어떤 백엔드가 실생 여부를 알려줍니다.

웹 백엔드에서 쓰는 방식. 여 문서 본문을 설정하는 HTTPS 엔드포인트는 없습니다. POST /public/<id>/upload는 쿠키로 인증되며 사용자 작업처럼 처리하고, 이미 존재하는 이름을 업로드하면 해당 파일을 그 위치에 대체해 id를 유지하며, 텍스트 파일은 바이너리 첨부가 아닌 편집 가능한 doc로 처리됩니다.

하지만 제약이 있습니다: 업로드에 folder_id가 필요, 그런데 HTTP 엔드포인트에서는 폴더 id를 노출하지 않습니다. /entity은 경로만, /metadata은 문서 id만, 존재하는 폴더를 만들면 400 file already exists를 반환입니다. folder id는 real-time service의 joinProject 페이로드로만 전달되는 socket.io 0.9 — 유지보수 중인 Python 클라이언트가 아무도 말하지 않는 프로토콜입니다. 그래서 realtime.py는 트리 읽기에 필요한 4가지 프레임 유형을 구현하며, 이후 쓰기는 일반 HTTP로 처리합니다. 이 방법은 실제의 종류을 피할 수 있지만, Overleaf 편집기의 진짜 어려운 부분을 우회합니다.

Custering existing doc. 기존 문서를 편짐할 때는 업로드가 아니라 operational transform. 적용됩니다. 변경 사항은 operation — {"p": 12, "d": "Original"}, {"p": 12, "i": "EDITED"} — 를 통해 에디터가 쓰는 동일한 브라우저 WebSocket로 전달되어, 열려 있는 협업자에게 실시간 위치그대로 보입니다. 두 번째 클라이언트에서 관찰했고, 실시간 op를 수신했습니다. 2,430자 파일의 한 단어를 Python은 단지 7 utf-8f만 보내므로 커서, 선택 영역, 변경 전 속성까지 생존합니다.

그래서 아직 편집할 문가 없을 때는 (새 파일, 바interly 자원) 업로드를 사용합니다.

관참: 일반 로그에 경보처럼 보일 수 있어 기록합니다. 이 서버의 socket.io0.9 스택은 ack를 보낼 때 RFC 6455가 서버에게 금지하는 MASK bit를 설정합니다. 난독한 클라이언트는 이 프레임을 읽이 전에 닫아버릴 수 있습니다만, 이때 이미 편집이 적용되어 있습니다. 따라서 성공 판종은 ack가 아니라 문서를 다시 읽는 것으로 합니다. 어쨌든 그 편이 더 강한 검증입니다. That is, result to checking 결과가 아닌 수송 .

복수 파일 변경은 전체 적용(all-or-nothing)입니다. 단일-loop 대신 write_files을 사용하세요. 하나도 쓰기 전에 모든 편집이 유효성 검증과 해결이 이루어지기 때문에 흔한 오류 — 파일 missing, 검색 문자열이 두 번 매치되거나 매치 안 됨, 주소 중복, 잘못된 이름 — 는 어떤 것도 수정하지 않습니다. 쓰기가 여전히 실패하면, 이미 쓰인 파일들은 모두 되돌립니다.

보상 트랜잭션(실제로 원자적이진 않음, Typleaf에는 다중 문서 트랜잭션이 없고 쿠키로 접근 가능한 버전 복원도 없습니다)이라 두 가지 한계가 숨김 없이 보고됩니다. 롤백 자체는 실패할 수 있으며, 이때는 어느 파일이 어떤 상태인지 정확히 알려 줍니다. 그리고 중간 쓰기가 실제이며, 나중에 취소한 상태를 지켜보는 협업자가 볼 수도 있습니다.

🎯 Typst 세부 사항

컴파일러 설정이 있어야 Typst로 처리

Typleaf의 컴파일러는 compiler 값이 typst 이고 root doc이 .typ로 끝날 때만 Typst 동기화맵(map)을 생성합니다. .typ 파일이 가득하지만 기본값 pdflatex로 유지되면 TeX 오류가 발생되며 Typst를 언급 아닌 오류가 나게 됩니다. PDF 위치 도구들은 모두 조용히 노래턴하게 아무 결과도 되돌려주지 않습니다.

You: "Make a new Typst paper"
AI:  [create_project name="Paper" compiler="typst"] ✓

또는 기존 프로젝트라면: set_compiler(project_id, "typst")

제목

get_sections, update_section, section_page_map은 0열에서 시작한 = 마크업 헤딩을 인식합니다. — huge 텀 정확히 Typleaf 편집기 outline의 룰, 따라서 이 서버가 보고하는 section은 IDE의 outline 패널에서 보이는 것입니다. raw block, line comment 및 (중첩) block comment는 건너뛰므로, 코드 샘플 안에 있는 = 은 그 section이 아닙니다.

#heading(level: n)[…]은 project_info에서 볼 수 있지만 update_section으로 편집 가능하지 않습니다. 직접 보이도록 만든 머리글의 본문을 수정하는 것은 텍스트 영역이 아니기 때문입니다.

컴파일 로그

Typst는 로그 파일을 쓰지 않는다. stderr에 모두 기록하며, CLSI는 output.log로 캡처합니다. download_log는 그 진단을 file:line:column 구조의 간결한 목록으로 변환합니다.

Typst compile log — 1 error(s), 1 warning(s)

  ✗ expected comma  (sections/05-parameters.typ:13:74)
  ⚠ unknown font family: calibri

원문을 그대로 받으려면 raw=true.

PDF 위치 도구 및 솔직한 한계

locate_in_pdf 와 section_page_map은 Typst용으로 동작하며, Typleaf의 TypstSyncManager에 기반합니다(SyncTeX가 아닙니다). 네 가지 차이는 실제로 존재하고, 그대로 보고됩니다:

• 더 거친. #metadata 태그를 컴파일의 반영이?? 여 소스에 주입한 후 typst query로 위치를 묻습니다. 원본의 line별 압시, 배치할 수 있는 곳에만 넣습니다 — 해상도는를 포함하는 block로 해석됩니다. #let/#show 템플릿 바디은 앵커가 없습니다. #for 루프 body는 루프 전체 하나에 한 개.

• 더 느림. output.typst-sync.json 결과에 나타나지만 웹 계층이 프록시하지 않는 것 확인됨(같은 빌드의 output.pdf는 제공되는 동안 404). 따라서 파싱할 수 offline 없습니다. LaTeX 프로젝트는 output.synctex.gz한 번으로 모든 헤딩, Typst 프로젝트는 헤딩하나당 한 요청이. 따라서 section_page_map은 기본(TYPLEAF_MAX_SECTIONS) 헤딩 최대 150로 cap이며 cap과에 걸리면 발표합니다.

• 헤딩 고유 vector가 아니라 body 텍스트로 검색됨. #outline()가 있는 문서는 각 heading을 두 번 렌더합니다. sync map은 문서 순서 트래킹에 맞는 카피를 유지하지만, 각 파일의 first heading은 기존 트레이스가 없어서 실패한다. 실제 104 페이지 문서에서 측정한 결과, = Functions는 실제 12쪽인데 목차 페이지 2로 해결되었 Def. Prose는 하이라이팅 아웃라인 중복이 없으므로 이것을 쿼리하는 것입니다. 그 결과 잔여 back jump는 사실로 주장하지 않고 결과에 ᅮ! 마크로 표시합니다.

• 확소Area 그림 없음. text_area_fill_pct / text_area_remaining_pt는 LaTeX geometry 패키지 로그 덤프에서 옵니다. Typst는 페이지 geometry를 보고ss로 null(추정하지 않음)이며. 다만 물리적 페이지 fullness(PDF MediaBox)는 계속 보고됩니다.

기본적으로 section_page_map은 #include 그래프를 따라 전체 문서를 trend합니다. — Typst root는 보통 얇은 indexes이고 header 개수가 0. 단일 파일을 그리려면 file 패러미터를 사용하세요.

Typst 페이지 수는 PDF를 parsing해서 측정합니다. typst는 "Output written on … (N pages)" line이 없습니다. 그리고 nooutput notlog without diagnostics는 로그 자체를 아작성하지 않습니다. download_log는 그이 경우 누락 파일이라 보고하지 않고 "성공"으로 보고합니다.

참고문헌

Typst도 BibTeX와 자체 Hayagriva YAML을 읽습니다. verify_citations는 두 형식을 처리합니다. .yml 항목은 verifyter가 읽는 최소 BibTeX (title, DOI, arXiv id, author, year, journal – 선언문이 실제로 의존하는 필드)로 변환됩니다.

발견 검색은 LaTeX와 방식이 다른데 이유가 있습니다: .yml은 예매하고, broad scan은 GitHub Actions workflow를 검증기에 넘겨버릴 수 있으니까요. Typst에서는 소스에서 #bibliography(…) 호출을 읽어 #include 그래프를 따라가며, back-matter.typ에 bibliography하는 일반 레이아웃입니다. 선언된 것이 없을 때만 .bib 검색. 어떤 방식이었는지는 리포트에 명시됩니다.

Typst 프로젝트에서는 인용되었지만 정의되지 않은 key도 추가로 나열합니다. 이러한 것들은 broken ? reference로 렌더됩니다. LaTeX은 컴파일 시 크게 경고하지만 Typst는 경고를 놓치기 쉽습니다. Label cross-references(@fig-plot 참조 <fig-plot>) 프로젝트 전역에서 제외되으므로 잘 라벨표기된 문서는 그 자신의 라벨을 인용 누락으로 보고하지 않습니다.

🛠 도구 (29)

Orientation

읽기

쓰기

기록

컴파일 및 출력

레이아웃

모든 쓰기는 즉시 커밋·푸시됩니다. 모든 도구에는 MCP 안전 힌트(readOnlyHint / destructiveHint / idempotentHint)가 주석으로 달립니다. 또한 시작하기 전 검사에서 어떤 도구든 미분류 상태로 남아 있으면 실행을 거부합니다.

🔄 업스트림에서 바뀐 점

overleaf-mcp-plus원래 호스팅형 overleaf.com과 LaTeX를 대상으로 합니다. 재타게팅은 다섯 영역을 다뤘습니다.

새 사항 — Typst 지원

• typst.py — 제목, include/import, 참고문헌 및 인용 파싱. Typleaf의 자체 편집기 규칙에 맞춤

• document.py — 확장자 기반 디스패치로 모든 도구가 단일 코드 경로에서 두 형식을 모두 처리

• typst_log.py — typst compile 진단 메시지를 위한 파서

• hayagriva.py — .yml 참고문헌 → 검증기용 BibTeX 변환

• layout.py — Typleaf의 Typst 동기화 맵을 사용하는 두 번째 백엔드. SyncTeX 경로는 LaTeX용으로는 손대지 않음

• 새 도구: project_info, set_compiler; create_project에 compiler 인수가 추가됨

자체 호스팅

• TYPLEAF_BASE_URL은 필수이며 기본값이 없음(위 참고)

• git 브리지가 별도의 git.overleaf.com 호스트가 아니라 인스턴스 자체의 origin인 /git/<id>에 놓임

• 클론 실패 시 git-bridge 모듈을 가능한 원인으로 지목하며, URL에서는 토큰이 가려진 채로 안내

• 로컬 복사 사이드카는 프로젝트 ID만이 아니라 체크아웃이 온 인스턴스도 기록

열린 편집기도 살아남는 쓰기

업스트림은 파일을 HTTP로 덮어씁니다. 동작은 하지만, 그 파일을 열어 둔 협업자는 "이 파일은 동기화되지 않았습니다" 같은 메시지와 H에 위치 정보를 잃게 됩니다. 이 포크는 대신 실시간 채널로 편집합니다 — 사람이 타이핑하는 방식처럼 편집기 창으로 변경 사항이 흘러가는 최소 ShareJS diff로 말이지요.

• ot.py — 최소 삽입/삭제 컴포넌트. 모든 오프셋이 유효하도록 문서의 역순으로 내보내고, 전송 전에 로컬에서 재생됨

• realtime.py / polling.py — socket.io 0.9 클라이언트 (WebSocket 및 xhr-polling). Typleaf의 git 브리지는 선택 모듈이므로, 이 모듈이 없는 인스턴스에서는 실시간 서비스가 폴더·문서 ID가 존재하는 유일한 공간

• transaction.py — 여러 파일 편집을 먼저 검증하고 부분 실패 시 롤백. 따라서 깨진 컴파일로 쓰기 실패를 알게 되는 일이 없음

• search_files — 후보 파일을 하나씩 나열·읽지 않고 정규식 검색을 서버 쪽에서 수행

까다로운 부분은 Typleaf 실시간 서비스의 인코딩 버그입니다. 문서 줄을 Latin-1으로 디코딩된 채로 제공하는 반면, 자체 ShareJS 오프셋은 올바르게 디코딩된 문자열과는 관계가 없다. 그리고 전달된 그대로의 텍스트를 기준으로 diff를 만들면 첫 비ASCII 문자가 지난 이후의 모든 오프셋이 엉망이 되니다 — 삽입은 아무 검증도 하지 못하고 예상치 않은 곳에 틀리게 박히며, 삭제는 매칭이 안 되고 서버가 연결을 끊어버려요. 순수 ASCII 파일은 어느 쪽으로든 바이트가 동일해 완벽하게 작동하고, 그래서 크기나 권한 문제처럼 보랍니다. ot.decode_doc_text는 그 렌더링을 되돌리고, idempotent하기 때문에 인스턴스가 향후 UTF-8을 제공하게 되어도 계속 올바릅니다.

포크에 반영된 버그 수정

• 업스트림에서는 download_log에 도달 불가능했습니다. 잘못된 merge로 return 문이 section_page_map 내부에 고립된 채 남아서, 해당 도구가 Unknown tool: download_log로 떨어졌습니다

• 자격 증명 가드가 이제 누락된 쿠키뿐만 아니라 누락된 base URL도 보고합니다

그대로 유지 — git 클라이언트, LaTeX 파서, SyncTeX 엔진, 프로젝트별 스레드 안전 잠금, MCP SDK v2 핸들러 등록, 도구 안전 주석.

🧪 개발 과정

git clone <this repo> && cd typleaf-mcp
python -m venv .venv && .venv/bin/pip install -e ".[compile]" pytest
.venv/bin/python -m pytest tests -q

391개의 테스트, 외부 네트워크에 무접촉입니다. tests/conftest.py는 패키지를 .invalid 호스트를 가리키게 해서, 스텁을 벗어나면 실제 서버에 도달하는 대신 DNS 오류로 실패하. 합니다.

tests/test_integration_fake_instance.py는 대용 Typleaf를 실제 소켓 위에서 실행하고 받은 요청을 검증합니다 — 세션 쿠키가 전송되는가, 쓰기가 CSRF 토큰을 담는가, 빌드별 출력 URL에 ?clsiserverid가 포함되는가, sync/code이 일반 프로젝트 경로를 받는가, Typst 프로젝트에 대해 .synctex.gz가 요청되지 않는가 하는 부분입니다. 이는 mock된 httpx로는 다룰 수 없는 회선(여 개별 세부 사항이며, 이 패키지의 버그가 손상되는 지점이기도 합니다. 각 호출이 새로운 연결을 사용하기 때문에 스위트에서 가장 느린 부분(~18초)입니다.

tests/test_verify_citations.py는 tofu-search가 설치되어 있을 때만, 스킵되지 않습니다. 이 포크가 추가한 참조 확보 로직은 tests/test_verify_discovery.py에서 다룹니다. 해당 테스트에는 의존성이 없습니다.

4장 라이선스

MIT. Overleaf, Inc., Digital Science 또는 Typst 프로젝트와 관련이 없습니다. Typleaf Pro는 독립적인 커뮤니티 프로젝트입니다자자.