@kolmopdf/mcp-server 1.0.2 → 1.1.0

package/dist/index.cjs

@@ -29,6 +29,7 @@ var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
 // src/client.ts
+var import_node_crypto = require("crypto");
 var import_node_stream = require("stream");
 var import_promises = require("stream/promises");
 
@@ -228,6 +229,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;
@@ -239,18 +246,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
       );
     }
@@ -271,6 +298,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);
@@ -284,13 +325,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": (0, import_node_crypto.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);
@@ -301,35 +343,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": (0, import_node_crypto.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": (0, import_node_crypto.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)
@@ -341,32 +425,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 = import_node_stream.Readable.from(generate());
     await (0, import_promises.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 ?? "")
+    };
   }
 };
 
@@ -429,8 +532,8 @@ async function checkBalanceHandler(_args, ctx) {
 
 // src/tools/convert.ts
 var import_node_fs = require("fs");
-var import_promises3 = require("fs/promises");
-var import_node_path = require("path");
+var import_promises4 = require("fs/promises");
+var import_node_path2 = require("path");
 var import_zod2 = require("zod");
 
 // src/pages.ts
@@ -457,8 +560,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,
@@ -488,19 +591,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"
       });
@@ -511,6 +714,52 @@ async function pollUntilComplete(ctx) {
   }
 }
 
+// src/sniff.ts
+var import_promises3 = require("fs/promises");
+var import_node_path = require("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 (0, import_promises3.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.";
@@ -519,22 +768,6 @@ var convertInputSchema = import_zod2.z.object({
   target_format: import_zod2.z.enum(["word", "docx", "html", "pdf", "latex", "tex"]).optional().default("word"),
   output_subdir: import_zod2.z.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":
@@ -549,8 +782,8 @@ function normalizeFormat(targetFormat) {
 }
 async function convertHandler(args, ctx) {
   const client = ctx.getClient();
-  const filePath = (0, import_node_path.resolve)(args.file_path);
-  const filename = (0, import_node_path.basename)(filePath);
+  const filePath = (0, import_node_path2.resolve)(args.file_path);
+  const filename = (0, import_node_path2.basename)(filePath);
   const fileSize = await readFileSize(filePath);
   if (fileSize > MAX_FILE_BYTES) {
     throw new KolmoPdfError("convert_file_too_large");
@@ -560,7 +793,7 @@ async function convertHandler(args, ctx) {
     throw new KolmoPdfError("convert_file_type_unsupported");
   }
   await ctx.progress?.report("[uploading] Sending file for conversion...");
-  const fileBuffer = await (0, import_promises3.readFile)(filePath);
+  const fileBuffer = await (0, import_promises4.readFile)(filePath);
   const submitResult = await client.convert(
     fileBuffer,
     {
@@ -581,26 +814,29 @@ async function convertHandler(args, ctx) {
   });
   await ctx.progress?.report("[downloading] Fetching converted file...");
   const subdir = args.output_subdir || taskId;
-  const outputRoot = (0, import_node_path.resolve)(ctx.config.outputDir, subdir);
+  const outputRoot = (0, import_node_path2.resolve)(ctx.config.outputDir, subdir);
   (0, import_node_fs.mkdirSync)(outputRoot, { recursive: true });
-  const outExt = formatToExtension(args.target_format);
-  const outputPath = (0, import_node_path.join)(outputRoot, `result${outExt}`);
-  const ws = (0, import_node_fs.createWriteStream)(outputPath);
-  await client.download(taskId, ws);
+  const tempPath = (0, import_node_path2.join)(outputRoot, "download.bin");
+  const ws = (0, import_node_fs.createWriteStream)(tempPath);
+  await client.download(taskId, ws, { destPath: tempPath });
+  const kind = await sniffFile(tempPath);
+  const outputPath = (0, import_node_path2.join)(outputRoot, `result${extensionForKind(kind)}`);
+  await (0, import_promises4.rename)(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);
 }
 
 // src/tools/estimate-cost.ts
-var import_node_path2 = require("path");
+var import_node_path3 = require("path");
 var import_zod3 = require("zod");
 var estimateCostName = "kolmopdf_estimate_cost";
 var estimateCostDescription = "Estimate the credit cost of a KolmoPDF operation before running it. Reads page count locally and checks the current balance. Does not spend credits.";
@@ -630,7 +866,7 @@ async function estimateCostHandler(args, ctx) {
   const client = ctx.getClient();
   let pages = null;
   if (args.operation !== "convert") {
-    const filePath = (0, import_node_path2.resolve)(args.file_path);
+    const filePath = (0, import_node_path3.resolve)(args.file_path);
     pages = await readPageCount(filePath);
   }
   const estimatedCredits = estimateCredits(args.operation, pages ?? 1);
@@ -663,23 +899,40 @@ async function getTaskStatusHandler(args, ctx) {
 
 // src/tools/parse-pdf.ts
 var import_node_fs3 = require("fs");
-var import_promises5 = require("fs/promises");
-var import_node_path4 = require("path");
+var import_promises6 = require("fs/promises");
+var import_node_path5 = require("path");
 var import_zod5 = require("zod");
 
 // src/extract.ts
 var import_node_fs2 = require("fs");
-var import_node_path3 = require("path");
-var import_promises4 = require("stream/promises");
+var import_node_path4 = require("path");
+var import_promises5 = require("stream/promises");
 var import_yauzl = require("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) {
   (0, import_node_fs2.mkdirSync)(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 = (0, import_node_path3.join)(destDir, entry.fileName);
+    const entryPath = (0, import_node_path4.join)(destDir, entry.fileName);
     if (entry.fileName.endsWith("/")) {
       (0, import_node_fs2.mkdirSync)(entryPath, { recursive: true });
       if (entry.fileName.includes("images")) {
@@ -687,19 +940,25 @@ async function extractZip(zipPath, destDir) {
       }
       continue;
     }
-    (0, import_node_fs2.mkdirSync)((0, import_node_path3.dirname)(entryPath), { recursive: true });
+    (0, import_node_fs2.mkdirSync)((0, import_node_path4.dirname)(entryPath), { recursive: true });
     const readStream = await openReadStream(zipFile, entry);
     const writeStream = (0, import_node_fs2.createWriteStream)(entryPath);
-    await (0, import_promises4.pipeline)(readStream, writeStream);
+    await (0, import_promises5.pipeline)(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 = (0, import_node_fs2.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 = (0, import_node_path3.join)(destDir, prefix, "images");
+      imagesDir = (0, import_node_path4.join)(destDir, prefix, "images");
     }
   }
+  const markdownPath = pickPrimaryMarkdownPath(mdCandidates);
   return { markdownPath, imagesDir, outputRoot: destDir, files };
 }
 function openZip(path) {
@@ -752,7 +1011,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 = import_zod5.z.object({
   file_path: import_zod5.z.string().describe("Absolute or cwd-relative path to a local PDF file."),
   table_mode: import_zod5.z.enum(["markdown", "image"]).optional(),
@@ -763,12 +1022,15 @@ var parsePdfInputSchema = import_zod5.z.object({
   images_as_url: import_zod5.z.boolean().optional(),
   skip_rotation_detection: import_zod5.z.boolean().optional(),
   enable_cross_page_merge: import_zod5.z.boolean().optional(),
+  enrichment: import_zod5.z.string().optional().describe(
+    "Parse-time AI sidecars. Omit for server default outline,summary. Use 'none' to disable. Examples: outline,summary,verification"
+  ),
   output_subdir: import_zod5.z.string().optional().describe("Subdirectory name under KOLMOPDF_OUTPUT_DIR. Defaults to <task_id>.")
 });
 async function parsePdfHandler(args, ctx) {
   const client = ctx.getClient();
-  const filePath = (0, import_node_path4.resolve)(args.file_path);
-  const filename = (0, import_node_path4.basename)(filePath);
+  const filePath = (0, import_node_path5.resolve)(args.file_path);
+  const filename = (0, import_node_path5.basename)(filePath);
   const fileSize = await readFileSize(filePath);
   if (fileSize > MAX_FILE_BYTES) {
     throw new KolmoPdfError("parse_file_too_large");
@@ -778,7 +1040,7 @@ async function parsePdfHandler(args, ctx) {
     throw new KolmoPdfError("parse_page_limit_exceeded");
   }
   await ctx.progress?.report("[uploading] Sending PDF to KolmoPDF...");
-  const fileBuffer = await (0, import_promises5.readFile)(filePath);
+  const fileBuffer = await (0, import_promises6.readFile)(filePath);
   const submitResult = await client.parse(
     fileBuffer,
     {
@@ -789,7 +1051,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
   );
@@ -806,27 +1069,28 @@ async function parsePdfHandler(args, ctx) {
   });
   await ctx.progress?.report("[downloading] Fetching result...");
   const subdir = args.output_subdir || taskId;
-  const outputRoot = (0, import_node_path4.resolve)(ctx.config.outputDir, subdir);
+  const outputRoot = (0, import_node_path5.resolve)(ctx.config.outputDir, subdir);
   (0, import_node_fs3.mkdirSync)(outputRoot, { recursive: true });
-  const isUrlMode = args.images_as_url === true;
+  const downloadPath = (0, import_node_path5.join)(outputRoot, "download.bin");
+  const ws = (0, import_node_fs3.createWriteStream)(downloadPath);
+  await client.download(taskId, ws, { destPath: downloadPath });
   let markdownPath;
   let imagesDir = null;
   let outputType;
-  if (isUrlMode) {
-    markdownPath = (0, import_node_path4.join)(outputRoot, "result.md");
-    const ws = (0, import_node_fs3.createWriteStream)(markdownPath);
-    await client.download(taskId, ws);
-    outputType = "markdown_file";
-  } else {
-    const zipPath = (0, import_node_path4.join)(outputRoot, "result.zip");
-    const ws = (0, import_node_fs3.createWriteStream)(zipPath);
-    await client.download(taskId, ws);
+  const kind = await sniffFile(downloadPath);
+  if (kind === "zip") {
+    const zipPath = (0, import_node_path5.join)(outputRoot, "result.zip");
+    await (0, import_promises6.rename)(downloadPath, zipPath);
     const extracted = await extractZip(zipPath, outputRoot);
-    markdownPath = extracted.markdownPath || (0, import_node_path4.join)(outputRoot, "result.md");
+    markdownPath = extracted.markdownPath || (0, import_node_path5.join)(outputRoot, "result.md");
     imagesDir = extracted.imagesDir;
     outputType = "zip_extracted";
+  } else {
+    markdownPath = (0, import_node_path5.join)(outputRoot, "result.md");
+    await (0, import_promises6.rename)(downloadPath, markdownPath);
+    outputType = "markdown_file";
   }
-  const mdContent = await (0, import_promises5.readFile)(markdownPath, "utf-8").catch(() => "");
+  const mdContent = await (0, import_promises6.readFile)(markdownPath, "utf-8").catch(() => "");
   const preview = mdContent.slice(0, 500);
   const ptsPerPage = args.enable_translation ? 3 : 2;
   const pagesParsed = Math.round(submitResult.points_deducted / ptsPerPage);
@@ -848,11 +1112,11 @@ async function parsePdfHandler(args, ctx) {
 
 // src/tools/translate-pdf.ts
 var import_node_fs4 = require("fs");
-var import_promises6 = require("fs/promises");
-var import_node_path5 = require("path");
+var import_promises7 = require("fs/promises");
+var import_node_path6 = require("path");
 var import_zod6 = require("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 = import_zod6.z.object({
   file_path: import_zod6.z.string(),
   source_language: import_zod6.z.string().optional().default("en"),
@@ -864,8 +1128,8 @@ var translatePdfInputSchema = import_zod6.z.object({
 });
 async function translatePdfHandler(args, ctx) {
   const client = ctx.getClient();
-  const filePath = (0, import_node_path5.resolve)(args.file_path);
-  const filename = (0, import_node_path5.basename)(filePath);
+  const filePath = (0, import_node_path6.resolve)(args.file_path);
+  const filename = (0, import_node_path6.basename)(filePath);
   const fileSize = await readFileSize(filePath);
   if (fileSize > MAX_FILE_BYTES) {
     throw new KolmoPdfError("translate_pdf_file_too_large");
@@ -875,7 +1139,7 @@ async function translatePdfHandler(args, ctx) {
     throw new KolmoPdfError("translate_pdf_page_limit_exceeded");
   }
   await ctx.progress?.report("[uploading] Sending PDF for translation...");
-  const fileBuffer = await (0, import_promises6.readFile)(filePath);
+  const fileBuffer = await (0, import_promises7.readFile)(filePath);
   const submitResult = await client.translatePdf(
     fileBuffer,
     {
@@ -898,13 +1162,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 = (0, import_node_path5.resolve)(ctx.config.outputDir, subdir);
+  const outputRoot = (0, import_node_path6.resolve)(ctx.config.outputDir, subdir);
   (0, import_node_fs4.mkdirSync)(outputRoot, { recursive: true });
-  const pdfPath = (0, import_node_path5.join)(outputRoot, "translated.pdf");
-  const ws = (0, import_node_fs4.createWriteStream)(pdfPath);
-  await client.download(taskId, ws);
+  const tempPath = (0, import_node_path6.join)(outputRoot, "download.bin");
+  const ws = (0, import_node_fs4.createWriteStream)(tempPath);
+  await client.download(taskId, ws, { destPath: tempPath });
+  const kind = await sniffFile(tempPath);
+  let translatedPdfPath = (0, import_node_path6.join)(outputRoot, `translated${extensionForKind(kind)}`);
+  let archivePath;
+  await (0, import_promises7.rename)(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,
@@ -912,14 +1186,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 {