@kolmopdf/mcp-server 1.0.3 → 1.1.0

package/dist/index.js

@@ -5,6 +5,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/client.ts
+import { randomUUID } from "crypto";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 
@@ -204,6 +205,12 @@ function errorFromApiBody(body, httpStatus) {
 }
 
 // src/client.ts
+function normalizeStatus(status) {
+  if (!status) return "processing";
+  if (status === "completed") return "succeeded";
+  if (status === "pending" || status === "waiting") return "queued";
+  return status;
+}
 var KolmoPdfClient = class {
   apiKey;
   baseUrl;
@@ -215,18 +222,38 @@ var KolmoPdfClient = class {
     this.httpTimeoutMs = opts.httpTimeoutMs;
     this.uploadTimeoutMs = opts.uploadTimeoutMs;
   }
-  get apiBase() {
-    return `${this.baseUrl}/api/pdf-to-markdown-proxy`;
+  get jobsBase() {
+    return `${this.baseUrl}/api/v1/jobs`;
   }
   headers() {
-    return { "X-API-Key": this.apiKey };
+    return {
+      "X-API-Key": this.apiKey,
+      Authorization: `Bearer ${this.apiKey}`
+    };
   }
   async jsonRequest(url, init) {
     const res = await fetch(url, init);
-    const body = await res.json();
+    let body = {};
+    const text = await res.text();
+    try {
+      body = text ? JSON.parse(text) : {};
+    } catch {
+      if (!res.ok) {
+        throw new KolmoPdfError("api_task_error", {
+          message: `HTTP ${res.status}: non-JSON body`,
+          httpStatus: res.status
+        });
+      }
+    }
     if (!res.ok || body.success === false) {
+      const errObj = body.error;
       throw errorFromApiBody(
-        body,
+        {
+          error_code: body.error_code || errObj?.code,
+          message: body.message || errObj?.message,
+          points_required: body.points_required,
+          current_points: body.current_points
+        },
         res.status
       );
     }
@@ -247,6 +274,20 @@ var KolmoPdfClient = class {
     form.append("file", blob, filename);
     return form;
   }
+  normalizeSubmit(body) {
+    const id = String(body.id ?? body.task_id ?? body.legacy_task_id ?? "");
+    if (!id) {
+      throw new KolmoPdfError("task_creation_failed", { message: "No job id in create response" });
+    }
+    const queue = body.queue;
+    return {
+      task_id: id,
+      status: normalizeStatus(String(body.status ?? "queued")),
+      points_deducted: Number(body.points_deducted ?? 0),
+      remaining_points: Number(body.remaining_points ?? 0),
+      queue_info: queue && typeof queue.ahead === "number" ? { position: queue.position ?? 0, ahead_tasks: queue.ahead } : void 0
+    };
+  }
   async parse(file, form, filename) {
     const fd = await this.buildFileForm(file, filename);
     if (form.table_mode) fd.append("table_mode", form.table_mode);
@@ -260,13 +301,14 @@ var KolmoPdfClient = class {
       fd.append("skip_rotation_detection", String(form.skip_rotation_detection));
     if (form.enable_cross_page_merge !== void 0)
       fd.append("enable_cross_page_merge", String(form.enable_cross_page_merge));
-    const body = await this.jsonRequest(`${this.apiBase}/parse`, {
+    if (form.enrichment !== void 0) fd.append("enrichment", form.enrichment);
+    const body = await this.jsonRequest(`${this.jobsBase}/parse`, {
       method: "POST",
-      headers: this.headers(),
+      headers: { ...this.headers(), "Idempotency-Key": randomUUID() },
       body: fd,
       signal: AbortSignal.timeout(this.uploadTimeoutMs)
     });
-    return body;
+    return this.normalizeSubmit(body);
   }
   async translatePdf(file, form, filename) {
     const fd = await this.buildFileForm(file, filename);
@@ -277,35 +319,77 @@ var KolmoPdfClient = class {
       fd.append("enableImageTranslation", String(form.enable_image_translation));
     if (form.enable_table_translation !== void 0)
       fd.append("enableTableTranslation", String(form.enable_table_translation));
-    const body = await this.jsonRequest(`${this.apiBase}/translate-pdf`, {
+    const body = await this.jsonRequest(`${this.jobsBase}/translate-pdf`, {
       method: "POST",
-      headers: this.headers(),
+      headers: { ...this.headers(), "Idempotency-Key": randomUUID() },
       body: fd,
       signal: AbortSignal.timeout(this.uploadTimeoutMs)
     });
-    return body;
+    return this.normalizeSubmit(body);
   }
   async convert(file, form, filename) {
     const fd = await this.buildFileForm(file, filename);
     if (form.target_format) fd.append("targetFormat", form.target_format);
-    const body = await this.jsonRequest(`${this.apiBase}/convert`, {
+    const body = await this.jsonRequest(`${this.jobsBase}/convert`, {
       method: "POST",
-      headers: this.headers(),
+      headers: { ...this.headers(), "Idempotency-Key": randomUUID() },
       body: fd,
       signal: AbortSignal.timeout(this.uploadTimeoutMs)
     });
-    return body;
+    return this.normalizeSubmit(body);
   }
   async getStatus(taskId) {
-    const body = await this.jsonRequest(`${this.apiBase}/status/${taskId}`, {
+    const body = await this.jsonRequest(`${this.jobsBase}/${encodeURIComponent(taskId)}`, {
       method: "GET",
       headers: this.headers(),
       signal: AbortSignal.timeout(this.httpTimeoutMs)
     });
-    return body;
+    const status = normalizeStatus(String(body.status ?? "processing"));
+    const err = body.error;
+    const queue = body.queue;
+    const result = body.result;
+    const ok = status === "succeeded" || status === "completed";
+    return {
+      success: ok,
+      status,
+      message: body.message || err?.message,
+      error_code: err?.code,
+      queue_info: queue && typeof queue.ahead === "number" ? { position: queue.position ?? 0, ahead_tasks: queue.ahead } : void 0,
+      result: result ? {
+        task_id: taskId,
+        download_url: result.download_url,
+        filename: result.filename ?? null,
+        kind: result.kind ?? null,
+        content_type: result.content_type ?? null,
+        sha256: result.sha256 ?? null,
+        bytes: result.bytes ?? null,
+        files: result.files ?? null
+      } : void 0
+    };
+  }
+  /** SSE stream for a job. Caller must abort/cancel the response body. */
+  async openEvents(taskId, signal) {
+    const res = await fetch(`${this.jobsBase}/${encodeURIComponent(taskId)}/events`, {
+      method: "GET",
+      headers: {
+        ...this.headers(),
+        Accept: "text/event-stream"
+      },
+      ...signal === void 0 ? {} : { signal }
+    });
+    if (!res.ok) {
+      throw new KolmoPdfError("api_task_error", {
+        message: `SSE failed with HTTP ${res.status}`,
+        httpStatus: res.status
+      });
+    }
+    return res;
   }
-  async download(taskId, dest) {
-    const res = await fetch(`${this.apiBase}/download/${taskId}`, {
+  /**
+   * Stream download to a Writable, or to destPath (preferred — allows ZIP sniff after write).
+   */
+  async download(taskId, dest, opts) {
+    const res = await fetch(`${this.jobsBase}/${encodeURIComponent(taskId)}/download`, {
       method: "GET",
       headers: this.headers(),
       signal: AbortSignal.timeout(this.uploadTimeoutMs)
@@ -317,32 +401,51 @@ var KolmoPdfClient = class {
       });
     }
     const contentType = res.headers.get("content-type");
-    const isZip = contentType?.includes("zip") || contentType?.includes("octet-stream") || false;
+    let isZip = !!contentType && (contentType.includes("zip") || contentType.includes("application/octet-stream") || contentType.includes("application/x-zip"));
     const body = res.body;
     if (!body) {
       throw new KolmoPdfError("api_task_error", { message: "Empty download response body" });
     }
     const reader = body.getReader();
     let bytesWritten = 0;
+    const firstChunks = [];
+    let sniffed = false;
     async function* generate() {
       while (true) {
         const { done, value } = await reader.read();
         if (done) break;
-        bytesWritten += value.byteLength;
-        yield Buffer.from(value);
+        const buf = Buffer.from(value);
+        bytesWritten += buf.byteLength;
+        if (!sniffed) {
+          firstChunks.push(buf);
+          const head = Buffer.concat(firstChunks);
+          if (head.byteLength >= 4) {
+            if (head[0] === 80 && head[1] === 75 && (head[2] === 3 || head[2] === 5 || head[2] === 7)) {
+              isZip = true;
+            } else if (!contentType?.includes("zip")) {
+              isZip = false;
+            }
+            sniffed = true;
+          }
+        }
+        yield buf;
       }
     }
     const readable = Readable.from(generate());
     await pipeline(readable, dest);
-    return { contentType, isZip, bytesWritten };
+    return { contentType, isZip, bytesWritten, destPath: opts?.destPath };
   }
   async getBalance() {
-    const body = await this.jsonRequest(`${this.apiBase}/balance`, {
+    const body = await this.jsonRequest(`${this.baseUrl}/api/v1/balance`, {
       method: "GET",
       headers: this.headers(),
       signal: AbortSignal.timeout(this.httpTimeoutMs)
     });
-    return body;
+    return {
+      success: body.success !== false,
+      points: Number(body.points ?? 0),
+      api_key: String(body.api_key ?? "")
+    };
   }
 };
 
@@ -405,8 +508,8 @@ async function checkBalanceHandler(_args, ctx) {
 
 // src/tools/convert.ts
 import { createWriteStream, mkdirSync } from "fs";
-import { readFile as readFile2 } from "fs/promises";
-import { basename, join, resolve } from "path";
+import { readFile as readFile2, rename as rename2 } from "fs/promises";
+import { basename, join as join2, resolve } from "path";
 import { z as z2 } from "zod";
 
 // src/pages.ts
@@ -433,8 +536,8 @@ function humanizeStatus(status, aheadTasks) {
 }
 
 // src/polling.ts
-var TERMINAL_OK = "completed";
-var TERMINAL_FAIL = "failed";
+var TERMINAL_OK = /* @__PURE__ */ new Set(["succeeded", "completed"]);
+var TERMINAL_FAIL = /* @__PURE__ */ new Set(["failed", "cancelled"]);
 var RETRY_POLICY = {
   maxAttempts: 3,
   baseDelayMs: 1e3,
@@ -464,19 +567,119 @@ async function fetchStatusWithRetry(client, taskId) {
   }
   throw new KolmoPdfError("client_network_error");
 }
+function nextSseFrame(buf) {
+  const lf = buf.indexOf("\n\n");
+  const crlf = buf.indexOf("\r\n\r\n");
+  if (lf < 0 && crlf < 0) return null;
+  if (crlf >= 0 && (lf < 0 || crlf < lf)) {
+    return { frame: buf.slice(0, crlf), rest: buf.slice(crlf + 4) };
+  }
+  return { frame: buf.slice(0, lf), rest: buf.slice(lf + 2) };
+}
+function eventNameFromFrame(raw) {
+  let eventName = "message";
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.startsWith("event:")) eventName = line.slice(6).trim();
+  }
+  return eventName;
+}
+async function waitViaSse(ctx, deadline) {
+  const { client, taskId, progress, options } = ctx;
+  const remaining = Math.max(1e3, deadline - Date.now());
+  const timeout = AbortSignal.timeout(remaining);
+  const parent = options.signal;
+  const combined = parent === void 0 ? timeout : AbortSignal.any([parent, timeout]);
+  let reader;
+  try {
+    const res = await client.openEvents(taskId, combined);
+    const body = res.body;
+    if (!body) return null;
+    reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    const handleEvent = async (eventName) => {
+      if (eventName === "job.succeeded") {
+        const status = await fetchStatusWithRetry(client, taskId);
+        if (TERMINAL_OK.has(String(status.status || ""))) {
+          await progress?.report(`[completed] Task ${taskId} done`);
+          return status;
+        }
+        return "continue";
+      }
+      if (eventName === "job.failed" || eventName === "job.cancelled") {
+        const failed = await fetchStatusWithRetry(client, taskId);
+        throw new KolmoPdfError(failed.error_code || eventName.slice("job.".length), {
+          message: failed.message || "Task failed"
+        });
+      }
+      if (eventName === "job.progress" || eventName === "job.snapshot") {
+        await progress?.report(humanizeStatus("processing"));
+      }
+      return "continue";
+    };
+    while (!timeout.aborted) {
+      if (parent?.aborted === true) throw new KolmoPdfError("client_polling_timeout");
+      const { done, value } = await reader.read();
+      if (done) {
+        buf += decoder.decode();
+        const last = nextSseFrame(`${buf}
+
+`);
+        if (last) {
+          const result = await handleEvent(eventNameFromFrame(last.frame));
+          if (result !== "continue") return result;
+        }
+        break;
+      }
+      buf += decoder.decode(value, { stream: true });
+      let next = nextSseFrame(buf);
+      while (next) {
+        buf = next.rest;
+        const result = await handleEvent(eventNameFromFrame(next.frame));
+        if (result !== "continue") return result;
+        next = nextSseFrame(buf);
+      }
+    }
+    return null;
+  } catch (err) {
+    if (err instanceof KolmoPdfError) {
+      const code = err.errorCode;
+      if (code !== "api_task_error" && code !== "client_network_error" && code !== "client_polling_timeout") {
+        throw err;
+      }
+    }
+    return null;
+  } finally {
+    try {
+      await reader?.cancel();
+    } catch {
+    }
+  }
+}
 async function pollUntilComplete(ctx) {
   const { client, taskId, options, progress } = ctx;
   const deadline = Date.now() + options.maxPollMinutes * 6e4;
+  const viaSse = await waitViaSse(ctx, deadline);
+  if (viaSse && TERMINAL_OK.has(String(viaSse.status || ""))) return viaSse;
+  if (viaSse && TERMINAL_FAIL.has(String(viaSse.status || ""))) {
+    throw new KolmoPdfError(viaSse.error_code || "api_task_error", {
+      message: viaSse.message || "Task failed"
+    });
+  }
   while (true) {
+    if (options.signal?.aborted === true) {
+      throw new KolmoPdfError("client_polling_timeout");
+    }
     if (Date.now() > deadline) {
       throw new KolmoPdfError("client_polling_timeout");
     }
     const result = await fetchStatusWithRetry(client, taskId);
-    if (result.status === TERMINAL_OK) {
+    const status = String(result.status || "");
+    if (TERMINAL_OK.has(status)) {
       await progress?.report(`[completed] Task ${taskId} done`);
       return result;
     }
-    if (result.status === TERMINAL_FAIL) {
+    if (TERMINAL_FAIL.has(status)) {
       throw new KolmoPdfError(result.error_code || "api_task_error", {
         message: result.message || "Task failed"
       });
@@ -487,6 +690,52 @@ async function pollUntilComplete(ctx) {
   }
 }
 
+// src/sniff.ts
+import { open, rename } from "fs/promises";
+import { join } from "path";
+var EXT = {
+  zip: ".zip",
+  pdf: ".pdf",
+  markdown: ".md",
+  docx: ".docx",
+  html: ".html",
+  latex: ".tex",
+  binary: ".bin"
+};
+function extensionForKind(kind) {
+  return EXT[kind];
+}
+function sniffBytes(buf) {
+  if (buf.length >= 4 && buf[0] === 80 && buf[1] === 75 && (buf[2] === 3 || buf[2] === 5 || buf[2] === 7)) {
+    const hay = Buffer.from(buf.subarray(0, Math.min(buf.length, 65536))).toString("latin1");
+    if (hay.includes("word/document.xml") || hay.includes("wordprocessingml.document") || hay.includes("[Content_Types].xml") && hay.toLowerCase().includes("word/")) {
+      return "docx";
+    }
+    return "zip";
+  }
+  if (buf.length >= 4 && buf[0] === 37 && buf[1] === 80 && buf[2] === 68 && buf[3] === 70) {
+    return "pdf";
+  }
+  const head = Buffer.from(buf.subarray(0, Math.min(buf.length, 800))).toString("utf8");
+  const trimmed = head.trimStart().toLowerCase();
+  if (trimmed.startsWith("<!doctype html") || trimmed.startsWith("<html")) return "html";
+  if (trimmed.startsWith("\\documentclass") || trimmed.startsWith("\\begin{document}"))
+    return "latex";
+  if (head.trimStart().startsWith("#") || head.includes("\n# ") || head.includes("\n```"))
+    return "markdown";
+  return "binary";
+}
+async function sniffFile(filePath) {
+  const handle = await open(filePath, "r");
+  try {
+    const bytes = Buffer.alloc(65536);
+    const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+    return sniffBytes(bytes.subarray(0, bytesRead));
+  } finally {
+    await handle.close();
+  }
+}
+
 // src/tools/convert.ts
 var convertName = "kolmopdf_convert_markdown";
 var convertDescription = "Convert a Markdown file (or a ZIP of markdown + images) to DOCX, HTML, PDF, or LaTeX via KolmoPDF.";
@@ -495,22 +744,6 @@ var convertInputSchema = z2.object({
   target_format: z2.enum(["word", "docx", "html", "pdf", "latex", "tex"]).optional().default("word"),
   output_subdir: z2.string().optional()
 });
-function formatToExtension(targetFormat) {
-  switch (targetFormat) {
-    case "word":
-    case "docx":
-      return ".docx";
-    case "html":
-      return ".html";
-    case "pdf":
-      return ".pdf";
-    case "latex":
-    case "tex":
-      return ".tex";
-    default:
-      return ".out";
-  }
-}
 function normalizeFormat(targetFormat) {
   switch (targetFormat) {
     case "word":
@@ -559,17 +792,20 @@ async function convertHandler(args, ctx) {
   const subdir = args.output_subdir || taskId;
   const outputRoot = resolve(ctx.config.outputDir, subdir);
   mkdirSync(outputRoot, { recursive: true });
-  const outExt = formatToExtension(args.target_format);
-  const outputPath = join(outputRoot, `result${outExt}`);
-  const ws = createWriteStream(outputPath);
-  await client.download(taskId, ws);
+  const tempPath = join2(outputRoot, "download.bin");
+  const ws = createWriteStream(tempPath);
+  await client.download(taskId, ws, { destPath: tempPath });
+  const kind = await sniffFile(tempPath);
+  const outputPath = join2(outputRoot, `result${extensionForKind(kind)}`);
+  await rename2(tempPath, outputPath);
   const output = {
     task_id: taskId,
     points_deducted: submitResult.points_deducted,
     remaining_points: submitResult.remaining_points,
     output: {
       output_path: outputPath,
-      target_format: normalizeFormat(args.target_format)
+      target_format: normalizeFormat(args.target_format),
+      kind
     }
   };
   return jsonResult(output);
@@ -639,23 +875,40 @@ async function getTaskStatusHandler(args, ctx) {
 
 // src/tools/parse-pdf.ts
 import { createWriteStream as createWriteStream3, mkdirSync as mkdirSync3 } from "fs";
-import { readFile as readFile3 } from "fs/promises";
-import { basename as basename2, join as join3, resolve as resolve3 } from "path";
+import { readFile as readFile3, rename as rename3 } from "fs/promises";
+import { basename as basename2, join as join4, resolve as resolve3 } from "path";
 import { z as z5 } from "zod";
 
 // src/extract.ts
-import { createWriteStream as createWriteStream2, mkdirSync as mkdirSync2 } from "fs";
-import { dirname, join as join2 } from "path";
+import { createWriteStream as createWriteStream2, mkdirSync as mkdirSync2, readFileSync } from "fs";
+import { dirname, join as join3 } from "path";
 import { pipeline as pipeline2 } from "stream/promises";
 import { open as yauzlOpen } from "yauzl";
+function pickPrimaryMarkdownPath(candidates) {
+  if (candidates.length === 0) return null;
+  const scored = candidates.map((c) => {
+    const base = (c.entryName.split("/").pop() || c.entryName).toLowerCase();
+    let score = c.size;
+    if (/^(outline|summary|verification_report|enrichment_meta|tables_changelog|tables_normalized)(\.|$)/i.test(
+      base
+    ) || /outline|summary|verification|enrichment|tables_/.test(base)) {
+      score -= 1e12;
+    }
+    if (base === "readme.md") score -= 1e9;
+    if (/translated|bilingual/.test(base)) score -= 1e6;
+    return { path: c.path, score };
+  });
+  scored.sort((a, b) => b.score - a.score);
+  return scored[0]?.path ?? null;
+}
 async function extractZip(zipPath, destDir) {
   mkdirSync2(destDir, { recursive: true });
   const zipFile = await openZip(zipPath);
   const files = [];
-  let markdownPath = null;
+  const mdCandidates = [];
   let imagesDir = null;
   for await (const entry of iterEntries(zipFile)) {
-    const entryPath = join2(destDir, entry.fileName);
+    const entryPath = join3(destDir, entry.fileName);
     if (entry.fileName.endsWith("/")) {
       mkdirSync2(entryPath, { recursive: true });
       if (entry.fileName.includes("images")) {
@@ -668,14 +921,20 @@ async function extractZip(zipPath, destDir) {
     const writeStream = createWriteStream2(entryPath);
     await pipeline2(readStream, writeStream);
     files.push(entryPath);
-    if (!markdownPath && /\.md$/i.test(entry.fileName)) {
-      markdownPath = entryPath;
+    if (/\.md$/i.test(entry.fileName)) {
+      let size = entry.uncompressedSize || 0;
+      try {
+        size = readFileSync(entryPath).byteLength;
+      } catch {
+      }
+      mdCandidates.push({ path: entryPath, entryName: entry.fileName, size });
     }
     if (!imagesDir && /images\//i.test(entry.fileName)) {
       const prefix = entry.fileName.split("images/")[0] ?? "";
-      imagesDir = join2(destDir, prefix, "images");
+      imagesDir = join3(destDir, prefix, "images");
     }
   }
+  const markdownPath = pickPrimaryMarkdownPath(mdCandidates);
   return { markdownPath, imagesDir, outputRoot: destDir, files };
 }
 function openZip(path) {
@@ -728,7 +987,7 @@ function openReadStream(zipFile, entry) {
 
 // src/tools/parse-pdf.ts
 var parsePdfName = "kolmopdf_parse_pdf";
-var parsePdfDescription = "Parse a local PDF into Markdown via KolmoPDF. Handles formulas, tables, multi-column layouts, and code blocks. Optionally translates while parsing.";
+var parsePdfDescription = "Parse a local PDF into Markdown via KolmoPDF. Handles formulas, tables, multi-column layouts, and code blocks. Optionally translates while parsing. Server may attach outline.md/summary.md sidecars (ZIP download).";
 var parsePdfInputSchema = z5.object({
   file_path: z5.string().describe("Absolute or cwd-relative path to a local PDF file."),
   table_mode: z5.enum(["markdown", "image"]).optional(),
@@ -739,6 +998,9 @@ var parsePdfInputSchema = z5.object({
   images_as_url: z5.boolean().optional(),
   skip_rotation_detection: z5.boolean().optional(),
   enable_cross_page_merge: z5.boolean().optional(),
+  enrichment: z5.string().optional().describe(
+    "Parse-time AI sidecars. Omit for server default outline,summary. Use 'none' to disable. Examples: outline,summary,verification"
+  ),
   output_subdir: z5.string().optional().describe("Subdirectory name under KOLMOPDF_OUTPUT_DIR. Defaults to <task_id>.")
 });
 async function parsePdfHandler(args, ctx) {
@@ -765,7 +1027,8 @@ async function parsePdfHandler(args, ctx) {
       output_options: args.output_options,
       images_as_url: args.images_as_url,
       skip_rotation_detection: args.skip_rotation_detection,
-      enable_cross_page_merge: args.enable_cross_page_merge
+      enable_cross_page_merge: args.enable_cross_page_merge,
+      enrichment: args.enrichment
     },
     filename
   );
@@ -784,23 +1047,24 @@ async function parsePdfHandler(args, ctx) {
   const subdir = args.output_subdir || taskId;
   const outputRoot = resolve3(ctx.config.outputDir, subdir);
   mkdirSync3(outputRoot, { recursive: true });
-  const isUrlMode = args.images_as_url === true;
+  const downloadPath = join4(outputRoot, "download.bin");
+  const ws = createWriteStream3(downloadPath);
+  await client.download(taskId, ws, { destPath: downloadPath });
   let markdownPath;
   let imagesDir = null;
   let outputType;
-  if (isUrlMode) {
-    markdownPath = join3(outputRoot, "result.md");
-    const ws = createWriteStream3(markdownPath);
-    await client.download(taskId, ws);
-    outputType = "markdown_file";
-  } else {
-    const zipPath = join3(outputRoot, "result.zip");
-    const ws = createWriteStream3(zipPath);
-    await client.download(taskId, ws);
+  const kind = await sniffFile(downloadPath);
+  if (kind === "zip") {
+    const zipPath = join4(outputRoot, "result.zip");
+    await rename3(downloadPath, zipPath);
     const extracted = await extractZip(zipPath, outputRoot);
-    markdownPath = extracted.markdownPath || join3(outputRoot, "result.md");
+    markdownPath = extracted.markdownPath || join4(outputRoot, "result.md");
     imagesDir = extracted.imagesDir;
     outputType = "zip_extracted";
+  } else {
+    markdownPath = join4(outputRoot, "result.md");
+    await rename3(downloadPath, markdownPath);
+    outputType = "markdown_file";
   }
   const mdContent = await readFile3(markdownPath, "utf-8").catch(() => "");
   const preview = mdContent.slice(0, 500);
@@ -824,11 +1088,11 @@ async function parsePdfHandler(args, ctx) {
 
 // src/tools/translate-pdf.ts
 import { createWriteStream as createWriteStream4, mkdirSync as mkdirSync4 } from "fs";
-import { readFile as readFile4 } from "fs/promises";
-import { basename as basename3, join as join4, resolve as resolve4 } from "path";
+import { readFile as readFile4, rename as rename4 } from "fs/promises";
+import { basename as basename3, join as join5, resolve as resolve4 } from "path";
 import { z as z6 } from "zod";
 var translatePdfName = "kolmopdf_translate_pdf";
-var translatePdfDescription = "Translate a PDF while preserving its original layout via KolmoPDF. Produces a translated PDF (optionally side-by-side bilingual).";
+var translatePdfDescription = "Translate a PDF while preserving its original layout via KolmoPDF. Produces a translated PDF, or a ZIP of PDFs when multiple layout modes are requested.";
 var translatePdfInputSchema = z6.object({
   file_path: z6.string(),
   source_language: z6.string().optional().default("en"),
@@ -874,13 +1138,23 @@ async function translatePdfHandler(args, ctx) {
     },
     progress: ctx.progress
   });
-  await ctx.progress?.report("[downloading] Fetching translated PDF...");
+  await ctx.progress?.report("[downloading] Fetching translated result...");
   const subdir = args.output_subdir || taskId;
   const outputRoot = resolve4(ctx.config.outputDir, subdir);
   mkdirSync4(outputRoot, { recursive: true });
-  const pdfPath = join4(outputRoot, "translated.pdf");
-  const ws = createWriteStream4(pdfPath);
-  await client.download(taskId, ws);
+  const tempPath = join5(outputRoot, "download.bin");
+  const ws = createWriteStream4(tempPath);
+  await client.download(taskId, ws, { destPath: tempPath });
+  const kind = await sniffFile(tempPath);
+  let translatedPdfPath = join5(outputRoot, `translated${extensionForKind(kind)}`);
+  let archivePath;
+  await rename4(tempPath, translatedPdfPath);
+  if (kind === "zip") {
+    archivePath = translatedPdfPath;
+    const extracted = await extractZip(archivePath, outputRoot);
+    const pdfs = extracted.files.filter((f) => f.toLowerCase().endsWith(".pdf"));
+    if (pdfs[0]) translatedPdfPath = pdfs[0];
+  }
   const pagesTranslated = Math.round(submitResult.points_deducted / 2);
   const output = {
     task_id: taskId,
@@ -888,14 +1162,16 @@ async function translatePdfHandler(args, ctx) {
     points_deducted: submitResult.points_deducted,
     remaining_points: submitResult.remaining_points,
     output: {
-      translated_pdf_path: pdfPath
+      kind,
+      translated_pdf_path: translatedPdfPath,
+      ...archivePath ? { archive_path: archivePath } : {}
     }
   };
   return jsonResult(output);
 }
 
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.1.0";
 function buildContext() {
   const config = loadConfig();
   return {