typst-mcp 1.0.2 → 1.1.0

package/README.md

@@ -4,73 +4,15 @@
 
 **Model Context Protocol (MCP) server for [`https://typst.app`](https://typst.app) — cloud projects, Yjs CRDT editing, and Typst compiler diagnostics**
 
-Install from npm as [`typst-mcp`](https://www.npmjs.com/package/typst-mcp). Source repo: [`typst-web-mcp`](https://github.com/caphefalumi/typst-web-mcp).
-
 [![npm version](https://img.shields.io/npm/v/typst-mcp.svg?style=flat-square)](https://www.npmjs.com/package/typst-mcp)
 [![Downloads](https://img.shields.io/npm/dt/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)
-[![CI](https://github.com/caphefalumi/typst-web-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/caphefalumi/typst-web-mcp/actions/workflows/ci.yml)
 [![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-mcp\n(Node / 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
@@ -120,6 +62,58 @@ Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`,
 
 ---
 
+## 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-mcp\n(Node / 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 (18 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 with offset/limit pagination, optional line numbering, truncation limits (2,000 lines/50KB), and multimodal MCP image content blocks (`PNG`, `JPG`, `SVG`, `WebP`). |
+| **Files & CRDT** | `typst_write_file` | Create or overwrite a `.typ`/`.bib`/`.toml` file, protected by per-file mutation queue serialization, syncing Yjs state diffs over `/editing/v3` WebSocket and REST. |
+| **Files & CRDT** | `typst_edit_file` | Apply surgical `oldText -> newText` replacements directly to the `Y.Text("text")` CRDT with CRLF/BOM resilience, fuzzy quote/dash matching, unified diff & patch output, and per-file mutation serialization. |
+| **Search & Replace** | `typst_grep_project` | Search for text or regular expressions across project files, returning file paths, line numbers, and optional surrounding context lines. |
+| **Search & Replace** | `typst_find_and_replace` | Find and replace text or regex across a single file or project-wide with regex capture groups (`$1`), dry-run preview diffs, and per-file mutation serialization. |
+| **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). |
+
+---
+
 ## Development & Verification
 
 ```bash
@@ -157,6 +151,7 @@ typst-web-mcp/
 │   └── PROTOCOL.md              # Reverse-engineered typst.app REST, GraphQL, Yjs & WS v3 spec
 ├── src/
 │   ├── protocol/
+│   │   ├── edit-diff.ts         # Fuzzy matching, CRLF/BOM resilience, unified diff & patch generator
 │   │   ├── 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
@@ -167,6 +162,10 @@ typst-web-mcp/
 │   │   └── typst-client.ts      # TypstCloudClient (REST, GraphQL, WebSocket v3, Compiler facade)
 │   ├── tools/
 │   │   └── definitions.ts       # MCP JSON Schema definitions for all 16 tools
+│   ├── utils/
+│   │   ├── file-mutation-queue.ts # Serialized mutation mutex queue per file
+│   │   ├── mime.ts              # Image MIME type detection
+│   │   └── truncate.ts          # Dual-limit (line & byte) head/tail truncation utilities
 │   └── index.ts                 # MCP stdio server entrypoint (dev); npm bin runs dist/index.js
 ├── test/
 │   └── typst-mcp.test.ts        # 7 test suites (57 assertions) covering codecs, CRDTs & E2E

package/dist/client/typst-client.js

@@ -7,6 +7,10 @@ import { captureBrowserPreviewScreenshot, captureWorkspacePageScreenshots, compi
 import { CREATE_PROJECT_MUTATION, DASHBOARD_CONTENT_QUERY, DELETE_FILES_MUTATION, DELETE_PROJECT_MUTATION, PROJECT_FILES_QUERY, UPDATE_FILES_MUTATION, } from "../protocol/graphql.js";
 import { decodeYjsText, editYjsText, replaceYjsText, } from "../protocol/yjs-doc.js";
 import { decodeMessage, encodeMessage, MessageKind, } from "../protocol/ws-codec.js";
+import { truncateHead, formatSize, } from "../utils/truncate.js";
+import { detectSupportedImageMimeType } from "../utils/mime.js";
+import { withFileMutationQueue } from "../utils/file-mutation-queue.js";
+import { matchGlob, searchInContent, replaceInContent, } from "../protocol/search-replace.js";
 export { TypstLoadError, resolveTypstBinary };
 const URL_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 export function generateClientId(size = 8) {
@@ -215,22 +219,102 @@ export class TypstCloudClient {
         const { response } = await this.restCall("GET", `files/${projectId}/${fileId}`);
         return new Uint8Array(await response.arrayBuffer());
     }
-    async readFile(projectId, fileIdOrPath) {
+    async readFile(projectId, fileIdOrPath, options) {
         const file = await this.resolveFile(projectId, fileIdOrPath);
         if (file.isMultiplayable) {
             const yjsBytes = await this.downloadFileYjs(projectId, file.id);
             const text = decodeYjsText(yjsBytes);
+            const allLines = text.split("\n");
+            const totalLines = allLines.length;
+            if (options?.offset !== undefined && options.offset > totalLines) {
+                throw new Error(`Offset ${options.offset} is beyond end of file (${totalLines} lines total)`);
+            }
+            const startLine = options?.offset ? Math.max(0, options.offset - 1) : 0;
+            const startLineDisplay = startLine + 1;
+            let selectedContent;
+            let userLimitedLines;
+            if (options?.limit !== undefined) {
+                const endLine = Math.min(startLine + options.limit, totalLines);
+                selectedContent = allLines.slice(startLine, endLine).join("\n");
+                userLimitedLines = endLine - startLine;
+            }
+            else {
+                selectedContent = allLines.slice(startLine).join("\n");
+            }
+            const truncation = truncateHead(selectedContent, {
+                maxLines: options?.maxLines,
+                maxBytes: options?.maxBytes,
+            });
+            let outputText;
+            let endLineDisplay = startLineDisplay;
+            if (truncation.firstLineExceedsLimit) {
+                const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine] ?? "", "utf-8"));
+                outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(truncation.maxBytes)} limit]`;
+            }
+            else if (truncation.truncated) {
+                endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+                const nextOffset = endLineDisplay + 1;
+                let body = truncation.content;
+                if (options?.lineNumbers) {
+                    const lines = body.split("\n");
+                    const width = String(endLineDisplay).length;
+                    body = lines
+                        .map((line, idx) => `${String(startLineDisplay + idx).padStart(width, " ")} | ${line}`)
+                        .join("\n");
+                }
+                if (truncation.truncatedBy === "lines") {
+                    outputText = `${body}\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
+                }
+                else {
+                    outputText = `${body}\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalLines} (${formatSize(truncation.maxBytes)} limit). Use offset=${nextOffset} to continue.]`;
+                }
+            }
+            else if (userLimitedLines !== undefined &&
+                startLine + userLimitedLines < totalLines) {
+                endLineDisplay = startLine + userLimitedLines;
+                const remaining = totalLines - endLineDisplay;
+                const nextOffset = endLineDisplay + 1;
+                let body = truncation.content;
+                if (options?.lineNumbers) {
+                    const lines = body.split("\n");
+                    const width = String(endLineDisplay).length;
+                    body = lines
+                        .map((line, idx) => `${String(startLineDisplay + idx).padStart(width, " ")} | ${line}`)
+                        .join("\n");
+                }
+                outputText = `${body}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
+            }
+            else {
+                endLineDisplay = totalLines;
+                let body = truncation.content;
+                if (options?.lineNumbers) {
+                    const lines = body.split("\n");
+                    const width = String(startLineDisplay + lines.length - 1).length;
+                    body = lines
+                        .map((line, idx) => `${String(startLineDisplay + idx).padStart(width, " ")} | ${line}`)
+                        .join("\n");
+                }
+                outputText = body;
+            }
             return {
                 file,
-                content: text,
+                content: outputText,
                 encoding: "utf-8",
+                totalLines,
+                startLine: startLineDisplay,
+                endLine: endLineDisplay,
+                truncation: truncation.truncated ? truncation : undefined,
             };
         }
         const blob = await this.downloadFileBlob(projectId, file.id);
+        const mimeType = detectSupportedImageMimeType(file.name);
+        const isImage = Boolean(mimeType && mimeType.startsWith("image/"));
         return {
             file,
             content: Buffer.from(blob).toString("base64"),
             encoding: "base64",
+            mimeType,
+            isImage,
         };
     }
     async pushYjsUpdateViaWebSocket(projectId, fileId, encodedUpdate, timeoutMs = 5000) {
@@ -342,61 +426,68 @@ export class TypstCloudClient {
         return { syncChannel };
     }
     async writeFile(projectId, filePathOrId, content, options) {
-        const files = await this.listFiles(projectId);
         const normalized = filePathOrId.replace(/^\/+/, "");
-        const existing = files.find((f) => f.id === filePathOrId) ??
-            files.find((f) => f.name === normalized || f.name === filePathOrId);
-        if (existing) {
-            if (existing.isMultiplayable) {
-                const remote = await this.downloadFileYjs(projectId, existing.id);
-                const { encodedUpdate } = replaceYjsText(remote, content);
-                const { syncChannel } = await this.saveYjsUpdate(projectId, existing.id, encodedUpdate, options?.preferWebSocket ?? true);
+        return withFileMutationQueue(`${projectId}:${normalized}`, async () => {
+            const files = await this.listFiles(projectId);
+            const existing = files.find((f) => f.id === filePathOrId) ??
+                files.find((f) => f.name === normalized || f.name === filePathOrId);
+            if (existing) {
+                if (existing.isMultiplayable) {
+                    const remote = await this.downloadFileYjs(projectId, existing.id);
+                    const { encodedUpdate } = replaceYjsText(remote, content);
+                    const { syncChannel } = await this.saveYjsUpdate(projectId, existing.id, encodedUpdate, options?.preferWebSocket ?? true);
+                    return {
+                        file: existing,
+                        created: false,
+                        bytesWritten: Buffer.byteLength(content, "utf8"),
+                        syncChannel,
+                    };
+                }
+                const rawBytes = new TextEncoder().encode(content);
+                const { response } = await this.restCall("PUT", `files/${projectId}/${existing.id}`, { body: rawBytes });
+                const updatedMeta = (await response.json());
                 return {
-                    file: existing,
+                    file: updatedMeta,
                     created: false,
-                    bytesWritten: Buffer.byteLength(content, "utf8"),
-                    syncChannel,
+                    bytesWritten: rawBytes.byteLength,
+                    syncChannel: "rest",
                 };
             }
             const rawBytes = new TextEncoder().encode(content);
-            const { response } = await this.restCall("PUT", `files/${projectId}/${existing.id}`, { body: rawBytes });
-            const updatedMeta = (await response.json());
+            const { response } = await this.restCall("POST", `files/${projectId}`, {
+                queryParams: { name: normalized, convert: "false" },
+                body: rawBytes,
+            });
+            const body = (await response.json());
+            const createdMeta = unwrapSingleOrFirstFile(body);
             return {
-                file: updatedMeta,
-                created: false,
+                file: createdMeta,
+                created: true,
                 bytesWritten: rawBytes.byteLength,
                 syncChannel: "rest",
             };
-        }
-        const rawBytes = new TextEncoder().encode(content);
-        const { response } = await this.restCall("POST", `files/${projectId}`, {
-            queryParams: { name: normalized, convert: "false" },
-            body: rawBytes,
         });
-        const body = (await response.json());
-        const createdMeta = unwrapSingleOrFirstFile(body);
-        return {
-            file: createdMeta,
-            created: true,
-            bytesWritten: rawBytes.byteLength,
-            syncChannel: "rest",
-        };
     }
     async editFile(projectId, filePathOrId, edits, options) {
         const file = await this.resolveFile(projectId, filePathOrId);
         if (!file.isMultiplayable) {
             throw new TypstLoadError(["NOT_MULTIPLAYABLE"], `File "${file.name}" is a binary blob and cannot be surgically text-edited`);
         }
-        const remote = await this.downloadFileYjs(projectId, file.id);
-        const { encodedUpdate, previousText, updatedText, appliedCount } = editYjsText(remote, edits);
-        const { syncChannel } = await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options?.preferWebSocket ?? true);
-        return {
-            file,
-            appliedCount,
-            previousLength: previousText.length,
-            updatedLength: updatedText.length,
-            syncChannel,
-        };
+        return withFileMutationQueue(`${projectId}:${file.id}`, async () => {
+            const remote = await this.downloadFileYjs(projectId, file.id);
+            const { encodedUpdate, previousText, updatedText, appliedCount, diff, patch, firstChangedLine, } = editYjsText(remote, edits, file.name);
+            const { syncChannel } = await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options?.preferWebSocket ?? true);
+            return {
+                file,
+                appliedCount,
+                previousLength: previousText.length,
+                updatedLength: updatedText.length,
+                diff,
+                patch,
+                firstChangedLine,
+                syncChannel,
+            };
+        });
     }
     async uploadAsset(projectId, fileName, data, options) {
         const normalized = fileName.replace(/^\/+/, "");
@@ -542,4 +633,93 @@ export class TypstCloudClient {
             rmSync(workspaceDir, { recursive: true, force: true });
         }
     }
+    async grepProject(projectId, options) {
+        const files = await this.listFiles(projectId);
+        const limit = options.limit ?? 100;
+        const allMatches = [];
+        let totalMatches = 0;
+        let filesSearched = 0;
+        for (const file of files) {
+            if (!file.isMultiplayable)
+                continue;
+            if (options.path) {
+                const normalizedPath = options.path.replace(/^\/+/, "");
+                if (file.name !== normalizedPath &&
+                    !file.name.startsWith(`${normalizedPath}/`) &&
+                    file.id !== options.path) {
+                    continue;
+                }
+            }
+            if (options.glob && !matchGlob(file.name, options.glob)) {
+                continue;
+            }
+            filesSearched++;
+            const yjsBytes = await this.downloadFileYjs(projectId, file.id);
+            const text = decodeYjsText(yjsBytes);
+            const remainingLimit = Math.max(0, limit - allMatches.length);
+            const result = searchInContent(file.name, text, {
+                pattern: options.pattern,
+                literal: options.literal,
+                ignoreCase: options.ignoreCase,
+                context: options.context,
+                limit: remainingLimit,
+            });
+            totalMatches += result.totalMatches;
+            allMatches.push(...result.matches);
+        }
+        return {
+            matches: allMatches,
+            totalMatches,
+            filesSearched,
+            truncated: totalMatches > allMatches.length,
+        };
+    }
+    async findAndReplace(projectId, options) {
+        const files = await this.listFiles(projectId);
+        const filesModified = [];
+        let totalReplacements = 0;
+        for (const file of files) {
+            if (!file.isMultiplayable)
+                continue;
+            if (options.filePath) {
+                const normalizedPath = options.filePath.replace(/^\/+/, "");
+                if (file.name !== normalizedPath && file.id !== options.filePath) {
+                    continue;
+                }
+            }
+            if (options.glob && !matchGlob(file.name, options.glob)) {
+                continue;
+            }
+            await withFileMutationQueue(`${projectId}:${file.id}`, async () => {
+                const remote = await this.downloadFileYjs(projectId, file.id);
+                const text = decodeYjsText(remote);
+                const repResult = replaceInContent(file.name, text, {
+                    pattern: options.pattern,
+                    replacement: options.replacement,
+                    regex: options.regex,
+                    ignoreCase: options.ignoreCase,
+                    limit: options.limit,
+                });
+                if (repResult.replacementCount > 0) {
+                    if (!options.dryRun) {
+                        const { encodedUpdate } = replaceYjsText(remote, repResult.updatedText);
+                        await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options.preferWebSocket ?? true);
+                    }
+                    filesModified.push({
+                        file: file.name,
+                        replacementsCount: repResult.replacementCount,
+                        diff: repResult.diff,
+                        patch: repResult.patch,
+                        firstChangedLine: repResult.firstChangedLine,
+                    });
+                    totalReplacements += repResult.replacementCount;
+                }
+            });
+        }
+        return {
+            filesModified,
+            totalReplacements,
+            dryRun: Boolean(options.dryRun),
+        };
+    }
 }

package/dist/index.js

@@ -21,6 +21,34 @@ function resolveOptionalNumber(value) {
     }
     return undefined;
 }
+export function prepareEditArguments(input) {
+    if (!input)
+        return [];
+    if (Array.isArray(input)) {
+        return input.filter((e) => e && typeof e.oldText === "string" && typeof e.newText === "string");
+    }
+    if (typeof input === "string") {
+        try {
+            const parsed = JSON.parse(input);
+            if (Array.isArray(parsed)) {
+                return parsed.filter((e) => e && typeof e.oldText === "string" && typeof e.newText === "string");
+            }
+            if (parsed &&
+                typeof parsed.oldText === "string" &&
+                typeof parsed.newText === "string") {
+                return [parsed];
+            }
+        }
+        catch { }
+    }
+    if (typeof input === "object" && input !== null) {
+        const obj = input;
+        if (typeof obj.oldText === "string" && typeof obj.newText === "string") {
+            return [{ oldText: obj.oldText, newText: obj.newText }];
+        }
+    }
+    return [];
+}
 export async function dispatchTypstTool(client, name, args = {}) {
     switch (name) {
         case "typst_auth_login":
@@ -51,15 +79,28 @@ export async function dispatchTypstTool(client, name, args = {}) {
         case "typst_list_files":
             return await client.listFiles(String(args.projectId));
         case "typst_read_file":
-            return await client.readFile(String(args.projectId), String(args.filePath));
+            return await client.readFile(String(args.projectId), String(args.filePath), {
+                offset: resolveOptionalNumber(args.offset),
+                limit: resolveOptionalNumber(args.limit),
+                lineNumbers: typeof args.lineNumbers === "boolean"
+                    ? args.lineNumbers
+                    : undefined,
+            });
         case "typst_write_file":
             return await client.writeFile(String(args.projectId), String(args.filePath), String(args.content), {
                 preferWebSocket: resolvePreferWebSocket(args.preferWebSocket),
             });
-        case "typst_edit_file":
-            return await client.editFile(String(args.projectId), String(args.filePath), args.edits ?? [], {
+        case "typst_edit_file": {
+            let edits = prepareEditArguments(args.edits);
+            if (edits.length === 0 &&
+                typeof args.oldText === "string" &&
+                typeof args.newText === "string") {
+                edits = [{ oldText: args.oldText, newText: args.newText }];
+            }
+            return await client.editFile(String(args.projectId), String(args.filePath), edits, {
                 preferWebSocket: resolvePreferWebSocket(args.preferWebSocket),
             });
+        }
         case "typst_upload_asset": {
             let bytes;
             if (typeof args.localFilePath === "string" && args.localFilePath) {
@@ -93,6 +134,28 @@ export async function dispatchTypstTool(client, name, args = {}) {
                 mode: args.mode ?? "pages",
                 includeBase64: Boolean(args.includeBase64),
             });
+        case "typst_grep_project":
+            return await client.grepProject(String(args.projectId), {
+                pattern: String(args.pattern),
+                path: args.path,
+                glob: args.glob,
+                literal: Boolean(args.literal),
+                ignoreCase: Boolean(args.ignoreCase),
+                context: resolveOptionalNumber(args.context),
+                limit: resolveOptionalNumber(args.limit),
+            });
+        case "typst_find_and_replace":
+            return await client.findAndReplace(String(args.projectId), {
+                pattern: String(args.pattern),
+                replacement: String(args.replacement),
+                filePath: args.filePath,
+                glob: args.glob,
+                regex: Boolean(args.regex),
+                ignoreCase: Boolean(args.ignoreCase),
+                limit: resolveOptionalNumber(args.limit),
+                dryRun: Boolean(args.dryRun),
+                preferWebSocket: resolvePreferWebSocket(args.preferWebSocket),
+            });
         default:
             throw new Error(`Unknown tool: ${name}`);
     }
@@ -101,7 +164,7 @@ export function createTypstMcpServer(options = {}) {
     const client = new TypstCloudClient(options);
     const server = new Server({
         name: "typst-mcp",
-        version: "1.0.0",
+        version: "1.1.0",
     }, {
         capabilities: {
             tools: {},
@@ -114,6 +177,32 @@ export function createTypstMcpServer(options = {}) {
         const { name, arguments: args } = request.params;
         try {
             const result = await dispatchTypstTool(client, name, args ?? {});
+            if (name === "typst_read_file" &&
+                typeof result === "object" &&
+                result !== null &&
+                Boolean(result.isImage) &&
+                typeof result.mimeType === "string" &&
+                typeof result.content === "string") {
+                const img = result;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                file: img.file,
+                                encoding: img.encoding,
+                                mimeType: img.mimeType,
+                                isImage: true,
+                            }, null, 2),
+                        },
+                        {
+                            type: "image",
+                            data: img.content,
+                            mimeType: img.mimeType,
+                        },
+                    ],
+                };
+            }
             return {
                 content: [
                     {