typst-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dang Duy Toan (caphefalumi)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE(FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Typst Web MCP (`typst-web-mcp`)
+
+**Model Context Protocol (MCP) Server for [`https://typst.app`](https://typst.app) Cloud Collaboration, Real-Time Yjs CRDT Editing & Compiler Diagnostics**
+
+[![npm version](https://img.shields.io/npm/v/typst-mcp.svg?style=flat-square)](https://www.npmjs.com/package/typst-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](./LICENSE)
+[![Node.js Package](https://github.com/caphefalumi/typst-web-mcp/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/caphefalumi/typst-web-mcp/actions/workflows/npm-publish.yml)
+[![Runtime: Bun](https://img.shields.io/badge/Runtime-Bun_%E2%89%A51.2-f9f1e1?style=flat-square&logo=bun&logoColor=black)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![MCP SDK](https://img.shields.io/badge/MCP-2024--11--05-10a37f?style=flat-square)](https://modelcontextprotocol.io)
+[![Protocol: Yjs + lib0](https://img.shields.io/badge/CRDT-Yjs_%2B_lib0_v3-ff69b4?style=flat-square)](./docs/PROTOCOL.md)
+[![Tests](https://img.shields.io/badge/Tests-7_Passing_(57_Assertions)-2ea44f?style=flat-square)](./test/typst-mcp.test.ts)
+
+</div>
+
+---
+
+## Overview
+
+`typst-web-mcp` connects AI coding and writing agents directly to collaborative [**typst.app**](https://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
+
+```mermaid
+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`](./docs/PROTOCOL.md) for the complete reverse-engineered protocol specification.
+
+---
+
+## MCP Tools (16 Tools)
+
+| Category | Tool Name | Description |
+|:---|:---|:---|
+| **Auth** | `typst_auth_login` | Authenticate with `https://typst.app` via email/password (`POST /v1/auth/signin`) or `__Http-typst-session` cookie, with browser fallback. |
+| **Auth** | `typst_auth_status` | Check active authentication state, login method, and stored session cookies. |
+| **Projects** | `typst_list_projects` | List all owned and shared/external projects in the user's `typst.app` dashboard (`DashboardContent`). |
+| **Projects** | `typst_get_project` | Retrieve full project metadata, access permissions, pinned compiler version, and file tree (`ProjectFiles`). |
+| **Projects** | `typst_create_project` | Create a new `typst.app` cloud project with initial `.typ`/`.bib` files and pinned compiler version. |
+| **Projects** | `typst_delete_project` | Permanently delete a `typst.app` project by ID (`DeleteProjectMutation`). |
+| **Files & CRDT** | `typst_list_files` | List all multiplayer Yjs text files and binary asset blobs in a project. |
+| **Files & CRDT** | `typst_read_file` | Read any project file — decodes binary Yjs CRDT state (`doc.getText("text")`) into UTF-8 text or base64 for binary assets. |
+| **Files & CRDT** | `typst_write_file` | Create or overwrite a `.typ`/`.bib`/`.toml` file, syncing Yjs state diffs over `/editing/v3` WebSocket and REST. |
+| **Files & CRDT** | `typst_edit_file` | Apply non-overlapping surgical `oldText -> newText` replacements directly to the `Y.Text("text")` CRDT. |
+| **Assets & Tree** | `typst_upload_asset` | Upload or replace binary assets (`PNG`, `JPG`, `SVG`, `PDF`, fonts) from a local path or base64 payload. |
+| **Assets & Tree** | `typst_rename_file` | Rename or move a file inside a `typst.app` project (`UpdatesFileMutation`). |
+| **Assets & Tree** | `typst_delete_file` | Delete a file or binary asset from a project (`DeleteFilesMutation`). |
+| **Compiler** | `typst_get_diagnostics` | Sync all cloud files and run `typst compile` to return structured errors, warnings, line/column spans, and hints. |
+| **Compiler** | `typst_export_pdf` | Sync all cloud text & binary assets, compile the project to PDF, and save to `outputPath`. |
+| **Preview** | `typst_capture_screenshot` | Capture high-DPI PNG preview screenshots (`mode="pages"` renders compiled PNG pages; `mode="browser"` screenshots the live `typst.app` web UI). |
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- [**Node.js**](https://nodejs.org/) `>= 18` (for `npx` install) or [**Bun**](https://bun.sh) `>= 1.2` (for local development)
+- [**Typst CLI**](https://github.com/typst/typst) (`typst` on `PATH` for `typst_get_diagnostics` and `typst_export_pdf`)
+
+### Installation
+
+**Recommended — no clone, no global install:**
+
+```bash
+npx -y typst-mcp
+```
+
+Use that same `npx -y typst-mcp` command in MCP config (see below). `-y` skips the install prompt.
+
+**From source (development):**
+
+```bash
+git clone https://github.com/caphefalumi/typst-web-mcp.git
+cd typst-web-mcp
+bun install
+bun run dev
+```
+
+### MCP Client Configuration
+
+Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`, `claude_desktop_config.json`, or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "typst-mcp": {
+      "command": "npx",
+      "args": ["-y", "typst-mcp"],
+      "env": {
+        "TYPST_EMAIL": "your-email@example.com",
+        "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
+
+```bash
+# Compile publishable output to dist/
+bun run build
+
+# Typecheck with strict TypeScript
+bun run typecheck
+
+# Run full unit, mock server, and live api.typst.app protocol test suite
+bun test
+```
+
+### Publishing to npm
+
+Matches [Canvas-CLI](https://github.com/caphefalumi/Canvas-CLI): GitHub **Release created** (or manual **workflow_dispatch**) runs [`.github/workflows/npm-publish.yml`](./.github/workflows/npm-publish.yml) — `bun ci`, `bun run build`, `npm publish` with OIDC environment `npm-publish` on npmjs.com.
+
+**One-time (new package name):** on [npmjs.com](https://www.npmjs.com) add a **Trusted Publisher** for package `typst-mcp` — GitHub Actions, org/user `caphefalumi`, repo `typst-web-mcp`, workflow `npm-publish.yml`, environment `npm-publish`, allow **npm publish**. First successful CI publish must happen within 2 days of creating that config.
+
+### Project Structure
+
+```text
+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](./LICENSE). Copyright (c) 2026 Dang Duy Toan (`caphefalumi`).

package/dist/client/auth.js

@@ -0,0 +1,310 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+const DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36";
+function extractRawSetCookies(headers) {
+    const headerWithGetSetCookie = headers;
+    if (typeof headerWithGetSetCookie.getSetCookie === "function") {
+        return headerWithGetSetCookie.getSetCookie();
+    }
+    const singleCookie = headers.get("set-cookie");
+    if (singleCookie) {
+        return [singleCookie];
+    }
+    return [];
+}
+function resolveSessionFilePath(configuredPath) {
+    if (configuredPath === undefined) {
+        return join(homedir(), ".pi", "agent", "typst-mcp-session.json");
+    }
+    return configuredPath;
+}
+export function parseSetCookieHeaders(headers) {
+    const result = {};
+    const rawList = extractRawSetCookies(headers);
+    for (const raw of rawList) {
+        const firstPart = raw.split(";")[0]?.trim();
+        if (!firstPart) {
+            continue;
+        }
+        const eqIdx = firstPart.indexOf("=");
+        if (eqIdx <= 0) {
+            continue;
+        }
+        const name = firstPart.slice(0, eqIdx).trim();
+        const val = firstPart.slice(eqIdx + 1).trim();
+        if (val === "") {
+            delete result[name];
+        }
+        else {
+            result[name] = val;
+        }
+    }
+    return result;
+}
+export function parseCookieString(cookieStr) {
+    const trimmed = cookieStr.trim();
+    if (!trimmed) {
+        return {};
+    }
+    if (!trimmed.includes("=")) {
+        return { "__Http-typst-session": trimmed };
+    }
+    const map = {};
+    for (const part of trimmed.split(";")) {
+        const p = part.trim();
+        if (!p) {
+            continue;
+        }
+        const eq = p.indexOf("=");
+        if (eq <= 0) {
+            continue;
+        }
+        const k = p.slice(0, eq).trim();
+        const v = p.slice(eq + 1).trim();
+        if (k && v) {
+            map[k] = v;
+        }
+    }
+    return map;
+}
+export class TypstAuthManager {
+    appUrl;
+    apiUrl;
+    sessionFilePath;
+    fetchImpl;
+    browserFallbackFn;
+    cookies = {};
+    authMethod = null;
+    email;
+    constructor(options = {}) {
+        const rawAppUrl = options.appUrl ?? process.env.TYPST_APP_URL ?? "https://typst.app";
+        const rawApiUrl = options.apiUrl ?? process.env.TYPST_API_URL ?? "https://api.typst.app";
+        this.appUrl = rawAppUrl.replace(/\/+$/, "");
+        this.apiUrl = rawApiUrl.replace(/\/+$/, "");
+        this.sessionFilePath = resolveSessionFilePath(options.sessionFilePath);
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.browserFallbackFn = options.browserFallbackFn;
+        this.loadStoredSession();
+        if (Object.keys(this.cookies).length === 0 &&
+            process.env.TYPST_SESSION_COOKIE) {
+            this.setSessionCookie(process.env.TYPST_SESSION_COOKIE);
+        }
+    }
+    loadStoredSession() {
+        if (!this.sessionFilePath || !existsSync(this.sessionFilePath)) {
+            return;
+        }
+        try {
+            const raw = JSON.parse(readFileSync(this.sessionFilePath, "utf8"));
+            if (raw && typeof raw.cookies === "object" && raw.cookies) {
+                this.cookies = { ...raw.cookies };
+                this.authMethod = raw.authMethod ?? "cookie";
+                this.email = raw.email;
+            }
+        }
+        catch {
+            // Ignore corrupted session file
+        }
+    }
+    saveStoredSession() {
+        if (!this.sessionFilePath) {
+            return;
+        }
+        try {
+            mkdirSync(dirname(this.sessionFilePath), { recursive: true });
+            const payload = {
+                cookies: this.cookies,
+                email: this.email,
+                authMethod: this.authMethod ?? "cookie",
+                updatedAt: new Date().toISOString(),
+            };
+            writeFileSync(this.sessionFilePath, JSON.stringify(payload, null, 2), "utf8");
+        }
+        catch {
+            // Non-fatal if filesystem is read-only
+        }
+    }
+    setSessionCookie(cookieInput, email) {
+        const parsed = parseCookieString(cookieInput);
+        this.cookies = { ...this.cookies, ...parsed };
+        this.authMethod = "cookie";
+        if (email) {
+            this.email = email;
+        }
+        this.saveStoredSession();
+    }
+    getCookieHeader() {
+        return Object.entries(this.cookies)
+            .map(([k, v]) => `${k}=${v}`)
+            .join("; ");
+    }
+    hasSession() {
+        return Boolean(this.cookies["__Http-typst-session"] ||
+            this.cookies["typst-session"] ||
+            this.cookies["session"]);
+    }
+    getStatus() {
+        return {
+            authenticated: this.hasSession(),
+            authMethod: this.authMethod,
+            email: this.email,
+            cookieNames: Object.keys(this.cookies),
+        };
+    }
+    async login(options = {}) {
+        const sessionCookie = options.sessionCookie ?? process.env.TYPST_SESSION_COOKIE;
+        const email = options.email ?? process.env.TYPST_EMAIL;
+        const password = options.password ?? process.env.TYPST_PASSWORD;
+        if (sessionCookie && (!email || !password)) {
+            this.setSessionCookie(sessionCookie, email);
+            return {
+                authenticated: this.hasSession(),
+                authMethod: "cookie",
+                email: this.email,
+                cookieNames: Object.keys(this.cookies),
+            };
+        }
+        if (!email || !password) {
+            if (sessionCookie) {
+                this.setSessionCookie(sessionCookie, email);
+                return {
+                    authenticated: this.hasSession(),
+                    authMethod: "cookie",
+                    email: this.email,
+                    cookieNames: Object.keys(this.cookies),
+                };
+            }
+            throw new Error("Missing credentials: provide email & password (or TYPST_EMAIL / TYPST_PASSWORD), or sessionCookie (TYPST_SESSION_COOKIE).");
+        }
+        // Step 1: Initialize pre-auth session cookie via GET /v1/to-signin
+        const initRes = await this.fetchImpl(`${this.apiUrl}/v1/to-signin`, {
+            method: "GET",
+            redirect: "manual",
+            headers: {
+                "User-Agent": DEFAULT_USER_AGENT,
+            },
+        });
+        const preAuthCookies = parseSetCookieHeaders(initRes.headers);
+        const mergedCookies = {
+            ...this.cookies,
+            ...preAuthCookies,
+        };
+        const cookieHeader = Object.entries(mergedCookies)
+            .map(([k, v]) => `${k}=${v}`)
+            .join("; ");
+        // Step 2: Submit credentials to POST /v1/auth/signin
+        const form = new URLSearchParams();
+        form.set("email", email);
+        form.set("password", password);
+        form.set("redirect", "");
+        form.set("grant-id", "");
+        form.set("captcha-trap", ""); // Honeypot field must remain empty
+        const signinRes = await this.fetchImpl(`${this.apiUrl}/v1/auth/signin`, {
+            method: "POST",
+            redirect: "manual",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Cookie: cookieHeader,
+                Origin: this.appUrl,
+                Referer: `${this.appUrl}/signin/`,
+                "User-Agent": DEFAULT_USER_AGENT,
+            },
+            body: form.toString(),
+        });
+        const postAuthCookies = parseSetCookieHeaders(signinRes.headers);
+        Object.assign(mergedCookies, postAuthCookies);
+        const location = signinRes.headers.get("location") ?? "";
+        const isChallengeOrBlocked = signinRes.status === 403 ||
+            signinRes.status === 429 ||
+            location.includes("captcha") ||
+            location.includes("challenge");
+        const isInvalidCredentials = signinRes.status === 401 ||
+            location.includes("error=") ||
+            location.includes("invalid");
+        if (!isChallengeOrBlocked &&
+            !isInvalidCredentials &&
+            (signinRes.status === 200 ||
+                signinRes.status === 302 ||
+                signinRes.status === 303) &&
+            (mergedCookies["__Http-typst-session"] || mergedCookies["typst-session"])) {
+            this.cookies = mergedCookies;
+            this.authMethod = "api-password";
+            this.email = email;
+            this.saveStoredSession();
+            return {
+                authenticated: true,
+                authMethod: "api-password",
+                email,
+                cookieNames: Object.keys(this.cookies),
+            };
+        }
+        // Step 3: Automatic fallback to cookie or browser session if Turnstile/CAPTCHA challenge occurs
+        if (options.useBrowserFallback !== false &&
+            (isChallengeOrBlocked || !this.hasSession())) {
+            if (sessionCookie) {
+                this.setSessionCookie(sessionCookie, email);
+                return {
+                    authenticated: this.hasSession(),
+                    authMethod: "cookie",
+                    email,
+                    cookieNames: Object.keys(this.cookies),
+                };
+            }
+            const fallbackRunner = this.browserFallbackFn ?? defaultPlaywrightBrowserFallback;
+            if (fallbackRunner) {
+                const fallbackCookies = await fallbackRunner(this.appUrl, this.apiUrl, email, password);
+                this.cookies = { ...mergedCookies, ...fallbackCookies };
+                this.authMethod = "browser-fallback";
+                this.email = email;
+                this.saveStoredSession();
+                return {
+                    authenticated: this.hasSession(),
+                    authMethod: "browser-fallback",
+                    email,
+                    cookieNames: Object.keys(this.cookies),
+                };
+            }
+        }
+        let redirectDetail = "";
+        if (location) {
+            redirectDetail = `, redirect: ${location}`;
+        }
+        throw new Error(`Sign-in failed (HTTP ${signinRes.status}${redirectDetail}). Verify TYPST_EMAIL/TYPST_PASSWORD or supply TYPST_SESSION_COOKIE.`);
+    }
+}
+export const defaultPlaywrightBrowserFallback = async (appUrl, _apiUrl, email, password) => {
+    const { spawnSync } = await import("node:child_process");
+    const pyScript = `
+import json, os
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(channel="msedge", headless=True)
+    ctx = browser.new_context()
+    page = ctx.new_page()
+    page.goto(os.environ["TYPST_FB_URL"] + "/signin/", wait_until="networkidle")
+    page.fill("input[name='email']", os.environ["TYPST_FB_EMAIL"])
+    page.fill("input[name='password']", os.environ["TYPST_FB_PASS"])
+    page.click("input[type='submit']")
+    page.wait_for_load_state("networkidle")
+    cookies = {c["name"]: c["value"] for c in ctx.cookies()}
+    print(json.dumps(cookies))
+    browser.close()
+`;
+    const proc = spawnSync("python", ["-c", pyScript], {
+        env: {
+            ...process.env,
+            TYPST_FB_URL: appUrl,
+            TYPST_FB_EMAIL: email,
+            TYPST_FB_PASS: password,
+        },
+        encoding: "utf8",
+        timeout: 30000,
+    });
+    if (proc.status !== 0 || !proc.stdout.trim()) {
+        throw new Error(`Playwright browser fallback failed: ${proc.stderr || "no output"}`);
+    }
+    const lines = proc.stdout.trim().split(/\r\n|\n/);
+    return JSON.parse(lines[lines.length - 1]);
+};