🌿 Typleaf MCP Server

Typst プロジェクト向けの Typleaf Pro 上の Model Context Protocol (MCP) サーバーです — **Typst をサポートするセルフホスト型 Overleaf フォークです。

28 ツールが、完全な CRUD、ドキュメント構造分析、git 履歴と差分、コンパイル、PDF ダウンロード、PDF レイアウト認識、引用検証をカバーしています。

Typleaf は Typst と LaTeX の両方をコンパイルするため、このサーバーは両方を扱います。適切なパーサーはファイル拡張子から自動的に選ばれるため、どちらかを指定する必要はありません。

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 …

これは rangehow による overleaf-mcp-plus のフォークで、セルフホスト型 Typleaf 向けに再調整されています。アップストリームからの変更点 を参照してください。

🚀 セットアップ

1. インストール

pip install "typleaf-mcp[compile]"

またはインストールせずに実行:

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

2. 認証情報を取得する

git トークンは不要です。 Typleaf の git ブリッジはオプションモジュールであり、多くのデプロイでは稼働していません。その場合、設定するトークンは存在しません。このサーバーはセッション cookie だけで読み書きします (Backends 参照)。git が必要なのは list_history、get_diff、sync_project だけであり、これらは暗号的な失敗ではなく、その不足点を説明します。

Cookie 名について: Overleaf には2つの cookie があります。Typleaf の基盤である Community Edition は overleaf.sid を設定し、ホスト型サービスは overleaf_session2 を設定します。間違った名前を使うと、セッションの期限切れとまったく同じように見えます。そのため、このサーバーは TYPLEAF_SESSION_COOKIE で1つに固定しない限り、両方の名前で指定された値を送信します。インスタンスに表示されるかたをそのままコピーしてください。

TYPLEAF_BASE_URL には意図的にデフォルトがありません。 このサーバーはセッション cookie と git トークンを、設定されたホストに送信します。www.overleaf.com をデフォルトにすると — 上流が単一ホストサービスとして正しく実行しているように — 設定が未完了のインストールで、プライベートインスタンスの認証情報が第三者に漏れることになります。そのため、デフォルトではなくエラーにします。3つの変数の OVERLEAF_* という綴りはすべてフォールバックとして受け入れられるため、既存の overleaf-mcp 設定はベース URL を変更するだけで済みます。

セッション cookie は HttpOnly です。DevTools の Cookies パネルからコピーしてください。JS コンソールからは取得できません。

git ツールは、デプロイ環境で git-bridge モジュールが有効になっている必要があります。モジュールがないと、すべてのプロジェクトが Web UI に表示されていても、クローンは 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

🔌 バックエンド

サーバーは、デプロイが実際に提供するものに基づいてバックエンドを選択します。

status_summary はどのバックエンドが機器で動作しているかを報告します。

Web バックエンドの書き込み方法。 ドキュメントの内容を設定する HTTP エンドポイントはありません。setDocument は存在しますが、サービス間認証の後ろにあり、エディタ自体は WebSocket を介して操作変換（operational transform）で書き込みます。しかし POST /Project/<id>/upload は cookie 認証で、upsert を行います。すでに存在する名前をアップロードすると、そのエンティティが置き換えられ、ID が維持され、テキストファイルはバイナリ添付ではなく編集可能な doc として返ります。

1点の注意: アップロードには folder_id が必要ですが、フォルダ ID を公開する HTTP エンドポイントはありません。/entities はパスのみ、/metadata はドキュメント ID のみ、既存フォルダの作成は 400 file already exists を返します。フォルダ ID は socket.io 0.9 によるリアルタイムサービスの joinProject ペイロードにのみ現れます。これは、メンテナンスされた Python クライアントが認識しないプロトコルです。そこで realtime.py はツリーを読み取るために必要な4種類のフレームを実装し、その後の書き込みは普通の HTTP で行います。これにより、Overleaf のエディタと通信するための本質上難しい部分である操作変換の実装を回避します。

既存のドキュメントの編集は、アップロードではなく操作変換で行われます。 変更はオペレーションとして — {"p": 12, "d": "Original"}, {"p": 12, "i": "EDITED"} — 編集者が使用するものと同じ WebSocket で送信されます。ファイルを開いている共同編集者は、その場で反映されるのを見ます。別のクライアントで確認しました：それはその操作を受信します。2,430 文字のファイルで 1 ワードの変更は 7 バイトを送信します。そのため、カーソル、選択範囲、未変更テキストの再生追跡属性はすべて保存されます。

UPLOADがまだ編集対象のドキュメントがない場所では、新規ファイルやバイナリ資産として使われます。

ログで警告にように見えるため、記録する価値があるひんしゅく点:このサーバーの socket.io 0.9 スタックは、MASK ビットをセットしたフレームで ack を送信します。これは RFC 6455 がサーバーに禁止していることで、厳格なクライアントが読み取る代わりに接続を閉じます — 編集が適用された後で。したがって、書き込みの確認は ack からではなく、ドキュメントを読み返すことによって行われます。これはいずれにしてもより強い検証です。それ転送ではなく結果を検証します。

複数ファイルの変更は、全有全無です。 rewrite_file をループする代わりに write_files を使用してください。各編集は書き込み前に* すべて検証され解決されるため、一般的な失敗 — ファイルの不足、検索文字列の一致が2回または0回、パスの重複、別名の不正 — は一切影響しません。書き込みが失敗した場合、すでに書き込んだファイルは復元されます。

これは補償トランザクションであり、本物のトランザクションではありません (Typleafにはマルチドキュメントトランザクションも、cookie からアクセス可能な版リストアもありません)。そのため2つの制限が報告されます：ロールバック自体も失敗する可能性があり、その場合は結果がどのファイルがどの状態かを正確に示します。また、途中の書き込みは実際に実行されたため、監視している共同編集者は、後で取り消された状態を見たかもしれません。

🎯 Typst 固有の設定

コンパイラ設定がプロジェクトを Typst にする

Typleaf の CLSI は、プロジェクトの compiler が typst であり、ルートドキュメントが .typ で終わる場合にのみ、Typst 同期マップを生成します。デフォルトの pdflatex のままがっかり .typ ファイルで埋め尽くされたプロジェクトは、Typst に一切触れない TeX エラーでコンパイルに失敗し、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にある = マークアップの見出しを認識します — まさに Typleaf のエディタアウトラインが使用するルールです。そのため、このサーバーが報告するセクションは IDE のアウトラインに表示されるものです。文字列の行、行コメント、および (ネストした) ブロックコメントはスキップされます。よって、コード例内の = はセクションとして誤認識され添。

#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 は、SyncTeX ではなく Typleaf の TypstSyncManager に基づいて Typst に対して機能します。実際の4つの差分は隠さずに報告されます:

• 粗い。 Typleaf はコンパイル後にソースにゼロ幅の #metadata マーカーを挿入し、typst query でその場所を問い合わせます。アンカーはソースの行ごとにありますが、マーカーを安全に置けた場所だけです。検索結果は外側のブロックに解決されます。#let/#show テンプレート本体の大きなコンテンツにはアンカーがまったくなく、#for 本体はループに対して1つのアンカーを得ます。

• 遅い。 output.typst-sync.json はコンパイル出力にリストされていますが、Web 層はそれをプロキシしません (確認済み: 同じビルドの output.pdf は提供されるのに、これは 404 になる)。したがって、オフラインで解析するものはありません。LaTeX のプロジェクトは1つの output.synctex.gz の解析だけで全見出しを解決しますが、Typst のプロジェクトは見出しごとに1つのリクエストが必要です。そのため section_page_map はデフォルトで150見出しで上限です (TYPLEAF_MAX_SECTIONS) で、上限に当たるとその旨を伝えます。

• 見出しは見出し行自体ではなく、本文の文章を使用して検索されます。 #outline() を含むドキュメントは、各見出しが二度表示されます。Typleafの同期マップは、ファイルのドキュメント順の道のりに適合するコピーを保持します — ただし、各ファイルの 先頭 の見出しで利用してください。互換がないからです。実測の104ページのドキュメントでは、真のページ12に対して、= Functions はページ2(目次)に解決されました。プロいわゆる「文章」は目次に二重化されないので、そちらが照会されます。残りの後方のジャンプは、事実として提示する代わりに ! で出力されます。

• テキストエリアの図はありません。 text_area_fill_pct/text_area_remaining_pt は LaTeX の geometry パッケージのログ出力から取得されます。Typst はページジオメトリを報告しないため、Typst の場合は推測するではなく欠落しているフィールドです。う物理ページの充足率 (PDF MediaBox から) は * で引き続き報告されます。

section_page_map はデフォルトで #include を注してすべてのドキュメントを辿ります。Typst のルートは通常、見出しがゼロの薄いインデックスです。単一ファイルだけをマップするには file を渡してください。

Typst のページ数は PDF を解析します。typst は「Output written on … (N pages)」という行を出力しないため。また、診断を生成しない Typst のコンパイルは ログを一切書きません。download_log はそれをファイルとしてではなく、成功として報告します。

参考文献

Typst は BibTeX とライブラリ固有の Hayagriva YAML を読み取ります。verify_citations は両方を処理します。.yml-エントリは、検証者が読み取る最小限の BibTeX (タイトル、DOI、ArXiv-ID、著者、年、( 判定が実際に依存するフィールド) に変換されます。

検出は LaTeX 側から理由があって異なります。.yml は曖昧な拡張子であり、単純なスキャンでは GitHub Actions ワークフローをフィードしてしまうからです。そこで Typst では、ツールが #bibliography(…) 呼び出しをソースから読み取ります。#include グラフをたどるのは、back.md に置かれた #bibliography が一般的なレイアウトだからです。特に .bib スキャンにフォールバックするのは宣言がない場合のみ. レポートはどの経路を使ったかを説明します。

Typst プロジェクトでは、引用された とも実現されていないキー リストします。これは、壊れた ? 参照として表示されますが、LaTeX はコンパイル時にこれらを声高い警告します。それに対する Typst の警告は陰見されやすいです。ラベリング (<fig-plot> を指す @fig-plot) はプロジェクト全体で除外されるため、 well-labeled なドキュメントが自身のラベルを欠落引用として の \. ソースを参照してください。

🛠 ツール (29)

オリエンテーション

読み取り

書込み

履歴

コンパイルと出力

レイアウト

すべての書き込み操作は、直ちにコミットされてプッシュされます。すべてのツールには MCP 安全性ヒント（readOnlyHint / destructiveHint / idempotentHint）が付与され、未分類のツールが残っている場合、起動時のチェックが実行を拒否します。

🔄 アップストリームからの変更点

overleaf-mcp-plus は、ホスティング型の overleaf.com と LaTeX を対象としています。この再ターゲットは、5つの領域に変更を加えました。

新機能 — Typst サポート

• typst.py — 見出し、include/import、参考文献と引用の解析。Typleaf 自身のエディタのルールに一致

• document.py — 拡張子に基づくディスパッチにより、すべてのツールがひとつのコードパスで両方のフォーマットを扱う

• typst_log.py — typst compile の診断結果を解析するパーサー

• hayagriva.py — 検証用に .yml 参考文献を BibTeX へ変換

• layout.py — Typleaf の Typst 同期マップを利用する第2のバックエンド。LaTeX 用の SyncTeX パスは変更されない

• 新しいツール：project_info、set_compiler。create_project には compiler 引数が追加

セルフホスティング

• TYPLEAF_BASE_URL が必須になり、デフォルト値はない（上記参照）

• git ブリッジは独立した git.overleaf.com ホストではなく、インスタンス自身のオリジン /git/<id> に配置される

• クローン失敗時は、git ブリッジモジュールを原因の候補として挙げ、URL からトークンを編集した形で報告する

• ローカルコピーのサイドカーは、プロジェクト ID だけでなくチェックアウト元のインスタンスも記録する

オープン中のエディタがそのまま維持される書き込み

アップストリームは HTTP 経由でファイルを置き換えます。これでも動作しますが、ファイルを開いている共同編集者には 「このファイルは同期が失われた」 と表示され、その編集位置が失われます。このフォークでは、代わりにリアルタイムチャネルを介して編集します — 最小限の ShareJS 差分で、人間のキータイプと同様に変更が開いているエディタへと反映されていきます。

• ot.py — 最小の挿入・削除コンポーネント。逆文書順で発行され、すべてのオフセットが有効なまま保たれ、送信前にローカルで再生される

• realtime.py / polling.py — socket.io 0.9 クライアント（WebSocket と xhr-polling）。Typleaf の git ブリッジはオプションモジュールであり、それが存在しないインスタンスでは、フォルダ ID とドキュメント ID が存在するのはリアルタイムサービスのみとなる

• transaction.py — 複数ファイルの編集を事前に検証し、一部でも失敗するとロールバックするため、コンパイルが失敗して初めて「書き込みに失敗した」と気づくということにはならない

• search_files — サーバーサイドで正規表現検索候補を列挙し、1つずつ読む代わりに一括で検索する

最も厄介なのは、Typleaf のリアルタイムサービスのエンコーディングバグです。ドキュメント行が Latin-1 でデコードされた状態で配信される一方、各サービス自身の ShareJS オフセットは正しくデコードされた文字列に対して計算されています。配信されたテキストにそのまま差分を当てると、最初の非 ASCII 文字以降のすべてのオフセットがずれてしまい、挿入は何も確認されずに静かに誤った場所へ置かれ、削除は一致できずサーバーが接続を切断します。純 ASCII のファイルはどちらの扱いでもバイト列が同一で正常に動作するため、まるでサイズか権限の問題のように見えます。ot.decode_doc_text はこのレンダリングを解除します。これは冪等であるため、将来インスタンス側が UTF-8 を提供するよう修正されても正しく機能し続けます。

フォークに引き継がれたバグ修正

• アップストリームでは download_log に到達できませんでした。不適切なマージにより section_page_map 内に return 文が孤立したままで、ツールは、Unknown tool: download_log にまでフォールスルーしていました

• 認証ガードは、クッキー欠落だけでなく缺少ベース 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 が一度も要求されないこと。これらは、モックされた httpx ではカバーできないワイヤーレベルの詳細であり、このパッケージでバグが歴史的に発生してきた場所でもあります。各呼び出しが新規の接続を開くため、スイットの中で最も遅い部分です（約18秒）。

tests/test_verify_citations.py は tofu-search がインストールされていない場合はスキップします。このフォークが追加した発見・報告ロジックは、tests/test_verify_discovery.py で別にカバーされており、そのテストは、tofu-search に依存しません。

📄 ライセンス

MIT ライセンス。Overleaf, Inc.、Digital Science、または Typst プロジェクトとは無関係です。Typleaf Pro は独立したコミュニティプロジェクトです。