@kolmopdf/mcp-server 1.2.0 → 1.2.2

package/dist/index.js

@@ -14,19 +14,19 @@ var ERROR_SPECS = {
   // --- API codes ---
   invalid_api_key: {
     message: "API key is missing or invalid.",
-    remediation: "Create a key at https://www.kolmopdf.com/api-keys (requires Plus/Pro).",
+    remediation: "Create a key at https://www.kolmopdf.com/api-keys. Every account, including PAYG, can create one API key.",
     httpStatus: 401,
     source: "api"
   },
   insufficient_points: {
     message: "Not enough credits.",
-    remediation: "Top up at https://www.kolmopdf.com/subscription.",
+    remediation: "Buy one-time credits at https://www.kolmopdf.com/credits \u2014 no subscription required. Credits are shared with the web account. Check the API key spending limit separately. Never start a purchase without the user's confirmation.",
     httpStatus: 402,
     source: "api"
   },
   points_deduction_failed: {
     message: "Credit deduction failed.",
-    remediation: "Retry; if it persists contact support.",
+    remediation: "Check your balance and API key limit. Buy one-time credits at https://www.kolmopdf.com/credits; do not retry a paid operation or purchase automatically.",
     httpStatus: 402,
     source: "api"
   },
@@ -450,9 +450,11 @@ var KolmoPdfClient = class {
 };
 
 // src/config.ts
+import { homedir } from "os";
+import { resolve } from "path";
 var DEFAULTS = {
   baseUrl: "https://www.kolmopdf.com",
-  outputDir: "./kolmopdf-output",
+  outputDir: resolve(homedir(), "kolmopdf-output"),
   pollIntervalMs: 2e3,
   maxPollMinutes: 30,
   httpTimeoutMs: 6e4,
@@ -466,12 +468,16 @@ function intFromEnv(value, fallback) {
 function trimTrailingSlash(url) {
   return url.replace(/\/+$/, "");
 }
+function normalizeApiKey(value) {
+  const trimmed = value?.trim();
+  if (!trimmed || /^\$\{KOLMOPDF_API_KEY(?::-[^}]*)?\}$/.test(trimmed)) return void 0;
+  return trimmed;
+}
 function loadConfig(env = process.env) {
-  const apiKeyRaw = env.KOLMOPDF_API_KEY?.trim();
   return {
-    apiKey: apiKeyRaw && apiKeyRaw.length > 0 ? apiKeyRaw : void 0,
+    apiKey: normalizeApiKey(env.KOLMOPDF_API_KEY),
     baseUrl: trimTrailingSlash(env.KOLMOPDF_BASE_URL?.trim() || DEFAULTS.baseUrl),
-    outputDir: env.KOLMOPDF_OUTPUT_DIR?.trim() || DEFAULTS.outputDir,
+    outputDir: resolve(env.KOLMOPDF_OUTPUT_DIR?.trim() || DEFAULTS.outputDir),
     pollIntervalMs: intFromEnv(env.KOLMOPDF_POLL_INTERVAL_MS, DEFAULTS.pollIntervalMs),
     maxPollMinutes: intFromEnv(env.KOLMOPDF_MAX_POLL_MINUTES, DEFAULTS.maxPollMinutes),
     httpTimeoutMs: intFromEnv(env.KOLMOPDF_HTTP_TIMEOUT_MS, DEFAULTS.httpTimeoutMs),
@@ -509,9 +515,23 @@ async function checkBalanceHandler(_args, ctx) {
 // src/tools/convert.ts
 import { createWriteStream, mkdirSync } from "fs";
 import { readFile as readFile2, rename as rename2 } from "fs/promises";
-import { basename, join as join2, resolve } from "path";
+import { basename, join as join2, resolve as resolve3 } from "path";
 import { z as z2 } from "zod";
 
+// src/output.ts
+import { isAbsolute, relative, resolve as resolve2 } from "path";
+function resolveOutputRoot(baseDir, subdir) {
+  const root = resolve2(baseDir);
+  const candidate = resolve2(root, subdir);
+  const rel = relative(root, candidate);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new KolmoPdfError("client_local_validation", {
+      message: "output_subdir must stay inside KOLMOPDF_OUTPUT_DIR."
+    });
+  }
+  return candidate;
+}
+
 // src/pages.ts
 import { readFile, stat } from "fs/promises";
 import { PDFDocument } from "pdf-lib";
@@ -553,7 +573,7 @@ function isRetryable(err) {
   return false;
 }
 function sleep(ms) {
-  return new Promise((resolve5) => setTimeout(resolve5, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 async function fetchStatusWithRetry(client, taskId) {
   for (let attempt = 1; attempt <= RETRY_POLICY.maxAttempts; attempt++) {
@@ -756,9 +776,12 @@ function normalizeFormat(targetFormat) {
       return targetFormat;
   }
 }
+function resolveConvertKind(sniffedKind, targetFormat) {
+  return normalizeFormat(targetFormat) === "docx" && sniffedKind === "zip" ? "docx" : sniffedKind;
+}
 async function convertHandler(args, ctx) {
   const client = ctx.getClient();
-  const filePath = resolve(args.file_path);
+  const filePath = resolve3(args.file_path);
   const filename = basename(filePath);
   const fileSize = await readFileSize(filePath);
   if (fileSize > MAX_FILE_BYTES) {
@@ -790,12 +813,13 @@ async function convertHandler(args, ctx) {
   });
   await ctx.progress?.report("[downloading] Fetching converted file...");
   const subdir = args.output_subdir || taskId;
-  const outputRoot = resolve(ctx.config.outputDir, subdir);
+  const outputRoot = resolveOutputRoot(ctx.config.outputDir, subdir);
   mkdirSync(outputRoot, { recursive: true });
   const tempPath = join2(outputRoot, "download.bin");
   const ws = createWriteStream(tempPath);
   await client.download(taskId, ws, { destPath: tempPath });
-  const kind = await sniffFile(tempPath);
+  const sniffedKind = await sniffFile(tempPath);
+  const kind = resolveConvertKind(sniffedKind, args.target_format);
   const outputPath = join2(outputRoot, `result${extensionForKind(kind)}`);
   await rename2(tempPath, outputPath);
   const output = {
@@ -812,7 +836,7 @@ async function convertHandler(args, ctx) {
 }
 
 // src/tools/estimate-cost.ts
-import { resolve as resolve2 } from "path";
+import { resolve as resolve4 } from "path";
 import { z as z3 } from "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.";
@@ -842,7 +866,7 @@ async function estimateCostHandler(args, ctx) {
   const client = ctx.getClient();
   let pages = null;
   if (args.operation !== "convert") {
-    const filePath = resolve2(args.file_path);
+    const filePath = resolve4(args.file_path);
     pages = await readPageCount(filePath);
   }
   const estimatedCredits = estimateCredits(args.operation, pages ?? 1);
@@ -876,12 +900,12 @@ async function getTaskStatusHandler(args, ctx) {
 // src/tools/parse-pdf.ts
 import { createWriteStream as createWriteStream3, mkdirSync as mkdirSync3 } from "fs";
 import { readFile as readFile3, rename as rename3 } from "fs/promises";
-import { basename as basename2, join as join4, resolve as resolve3 } from "path";
+import { basename as basename2, join as join4, resolve as resolve6 } from "path";
 import { z as z5 } from "zod";
 
 // src/extract.ts
 import { createWriteStream as createWriteStream2, mkdirSync as mkdirSync2, readFileSync } from "fs";
-import { dirname, join as join3 } from "path";
+import { dirname, isAbsolute as isAbsolute2, join as join3, relative as relative2, resolve as resolve5 } from "path";
 import { pipeline as pipeline2 } from "stream/promises";
 import { open as yauzlOpen } from "yauzl";
 function pickPrimaryMarkdownPath(candidates) {
@@ -901,6 +925,24 @@ function pickPrimaryMarkdownPath(candidates) {
   scored.sort((a, b) => b.score - a.score);
   return scored[0]?.path ?? null;
 }
+function safeZipEntryPath(destDir, entryName) {
+  const normalized = entryName.replace(/\\/g, "/");
+  const segments = normalized.split("/").filter((segment) => segment && segment !== ".");
+  if (normalized.includes("\0") || normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized) || segments.includes("..")) {
+    throw new KolmoPdfError("client_extract_failed", {
+      message: `Unsafe ZIP entry path: ${entryName}`
+    });
+  }
+  const root = resolve5(destDir);
+  const entryPath = resolve5(root, ...segments);
+  const rel = relative2(root, entryPath);
+  if (rel.startsWith("..") || isAbsolute2(rel)) {
+    throw new KolmoPdfError("client_extract_failed", {
+      message: `Unsafe ZIP entry path: ${entryName}`
+    });
+  }
+  return entryPath;
+}
 async function extractZip(zipPath, destDir) {
   mkdirSync2(destDir, { recursive: true });
   const zipFile = await openZip(zipPath);
@@ -908,7 +950,7 @@ async function extractZip(zipPath, destDir) {
   const mdCandidates = [];
   let imagesDir = null;
   for await (const entry of iterEntries(zipFile)) {
-    const entryPath = join3(destDir, entry.fileName);
+    const entryPath = safeZipEntryPath(destDir, entry.fileName);
     if (entry.fileName.endsWith("/")) {
       mkdirSync2(entryPath, { recursive: true });
       if (entry.fileName.includes("images")) {
@@ -938,29 +980,29 @@ async function extractZip(zipPath, destDir) {
   return { markdownPath, imagesDir, outputRoot: destDir, files };
 }
 function openZip(path) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve8, reject) => {
     yauzlOpen(path, { lazyEntries: true }, (err, zf) => {
       if (err || !zf) return reject(err ?? new Error("Failed to open zip"));
-      resolve5(zf);
+      resolve8(zf);
     });
   });
 }
 async function* iterEntries(zipFile) {
-  let resolve5 = null;
+  let resolve8 = null;
   const queue = [];
   zipFile.on("entry", (entry) => {
-    if (resolve5) {
-      const r = resolve5;
-      resolve5 = null;
+    if (resolve8) {
+      const r = resolve8;
+      resolve8 = null;
       r(entry);
     } else {
       queue.push(entry);
     }
   });
   zipFile.on("end", () => {
-    if (resolve5) {
-      const r = resolve5;
-      resolve5 = null;
+    if (resolve8) {
+      const r = resolve8;
+      resolve8 = null;
       r(null);
     } else {
       queue.push(null);
@@ -969,7 +1011,7 @@ async function* iterEntries(zipFile) {
   zipFile.readEntry();
   while (true) {
     const entry = queue.length > 0 ? queue.shift() : await new Promise((r) => {
-      resolve5 = r;
+      resolve8 = r;
     });
     if (entry === null) break;
     yield entry;
@@ -977,10 +1019,10 @@ async function* iterEntries(zipFile) {
   }
 }
 function openReadStream(zipFile, entry) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve8, reject) => {
     zipFile.openReadStream(entry, (err, stream) => {
       if (err || !stream) return reject(err ?? new Error("Failed to open entry stream"));
-      resolve5(stream);
+      resolve8(stream);
     });
   });
 }
@@ -1005,7 +1047,7 @@ var parsePdfInputSchema = z5.object({
 });
 async function parsePdfHandler(args, ctx) {
   const client = ctx.getClient();
-  const filePath = resolve3(args.file_path);
+  const filePath = resolve6(args.file_path);
   const filename = basename2(filePath);
   const fileSize = await readFileSize(filePath);
   if (fileSize > MAX_FILE_BYTES) {
@@ -1045,7 +1087,7 @@ async function parsePdfHandler(args, ctx) {
   });
   await ctx.progress?.report("[downloading] Fetching result...");
   const subdir = args.output_subdir || taskId;
-  const outputRoot = resolve3(ctx.config.outputDir, subdir);
+  const outputRoot = resolveOutputRoot(ctx.config.outputDir, subdir);
   mkdirSync3(outputRoot, { recursive: true });
   const downloadPath = join4(outputRoot, "download.bin");
   const ws = createWriteStream3(downloadPath);
@@ -1089,7 +1131,7 @@ async function parsePdfHandler(args, ctx) {
 // src/tools/translate-pdf.ts
 import { createWriteStream as createWriteStream4, mkdirSync as mkdirSync4 } from "fs";
 import { readFile as readFile4, rename as rename4 } from "fs/promises";
-import { basename as basename3, join as join5, resolve as resolve4 } from "path";
+import { basename as basename3, join as join5, resolve as resolve7 } 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, or a ZIP of PDFs when multiple layout modes are requested.";
@@ -1104,7 +1146,7 @@ var translatePdfInputSchema = z6.object({
 });
 async function translatePdfHandler(args, ctx) {
   const client = ctx.getClient();
-  const filePath = resolve4(args.file_path);
+  const filePath = resolve7(args.file_path);
   const filename = basename3(filePath);
   const fileSize = await readFileSize(filePath);
   if (fileSize > MAX_FILE_BYTES) {
@@ -1140,7 +1182,7 @@ async function translatePdfHandler(args, ctx) {
   });
   await ctx.progress?.report("[downloading] Fetching translated result...");
   const subdir = args.output_subdir || taskId;
-  const outputRoot = resolve4(ctx.config.outputDir, subdir);
+  const outputRoot = resolveOutputRoot(ctx.config.outputDir, subdir);
   mkdirSync4(outputRoot, { recursive: true });
   const tempPath = join5(outputRoot, "download.bin");
   const ws = createWriteStream4(tempPath);
@@ -1171,7 +1213,7 @@ async function translatePdfHandler(args, ctx) {
 }
 
 // src/index.ts
-var VERSION = "1.1.0";
+var VERSION = "1.2.2";
 function buildContext() {
   const config = loadConfig();
   return {