typst-mcp 1.0.2 → 1.2.0

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. Decodes Yjs CRDT state (doc.getText('text')) into UTF-8 text for multiplayer files (.typ, .bib, .toml, etc.) or returns base64 for binary assets.",
+        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.",
         inputSchema: {
             type: "object",
             properties: {
@@ -134,6 +134,18 @@ export const TYPST_MCP_TOOLS = [
                     type: "string",
                     description: "File path/name (e.g. 'main.typ') or file ID",
                 },
+                offset: {
+                    type: "number",
+                    description: "Line number to start reading from (1-indexed)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of lines to read",
+                },
+                lineNumbers: {
+                    type: "boolean",
+                    description: "Whether to prefix each line with its 1-indexed line number (e.g. '1 | ')",
+                },
             },
             required: ["projectId", "filePath"],
         },
@@ -166,7 +178,7 @@ export const TYPST_MCP_TOOLS = [
     },
     {
         name: "typst_edit_file",
-        description: "Apply one or more exact surgical text replacements (oldText -> newText) directly to a multiplayer file's Yjs CRDT document in a https://typst.app project.",
+        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.",
         inputSchema: {
             type: "object",
             properties: {
@@ -180,13 +192,13 @@ export const TYPST_MCP_TOOLS = [
                 },
                 edits: {
                     type: "array",
-                    description: "Non-overlapping exact text replacements to apply to the Yjs document",
+                    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: "Exact unique substring to replace",
+                                description: "Unique substring to replace (matches exact or normalized quotes/dashes)",
                             },
                             newText: {
                                 type: "string",
@@ -196,12 +208,20 @@ export const TYPST_MCP_TOOLS = [
                         required: ["oldText", "newText"],
                     },
                 },
+                oldText: {
+                    type: "string",
+                    description: "Optional shorthand for a single replacement (used if edits is omitted)",
+                },
+                newText: {
+                    type: "string",
+                    description: "Optional replacement text for single replacement shorthand",
+                },
                 preferWebSocket: {
                     type: "boolean",
                     description: "Push real-time TextUpdate over /editing/v3 WebSocket in addition to REST persistence (default: true)",
                 },
             },
-            required: ["projectId", "filePath", "edits"],
+            required: ["projectId", "filePath"],
         },
     },
     {
@@ -276,7 +296,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: {
@@ -288,6 +308,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"],
         },
@@ -353,4 +378,96 @@ export const TYPST_MCP_TOOLS = [
             required: ["projectId"],
         },
     },
+    {
+        name: "typst_grep_project",
+        description: "Search for text or regular expressions across files in a https://typst.app project. Returns matching lines with file paths, line numbers, and optional surrounding context lines.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: {
+                    type: "string",
+                    description: "The Typst project ID",
+                },
+                pattern: {
+                    type: "string",
+                    description: "Search pattern (regular expression or literal string)",
+                },
+                path: {
+                    type: "string",
+                    description: "Optional directory or file path to restrict search (e.g. 'chapters/' or 'main.typ')",
+                },
+                glob: {
+                    type: "string",
+                    description: "Optional glob pattern to filter files (e.g. '*.typ' or '*.bib')",
+                },
+                ignoreCase: {
+                    type: "boolean",
+                    description: "Case-insensitive search (default: false)",
+                },
+                literal: {
+                    type: "boolean",
+                    description: "Treat pattern as literal string instead of regex (default: false)",
+                },
+                context: {
+                    type: "number",
+                    description: "Number of lines to show before and after each match (default: 0)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of matches to return (default: 100)",
+                },
+            },
+            required: ["projectId", "pattern"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: {
+                    type: "string",
+                    description: "The Typst project ID",
+                },
+                pattern: {
+                    type: "string",
+                    description: "Search pattern to replace (literal substring or regex)",
+                },
+                replacement: {
+                    type: "string",
+                    description: "Replacement text (supports $1, $2 capture groups if regex is true)",
+                },
+                filePath: {
+                    type: "string",
+                    description: "Optional file path/name (e.g. 'main.typ'). If omitted, searches and replaces across all text files in the project.",
+                },
+                glob: {
+                    type: "string",
+                    description: "Optional glob pattern to filter target files when searching project-wide (e.g. '*.typ')",
+                },
+                regex: {
+                    type: "boolean",
+                    description: "Whether pattern is a regular expression (default: false)",
+                },
+                ignoreCase: {
+                    type: "boolean",
+                    description: "Case-insensitive search (default: false)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of replacements per file (default: replace all occurrences)",
+                },
+                dryRun: {
+                    type: "boolean",
+                    description: "If true, returns unified diffs and match counts without saving changes (default: false)",
+                },
+                preferWebSocket: {
+                    type: "boolean",
+                    description: "Push real-time TextUpdate over /editing/v3 WebSocket before REST persistence (default: true)",
+                },
+            },
+            required: ["projectId", "pattern", "replacement"],
+        },
+    },
 ];

package/dist/utils/file-mutation-queue.js

@@ -0,0 +1,30 @@
+const fileMutationQueues = new Map();
+let registrationQueue = Promise.resolve();
+/**
+ * Serialize file mutation operations targeting the same resource key (e.g. `${projectId}:${fileId}`).
+ * Operations for different files/projects continue to run concurrently.
+ */
+export async function withFileMutationQueue(key, fn) {
+    const registration = registrationQueue.then(async () => {
+        const currentQueue = fileMutationQueues.get(key) ?? Promise.resolve();
+        let releaseNext;
+        const nextQueue = new Promise((resolveQueue) => {
+            releaseNext = resolveQueue;
+        });
+        const chainedQueue = currentQueue.then(() => nextQueue);
+        fileMutationQueues.set(key, chainedQueue);
+        return { key, currentQueue, chainedQueue, releaseNext };
+    });
+    registrationQueue = registration.then(() => undefined, () => undefined);
+    const { currentQueue, chainedQueue, releaseNext } = await registration;
+    await currentQueue;
+    try {
+        return await fn();
+    }
+    finally {
+        releaseNext();
+        if (fileMutationQueues.get(key) === chainedQueue) {
+            fileMutationQueues.delete(key);
+        }
+    }
+}

package/dist/utils/mime.js

@@ -0,0 +1,23 @@
+/**
+ * Utility for detecting supported image MIME types in Typst projects.
+ */
+export function detectSupportedImageMimeType(fileName) {
+    const ext = fileName.toLowerCase().split(".").pop();
+    switch (ext) {
+        case "png":
+            return "image/png";
+        case "jpg":
+        case "jpeg":
+            return "image/jpeg";
+        case "svg":
+            return "image/svg+xml";
+        case "webp":
+            return "image/webp";
+        case "gif":
+            return "image/gif";
+        case "bmp":
+            return "image/bmp";
+        default:
+            return undefined;
+    }
+}

package/dist/utils/truncate.js

@@ -0,0 +1,114 @@
+/**
+ * Shared truncation utilities for tool outputs, ported and adapted from Pi (earendil-works/pi).
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 50KB)
+ *
+ * Never returns partial lines during normal truncation.
+ */
+export const DEFAULT_MAX_LINES = 2000;
+export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
+function splitLinesForCounting(content) {
+    if (content.length === 0) {
+        return [];
+    }
+    const lines = content.split("\n");
+    if (content.endsWith("\n")) {
+        lines.pop();
+    }
+    return lines;
+}
+/**
+ * Format bytes as human-readable size.
+ */
+export function formatSize(bytes) {
+    if (bytes < 1024) {
+        return `${bytes}B`;
+    }
+    else if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    }
+    else {
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    }
+}
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If the first line exceeds the byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export function truncateHead(content, options = {}) {
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const totalBytes = Buffer.byteLength(content, "utf-8");
+    const lines = splitLinesForCounting(content);
+    const totalLines = lines.length;
+    if (totalLines <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content,
+            truncated: false,
+            truncatedBy: null,
+            totalLines,
+            totalBytes,
+            outputLines: totalLines,
+            outputBytes: totalBytes,
+            lastLinePartial: false,
+            firstLineExceedsLimit: false,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Check if first line alone exceeds byte limit
+    const firstLine = lines[0] ?? "";
+    const firstLineBytes = Buffer.byteLength(firstLine, "utf-8");
+    if (firstLineBytes > maxBytes) {
+        return {
+            content: "",
+            truncated: true,
+            truncatedBy: "bytes",
+            totalLines,
+            totalBytes,
+            outputLines: 0,
+            outputBytes: 0,
+            lastLinePartial: false,
+            firstLineExceedsLimit: true,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Collect complete lines that fit
+    const outputLinesArr = [];
+    let outputBytesCount = 0;
+    let truncatedBy = "lines";
+    for (let i = 0; i < lines.length && i < maxLines; i++) {
+        const line = lines[i];
+        const lineBytes = Buffer.byteLength(line, "utf-8") + (i > 0 ? 1 : 0); // +1 for newline
+        if (outputBytesCount + lineBytes > maxBytes) {
+            truncatedBy = "bytes";
+            break;
+        }
+        outputLinesArr.push(line);
+        outputBytesCount += lineBytes;
+    }
+    if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+        truncatedBy = "lines";
+    }
+    const outputContent = outputLinesArr.join("\n");
+    const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+    return {
+        content: outputContent,
+        truncated: true,
+        truncatedBy,
+        totalLines,
+        totalBytes,
+        outputLines: outputLinesArr.length,
+        outputBytes: finalOutputBytes,
+        lastLinePartial: false,
+        firstLineExceedsLimit: false,
+        maxLines,
+        maxBytes,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typst-mcp",
-  "version": "1.0.2",
+  "version": "1.2.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",
@@ -46,12 +46,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.0",
+    "diff": "^9.0.0",
     "lib0": "^0.2.99",
     "yjs": "^13.6.24",
     "zod": "^3.24.2"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/diff": "^8.0.0",
     "@types/node": "^25.0.3",
     "typescript": "^5.8.2"
   }