typst-mcp 1.2.0 → 1.3.0

package/README.md

@@ -13,48 +13,44 @@
 
 ---
 
-## Quick Start
+## Installation
+
+Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`, `claude_desktop_config.json`, or `.cursor/mcp.json`).
 
 ### Prerequisites
 
-- [**Node.js**](https://nodejs.org/) `>= 18` (for `npx` install) or [**Bun**](https://bun.sh) `>= 1.2` (for local development)
+- [**Node.js**](https://nodejs.org/) `>= 18`
 - [**Typst CLI**](https://github.com/typst/typst) (optional: `typst` on `PATH` for local CLI compilation speed; if not installed, `typst_get_diagnostics` automatically uses Typst Web cloud compiler diagnostics)
 
-### Installation
-
-**Option 1: Quick start (no clone, no global install):**
-
-```bash
-npx -y typst-mcp
-```
-
-**Option 2: Always run latest release (bypasses local `npx` cache):**
-
-```bash
-npx -y typst-mcp@latest
-```
-
-Runs the published [`typst-mcp`](https://www.npmjs.com/package/typst-mcp) package (Node `>= 18`). `-y` skips the npx confirmation prompt.
+### Option 1: Normal (Standard)
 
-**Option 3: From source (development):**
+Runs the published [`typst-mcp`](https://www.npmjs.com/package/typst-mcp) package (`npx -y typst-mcp`):
 
-```bash
-git clone https://github.com/caphefalumi/typst-web-mcp.git
-cd typst-web-mcp
-bun install
-bun run dev
+```json
+{
+  "mcpServers": {
+    "typst-mcp": {
+      "command": "npx",
+      "args": ["-y", "typst-mcp"],
+      "env": {
+        "TYPST_EMAIL": "your-email@example.com",
+        "TYPST_PASSWORD": "your-password"
+      }
+    }
+  }
+}
 ```
 
-### MCP Client Configuration
+### Option 2: Always Latest
 
-Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`, `claude_desktop_config.json`, or `.cursor/mcp.json`):
+Bypasses local `npx` cache to automatically pull and run the newest release on launch (`npx -y typst-mcp@latest`):
 
 ```json
 {
   "mcpServers": {
     "typst-mcp": {
       "command": "npx",
-      "args": ["-y", "typst-mcp"],
+      "args": ["-y", "typst-mcp@latest"],
       "env": {
         "TYPST_EMAIL": "your-email@example.com",
         "TYPST_PASSWORD": "your-password"
@@ -64,10 +60,6 @@ Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`,
 }
 ```
 
-> **Tip:** You can also set `"args": ["-y", "typst-mcp@latest"]` to guarantee your MCP client automatically pulls and runs the newest version on launch.
-
-> **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.
-
 ---
 
 ## Overview
@@ -93,11 +85,11 @@ Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`,
 | **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_read_file` | Read bounded source pages (200 lines/16 KiB by default), with compact metadata, whole-file content hashes, separate continuation fields, and native image blocks. |
 | **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. |
+| **Files & CRDT** | `typst_edit_file` | Apply validated, unique edits to one snapshot with optional stale-content protection, exact matching by default, compact receipts, opt-in fuzzy fallback, and bounded diff previews. |
 | **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. |
+| **Search & Replace** | `typst_find_and_replace` | Replace text or regex in one file or project-wide. Batch ordered replacement rules in one call with one save per changed file, compact summaries, optional diffs, and dry-run previews. |
 | **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`). |
@@ -107,8 +99,96 @@ Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`,
 
 ---
 
+## Read and edit efficiently
+
+1. Use `typst_grep_project` to locate relevant text, then read just that range with `typst_read_file` (`offset` is 1-based, `limit` defaults to 200 lines, `maxBytes` defaults to 16 KiB and can be raised to 1 MiB).
+2. Keep the returned `contentHash`. It is SHA-256 of the **entire raw text file**, including BOM and line endings, even when reading a range or displaying line numbers.
+3. Send all disjoint edits in one `typst_edit_file` call, with `expectedHash` set to that hash. Prefer a short unique `oldText` anchor over repeating a whole file.
+
+```json
+{
+  "projectId": "your-project-id",
+  "filePath": "main.typ",
+  "expectedHash": "<contentHash from the read response>",
+  "edits": [
+    { "oldText": "September 2025", "newText": "September 2026" }
+  ]
+}
+```
+
+Text read responses include source only in `content`, with `totalLines`, `startLine`, `endLine`, `truncated`, and `nextOffset` when more source remains. They never repeat source in truncation metadata or append instructions to it. Complete lines and original line endings are retained, so unnumbered pages can be concatenated without losing bytes. A trailing newline does not create a phantom extra line. An empty file has `totalLines: 0`, `startLine: 1`, `endLine: 0`.
+
+Read metadata defaults to `{id, name}`. Use `output: "full"` for full file metadata; this does not increase the source range. `lineNumbers: true` adds display prefixes: remove those prefixes when constructing `oldText`. Byte budgets include those prefixes. If one line cannot fit, the tool returns an actionable error rather than an empty page that cannot advance.
+
+Edits match against the same original snapshot, not the result of previous edits. All entries must be valid, and each anchor must be unique, including overlapping occurrences. Invalid batches, overlapping ranges, and stale hashes fail before saving. `matchMode: "exact"` is the default and accepts LF/CRLF differences. Use `matchMode: "fuzzy"` to opt into Unicode quote/dash/space and NFKC fallback when no exact match exists. Fallback matching preserves characters outside the matched span. Edits retain the BOM and untouched line endings, including mixed LF/CRLF files.
+
+Successful edits return a compact receipt with file ID/name, `appliedCount`, the resulting `contentHash`, and `firstChangedLine`. This avoids returning the same changes as both a diff and a patch. Optional controls:
+
+- `output: "diff"` adds a display diff; `output: "full"` also adds a patch and full metadata.
+- Each diff/patch field is limited to 100 lines and `maxDiffBytes` bytes (default 8192, maximum 1 MiB). `diffTruncated` / `patchTruncated` explicitly flag omissions; read the affected range for complete source.
+- `dryRun: true` validates and previews without saving and defaults to diff output. Its `appliedCount` describes proposed edits; its `contentHash` still identifies the unchanged cloud text.
+
+`expectedHash` is checked on fresh text inside the shared file mutation queue, which serializes local edits, replacements, and whole-file writes to existing files. It detects changes made since the read; it is not a cloud compare-and-swap transaction and cannot prevent a collaborator from editing during the subsequent save. Yjs still merges concurrent cloud updates.
+
+**Changed defaults:** reads previously allowed 2,000 lines/50 KiB and embedded continuation hints in `content`. Read callers should follow `nextOffset` now. MCP edits previously returned full diffs/patches and used fuzzy fallback automatically; request `output: "full"` or `matchMode: "fuzzy"` explicitly when needed. The low-level `editYjsText` helper retains its legacy fuzzy default; the client/MCP edit path defaults to exact matching.
+
+## Batch replacements for agents
+
+Use one `typst_find_and_replace` call for related replacements. For example, expand abbreviated month names throughout all `.typ` files:
+
+```json
+{
+  "projectId": "your-project-id",
+  "glob": "*.typ",
+  "replacements": [
+    { "pattern": "\\bSep\\b", "replacement": "September", "regex": true },
+    { "pattern": "\\bOct\\b", "replacement": "October", "regex": true }
+  ]
+}
+```
+
+Each file is downloaded once, all rules run in order on the previous rule's result, and the file is saved once if its final text changed. All rules are validated before any files are written. File mutations remain serialized with other edits; a project-wide operation is **not atomic across files** if a network or save error occurs.
+
+Batch calls default to `output: "summary"`:
+
+```json
+{
+  "filesModified": [
+    {
+      "file": "main.typ",
+      "replacementsCount": 3,
+      "replacementCounts": [2, 1],
+      "firstChangedLine": 4
+    }
+  ],
+  "totalReplacements": 3,
+  "dryRun": false
+}
+```
+
+`replacementCounts` follows the input rule order and counts matches applied by each rule in that changed file. Unchanged files, including batches whose rules cancel each other out, are omitted and do not contribute to totals.
+
+- Set `dryRun: true` to preview without saving. Add `output: "diff"` to include a single combined display diff per file.
+- Set `output: "full"` to include both the display diff and unified patch.
+- Set `regex`, `ignoreCase`, and `limit` on each batch rule. `limit` is a non-negative integer per rule per file; `0` disables that rule.
+- Use either `replacements` or the existing `pattern`/`replacement` fields. Existing single-replacement calls still default to `output: "full"`; they can request `"summary"` too.
+- Use `filePath` to target one file by path or ID. A missing explicit file returns an error.
+
 ## Development & Verification
 
+### From Source (Development)
+
+Requires [**Bun**](https://bun.sh) `>= 1.2`:
+
+```bash
+git clone https://github.com/caphefalumi/typst-web-mcp.git
+cd typst-web-mcp
+bun install
+bun run dev
+```
+
+### Build & Test
+
 ```bash
 # Compile publishable output to dist/
 bun run build

package/dist/client/auth.js

@@ -13,9 +13,31 @@ function extractRawSetCookies(headers) {
     }
     return [];
 }
+export function getDefaultSessionFilePath() {
+    if (process.env.TYPST_SESSION_FILE) {
+        return process.env.TYPST_SESSION_FILE;
+    }
+    const platform = process.platform;
+    if (platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ||
+            (process.env.APPDATA
+                ? join(process.env.APPDATA, "..", "Local")
+                : join(homedir(), "AppData", "Local"));
+        return join(localAppData, "typst-mcp", "session.json");
+    }
+    if (platform === "darwin") {
+        if (process.env.XDG_CACHE_HOME) {
+            return join(process.env.XDG_CACHE_HOME, "typst-mcp", "session.json");
+        }
+        return join(homedir(), "Library", "Caches", "typst-mcp", "session.json");
+    }
+    // Linux and other POSIX systems (XDG Base Directory specification)
+    const cacheDir = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+    return join(cacheDir, "typst-mcp", "session.json");
+}
 function resolveSessionFilePath(configuredPath) {
     if (configuredPath === undefined) {
-        return join(homedir(), ".pi", "agent", "typst-mcp-session.json");
+        return getDefaultSessionFilePath();
     }
     return configuredPath;
 }
@@ -92,11 +114,22 @@ export class TypstAuthManager {
         }
     }
     loadStoredSession() {
-        if (!this.sessionFilePath || !existsSync(this.sessionFilePath)) {
+        if (!this.sessionFilePath) {
             return;
         }
+        let targetPath = this.sessionFilePath;
+        if (!existsSync(targetPath)) {
+            // Legacy fallback check for seamless migration from ~/.pi/agent/typst-mcp-session.json
+            const legacyPath = join(homedir(), ".pi", "agent", "typst-mcp-session.json");
+            if (existsSync(legacyPath)) {
+                targetPath = legacyPath;
+            }
+            else {
+                return;
+            }
+        }
         try {
-            const raw = JSON.parse(readFileSync(this.sessionFilePath, "utf8"));
+            const raw = JSON.parse(readFileSync(targetPath, "utf8"));
             if (raw && typeof raw.cookies === "object" && raw.cookies) {
                 this.cookies = { ...raw.cookies };
                 this.authMethod = raw.authMethod ?? "cookie";

package/dist/client/typst-client.js

@@ -7,10 +7,11 @@ import { captureBrowserPreviewScreenshot, captureWebDiagnostics, captureWorkspac
 import { CREATE_PROJECT_MUTATION, DASHBOARD_CONTENT_QUERY, DELETE_FILES_MUTATION, DELETE_PROJECT_MUTATION, EDIT_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 { readTextContent, validateReadOptions, hashText } from "../protocol/read-content.js";
+import { validateEdits } from "../protocol/edit-diff.js";
 import { detectSupportedImageMimeType } from "../utils/mime.js";
 import { withFileMutationQueue } from "../utils/file-mutation-queue.js";
-import { matchGlob, searchInContent, replaceInContent, } from "../protocol/search-replace.js";
+import { matchGlob, searchInContent, replaceBatchInContent, resolveReplacementRules, } from "../protocol/search-replace.js";
 export { TypstLoadError, resolveTypstBinary };
 const URL_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 export function generateClientId(size = 8) {
@@ -220,90 +221,14 @@ export class TypstCloudClient {
         return new Uint8Array(await response.arrayBuffer());
     }
     async readFile(projectId, fileIdOrPath, options) {
+        validateReadOptions(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: outputText,
                 encoding: "utf-8",
-                totalLines,
-                startLine: startLineDisplay,
-                endLine: endLineDisplay,
-                truncation: truncation.truncated ? truncation : undefined,
+                ...readTextContent(decodeYjsText(yjsBytes), options),
             };
         }
         const blob = await this.downloadFileBlob(projectId, file.id);
@@ -433,15 +358,20 @@ export class TypstCloudClient {
                 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 replaceExisting = async () => {
+                        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,
+                        };
                     };
+                    // Path-based writes must use the same ID lock as surgical edits.
+                    return normalized === existing.id ? replaceExisting() :
+                        withFileMutationQueue(`${projectId}:${existing.id}`, replaceExisting);
                 }
                 const rawBytes = new TextEncoder().encode(content);
                 const { response } = await this.restCall("PUT", `files/${projectId}/${existing.id}`, { body: rawBytes });
@@ -469,14 +399,29 @@ export class TypstCloudClient {
         });
     }
     async editFile(projectId, filePathOrId, edits, options) {
+        validateEdits(edits);
+        if (options?.expectedHash !== undefined &&
+            (typeof options.expectedHash !== "string" || !/^[a-f\d]{64}$/i.test(options.expectedHash))) {
+            throw new Error("expectedHash must be the SHA-256 contentHash returned by typst_read_file.");
+        }
+        if (options?.matchMode !== undefined && !["exact", "fuzzy"].includes(options.matchMode)) {
+            throw new Error("matchMode must be exact or fuzzy.");
+        }
+        if (options?.dryRun !== undefined && typeof options.dryRun !== "boolean") {
+            throw new Error("dryRun must be a boolean.");
+        }
         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`);
         }
         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);
+            const currentHash = hashText(decodeYjsText(remote));
+            if (options?.expectedHash !== undefined && currentHash !== options.expectedHash.toLowerCase()) {
+                throw new TypstLoadError(["STALE_CONTENT"], "File changed since read. Read the affected range again and retry with its contentHash.");
+            }
+            const { encodedUpdate, previousText, updatedText, appliedCount, diff, patch, firstChangedLine, usedFuzzyMatch, } = editYjsText(remote, edits, file.name, options?.matchMode ?? "exact");
+            const { syncChannel } = options?.dryRun ? { syncChannel: "none" } : await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options?.preferWebSocket ?? true);
             return {
                 file,
                 appliedCount,
@@ -486,6 +431,9 @@ export class TypstCloudClient {
                 patch,
                 firstChangedLine,
                 syncChannel,
+                contentHash: options?.dryRun ? currentHash : hashText(updatedText),
+                dryRun: Boolean(options?.dryRun),
+                usedFuzzyMatch,
             };
         });
     }
@@ -749,7 +697,13 @@ export class TypstCloudClient {
         };
     }
     async findAndReplace(projectId, options) {
+        const rules = resolveReplacementRules(options);
+        const output = options.output ?? (options.replacements ? "summary" : "full");
         const files = await this.listFiles(projectId);
+        if (options.filePath && !files.some(file => file.isMultiplayable &&
+            (file.name === options.filePath.replace(/^\/+/, "") || file.id === options.filePath))) {
+            throw new Error(`Text file not found: ${options.filePath}`);
+        }
         const filesModified = [];
         let totalReplacements = 0;
         for (const file of files) {
@@ -767,14 +721,8 @@ export class TypstCloudClient {
             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) {
+                const repResult = replaceBatchInContent(file.name, text, rules, output);
+                if (repResult.updatedText !== text) {
                     if (!options.dryRun) {
                         const { encodedUpdate } = replaceYjsText(remote, repResult.updatedText);
                         await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options.preferWebSocket ?? true);
@@ -782,8 +730,9 @@ export class TypstCloudClient {
                     filesModified.push({
                         file: file.name,
                         replacementsCount: repResult.replacementCount,
-                        diff: repResult.diff,
-                        patch: repResult.patch,
+                        ...(repResult.diff !== undefined ? { diff: repResult.diff } : {}),
+                        ...(repResult.patch !== undefined ? { patch: repResult.patch } : {}),
+                        ...(options.replacements ? { replacementCounts: repResult.replacementCounts } : {}),
                         firstChangedLine: repResult.firstChangedLine,
                     });
                     totalReplacements += repResult.replacementCount;

package/dist/index.js

@@ -8,6 +8,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { TypstCloudClient, } from "./client/typst-client.js";
 import { formatUnknownError } from "./client/errors.js";
 import { TYPST_MCP_TOOLS } from "./tools/definitions.js";
+import { validateEdits } from "./protocol/edit-diff.js";
+import { truncateHead } from "./utils/truncate.js";
 export { TYPST_MCP_TOOLS };
 function resolvePreferWebSocket(value) {
     if (typeof value === "boolean") {
@@ -22,32 +24,25 @@ function resolveOptionalNumber(value) {
     return undefined;
 }
 export function prepareEditArguments(input) {
-    if (!input)
+    if (input === undefined)
         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];
-            }
+            input = JSON.parse(input);
         }
-        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 }];
+        catch {
+            throw new Error("edits must be an array of {oldText, newText}; invalid JSON.");
         }
     }
-    return [];
+    const edits = (Array.isArray(input) ? input : [input]);
+    validateEdits(edits);
+    return edits.map(({ oldText, newText }) => ({ oldText, newText }));
+}
+function requiredText(args, key) {
+    if (typeof args[key] !== "string" || !args[key].length) {
+        throw new Error(`${key} must be a non-empty string.`);
+    }
+    return args[key];
 }
 export async function dispatchTypstTool(client, name, args = {}) {
     switch (name) {
@@ -78,28 +73,71 @@ 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), {
-                offset: resolveOptionalNumber(args.offset),
-                limit: resolveOptionalNumber(args.limit),
-                lineNumbers: typeof args.lineNumbers === "boolean"
-                    ? args.lineNumbers
-                    : undefined,
+        case "typst_read_file": {
+            if (args.output !== undefined && args.output !== "compact" && args.output !== "full") {
+                throw new Error("output must be compact or full.");
+            }
+            const result = await client.readFile(requiredText(args, "projectId"), requiredText(args, "filePath"), {
+                offset: args.offset,
+                limit: args.limit,
+                maxBytes: args.maxBytes,
+                lineNumbers: args.lineNumbers,
             });
+            return args.output === "full" ? result : {
+                ...result, file: { id: result.file.id, name: result.file.name },
+            };
+        }
         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": {
-            let edits = prepareEditArguments(args.edits);
-            if (edits.length === 0 &&
-                typeof args.oldText === "string" &&
-                typeof args.newText === "string") {
-                edits = [{ oldText: args.oldText, newText: args.newText }];
+            const hasShorthand = args.oldText !== undefined || args.newText !== undefined;
+            if (args.edits !== undefined && hasShorthand) {
+                throw new Error("Use either edits or oldText/newText, not both.");
             }
-            return await client.editFile(String(args.projectId), String(args.filePath), edits, {
+            const edits = prepareEditArguments(args.edits !== undefined ? args.edits :
+                hasShorthand ? { oldText: args.oldText, newText: args.newText } : undefined);
+            const output = args.output ?? (args.dryRun === true ? "diff" : "summary");
+            if (!["summary", "diff", "full"].includes(output)) {
+                throw new Error("output must be summary, diff, or full.");
+            }
+            const maxDiffBytes = args.maxDiffBytes ?? 8192;
+            if (typeof maxDiffBytes !== "number" || !Number.isSafeInteger(maxDiffBytes) ||
+                maxDiffBytes < 1 || maxDiffBytes > 1048576) {
+                throw new Error("maxDiffBytes must be an integer between 1 and 1048576.");
+            }
+            if (args.preferWebSocket !== undefined && typeof args.preferWebSocket !== "boolean") {
+                throw new Error("preferWebSocket must be a boolean.");
+            }
+            const result = await client.editFile(requiredText(args, "projectId"), requiredText(args, "filePath"), edits, {
                 preferWebSocket: resolvePreferWebSocket(args.preferWebSocket),
+                expectedHash: args.expectedHash,
+                matchMode: args.matchMode,
+                dryRun: args.dryRun,
             });
+            const compact = {
+                file: { id: result.file.id, name: result.file.name },
+                appliedCount: result.appliedCount,
+                contentHash: result.contentHash,
+                firstChangedLine: result.firstChangedLine,
+                ...(result.dryRun ? { dryRun: true } : {}),
+                ...(result.usedFuzzyMatch ? { usedFuzzyMatch: true } : {}),
+            };
+            if (output === "summary")
+                return compact;
+            const diff = truncateHead(result.diff, { maxLines: 100, maxBytes: maxDiffBytes });
+            const diffFields = {
+                diff: diff.content,
+                ...(diff.truncated ? { diffTruncated: true, hint: "Read the affected range to inspect all changes, or increase maxDiffBytes (100 diff lines maximum)." } : {}),
+            };
+            if (output === "diff")
+                return { ...compact, ...diffFields };
+            const patch = truncateHead(result.patch, { maxLines: 100, maxBytes: maxDiffBytes });
+            return {
+                ...result, ...diffFields, patch: patch.content,
+                ...(patch.truncated ? { patchTruncated: true } : {}),
+            };
         }
         case "typst_upload_asset": {
             let bytes;
@@ -149,13 +187,15 @@ export async function dispatchTypstTool(client, name, args = {}) {
             });
         case "typst_find_and_replace":
             return await client.findAndReplace(String(args.projectId), {
-                pattern: String(args.pattern),
-                replacement: String(args.replacement),
+                pattern: args.pattern,
+                replacement: args.replacement,
+                replacements: args.replacements,
+                output: args.output,
                 filePath: args.filePath,
                 glob: args.glob,
-                regex: Boolean(args.regex),
-                ignoreCase: Boolean(args.ignoreCase),
-                limit: resolveOptionalNumber(args.limit),
+                regex: args.regex,
+                ignoreCase: args.ignoreCase,
+                limit: args.limit,
                 dryRun: Boolean(args.dryRun),
                 preferWebSocket: resolvePreferWebSocket(args.preferWebSocket),
             });
@@ -167,7 +207,7 @@ export function createTypstMcpServer(options = {}) {
     const client = new TypstCloudClient(options);
     const server = new Server({
         name: "typst-mcp",
-        version: "1.1.0",
+        version: "1.3.0",
     }, {
         capabilities: {
             tools: {},
@@ -210,7 +250,7 @@ export function createTypstMcpServer(options = {}) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(result, null, 2),
+                        text: JSON.stringify(result, null, name === "typst_read_file" || name === "typst_edit_file" ? undefined : 2),
                     },
                 ],
             };

package/dist/protocol/edit-diff.js

@@ -133,10 +133,13 @@ export function fuzzyFindText(content, oldText) {
             contentForReplacement: content,
         };
     }
-    const fuzzyContent = normalizeForFuzzyMatch(content);
+    const { normalized: fuzzyContent, starts, ends } = fuzzyTextWithOffsets(content);
     const fuzzyOldText = normalizeForFuzzyMatch(oldText);
-    const fuzzyIndex = fuzzyContent.indexOf(fuzzyOldText);
-    if (fuzzyIndex === -1) {
+    const fuzzyIndex = fuzzyOldText.length ? fuzzyContent.indexOf(fuzzyOldText) : -1;
+    // Do not replace part of an expanded Unicode grapheme (e.g. one f in ffi).
+    const last = fuzzyIndex + fuzzyOldText.length - 1;
+    if (fuzzyIndex === -1 || starts[fuzzyIndex] === starts[fuzzyIndex - 1] ||
+        ends[last] === ends[last + 1]) {
         return {
             found: false,
             index: -1,
@@ -147,20 +150,69 @@ export function fuzzyFindText(content, oldText) {
     }
     return {
         found: true,
-        index: fuzzyIndex,
-        matchLength: fuzzyOldText.length,
+        index: starts[fuzzyIndex],
+        matchLength: ends[last] - starts[fuzzyIndex],
         usedFuzzyMatch: true,
-        contentForReplacement: fuzzyContent,
+        contentForReplacement: content,
     };
 }
+/** Keep original offsets so fallback matching cannot normalize unrelated text. */
+function fuzzyTextWithOffsets(content) {
+    let normalized = "";
+    const starts = [];
+    const ends = [];
+    const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+    for (const { segment, index } of segmenter.segment(content)) {
+        // Append a sentinel so trailing spaces are retained until the line-level trim.
+        const value = normalizeForFuzzyMatch(segment + "\u0000").slice(0, -1);
+        normalized += value;
+        for (let i = 0; i < value.length; i++) {
+            starts.push(index);
+            ends.push(index + segment.length);
+        }
+    }
+    let offset = 0;
+    const keptStarts = [];
+    const keptEnds = [];
+    const trimmedLines = normalized.split("\n").map(line => {
+        const trimmed = line.trimEnd();
+        for (let i = 0; i < trimmed.length; i++) {
+            keptStarts.push(starts[offset + i]);
+            keptEnds.push(ends[offset + i]);
+        }
+        offset += line.length;
+        if (offset < normalized.length) {
+            keptStarts.push(starts[offset]);
+            keptEnds.push(ends[offset]);
+            offset++;
+        }
+        return trimmed;
+    });
+    return { normalized: trimmedLines.join("\n"), starts: keptStarts, ends: keptEnds };
+}
 export function countOccurrences(content, oldText) {
-    const fuzzyContent = normalizeForFuzzyMatch(content);
-    const fuzzyOldText = normalizeForFuzzyMatch(oldText);
-    if (fuzzyOldText.length === 0)
+    if (!oldText.length)
         return 0;
-    return fuzzyContent.split(fuzzyOldText).length - 1;
+    let count = 0;
+    let offset = content.indexOf(oldText);
+    while (offset !== -1) {
+        count++;
+        offset = content.indexOf(oldText, offset + 1);
+    }
+    return count;
+}
+export function validateEdits(edits) {
+    if (!Array.isArray(edits) || edits.length === 0) {
+        throw new Error("At least one edit operation is required");
+    }
+    for (const [index, edit] of edits.entries()) {
+        if (!edit || typeof edit.oldText !== "string" || typeof edit.newText !== "string" || !edit.oldText.length) {
+            throw new Error(`Edit ${index + 1} requires a non-empty oldText and a string newText.`);
+        }
+    }
 }
-export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
+export function applyEditsToNormalizedContent(normalizedContent, edits, path, matchMode = "fuzzy") {
+    validateEdits(edits);
     const normalizedEdits = edits.map((e) => ({
         oldText: normalizeToLF(e.oldText),
         newText: normalizeToLF(e.newText),
@@ -170,19 +222,20 @@ export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
             throw new Error(`oldText cannot be empty for edit in ${path}`);
         }
     }
-    const initialMatches = normalizedEdits.map((e) => fuzzyFindText(normalizedContent, e.oldText));
-    const usedFuzzyMatch = initialMatches.some((m) => m.usedFuzzyMatch);
-    const replacementBaseContent = usedFuzzyMatch
-        ? normalizeForFuzzyMatch(normalizedContent)
-        : normalizedContent;
+    let usedFuzzyMatch = false;
     const matchedEdits = [];
     for (let i = 0; i < normalizedEdits.length; i++) {
         const edit = normalizedEdits[i];
-        const matchResult = fuzzyFindText(replacementBaseContent, edit.oldText);
+        const exactIndex = normalizedContent.indexOf(edit.oldText);
+        const matchResult = exactIndex !== -1 ? {
+            found: true, index: exactIndex, matchLength: edit.oldText.length, usedFuzzyMatch: false,
+        } : matchMode === "fuzzy" ? fuzzyFindText(normalizedContent, edit.oldText) : { found: false };
         if (!matchResult.found) {
             throw new Error(`Could not find match for oldText in ${path}: ${JSON.stringify(edit.oldText.slice(0, 80))}`);
         }
-        const occurrences = countOccurrences(replacementBaseContent, edit.oldText);
+        const fuzzy = Boolean(matchResult.usedFuzzyMatch);
+        usedFuzzyMatch ||= fuzzy;
+        const occurrences = countOccurrences(fuzzy ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent, fuzzy ? normalizeForFuzzyMatch(edit.oldText) : edit.oldText);
         if (occurrences > 1) {
             throw new Error(`Found ${occurrences} occurrences of oldText in ${path} (must be unique): ${JSON.stringify(edit.oldText.slice(0, 80))}`);
         }
@@ -202,13 +255,11 @@ export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
         }
     }
     const baseContent = normalizedContent;
-    const newContent = usedFuzzyMatch
-        ? applyReplacementsPreservingUnchangedLines(normalizedContent, replacementBaseContent, matchedEdits)
-        : applyReplacements(replacementBaseContent, matchedEdits);
+    const newContent = applyReplacements(normalizedContent, matchedEdits);
     if (baseContent === newContent) {
         throw new Error(`No changes made to ${path}: newText equals oldText.`);
     }
-    return { baseContent, newContent };
+    return { baseContent, newContent, matchedEdits, usedFuzzyMatch };
 }
 /**
  * Generate a standard unified patch.
@@ -239,7 +290,7 @@ export function generateDiffString(oldContent, newContent, contextLines = 4) {
             raw.pop();
         }
         if (part.added || part.removed) {
-            if (firstChangedLine === undefined && part.added) {
+            if (firstChangedLine === undefined) {
                 firstChangedLine = newLineNum;
             }
             for (const line of raw) {

package/dist/protocol/read-content.js

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+export function hashText(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function validateReadOptions(options) {
+    for (const key of ["offset", "limit", "maxLines", "maxBytes"]) {
+        const value = options[key];
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 1)) {
+            throw new Error(`${key} must be a positive integer.`);
+        }
+    }
+    if (options.maxBytes !== undefined && options.maxBytes > 1024 * 1024) {
+        throw new Error("maxBytes must not exceed 1048576 (1 MiB). Read smaller ranges.");
+    }
+    if (options.lineNumbers !== undefined && typeof options.lineNumbers !== "boolean") {
+        throw new Error("lineNumbers must be a boolean.");
+    }
+}
+/** Return only complete source lines. Continuation metadata never enters source text. */
+export function readTextContent(text, options = {}) {
+    validateReadOptions(options);
+    const lines = text.match(/[^\n]*\n|[^\n]+/g) ?? [];
+    const totalLines = lines.length;
+    const offset = options.offset ?? 1;
+    if (offset > Math.max(1, totalLines)) {
+        throw new Error(`Offset ${offset} is beyond end of file (${totalLines} lines total)`);
+    }
+    const maxLines = Math.min(options.limit ?? 200, options.maxLines ?? Infinity);
+    const maxBytes = options.maxBytes ?? 16 * 1024;
+    const selected = [];
+    let bytes = 0;
+    let truncatedBy = "lines";
+    const stop = Math.min(totalLines, offset - 1 + maxLines);
+    const width = String(stop).length;
+    for (let index = offset - 1; index < stop; index++) {
+        const line = lines[index];
+        const rendered = options.lineNumbers
+            ? `${String(index + 1).padStart(width, " ")} | ${line}` : line;
+        const lineBytes = Buffer.byteLength(rendered, "utf8");
+        if (bytes + lineBytes > maxBytes) {
+            if (selected.length === 0) {
+                throw new Error(`Line ${offset} needs ${lineBytes} bytes. Increase maxBytes (up to 1048576) or read another line.`);
+            }
+            truncatedBy = "bytes";
+            break;
+        }
+        selected.push(rendered);
+        bytes += lineBytes;
+    }
+    const endLine = offset - 1 + selected.length;
+    const truncated = endLine < totalLines;
+    return {
+        content: selected.join(""),
+        contentHash: hashText(text),
+        totalLines,
+        startLine: offset,
+        endLine,
+        truncated,
+        ...(truncated ? { nextOffset: endLine + 1, truncatedBy } : {}),
+    };
+}

package/dist/protocol/search-replace.js

@@ -57,41 +57,118 @@ export function searchInContent(filePath, content, options) {
     }
     return { matches, totalMatches };
 }
-export function replaceInContent(filePath, content, options) {
-    let flags = "g";
-    if (options.ignoreCase)
-        flags += "i";
-    let searchRegex;
-    if (options.regex) {
-        searchRegex = new RegExp(options.pattern, flags);
+/** Validate the entire request before any project files can be mutated. */
+export function resolveReplacementRules(options) {
+    const hasSingle = options.pattern !== undefined || options.replacement !== undefined;
+    if (options.replacements !== undefined && hasSingle) {
+        throw new Error("Use either replacements or pattern/replacement, not both.");
     }
-    else {
-        const escaped = options.pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        searchRegex = new RegExp(escaped, flags);
+    if (options.output !== undefined && !["summary", "diff", "full"].includes(options.output)) {
+        throw new Error("output must be summary, diff, or full.");
+    }
+    if (options.replacements !== undefined &&
+        (options.regex !== undefined || options.ignoreCase !== undefined || options.limit !== undefined)) {
+        throw new Error("For batch replacements, set regex, ignoreCase, and limit on each rule.");
+    }
+    const rules = options.replacements ?? [{
+            pattern: options.pattern, replacement: options.replacement,
+            regex: options.regex, ignoreCase: options.ignoreCase, limit: options.limit,
+        }];
+    if (!Array.isArray(rules) || rules.length === 0) {
+        throw new Error("replacements must be a non-empty array.");
+    }
+    for (const [index, rule] of rules.entries()) {
+        if (!rule || typeof rule.pattern !== "string" || !rule.pattern.length ||
+            typeof rule.replacement !== "string") {
+            throw new Error(`Replacement ${index + 1} requires a non-empty pattern and a string replacement.`);
+        }
+        for (const key of ["regex", "ignoreCase"]) {
+            if (rule[key] !== undefined && typeof rule[key] !== "boolean") {
+                throw new Error(`Replacement ${index + 1}: ${key} must be a boolean.`);
+            }
+        }
+        if (rule.limit !== undefined && (!Number.isInteger(rule.limit) || rule.limit < 0)) {
+            throw new Error(`Replacement ${index + 1}: limit must be a non-negative integer.`);
+        }
+        if (rule.regex) {
+            try {
+                new RegExp(rule.pattern, rule.ignoreCase ? "gi" : "g");
+            }
+            catch {
+                throw new Error(`Replacement ${index + 1} has an invalid regular expression.`);
+            }
+        }
     }
-    let count = 0;
-    const limit = options.limit;
-    const updatedText = content.replace(searchRegex, (match, ...args) => {
-        if (limit !== undefined && count >= limit) {
-            return match;
+    return rules;
+}
+export function replaceInContent(filePath, content, options) {
+    const result = replaceBatchInContent(filePath, content, [options]);
+    return { ...result, diff: result.diff, patch: result.patch };
+}
+/** Rules run in order on the result of the previous rule. Diff covers the whole batch. */
+export function replaceBatchInContent(filePath, content, rules, output = "full") {
+    resolveReplacementRules({ replacements: rules, output });
+    let updatedText = content;
+    const replacementCounts = [];
+    for (const options of rules) {
+        let flags = "g";
+        if (options.ignoreCase)
+            flags += "i";
+        let searchRegex;
+        if (options.regex) {
+            searchRegex = new RegExp(options.pattern, flags);
         }
-        count++;
-        if (!options.regex) {
-            return options.replacement;
+        else {
+            const escaped = options.pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            searchRegex = new RegExp(escaped, flags);
         }
-        // For regex, support standard replacement with capture groups ($1, $2)
-        return options.replacement.replace(/\$(\d+)/g, (_, groupIdx) => {
-            const idx = parseInt(groupIdx, 10);
-            return args[idx - 1] ?? "";
+        let count = 0;
+        const limit = options.limit;
+        updatedText = updatedText.replace(searchRegex, (match, ...args) => {
+            if (limit !== undefined && count >= limit) {
+                return match;
+            }
+            count++;
+            if (!options.regex) {
+                return options.replacement;
+            }
+            // The final callback arguments are offset/input and optional named groups,
+            // not captures. Implement JS replacement tokens without exposing metadata.
+            const hasNamedGroups = typeof args[args.length - 1] === "object";
+            const groups = hasNamedGroups ? args[args.length - 1] : undefined;
+            const input = args[args.length - (hasNamedGroups ? 2 : 1)];
+            const offset = args[args.length - (hasNamedGroups ? 3 : 2)];
+            const captures = args.slice(0, hasNamedGroups ? -3 : -2);
+            return options.replacement.replace(/\$(\$|&|`|'|\d{1,2}|<[^>]*>)/g, (token, key) => {
+                if (key === "$")
+                    return "$";
+                if (key === "&")
+                    return match;
+                if (key === "`")
+                    return input.slice(0, offset);
+                if (key === "'")
+                    return input.slice(offset + match.length);
+                if (key.startsWith("<"))
+                    return groups ? groups[key.slice(1, -1)] ?? "" : token;
+                const index = Number(key);
+                if (index > 0 && index <= captures.length)
+                    return captures[index - 1] ?? "";
+                const first = Number(key[0]);
+                if (key.length === 2 && first > 0 && first <= captures.length) {
+                    return (captures[first - 1] ?? "") + key[1];
+                }
+                return token;
+            });
         });
-    });
+        replacementCounts.push(count);
+    }
     const diffResult = generateDiffString(content, updatedText);
-    const patch = generateUnifiedPatch(filePath, content, updatedText);
     return {
         updatedText,
-        replacementCount: count,
-        diff: diffResult.diff,
-        patch,
+        replacementCount: replacementCounts.reduce((sum, count) => sum + count, 0),
+        replacementCounts,
+        ...(output !== "summary" ? { diff: diffResult.diff } : {}),
+        ...(output === "full" ? { patch: generateUnifiedPatch(filePath, content, updatedText) } : {}),
         firstChangedLine: diffResult.firstChangedLine,
     };
 }

package/dist/protocol/yjs-doc.js

@@ -1,6 +1,5 @@
 import * as Y from "yjs";
-import * as Diff from "diff";
-import { applyEditsToNormalizedContent, detectLineEnding, generateDiffString, generateUnifiedPatch, normalizeToLF, restoreLineEndings, splitBom, } from "./edit-diff.js";
+import { applyEditsToNormalizedContent, detectLineEnding, generateDiffString, generateUnifiedPatch, normalizeToLF, restoreLineEndings, splitBom, validateEdits, } from "./edit-diff.js";
 function computeUpdateDiff(doc, remoteUpdate) {
     let stateVector;
     if (remoteUpdate.byteLength > 0) {
@@ -79,10 +78,8 @@ export function replaceYjsText(remoteUpdate, newContent) {
  * directly on the `Y.Text("text")` CRDT, with CRLF/BOM resilience, fuzzy matching,
  * and unified diff generation.
  */
-export function editYjsText(remoteUpdate, edits, filePath = "file") {
-    if (edits.length === 0) {
-        throw new Error("At least one edit operation is required");
-    }
+export function editYjsText(remoteUpdate, edits, filePath = "file", matchMode = "fuzzy") {
+    validateEdits(edits);
     const doc = new Y.Doc();
     try {
         if (remoteUpdate.byteLength > 0) {
@@ -93,23 +90,50 @@ export function editYjsText(remoteUpdate, edits, filePath = "file") {
         const { bom, text: contentWithoutBom } = splitBom(previousText);
         const originalEnding = detectLineEnding(contentWithoutBom);
         const normalizedContent = normalizeToLF(contentWithoutBom);
-        const { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, filePath);
-        const finalContent = bom + restoreLineEndings(newContent, originalEnding);
-        // Apply minimal surgical character changes to Y.Text
-        const diffs = Diff.diffChars(previousText, finalContent);
+        const { baseContent, newContent, matchedEdits, usedFuzzyMatch } = applyEditsToNormalizedContent(normalizedContent, edits, filePath, matchMode);
+        // Map LF-normalized match boundaries back to original UTF-16 offsets.
+        // Preserve all untouched characters, including mixed CRLF/LF line endings.
+        const offsets = [0];
+        for (let i = 0; i < contentWithoutBom.length; i++) {
+            if (contentWithoutBom[i] === "\r" && contentWithoutBom[i + 1] === "\n")
+                i++;
+            offsets.push(i + 1);
+        }
+        const rawEdits = [...matchedEdits].reverse().map(edit => {
+            const start = offsets[edit.matchIndex];
+            const end = offsets[edit.matchIndex + edit.matchLength];
+            return { start, end, newText: restoreLineEndings(edit.newText, originalEnding) };
+        });
+        let updatedContent = contentWithoutBom;
+        for (const edit of rawEdits) {
+            updatedContent = updatedContent.slice(0, edit.start) + edit.newText + updatedContent.slice(edit.end);
+        }
+        const finalContent = bom + updatedContent;
+        // Use known edit ranges instead of diffing the entire document character by
+        // character. Retain each anchor's unchanged prefix/suffix and their CRDT IDs.
         doc.transact(() => {
-            let offset = 0;
-            for (const part of diffs) {
-                if (part.added) {
-                    ytext.insert(offset, part.value);
-                    offset += part.value.length;
-                }
-                else if (part.removed) {
-                    ytext.delete(offset, part.value.length);
-                }
-                else {
-                    offset += part.value.length;
-                }
+            for (const edit of rawEdits) {
+                const old = contentWithoutBom.slice(edit.start, edit.end);
+                let prefix = 0;
+                while (prefix < old.length && prefix < edit.newText.length && old[prefix] === edit.newText[prefix])
+                    prefix++;
+                // Never split surrogate pairs when trimming a common prefix/suffix.
+                if (prefix > 0 && /[\uD800-\uDBFF]/.test(old[prefix - 1]) && /[\uDC00-\uDFFF]/.test(old[prefix] ?? ""))
+                    prefix--;
+                let suffix = 0;
+                while (suffix < old.length - prefix && suffix < edit.newText.length - prefix &&
+                    old[old.length - 1 - suffix] === edit.newText[edit.newText.length - 1 - suffix])
+                    suffix++;
+                if (suffix > 0 && /[\uDC00-\uDFFF]/.test(old[old.length - suffix]) &&
+                    /[\uD800-\uDBFF]/.test(old[old.length - suffix - 1] ?? ""))
+                    suffix--;
+                const index = bom.length + edit.start + prefix;
+                const removed = old.length - prefix - suffix;
+                const inserted = edit.newText.slice(prefix, edit.newText.length - suffix);
+                if (removed)
+                    ytext.delete(index, removed);
+                if (inserted)
+                    ytext.insert(index, inserted);
             }
         });
         const { encodedUpdate, mergedState } = computeUpdateDiff(doc, remoteUpdate);
@@ -124,6 +148,7 @@ export function editYjsText(remoteUpdate, edits, filePath = "file") {
             diff: diffResult.diff,
             patch,
             firstChangedLine: diffResult.firstChangedLine,
+            usedFuzzyMatch,
         };
     }
     finally {

package/dist/tools/definitions.js

@@ -122,7 +122,7 @@ export const TYPST_MCP_TOOLS = [
     },
     {
         name: "typst_read_file",
-        description: "Read a file from a https://typst.app project. Supports text files (.typ, .bib, .toml, etc.) with offset/limit pagination, optional line numbering, and automatic truncation safeguards (2,000 lines or 50KB). Binary image assets (PNG, JPEG, SVG, WebP, GIF, BMP) are returned with native multimodal MCP image content blocks.",
+        description: "Read project text in bounded pages (default 200 lines/16 KiB) or images as native image blocks. content contains source only; use nextOffset for continuation. contentHash covers the entire raw text file: pass it as expectedHash to typst_edit_file. Compact file metadata by default; output='full' adds metadata, not extra source lines. Use grep to locate relevant lines before reading large files.",
         inputSchema: {
             type: "object",
             properties: {
@@ -135,12 +135,22 @@ export const TYPST_MCP_TOOLS = [
                     description: "File path/name (e.g. 'main.typ') or file ID",
                 },
                 offset: {
-                    type: "number",
+                    type: "integer",
+                    minimum: 1,
                     description: "Line number to start reading from (1-indexed)",
                 },
                 limit: {
-                    type: "number",
-                    description: "Maximum number of lines to read",
+                    type: "integer",
+                    minimum: 1,
+                    description: "Maximum complete lines to read (default: 200). Use nextOffset to continue.",
+                },
+                maxBytes: {
+                    type: "integer", minimum: 1, maximum: 1048576,
+                    description: "Maximum returned source bytes, including line number prefixes (default: 16384, maximum: 1 MiB). Increase for unusually long lines.",
+                },
+                output: {
+                    type: "string", enum: ["compact", "full"],
+                    description: "compact (default): minimal file metadata; full: all file metadata. Both use offset/limit/maxBytes pagination.",
                 },
                 lineNumbers: {
                     type: "boolean",
@@ -178,7 +188,7 @@ export const TYPST_MCP_TOOLS = [
     },
     {
         name: "typst_edit_file",
-        description: "Apply one or more surgical text replacements (oldText -> newText) directly to a multiplayer file's Yjs CRDT document in a https://typst.app project. Supports CRLF/LF resilience, UTF-8 BOM preservation, fuzzy matching for Unicode quotes/dashes/whitespace, and returns a unified diff and patch of the changes.",
+        description: "Apply all targeted edits against one original file snapshot, with one save. Prefer short unique oldText anchors and expectedHash from typst_read_file to reject stale edits. Exact matching by default (LF/CRLF resilient); matchMode='fuzzy' opts into Unicode/whitespace fallback. Malformed, ambiguous, or overlapping edits fail without saving. Summary output by default; dryRun previews a bounded diff. Unchanged characters and BOM are preserved.",
         inputSchema: {
             type: "object",
             properties: {
@@ -192,13 +202,15 @@ export const TYPST_MCP_TOOLS = [
                 },
                 edits: {
                     type: "array",
+                    minItems: 1,
                     description: "One or more targeted non-overlapping replacements. Each oldText must be unique in the original file.",
                     items: {
                         type: "object",
                         properties: {
                             oldText: {
                                 type: "string",
-                                description: "Unique substring to replace (matches exact or normalized quotes/dashes)",
+                                minLength: 1,
+                                description: "Unique source substring to replace. All edits match the original file, not earlier edits' results.",
                             },
                             newText: {
                                 type: "string",
@@ -216,12 +228,36 @@ export const TYPST_MCP_TOOLS = [
                     type: "string",
                     description: "Optional replacement text for single replacement shorthand",
                 },
+                expectedHash: {
+                    type: "string", pattern: "^[a-fA-F0-9]{64}$",
+                    description: "Recommended: contentHash from the latest read. Checked against fresh downloaded text inside the file mutation queue; stale files fail without saving.",
+                },
+                matchMode: {
+                    type: "string", enum: ["exact", "fuzzy"],
+                    description: "exact (default) matches source with newline normalization. fuzzy enables Unicode quote/dash/space/NFKC fallback only when an exact match is absent.",
+                },
+                dryRun: {
+                    type: "boolean",
+                    description: "Validate and preview edits without saving (default: false). Returned contentHash still identifies unchanged cloud text.",
+                },
+                output: {
+                    type: "string", enum: ["summary", "diff", "full"],
+                    description: "summary (default): counts, new contentHash, firstChangedLine; diff: also a bounded display diff; full: also bounded patch and full metadata. dryRun defaults to diff.",
+                },
+                maxDiffBytes: {
+                    type: "integer", minimum: 1, maximum: 1048576,
+                    description: "Byte budget per diff/patch field (default: 8192). Each also has a 100-line cap. Truncation is explicit; read affected ranges for full details.",
+                },
                 preferWebSocket: {
                     type: "boolean",
                     description: "Push real-time TextUpdate over /editing/v3 WebSocket in addition to REST persistence (default: true)",
                 },
             },
             required: ["projectId", "filePath"],
+            oneOf: [
+                { required: ["edits"], not: { anyOf: [{ required: ["oldText"] }, { required: ["newText"] }] } },
+                { required: ["oldText", "newText"], not: { required: ["edits"] } },
+            ],
         },
     },
     {
@@ -422,7 +458,7 @@ export const TYPST_MCP_TOOLS = [
     },
     {
         name: "typst_find_and_replace",
-        description: "Find and replace text or regular expressions across a single file or all files in a https://typst.app project. Supports dry-run preview diffs, regex capture groups, and per-file mutation queue serialization.",
+        description: "Find and replace text or regex in one file or project-wide. Use replacements to batch mappings (e.g. Sep → September, Oct → October) in one call with one save per file. Rules run sequentially; later rules see earlier results. Batch output defaults to compact summary; request output='diff' or 'full' for previews. Supports dryRun and per-file mutation serialization. Project-wide changes are not atomic across files.",
         inputSchema: {
             type: "object",
             properties: {
@@ -438,6 +474,27 @@ export const TYPST_MCP_TOOLS = [
                     type: "string",
                     description: "Replacement text (supports $1, $2 capture groups if regex is true)",
                 },
+                replacements: {
+                    type: "array",
+                    minItems: 1,
+                    description: "Ordered replacement rules instead of pattern/replacement. Each rule runs on the previous result. Set regex, ignoreCase, and limit per rule. All rules are validated before any writes; each changed file is saved once.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            pattern: { type: "string", minLength: 1 },
+                            replacement: { type: "string" },
+                            regex: { type: "boolean", description: "Treat pattern as regex (default: false)" },
+                            ignoreCase: { type: "boolean", description: "Case-insensitive matching (default: false)" },
+                            limit: { type: "integer", minimum: 0, description: "Maximum replacements for this rule per file" },
+                        },
+                        required: ["pattern", "replacement"],
+                    },
+                },
+                output: {
+                    type: "string",
+                    enum: ["summary", "diff", "full"],
+                    description: "summary: counts and first changed line; diff: also display diff; full: also unified patch. Defaults to summary for batches, full for legacy pattern/replacement calls. Applies to dry runs too.",
+                },
                 filePath: {
                     type: "string",
                     description: "Optional file path/name (e.g. 'main.typ'). If omitted, searches and replaces across all text files in the project.",
@@ -467,7 +524,11 @@ export const TYPST_MCP_TOOLS = [
                     description: "Push real-time TextUpdate over /editing/v3 WebSocket before REST persistence (default: true)",
                 },
             },
-            required: ["projectId", "pattern", "replacement"],
+            required: ["projectId"],
+            oneOf: [
+                { required: ["pattern", "replacement"], not: { required: ["replacements"] } },
+                { required: ["replacements"], not: { anyOf: [{ required: ["pattern"] }, { required: ["replacement"] }, { required: ["regex"] }, { required: ["ignoreCase"] }, { required: ["limit"] }] } },
+            ],
         },
     },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typst-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Model Context Protocol (MCP) server for https://typst.app/ cloud projects, Yjs real-time text editing, asset management, and Typst compiler diagnostics",
   "keywords": [
     "mcp",