@kolmopdf/mcp-server 1.0.0 → 1.0.2

package/packages/mcp-server/src/tools/convert.ts

@@ -1,130 +0,0 @@
-import { createWriteStream, mkdirSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
-import { z } from "zod";
-import type { McpSuccessResult, ToolContext } from "../context.js";
-import { jsonResult } from "../context.js";
-import { KolmoPdfError } from "../errors.js";
-import { MAX_FILE_BYTES, readFileSize } from "../pages.js";
-import { pollUntilComplete } from "../polling.js";
-
-export const convertName = "kolmopdf_convert_markdown";
-
-export const convertDescription =
-  "Convert a Markdown file (or a ZIP of markdown + images) to DOCX, HTML, PDF, " +
-  "or LaTeX via KolmoPDF.";
-
-export const convertInputSchema = z.object({
-  file_path: z
-    .string()
-    .describe("Path to a .md/.markdown file or .zip containing markdown + images."),
-  target_format: z.enum(["word", "docx", "html", "pdf", "latex", "tex"]).optional().default("word"),
-  output_subdir: z.string().optional(),
-});
-
-export type ConvertInput = z.infer<typeof convertInputSchema>;
-
-export interface ConvertOutput {
-  task_id: string;
-  points_deducted: number;
-  remaining_points: number;
-  output: {
-    output_path: string;
-    target_format: string;
-  };
-}
-
-export function formatToExtension(targetFormat: string): string {
-  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";
-  }
-}
-
-export function normalizeFormat(targetFormat: string): string {
-  switch (targetFormat) {
-    case "word":
-    case "docx":
-      return "docx";
-    case "latex":
-    case "tex":
-      return "tex";
-    default:
-      return targetFormat;
-  }
-}
-export async function convertHandler(
-  args: ConvertInput,
-  ctx: ToolContext,
-): Promise<McpSuccessResult> {
-  const client = ctx.getClient();
-  const filePath = resolve(args.file_path);
-  const filename = basename(filePath);
-
-  const fileSize = await readFileSize(filePath);
-  if (fileSize > MAX_FILE_BYTES) {
-    throw new KolmoPdfError("convert_file_too_large");
-  }
-
-  const ext = filePath.toLowerCase();
-  if (!ext.endsWith(".md") && !ext.endsWith(".markdown") && !ext.endsWith(".zip")) {
-    throw new KolmoPdfError("convert_file_type_unsupported");
-  }
-
-  await ctx.progress?.report("[uploading] Sending file for conversion...");
-
-  const fileBuffer = await readFile(filePath);
-  const submitResult = await client.convert(
-    fileBuffer,
-    {
-      target_format: args.target_format,
-    },
-    filename,
-  );
-
-  const taskId = submitResult.task_id;
-  await ctx.progress?.report(`[submitted] Task ${taskId} created`);
-
-  await pollUntilComplete({
-    client,
-    taskId,
-    options: {
-      pollIntervalMs: ctx.config.pollIntervalMs,
-      maxPollMinutes: ctx.config.maxPollMinutes,
-    },
-    progress: ctx.progress,
-  });
-
-  await ctx.progress?.report("[downloading] Fetching converted file...");
-
-  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 output: ConvertOutput = {
-    task_id: taskId,
-    points_deducted: submitResult.points_deducted,
-    remaining_points: submitResult.remaining_points,
-    output: {
-      output_path: outputPath,
-      target_format: normalizeFormat(args.target_format),
-    },
-  };
-
-  return jsonResult(output as unknown as Record<string, unknown>);
-}

package/packages/mcp-server/src/tools/estimate-cost.ts

@@ -1,82 +0,0 @@
-import { resolve } from "node:path";
-import { z } from "zod";
-import type { McpSuccessResult, ToolContext } from "../context.js";
-import { jsonResult } from "../context.js";
-import { readPageCount } from "../pages.js";
-
-export const estimateCostName = "kolmopdf_estimate_cost";
-
-export const 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.";
-
-export const estimateCostInputSchema = z.object({
-  file_path: z.string(),
-  operation: z.enum(["parse", "parse_translate", "translate", "convert"]),
-  options: z
-    .object({
-      images_as_url: z.boolean().optional(),
-    })
-    .optional(),
-});
-
-export type EstimateCostInput = z.infer<typeof estimateCostInputSchema>;
-
-export type Operation = EstimateCostInput["operation"];
-
-export interface EstimateCostOutput {
-  pages: number | null;
-  estimated_credits: number;
-  current_balance: number;
-  sufficient: boolean;
-  shortfall: number;
-  recommendation: string;
-}
-
-export function estimateCredits(operation: Operation, pages: number): number {
-  switch (operation) {
-    case "parse":
-      return pages * 2;
-    case "parse_translate":
-      return pages * 3;
-    case "translate":
-      return pages * 2;
-    case "convert":
-      return 1;
-  }
-}
-
-export function buildRecommendation(shortfall: number): string {
-  return shortfall > 0
-    ? `Need top-up at https://www.kolmopdf.com/subscription (short by ${shortfall} credits).`
-    : "Sufficient";
-}
-
-export async function estimateCostHandler(
-  args: EstimateCostInput,
-  ctx: ToolContext,
-): Promise<McpSuccessResult> {
-  const client = ctx.getClient();
-
-  let pages: number | null = null;
-  if (args.operation !== "convert") {
-    const filePath = resolve(args.file_path);
-    pages = await readPageCount(filePath);
-  }
-
-  const estimatedCredits = estimateCredits(args.operation, pages ?? 1);
-  const balance = await client.getBalance();
-  const currentBalance = balance.points;
-  const shortfall = Math.max(0, estimatedCredits - currentBalance);
-
-  const output: EstimateCostOutput = {
-    pages,
-    estimated_credits: estimatedCredits,
-    current_balance: currentBalance,
-    sufficient: shortfall === 0,
-    shortfall,
-    recommendation: buildRecommendation(shortfall),
-  };
-
-  return jsonResult(output as unknown as Record<string, unknown>);
-}

package/packages/mcp-server/src/tools/get-task-status.ts

@@ -1,24 +0,0 @@
-import { z } from "zod";
-import type { McpSuccessResult, ToolContext } from "../context.js";
-import { jsonResult } from "../context.js";
-
-export const getTaskStatusName = "kolmopdf_get_task_status";
-
-export const getTaskStatusDescription =
-  "Advanced/debug tool. Returns raw status for a KolmoPDF task. Use only when " +
-  "explicitly asked to inspect a task by ID, or when troubleshooting a stuck task.";
-
-export const getTaskStatusInputSchema = z.object({
-  task_id: z.string(),
-});
-
-export type GetTaskStatusInput = z.infer<typeof getTaskStatusInputSchema>;
-
-export async function getTaskStatusHandler(
-  args: GetTaskStatusInput,
-  ctx: ToolContext,
-): Promise<McpSuccessResult> {
-  const client = ctx.getClient();
-  const status = await client.getStatus(args.task_id);
-  return jsonResult(status as unknown as Record<string, unknown>);
-}

package/packages/mcp-server/src/tools/parse-pdf.ts

@@ -1,147 +0,0 @@
-import { createWriteStream, mkdirSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
-import { z } from "zod";
-import type { McpSuccessResult, ToolContext } from "../context.js";
-import { jsonResult } from "../context.js";
-import { KolmoPdfError } from "../errors.js";
-import { extractZip } from "../extract.js";
-import { MAX_FILE_BYTES, MAX_PAGES, readFileSize, readPageCount } from "../pages.js";
-import { pollUntilComplete } from "../polling.js";
-
-export const parsePdfName = "kolmopdf_parse_pdf";
-
-export const parsePdfDescription =
-  "Parse a local PDF into Markdown via KolmoPDF. Handles formulas, tables, " +
-  "multi-column layouts, and code blocks. Optionally translates while parsing.";
-
-export const parsePdfInputSchema = z.object({
-  file_path: z.string().describe("Absolute or cwd-relative path to a local PDF file."),
-  table_mode: z.enum(["markdown", "image"]).optional(),
-  formula_format: z.enum(["dollar", "bracket"]).optional(),
-  enable_translation: z.boolean().optional(),
-  target_language: z.enum(["zh", "en", "ja", "ko", "fr", "de", "es", "ru"]).optional(),
-  output_options: z.array(z.enum(["original", "translated", "bilingual"])).optional(),
-  images_as_url: z.boolean().optional(),
-  skip_rotation_detection: z.boolean().optional(),
-  enable_cross_page_merge: z.boolean().optional(),
-  output_subdir: z
-    .string()
-    .optional()
-    .describe("Subdirectory name under KOLMOPDF_OUTPUT_DIR. Defaults to <task_id>."),
-});
-
-export type ParsePdfInput = z.infer<typeof parsePdfInputSchema>;
-
-export interface ParsePdfOutput {
-  task_id: string;
-  pages_parsed: number;
-  points_deducted: number;
-  remaining_points: number;
-  output: {
-    type: "zip_extracted" | "markdown_file";
-    markdown_path: string;
-    images_dir: string | null;
-    output_root: string;
-  };
-  preview: string;
-}
-
-export async function parsePdfHandler(
-  args: ParsePdfInput,
-  ctx: ToolContext,
-): Promise<McpSuccessResult> {
-  const client = ctx.getClient();
-  const filePath = resolve(args.file_path);
-  const filename = basename(filePath);
-
-  const fileSize = await readFileSize(filePath);
-  if (fileSize > MAX_FILE_BYTES) {
-    throw new KolmoPdfError("parse_file_too_large");
-  }
-
-  const pageCount = await readPageCount(filePath);
-  if (pageCount > MAX_PAGES) {
-    throw new KolmoPdfError("parse_page_limit_exceeded");
-  }
-
-  await ctx.progress?.report("[uploading] Sending PDF to KolmoPDF...");
-
-  const fileBuffer = await readFile(filePath);
-  const submitResult = await client.parse(
-    fileBuffer,
-    {
-      table_mode: args.table_mode,
-      formula_format: args.formula_format,
-      enable_translation: args.enable_translation,
-      target_language: args.target_language,
-      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,
-    },
-    filename,
-  );
-
-  const taskId = submitResult.task_id;
-  await ctx.progress?.report(`[submitted] Task ${taskId} created`);
-
-  await pollUntilComplete({
-    client,
-    taskId,
-    options: {
-      pollIntervalMs: ctx.config.pollIntervalMs,
-      maxPollMinutes: ctx.config.maxPollMinutes,
-    },
-    progress: ctx.progress,
-  });
-
-  await ctx.progress?.report("[downloading] Fetching result...");
-
-  const subdir = args.output_subdir || taskId;
-  const outputRoot = resolve(ctx.config.outputDir, subdir);
-  mkdirSync(outputRoot, { recursive: true });
-
-  const isUrlMode = args.images_as_url === true;
-
-  let markdownPath: string;
-  let imagesDir: string | null = null;
-  let outputType: "zip_extracted" | "markdown_file";
-
-  if (isUrlMode) {
-    markdownPath = join(outputRoot, "result.md");
-    const ws = createWriteStream(markdownPath);
-    await client.download(taskId, ws);
-    outputType = "markdown_file";
-  } else {
-    const zipPath = join(outputRoot, "result.zip");
-    const ws = createWriteStream(zipPath);
-    await client.download(taskId, ws);
-    const extracted = await extractZip(zipPath, outputRoot);
-    markdownPath = extracted.markdownPath || join(outputRoot, "result.md");
-    imagesDir = extracted.imagesDir;
-    outputType = "zip_extracted";
-  }
-
-  const mdContent = await 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);
-
-  const output: ParsePdfOutput = {
-    task_id: taskId,
-    pages_parsed: pagesParsed,
-    points_deducted: submitResult.points_deducted,
-    remaining_points: submitResult.remaining_points,
-    output: {
-      type: outputType,
-      markdown_path: markdownPath,
-      images_dir: imagesDir,
-      output_root: outputRoot,
-    },
-    preview,
-  };
-
-  return jsonResult(output as unknown as Record<string, unknown>);
-}

package/packages/mcp-server/src/tools/translate-pdf.ts

@@ -1,110 +0,0 @@
-import { createWriteStream, mkdirSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
-import { z } from "zod";
-import type { McpSuccessResult, ToolContext } from "../context.js";
-import { jsonResult } from "../context.js";
-import { KolmoPdfError } from "../errors.js";
-import { MAX_FILE_BYTES, MAX_PAGES, readFileSize, readPageCount } from "../pages.js";
-import { pollUntilComplete } from "../polling.js";
-
-export const translatePdfName = "kolmopdf_translate_pdf";
-
-export const translatePdfDescription =
-  "Translate a PDF while preserving its original layout via KolmoPDF. " +
-  "Produces a translated PDF (optionally side-by-side bilingual).";
-
-export const translatePdfInputSchema = z.object({
-  file_path: z.string(),
-  source_language: z.string().optional().default("en"),
-  target_language: z.string().optional().default("zh"),
-  layout_modes: z
-    .array(z.enum(["translated_only", "side_by_side"]))
-    .optional()
-    .default(["translated_only"]),
-  enable_image_translation: z.boolean().optional().default(false),
-  enable_table_translation: z.boolean().optional().default(false),
-  output_subdir: z.string().optional(),
-});
-
-export type TranslatePdfInput = z.infer<typeof translatePdfInputSchema>;
-
-export interface TranslatePdfOutput {
-  task_id: string;
-  pages_translated: number;
-  points_deducted: number;
-  remaining_points: number;
-  output: {
-    translated_pdf_path: string;
-  };
-}
-
-export async function translatePdfHandler(
-  args: TranslatePdfInput,
-  ctx: ToolContext,
-): Promise<McpSuccessResult> {
-  const client = ctx.getClient();
-  const filePath = resolve(args.file_path);
-  const filename = basename(filePath);
-  const fileSize = await readFileSize(filePath);
-  if (fileSize > MAX_FILE_BYTES) {
-    throw new KolmoPdfError("translate_pdf_file_too_large");
-  }
-
-  const pageCount = await readPageCount(filePath);
-  if (pageCount > MAX_PAGES) {
-    throw new KolmoPdfError("translate_pdf_page_limit_exceeded");
-  }
-
-  await ctx.progress?.report("[uploading] Sending PDF for translation...");
-
-  const fileBuffer = await readFile(filePath);
-  const submitResult = await client.translatePdf(
-    fileBuffer,
-    {
-      source_language: args.source_language,
-      target_language: args.target_language,
-      layout_modes: args.layout_modes,
-      enable_image_translation: args.enable_image_translation,
-      enable_table_translation: args.enable_table_translation,
-    },
-    filename,
-  );
-
-  const taskId = submitResult.task_id;
-  await ctx.progress?.report(`[submitted] Task ${taskId} created`);
-
-  await pollUntilComplete({
-    client,
-    taskId,
-    options: {
-      pollIntervalMs: ctx.config.pollIntervalMs,
-      maxPollMinutes: ctx.config.maxPollMinutes,
-    },
-    progress: ctx.progress,
-  });
-
-  await ctx.progress?.report("[downloading] Fetching translated PDF...");
-
-  const subdir = args.output_subdir || taskId;
-  const outputRoot = resolve(ctx.config.outputDir, subdir);
-  mkdirSync(outputRoot, { recursive: true });
-
-  const pdfPath = join(outputRoot, "translated.pdf");
-  const ws = createWriteStream(pdfPath);
-  await client.download(taskId, ws);
-
-  const pagesTranslated = Math.round(submitResult.points_deducted / 2);
-
-  const output: TranslatePdfOutput = {
-    task_id: taskId,
-    pages_translated: pagesTranslated,
-    points_deducted: submitResult.points_deducted,
-    remaining_points: submitResult.remaining_points,
-    output: {
-      translated_pdf_path: pdfPath,
-    },
-  };
-
-  return jsonResult(output as unknown as Record<string, unknown>);
-}

package/packages/mcp-server/tests/integration/smoke.test.ts

@@ -1,33 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { KolmoPdfClient } from "../../src/client.js";
-import { loadConfig } from "../../src/config.js";
-
-/**
- * Live smoke tests (TESTING_AND_USAGE.md §7). These hit the real API and only
- * run when KOLMOPDF_API_KEY is present (CI nightly job / manual). Skipped
- * otherwise so the default `pnpm test` stays offline and deterministic.
- */
-const hasKey = Boolean(process.env.KOLMOPDF_API_KEY);
-const maybe = hasKey ? describe : describe.skip;
-
-maybe("smoke-balance", () => {
-  it("returns a non-negative balance for a valid key", async () => {
-    const cfg = loadConfig();
-    const client = new KolmoPdfClient({
-      apiKey: cfg.apiKey as string,
-      baseUrl: cfg.baseUrl,
-      httpTimeoutMs: cfg.httpTimeoutMs,
-      uploadTimeoutMs: cfg.uploadTimeoutMs,
-    });
-    const balance = await client.getBalance();
-    expect(balance.success).toBe(true);
-    expect(balance.points).toBeGreaterThanOrEqual(0);
-  });
-});
-
-describe("smoke harness", () => {
-  it("is configured to skip when no API key is set", () => {
-    // Guards against accidentally enabling live calls in offline CI.
-    expect(typeof hasKey).toBe("boolean");
-  });
-});

package/packages/mcp-server/tests/unit/config.test.ts

@@ -1,49 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { configDefaults, loadConfig, maskApiKey } from "../../src/config.js";
-
-describe("loadConfig", () => {
-  it("applies defaults when env is empty", () => {
-    const cfg = loadConfig({});
-    expect(cfg.apiKey).toBeUndefined();
-    expect(cfg.baseUrl).toBe(configDefaults.baseUrl);
-    expect(cfg.outputDir).toBe(configDefaults.outputDir);
-    expect(cfg.pollIntervalMs).toBe(configDefaults.pollIntervalMs);
-    expect(cfg.maxPollMinutes).toBe(configDefaults.maxPollMinutes);
-    expect(cfg.httpTimeoutMs).toBe(configDefaults.httpTimeoutMs);
-    expect(cfg.uploadTimeoutMs).toBe(configDefaults.uploadTimeoutMs);
-  });
-
-  it("reads and trims the API key", () => {
-    expect(loadConfig({ KOLMOPDF_API_KEY: "  sk-abc  " }).apiKey).toBe("sk-abc");
-    expect(loadConfig({ KOLMOPDF_API_KEY: "   " }).apiKey).toBeUndefined();
-  });
-
-  it("strips trailing slashes from the base URL", () => {
-    expect(loadConfig({ KOLMOPDF_BASE_URL: "https://example.com/" }).baseUrl).toBe(
-      "https://example.com",
-    );
-    expect(loadConfig({ KOLMOPDF_BASE_URL: "https://example.com///" }).baseUrl).toBe(
-      "https://example.com",
-    );
-  });
-
-  it("parses numeric envs and falls back on invalid values", () => {
-    expect(loadConfig({ KOLMOPDF_POLL_INTERVAL_MS: "500" }).pollIntervalMs).toBe(500);
-    expect(loadConfig({ KOLMOPDF_POLL_INTERVAL_MS: "abc" }).pollIntervalMs).toBe(
-      configDefaults.pollIntervalMs,
-    );
-    expect(loadConfig({ KOLMOPDF_MAX_POLL_MINUTES: "-3" }).maxPollMinutes).toBe(
-      configDefaults.maxPollMinutes,
-    );
-  });
-});
-
-describe("maskApiKey", () => {
-  it("shows first 6 + last 4 for long keys", () => {
-    expect(maskApiKey("sk-1234567890abcdef")).toBe("sk-123***cdef");
-  });
-
-  it("fully masks short keys", () => {
-    expect(maskApiKey("short")).toBe("***");
-  });
-});

package/packages/mcp-server/tests/unit/convert.test.ts

@@ -1,28 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { formatToExtension, normalizeFormat } from "../../src/tools/convert.js";
-
-describe("formatToExtension", () => {
-  it.each([
-    ["word", ".docx"],
-    ["docx", ".docx"],
-    ["html", ".html"],
-    ["pdf", ".pdf"],
-    ["latex", ".tex"],
-    ["tex", ".tex"],
-  ])("%s → %s", (input, expected) => {
-    expect(formatToExtension(input)).toBe(expected);
-  });
-});
-
-describe("normalizeFormat", () => {
-  it.each([
-    ["word", "docx"],
-    ["docx", "docx"],
-    ["latex", "tex"],
-    ["tex", "tex"],
-    ["html", "html"],
-    ["pdf", "pdf"],
-  ])("%s → %s", (input, expected) => {
-    expect(normalizeFormat(input)).toBe(expected);
-  });
-});