typst-mcp 1.1.0 → 1.3.0

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"] } },
+            ],
         },
     },
     {
@@ -296,7 +332,7 @@ export const TYPST_MCP_TOOLS = [
     },
     {
         name: "typst_get_diagnostics",
-        description: "Synchronize all files from a https://typst.app project and run the Typst compiler to retrieve structured errors, warnings, line/column numbers, and hints.",
+        description: "Retrieve compiler diagnostics (errors, warnings, line/column numbers, and hints) for a https://typst.app project. Supports both local Typst CLI compilation (fastest) and Typst Web cloud diagnostics (zero-binary fallback using typst.app cloud compiler).",
         inputSchema: {
             type: "object",
             properties: {
@@ -308,6 +344,11 @@ export const TYPST_MCP_TOOLS = [
                     type: "string",
                     description: "Optional main .typ entry file override (defaults to project previewed file or main.typ)",
                 },
+                mode: {
+                    type: "string",
+                    enum: ["auto", "cli", "web"],
+                    description: "Diagnostics mode: 'auto' (prefers local Typst CLI if installed, falls back to Typst Web cloud compiler), 'cli' (requires local typst binary), or 'web' (uses Typst Web cloud compiler). Defaults to 'auto'.",
+                },
             },
             required: ["projectId"],
         },
@@ -417,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: {
@@ -433,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.",
@@ -462,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.1.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",