caphefalumi/typst-web-mcp

---

Overview

typst-web-mcp connects AI coding and writing agents directly to collaborative typst.app cloud projects. Instead of relying on brittle browser DOM scraping, it implements the native typst.app client protocol:

• Native Yjs CRDT Text Sync: Decodes and mutates multiplayer Y.Doc (doc.getText("text")) state vectors so surgical edits preserve collaborator cursors and version history.
• Binary /editing/v3 WebSocket Wire Protocol: Encodes and decodes lib0 variable-length binary frames (Subscribe, TextUpdate, Pong, Refresh, Presence, Cursor, Leave) with REST /v1/files/:projectId/:fileId/yjs persistence.
• GraphQL & REST Project Management: Full project CRUD, file tree inspection, rename/move, delete, and binary figure/asset uploads (PNG, JPG, SVG, PDF, fonts).
• Direct Authentication + Fallback: Authenticates via GET /v1/to-signin + POST /v1/auth/signin (__Http-typst-session), with persistent session caching and automatic cookie/Playwright fallback on challenge.
• Compiler Diagnostics, Preview Screenshots & PDF Export: Synchronizes cloud Yjs text and binary assets into an isolated workspace and runs the Typst compiler to return structured line/column diagnostics, high-DPI PNG preview screenshots (typst_capture_screenshot), and compiled PDFs (typst_export_pdf).

---

Architecture

flowchart LR
    Agent["AI Agent\n(Pi / Claude / Cursor)"] |"JSON-RPC (stdio)"| MCP["typst-web-mcp\n(Bun / TypeScript)"]
    MCP |"GraphQL (/v1/graphql)\n+ X-Typst-Preflight"| API["https://api.typst.app"]
    MCP |"REST Yjs & Blobs\n(/v1/files/:pid/:fid/yjs)"| API
    MCP |"Binary lib0 WebSocket\n(wss://api.typst.app/editing/v3)"| WS["typst.app Real-Time Sync"]
    MCP -->|"Workspace Sync + Compile"| TypstCLI["Typst Compiler\n(Diagnostics & PDF)"]

See docs/PROTOCOL.md for the complete reverse-engineered protocol specification.

---

MCP Tools (16 Tools)

---

Quick Start

Prerequisites

• Bun >= 1.2
• Typst CLI (typst on PATH for typst_get_diagnostics and typst_export_pdf)

Installation

git clone https://github.com/caphefalumi/typst-web-mcp.git
cd typst-web-mcp
bun install

MCP Client Configuration

Add typst-mcp to your MCP client configuration (.pi/agent/mcp-adapter.json, claude_desktop_config.json, or .cursor/mcp.json):

{
  "mcpServers": {
    "typst-mcp": {
      "command": "bun",
      "args": ["/absolute/path/to/typst-web-mcp/src/index.ts"],
      "env": {
        "TYPST_EMAIL": "[email protected]",
        "TYPST_PASSWORD": "your-password"
      }
    }
  }
}

Session Persistence: Once authenticated via typst_auth_login (or environment variables), the __Http-typst-session cookie is cached locally at ~/.pi/agent/typst-mcp-session.json so subsequent tool calls authenticate automatically without re-signing in.

---

Development & Verification

# Typecheck with strict TypeScript
bun run typecheck

# Run full unit, mock server, and live api.typst.app protocol test suite
bun test

Project Structure

typst-web-mcp/
├── docs/
│   └── PROTOCOL.md              # Reverse-engineered typst.app REST, GraphQL, Yjs & WS v3 spec
├── src/
│   ├── protocol/
│   │   ├── ws-codec.ts          # Binary lib0 /editing/v3 WebSocket encoder & decoder
│   │   ├── yjs-doc.ts           # Yjs CRDT text decoding, replacement & surgical patching
│   │   └── graphql.ts           # GraphQL queries, mutations, fragments & types
│   ├── client/
│   │   ├── auth.ts              # Direct /v1/auth/signin login, cookie jar & Playwright fallback
│   │   ├── compiler.ts          # Typst binary resolver, diagnostic parser, PDF & PNG preview compiler
│   │   ├── errors.ts            # Structured TypstLoadError & error formatting helpers
│   │   └── typst-client.ts      # TypstCloudClient (REST, GraphQL, WebSocket v3, Compiler facade)
│   ├── tools/
│   │   └── definitions.ts       # MCP JSON Schema definitions for all 16 tools
│   └── index.ts                 # MCP stdio server entrypoint & tool dispatcher
├── test/
│   └── typst-mcp.test.ts        # 7 test suites (57 assertions) covering codecs, CRDTs & E2E
├── LICENSE                      # MIT License
└── package.json

---

License

Released under the MIT License. Copyright © 2026 Dang Duy Toan (caphefalumi).