@kolmopdf/mcp-server 1.2.1 → 1.2.2

package/README.md

@@ -16,13 +16,15 @@ MCP server for [KolmoPDF](https://www.kolmopdf.com) — high-fidelity PDF→Mark
 }
 ```
 
+On macOS GUI clients, `npx` may not be on the app's PATH even when it works in Terminal. Run `command -v npx` and use that absolute path as `command`. Put `KOLMOPDF_API_KEY` in the client's private MCP `env`, then fully restart the app.
+
 ## Environment variables
 
 | Variable | Required | Default | Description |
 | --- | --- | --- | --- |
 | `KOLMOPDF_API_KEY` | yes | — | API key from https://www.kolmopdf.com/api-keys |
 | `KOLMOPDF_BASE_URL` | no | `https://www.kolmopdf.com` | Override for enterprise/debug |
-| `KOLMOPDF_OUTPUT_DIR` | no | `./kolmopdf-output` | Extraction root |
+| `KOLMOPDF_OUTPUT_DIR` | no | `~/kolmopdf-output` | Absolute or cwd-relative extraction root |
 | `KOLMOPDF_POLL_INTERVAL_MS` | no | `2000` | Status poll interval |
 | `KOLMOPDF_MAX_POLL_MINUTES` | no | `30` | Max client-side wait |
 | `KOLMOPDF_HTTP_TIMEOUT_MS` | no | `60000` | Per-call HTTP timeout |

package/dist/index.cjs

@@ -38,19 +38,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"
   },
@@ -474,9 +474,11 @@ var KolmoPdfClient = class {
 };
 
 // src/config.ts
+var import_node_os = require("os");
+var import_node_path = require("path");
 var DEFAULTS = {
   baseUrl: "https://www.kolmopdf.com",
-  outputDir: "./kolmopdf-output",
+  outputDir: (0, import_node_path.resolve)((0, import_node_os.homedir)(), "kolmopdf-output"),
   pollIntervalMs: 2e3,
   maxPollMinutes: 30,
   httpTimeoutMs: 6e4,
@@ -490,12 +492,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: (0, import_node_path.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),
@@ -533,9 +539,23 @@ async function checkBalanceHandler(_args, ctx) {
 // src/tools/convert.ts
 var import_node_fs = require("fs");
 var import_promises4 = require("fs/promises");
-var import_node_path2 = require("path");
+var import_node_path4 = require("path");
 var import_zod2 = require("zod");
 
+// src/output.ts
+var import_node_path2 = require("path");
+function resolveOutputRoot(baseDir, subdir) {
+  const root = (0, import_node_path2.resolve)(baseDir);
+  const candidate = (0, import_node_path2.resolve)(root, subdir);
+  const rel = (0, import_node_path2.relative)(root, candidate);
+  if (rel.startsWith("..") || (0, import_node_path2.isAbsolute)(rel)) {
+    throw new KolmoPdfError("client_local_validation", {
+      message: "output_subdir must stay inside KOLMOPDF_OUTPUT_DIR."
+    });
+  }
+  return candidate;
+}
+
 // src/pages.ts
 var import_promises2 = require("fs/promises");
 var import_pdf_lib = require("pdf-lib");
@@ -577,7 +597,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++) {
@@ -716,7 +736,7 @@ async function pollUntilComplete(ctx) {
 
 // src/sniff.ts
 var import_promises3 = require("fs/promises");
-var import_node_path = require("path");
+var import_node_path3 = require("path");
 var EXT = {
   zip: ".zip",
   pdf: ".pdf",
@@ -780,10 +800,13 @@ 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 = (0, import_node_path2.resolve)(args.file_path);
-  const filename = (0, import_node_path2.basename)(filePath);
+  const filePath = (0, import_node_path4.resolve)(args.file_path);
+  const filename = (0, import_node_path4.basename)(filePath);
   const fileSize = await readFileSize(filePath);
   if (fileSize > MAX_FILE_BYTES) {
     throw new KolmoPdfError("convert_file_too_large");
@@ -814,13 +837,14 @@ async function convertHandler(args, ctx) {
   });
   await ctx.progress?.report("[downloading] Fetching converted file...");
   const subdir = args.output_subdir || taskId;
-  const outputRoot = (0, import_node_path2.resolve)(ctx.config.outputDir, subdir);
+  const outputRoot = resolveOutputRoot(ctx.config.outputDir, subdir);
   (0, import_node_fs.mkdirSync)(outputRoot, { recursive: true });
-  const tempPath = (0, import_node_path2.join)(outputRoot, "download.bin");
+  const tempPath = (0, import_node_path4.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)}`);
+  const sniffedKind = await sniffFile(tempPath);
+  const kind = resolveConvertKind(sniffedKind, args.target_format);
+  const outputPath = (0, import_node_path4.join)(outputRoot, `result${extensionForKind(kind)}`);
   await (0, import_promises4.rename)(tempPath, outputPath);
   const output = {
     task_id: taskId,
@@ -836,7 +860,7 @@ async function convertHandler(args, ctx) {
 }
 
 // src/tools/estimate-cost.ts
-var import_node_path3 = require("path");
+var import_node_path5 = 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.";
@@ -866,7 +890,7 @@ async function estimateCostHandler(args, ctx) {
   const client = ctx.getClient();
   let pages = null;
   if (args.operation !== "convert") {
-    const filePath = (0, import_node_path3.resolve)(args.file_path);
+    const filePath = (0, import_node_path5.resolve)(args.file_path);
     pages = await readPageCount(filePath);
   }
   const estimatedCredits = estimateCredits(args.operation, pages ?? 1);
@@ -900,12 +924,12 @@ async function getTaskStatusHandler(args, ctx) {
 // src/tools/parse-pdf.ts
 var import_node_fs3 = require("fs");
 var import_promises6 = require("fs/promises");
-var import_node_path5 = require("path");
+var import_node_path7 = require("path");
 var import_zod5 = require("zod");
 
 // src/extract.ts
 var import_node_fs2 = require("fs");
-var import_node_path4 = require("path");
+var import_node_path6 = require("path");
 var import_promises5 = require("stream/promises");
 var import_yauzl = require("yauzl");
 function pickPrimaryMarkdownPath(candidates) {
@@ -925,6 +949,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 = (0, import_node_path6.resolve)(destDir);
+  const entryPath = (0, import_node_path6.resolve)(root, ...segments);
+  const rel = (0, import_node_path6.relative)(root, entryPath);
+  if (rel.startsWith("..") || (0, import_node_path6.isAbsolute)(rel)) {
+    throw new KolmoPdfError("client_extract_failed", {
+      message: `Unsafe ZIP entry path: ${entryName}`
+    });
+  }
+  return entryPath;
+}
 async function extractZip(zipPath, destDir) {
   (0, import_node_fs2.mkdirSync)(destDir, { recursive: true });
   const zipFile = await openZip(zipPath);
@@ -932,7 +974,7 @@ async function extractZip(zipPath, destDir) {
   const mdCandidates = [];
   let imagesDir = null;
   for await (const entry of iterEntries(zipFile)) {
-    const entryPath = (0, import_node_path4.join)(destDir, entry.fileName);
+    const entryPath = safeZipEntryPath(destDir, entry.fileName);
     if (entry.fileName.endsWith("/")) {
       (0, import_node_fs2.mkdirSync)(entryPath, { recursive: true });
       if (entry.fileName.includes("images")) {
@@ -940,7 +982,7 @@ async function extractZip(zipPath, destDir) {
       }
       continue;
     }
-    (0, import_node_fs2.mkdirSync)((0, import_node_path4.dirname)(entryPath), { recursive: true });
+    (0, import_node_fs2.mkdirSync)((0, import_node_path6.dirname)(entryPath), { recursive: true });
     const readStream = await openReadStream(zipFile, entry);
     const writeStream = (0, import_node_fs2.createWriteStream)(entryPath);
     await (0, import_promises5.pipeline)(readStream, writeStream);
@@ -955,36 +997,36 @@ async function extractZip(zipPath, destDir) {
     }
     if (!imagesDir && /images\//i.test(entry.fileName)) {
       const prefix = entry.fileName.split("images/")[0] ?? "";
-      imagesDir = (0, import_node_path4.join)(destDir, prefix, "images");
+      imagesDir = (0, import_node_path6.join)(destDir, prefix, "images");
     }
   }
   const markdownPath = pickPrimaryMarkdownPath(mdCandidates);
   return { markdownPath, imagesDir, outputRoot: destDir, files };
 }
 function openZip(path) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve8, reject) => {
     (0, import_yauzl.open)(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);
@@ -993,7 +1035,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;
@@ -1001,10 +1043,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);
     });
   });
 }
@@ -1029,8 +1071,8 @@ var parsePdfInputSchema = import_zod5.z.object({
 });
 async function parsePdfHandler(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_path7.resolve)(args.file_path);
+  const filename = (0, import_node_path7.basename)(filePath);
   const fileSize = await readFileSize(filePath);
   if (fileSize > MAX_FILE_BYTES) {
     throw new KolmoPdfError("parse_file_too_large");
@@ -1069,9 +1111,9 @@ async function parsePdfHandler(args, ctx) {
   });
   await ctx.progress?.report("[downloading] Fetching result...");
   const subdir = args.output_subdir || taskId;
-  const outputRoot = (0, import_node_path5.resolve)(ctx.config.outputDir, subdir);
+  const outputRoot = resolveOutputRoot(ctx.config.outputDir, subdir);
   (0, import_node_fs3.mkdirSync)(outputRoot, { recursive: true });
-  const downloadPath = (0, import_node_path5.join)(outputRoot, "download.bin");
+  const downloadPath = (0, import_node_path7.join)(outputRoot, "download.bin");
   const ws = (0, import_node_fs3.createWriteStream)(downloadPath);
   await client.download(taskId, ws, { destPath: downloadPath });
   let markdownPath;
@@ -1079,14 +1121,14 @@ async function parsePdfHandler(args, ctx) {
   let outputType;
   const kind = await sniffFile(downloadPath);
   if (kind === "zip") {
-    const zipPath = (0, import_node_path5.join)(outputRoot, "result.zip");
+    const zipPath = (0, import_node_path7.join)(outputRoot, "result.zip");
     await (0, import_promises6.rename)(downloadPath, zipPath);
     const extracted = await extractZip(zipPath, outputRoot);
-    markdownPath = extracted.markdownPath || (0, import_node_path5.join)(outputRoot, "result.md");
+    markdownPath = extracted.markdownPath || (0, import_node_path7.join)(outputRoot, "result.md");
     imagesDir = extracted.imagesDir;
     outputType = "zip_extracted";
   } else {
-    markdownPath = (0, import_node_path5.join)(outputRoot, "result.md");
+    markdownPath = (0, import_node_path7.join)(outputRoot, "result.md");
     await (0, import_promises6.rename)(downloadPath, markdownPath);
     outputType = "markdown_file";
   }
@@ -1113,7 +1155,7 @@ async function parsePdfHandler(args, ctx) {
 // src/tools/translate-pdf.ts
 var import_node_fs4 = require("fs");
 var import_promises7 = require("fs/promises");
-var import_node_path6 = require("path");
+var import_node_path8 = 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, or a ZIP of PDFs when multiple layout modes are requested.";
@@ -1128,8 +1170,8 @@ var translatePdfInputSchema = import_zod6.z.object({
 });
 async function translatePdfHandler(args, ctx) {
   const client = ctx.getClient();
-  const filePath = (0, import_node_path6.resolve)(args.file_path);
-  const filename = (0, import_node_path6.basename)(filePath);
+  const filePath = (0, import_node_path8.resolve)(args.file_path);
+  const filename = (0, import_node_path8.basename)(filePath);
   const fileSize = await readFileSize(filePath);
   if (fileSize > MAX_FILE_BYTES) {
     throw new KolmoPdfError("translate_pdf_file_too_large");
@@ -1164,13 +1206,13 @@ async function translatePdfHandler(args, ctx) {
   });
   await ctx.progress?.report("[downloading] Fetching translated result...");
   const subdir = args.output_subdir || taskId;
-  const outputRoot = (0, import_node_path6.resolve)(ctx.config.outputDir, subdir);
+  const outputRoot = resolveOutputRoot(ctx.config.outputDir, subdir);
   (0, import_node_fs4.mkdirSync)(outputRoot, { recursive: true });
-  const tempPath = (0, import_node_path6.join)(outputRoot, "download.bin");
+  const tempPath = (0, import_node_path8.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 translatedPdfPath = (0, import_node_path8.join)(outputRoot, `translated${extensionForKind(kind)}`);
   let archivePath;
   await (0, import_promises7.rename)(tempPath, translatedPdfPath);
   if (kind === "zip") {
@@ -1195,7 +1237,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 {