typst-mcp 1.0.2 → 1.2.0

package/dist/client/typst-client.js

@@ -3,10 +3,14 @@ import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import { TypstAuthManager } from "./auth.js";
 import { TypstLoadError, formatUnknownError } from "./errors.js";
-import { captureBrowserPreviewScreenshot, captureWorkspacePageScreenshots, compileWorkspaceDiagnostics, compileWorkspacePdf, parseShortDiagnostics, resolveTypstBinary, } from "./compiler.js";
-import { CREATE_PROJECT_MUTATION, DASHBOARD_CONTENT_QUERY, DELETE_FILES_MUTATION, DELETE_PROJECT_MUTATION, PROJECT_FILES_QUERY, UPDATE_FILES_MUTATION, } from "../protocol/graphql.js";
+import { captureBrowserPreviewScreenshot, captureWebDiagnostics, captureWorkspacePageScreenshots, compileWorkspaceDiagnostics, compileWorkspacePdf, hasTypstBinary, parseShortDiagnostics, resolveTypstBinary, } from "./compiler.js";
+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 { detectSupportedImageMimeType } from "../utils/mime.js";
+import { withFileMutationQueue } from "../utils/file-mutation-queue.js";
+import { matchGlob, searchInContent, replaceInContent, } from "../protocol/search-replace.js";
 export { TypstLoadError, resolveTypstBinary };
 const URL_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 export function generateClientId(size = 8) {
@@ -215,22 +219,102 @@ export class TypstCloudClient {
         const { response } = await this.restCall("GET", `files/${projectId}/${fileId}`);
         return new Uint8Array(await response.arrayBuffer());
     }
-    async readFile(projectId, fileIdOrPath) {
+    async readFile(projectId, fileIdOrPath, options) {
         const file = await this.resolveFile(projectId, fileIdOrPath);
         if (file.isMultiplayable) {
             const yjsBytes = await this.downloadFileYjs(projectId, file.id);
             const text = decodeYjsText(yjsBytes);
+            const allLines = text.split("\n");
+            const totalLines = allLines.length;
+            if (options?.offset !== undefined && options.offset > totalLines) {
+                throw new Error(`Offset ${options.offset} is beyond end of file (${totalLines} lines total)`);
+            }
+            const startLine = options?.offset ? Math.max(0, options.offset - 1) : 0;
+            const startLineDisplay = startLine + 1;
+            let selectedContent;
+            let userLimitedLines;
+            if (options?.limit !== undefined) {
+                const endLine = Math.min(startLine + options.limit, totalLines);
+                selectedContent = allLines.slice(startLine, endLine).join("\n");
+                userLimitedLines = endLine - startLine;
+            }
+            else {
+                selectedContent = allLines.slice(startLine).join("\n");
+            }
+            const truncation = truncateHead(selectedContent, {
+                maxLines: options?.maxLines,
+                maxBytes: options?.maxBytes,
+            });
+            let outputText;
+            let endLineDisplay = startLineDisplay;
+            if (truncation.firstLineExceedsLimit) {
+                const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine] ?? "", "utf-8"));
+                outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(truncation.maxBytes)} limit]`;
+            }
+            else if (truncation.truncated) {
+                endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+                const nextOffset = endLineDisplay + 1;
+                let body = truncation.content;
+                if (options?.lineNumbers) {
+                    const lines = body.split("\n");
+                    const width = String(endLineDisplay).length;
+                    body = lines
+                        .map((line, idx) => `${String(startLineDisplay + idx).padStart(width, " ")} | ${line}`)
+                        .join("\n");
+                }
+                if (truncation.truncatedBy === "lines") {
+                    outputText = `${body}\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
+                }
+                else {
+                    outputText = `${body}\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalLines} (${formatSize(truncation.maxBytes)} limit). Use offset=${nextOffset} to continue.]`;
+                }
+            }
+            else if (userLimitedLines !== undefined &&
+                startLine + userLimitedLines < totalLines) {
+                endLineDisplay = startLine + userLimitedLines;
+                const remaining = totalLines - endLineDisplay;
+                const nextOffset = endLineDisplay + 1;
+                let body = truncation.content;
+                if (options?.lineNumbers) {
+                    const lines = body.split("\n");
+                    const width = String(endLineDisplay).length;
+                    body = lines
+                        .map((line, idx) => `${String(startLineDisplay + idx).padStart(width, " ")} | ${line}`)
+                        .join("\n");
+                }
+                outputText = `${body}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
+            }
+            else {
+                endLineDisplay = totalLines;
+                let body = truncation.content;
+                if (options?.lineNumbers) {
+                    const lines = body.split("\n");
+                    const width = String(startLineDisplay + lines.length - 1).length;
+                    body = lines
+                        .map((line, idx) => `${String(startLineDisplay + idx).padStart(width, " ")} | ${line}`)
+                        .join("\n");
+                }
+                outputText = body;
+            }
             return {
                 file,
-                content: text,
+                content: outputText,
                 encoding: "utf-8",
+                totalLines,
+                startLine: startLineDisplay,
+                endLine: endLineDisplay,
+                truncation: truncation.truncated ? truncation : undefined,
             };
         }
         const blob = await this.downloadFileBlob(projectId, file.id);
+        const mimeType = detectSupportedImageMimeType(file.name);
+        const isImage = Boolean(mimeType && mimeType.startsWith("image/"));
         return {
             file,
             content: Buffer.from(blob).toString("base64"),
             encoding: "base64",
+            mimeType,
+            isImage,
         };
     }
     async pushYjsUpdateViaWebSocket(projectId, fileId, encodedUpdate, timeoutMs = 5000) {
@@ -342,61 +426,68 @@ export class TypstCloudClient {
         return { syncChannel };
     }
     async writeFile(projectId, filePathOrId, content, options) {
-        const files = await this.listFiles(projectId);
         const normalized = filePathOrId.replace(/^\/+/, "");
-        const existing = files.find((f) => f.id === filePathOrId) ??
-            files.find((f) => f.name === normalized || f.name === filePathOrId);
-        if (existing) {
-            if (existing.isMultiplayable) {
-                const remote = await this.downloadFileYjs(projectId, existing.id);
-                const { encodedUpdate } = replaceYjsText(remote, content);
-                const { syncChannel } = await this.saveYjsUpdate(projectId, existing.id, encodedUpdate, options?.preferWebSocket ?? true);
+        return withFileMutationQueue(`${projectId}:${normalized}`, async () => {
+            const files = await this.listFiles(projectId);
+            const existing = files.find((f) => f.id === filePathOrId) ??
+                files.find((f) => f.name === normalized || f.name === filePathOrId);
+            if (existing) {
+                if (existing.isMultiplayable) {
+                    const remote = await this.downloadFileYjs(projectId, existing.id);
+                    const { encodedUpdate } = replaceYjsText(remote, content);
+                    const { syncChannel } = await this.saveYjsUpdate(projectId, existing.id, encodedUpdate, options?.preferWebSocket ?? true);
+                    return {
+                        file: existing,
+                        created: false,
+                        bytesWritten: Buffer.byteLength(content, "utf8"),
+                        syncChannel,
+                    };
+                }
+                const rawBytes = new TextEncoder().encode(content);
+                const { response } = await this.restCall("PUT", `files/${projectId}/${existing.id}`, { body: rawBytes });
+                const updatedMeta = (await response.json());
                 return {
-                    file: existing,
+                    file: updatedMeta,
                     created: false,
-                    bytesWritten: Buffer.byteLength(content, "utf8"),
-                    syncChannel,
+                    bytesWritten: rawBytes.byteLength,
+                    syncChannel: "rest",
                 };
             }
             const rawBytes = new TextEncoder().encode(content);
-            const { response } = await this.restCall("PUT", `files/${projectId}/${existing.id}`, { body: rawBytes });
-            const updatedMeta = (await response.json());
+            const { response } = await this.restCall("POST", `files/${projectId}`, {
+                queryParams: { name: normalized, convert: "false" },
+                body: rawBytes,
+            });
+            const body = (await response.json());
+            const createdMeta = unwrapSingleOrFirstFile(body);
             return {
-                file: updatedMeta,
-                created: false,
+                file: createdMeta,
+                created: true,
                 bytesWritten: rawBytes.byteLength,
                 syncChannel: "rest",
             };
-        }
-        const rawBytes = new TextEncoder().encode(content);
-        const { response } = await this.restCall("POST", `files/${projectId}`, {
-            queryParams: { name: normalized, convert: "false" },
-            body: rawBytes,
         });
-        const body = (await response.json());
-        const createdMeta = unwrapSingleOrFirstFile(body);
-        return {
-            file: createdMeta,
-            created: true,
-            bytesWritten: rawBytes.byteLength,
-            syncChannel: "rest",
-        };
     }
     async editFile(projectId, filePathOrId, edits, options) {
         const file = await this.resolveFile(projectId, filePathOrId);
         if (!file.isMultiplayable) {
             throw new TypstLoadError(["NOT_MULTIPLAYABLE"], `File "${file.name}" is a binary blob and cannot be surgically text-edited`);
         }
-        const remote = await this.downloadFileYjs(projectId, file.id);
-        const { encodedUpdate, previousText, updatedText, appliedCount } = editYjsText(remote, edits);
-        const { syncChannel } = await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options?.preferWebSocket ?? true);
-        return {
-            file,
-            appliedCount,
-            previousLength: previousText.length,
-            updatedLength: updatedText.length,
-            syncChannel,
-        };
+        return withFileMutationQueue(`${projectId}:${file.id}`, async () => {
+            const remote = await this.downloadFileYjs(projectId, file.id);
+            const { encodedUpdate, previousText, updatedText, appliedCount, diff, patch, firstChangedLine, } = editYjsText(remote, edits, file.name);
+            const { syncChannel } = await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options?.preferWebSocket ?? true);
+            return {
+                file,
+                appliedCount,
+                previousLength: previousText.length,
+                updatedLength: updatedText.length,
+                diff,
+                patch,
+                firstChangedLine,
+                syncChannel,
+            };
+        });
     }
     async uploadAsset(projectId, fileName, data, options) {
         const normalized = fileName.replace(/^\/+/, "");
@@ -480,18 +571,92 @@ export class TypstCloudClient {
     static parseShortDiagnostics(stderrText) {
         return parseShortDiagnostics(stderrText);
     }
-    async getDiagnostics(projectId, mainFile) {
-        const { workspaceDir, mainFileName } = await this.materializeProjectWorkspace(projectId, mainFile);
+    async updateProject(projectId, updates) {
+        const res = await this.graphql(EDIT_PROJECT_MUTATION, {
+            projectId,
+            name: updates.name,
+            previewed: updates.previewed,
+            pinnedVersion: updates.pinnedVersion,
+        });
+        return res.updateProject;
+    }
+    async getWebDiagnostics(projectId, mainFile) {
+        const project = await this.getProject(projectId);
+        let effectiveMainFile = mainFile;
+        if (!effectiveMainFile) {
+            const previewedFile = project.files.find((f) => f.id === project.previewed);
+            effectiveMainFile = previewedFile?.name ?? "main.typ";
+        }
+        else {
+            const requestedFile = project.files.find((f) => f.name === mainFile || f.id === mainFile);
+            if (requestedFile && requestedFile.id !== project.previewed) {
+                try {
+                    await this.updateProject(projectId, { previewed: requestedFile.id });
+                }
+                catch {
+                    // If permission denied or mutation rejected, proceed anyway
+                }
+            }
+        }
+        const fileContents = {};
+        for (const f of project.files) {
+            if (f.isMultiplayable) {
+                try {
+                    const res = await this.readFile(projectId, f.name);
+                    if (res.encoding === "utf-8" && typeof res.content === "string") {
+                        fileContents[f.name] = res.content;
+                    }
+                }
+                catch {
+                    // Ignore read failures for auxiliary files
+                }
+            }
+        }
+        return captureWebDiagnostics({
+            appUrl: this.auth.appUrl,
+            projectId,
+            cookieHeader: this.auth.getCookieHeader(),
+            mainFile: effectiveMainFile,
+            fileContents,
+        });
+    }
+    async getDiagnostics(projectId, options) {
+        const opts = typeof options === "string" ? { mainFile: options } : options;
+        const mode = opts?.mode ?? "auto";
+        const requestedMainFile = opts?.mainFile;
+        if (mode === "web") {
+            return await this.getWebDiagnostics(projectId, requestedMainFile);
+        }
+        const typstAvailable = hasTypstBinary(this.typstBin);
+        if (!typstAvailable) {
+            if (mode === "cli") {
+                throw new TypstLoadError(["TYPST_BINARY_NOT_FOUND"], `Typst compiler binary '${this.typstBin}' was not found. Please install the Typst compiler (e.g. 'winget install Typst.Typst' / 'brew install typst') or use mode: 'web' for zero-binary cloud diagnostics.`);
+            }
+            return await this.getWebDiagnostics(projectId, requestedMainFile);
+        }
         try {
-            return compileWorkspaceDiagnostics({
-                typstBin: this.typstBin,
-                projectId,
-                workspaceDir,
-                mainFileName,
-            });
+            const { workspaceDir, mainFileName } = await this.materializeProjectWorkspace(projectId, requestedMainFile);
+            try {
+                const res = compileWorkspaceDiagnostics({
+                    typstBin: this.typstBin,
+                    projectId,
+                    workspaceDir,
+                    mainFileName,
+                });
+                return {
+                    ...res,
+                    mode: "cli",
+                };
+            }
+            finally {
+                rmSync(workspaceDir, { recursive: true, force: true });
+            }
         }
-        finally {
-            rmSync(workspaceDir, { recursive: true, force: true });
+        catch (err) {
+            if (mode === "auto") {
+                return await this.getWebDiagnostics(projectId, requestedMainFile);
+            }
+            throw err;
         }
     }
     async exportPdf(projectId, options) {
@@ -542,4 +707,93 @@ export class TypstCloudClient {
             rmSync(workspaceDir, { recursive: true, force: true });
         }
     }
+    async grepProject(projectId, options) {
+        const files = await this.listFiles(projectId);
+        const limit = options.limit ?? 100;
+        const allMatches = [];
+        let totalMatches = 0;
+        let filesSearched = 0;
+        for (const file of files) {
+            if (!file.isMultiplayable)
+                continue;
+            if (options.path) {
+                const normalizedPath = options.path.replace(/^\/+/, "");
+                if (file.name !== normalizedPath &&
+                    !file.name.startsWith(`${normalizedPath}/`) &&
+                    file.id !== options.path) {
+                    continue;
+                }
+            }
+            if (options.glob && !matchGlob(file.name, options.glob)) {
+                continue;
+            }
+            filesSearched++;
+            const yjsBytes = await this.downloadFileYjs(projectId, file.id);
+            const text = decodeYjsText(yjsBytes);
+            const remainingLimit = Math.max(0, limit - allMatches.length);
+            const result = searchInContent(file.name, text, {
+                pattern: options.pattern,
+                literal: options.literal,
+                ignoreCase: options.ignoreCase,
+                context: options.context,
+                limit: remainingLimit,
+            });
+            totalMatches += result.totalMatches;
+            allMatches.push(...result.matches);
+        }
+        return {
+            matches: allMatches,
+            totalMatches,
+            filesSearched,
+            truncated: totalMatches > allMatches.length,
+        };
+    }
+    async findAndReplace(projectId, options) {
+        const files = await this.listFiles(projectId);
+        const filesModified = [];
+        let totalReplacements = 0;
+        for (const file of files) {
+            if (!file.isMultiplayable)
+                continue;
+            if (options.filePath) {
+                const normalizedPath = options.filePath.replace(/^\/+/, "");
+                if (file.name !== normalizedPath && file.id !== options.filePath) {
+                    continue;
+                }
+            }
+            if (options.glob && !matchGlob(file.name, options.glob)) {
+                continue;
+            }
+            await withFileMutationQueue(`${projectId}:${file.id}`, async () => {
+                const remote = await this.downloadFileYjs(projectId, file.id);
+                const text = decodeYjsText(remote);
+                const repResult = replaceInContent(file.name, text, {
+                    pattern: options.pattern,
+                    replacement: options.replacement,
+                    regex: options.regex,
+                    ignoreCase: options.ignoreCase,
+                    limit: options.limit,
+                });
+                if (repResult.replacementCount > 0) {
+                    if (!options.dryRun) {
+                        const { encodedUpdate } = replaceYjsText(remote, repResult.updatedText);
+                        await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options.preferWebSocket ?? true);
+                    }
+                    filesModified.push({
+                        file: file.name,
+                        replacementsCount: repResult.replacementCount,
+                        diff: repResult.diff,
+                        patch: repResult.patch,
+                        firstChangedLine: repResult.firstChangedLine,
+                    });
+                    totalReplacements += repResult.replacementCount;
+                }
+            });
+        }
+        return {
+            filesModified,
+            totalReplacements,
+            dryRun: Boolean(options.dryRun),
+        };
+    }
 }

package/dist/index.js

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