@kolmopdf/mcp-server 1.0.0 → 1.0.1

package/packages/mcp-server/src/errors.ts

@@ -1,271 +0,0 @@
-/**
- * Unified KolmoPDF error model and MCP error-result formatting.
- *
- * Implements the error-code mapping table in DEVELOPMENT.md §8 and the
- * MCP tool error envelope in §5.13.
- */
-
-export type ErrorSource = "api" | "client";
-
-export interface ErrorSpec {
-  /** Default human-readable message. */
-  message: string;
-  /** Actionable remediation hint surfaced to the LLM / user. */
-  remediation: string;
-  /** Typical HTTP status; null for client-side codes. */
-  httpStatus: number | null;
-  source: ErrorSource;
-}
-
-/** Canonical mapping of every error_code we may surface (DEVELOPMENT.md §8). */
-export const ERROR_SPECS: Record<string, ErrorSpec> = {
-  // --- 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).",
-    httpStatus: 401,
-    source: "api",
-  },
-  insufficient_points: {
-    message: "Not enough credits.",
-    remediation: "Top up at https://www.kolmopdf.com/subscription.",
-    httpStatus: 402,
-    source: "api",
-  },
-  points_deduction_failed: {
-    message: "Credit deduction failed.",
-    remediation: "Retry; if it persists contact support.",
-    httpStatus: 402,
-    source: "api",
-  },
-  no_file_found: {
-    message: "Request missing file field.",
-    remediation: "(internal) MCP server bug, please report.",
-    httpStatus: 400,
-    source: "api",
-  },
-  parse_file_too_large: {
-    message: "PDF exceeds 300MB.",
-    remediation: "Split the PDF locally.",
-    httpStatus: 400,
-    source: "api",
-  },
-  parse_page_limit_exceeded: {
-    message: "PDF exceeds 800 pages.",
-    remediation: "Split the PDF locally.",
-    httpStatus: 400,
-    source: "api",
-  },
-  parse_file_not_pdf: {
-    message: "File is not a valid PDF.",
-    remediation: "Upload a .pdf file.",
-    httpStatus: 400,
-    source: "api",
-  },
-  translate_pdf_file_too_large: {
-    message: "PDF exceeds 300MB.",
-    remediation: "Split the PDF locally.",
-    httpStatus: 400,
-    source: "api",
-  },
-  translate_pdf_file_not_pdf: {
-    message: "File is not a valid PDF.",
-    remediation: "Upload a .pdf file.",
-    httpStatus: 400,
-    source: "api",
-  },
-  translate_pdf_page_limit_exceeded: {
-    message: "PDF exceeds 800 pages.",
-    remediation: "Split the PDF locally.",
-    httpStatus: 400,
-    source: "api",
-  },
-  convert_file_too_large: {
-    message: "File exceeds 300MB.",
-    remediation: "Reduce file size.",
-    httpStatus: 400,
-    source: "api",
-  },
-  convert_file_type_unsupported: {
-    message: "File must be .md / .markdown / .zip.",
-    remediation: "Convert source to markdown first.",
-    httpStatus: 400,
-    source: "api",
-  },
-  convert_target_format_unsupported: {
-    message: "Target format unsupported.",
-    remediation: "Use word/docx/html/pdf/latex/tex.",
-    httpStatus: 400,
-    source: "api",
-  },
-  file_upload_failed: {
-    message: "Upload to storage failed.",
-    remediation: "Check network and retry.",
-    httpStatus: 500,
-    source: "api",
-  },
-  task_creation_failed: {
-    message: "Task creation failed.",
-    remediation: "Retry.",
-    httpStatus: 500,
-    source: "api",
-  },
-  parse_error: {
-    message: "Parsing failed.",
-    remediation: "Retry; if it persists, split and try again.",
-    httpStatus: 500,
-    source: "api",
-  },
-  parse_file_invalid: {
-    message: "PDF is malformed.",
-    remediation: "Re-export the PDF.",
-    httpStatus: 500,
-    source: "api",
-  },
-  parse_timeout: {
-    message: "Server-side timeout.",
-    remediation: "Split into smaller PDFs.",
-    httpStatus: 500,
-    source: "api",
-  },
-  api_task_error: {
-    message: "Generic task error.",
-    remediation: "Retry; if it persists contact support.",
-    httpStatus: 500,
-    source: "api",
-  },
-  // --- client codes ---
-  client_polling_timeout: {
-    message: "Local polling exceeded KOLMOPDF_MAX_POLL_MINUTES.",
-    remediation: "Task may still be running. Use kolmopdf_get_task_status with task_id.",
-    httpStatus: null,
-    source: "client",
-  },
-  client_network_error: {
-    message: "Network error after retries.",
-    remediation: "Check network.",
-    httpStatus: null,
-    source: "client",
-  },
-  client_local_validation: {
-    message: "Local pre-check failed (page count / file size).",
-    remediation: "See message for the specific limit that was exceeded.",
-    httpStatus: null,
-    source: "client",
-  },
-  client_extract_failed: {
-    message: "ZIP extraction failed.",
-    remediation: "Check disk permissions on output dir.",
-    httpStatus: null,
-    source: "client",
-  },
-} as const;
-
-const UNKNOWN_SPEC: ErrorSpec = {
-  message: "Unknown error.",
-  remediation: "Retry; if it persists contact https://www.kolmopdf.com/contact.",
-  httpStatus: null,
-  source: "client",
-};
-
-export interface KolmoPdfErrorOptions {
-  /** Override the default message from the spec. */
-  message?: string;
-  /** Override the default HTTP status from the spec. */
-  httpStatus?: number | null;
-  pointsRequired?: number;
-  currentPoints?: number;
-  /** Override the default remediation hint. */
-  remediation?: string;
-}
-
-/** Structured error thrown across the MCP server; carries a stable error_code. */
-export class KolmoPdfError extends Error {
-  readonly errorCode: string;
-  readonly httpStatus: number | null;
-  readonly remediation: string;
-  readonly pointsRequired: number | undefined;
-  readonly currentPoints: number | undefined;
-  readonly source: ErrorSource;
-
-  constructor(errorCode: string, opts: KolmoPdfErrorOptions = {}) {
-    const spec = ERROR_SPECS[errorCode] ?? UNKNOWN_SPEC;
-    super(opts.message ?? spec.message);
-    this.name = "KolmoPdfError";
-    this.errorCode = errorCode;
-    this.httpStatus = opts.httpStatus !== undefined ? opts.httpStatus : spec.httpStatus;
-    this.remediation = opts.remediation ?? spec.remediation;
-    this.pointsRequired = opts.pointsRequired;
-    this.currentPoints = opts.currentPoints;
-    this.source = spec.source;
-  }
-}
-
-/** Shape of the JSON payload embedded in an MCP error result (DEVELOPMENT.md §5.13). */
-export interface McpErrorPayload {
-  error_code: string;
-  message: string;
-  http_status: number | null;
-  points_required?: number;
-  current_points?: number;
-  remediation: string;
-}
-
-/** MCP tool result envelope for an error (matches MCP SDK `CallToolResult`). */
-export interface McpErrorResult {
-  isError: true;
-  content: Array<{ type: "text"; text: string }>;
-}
-
-/** Convert a KolmoPdfError (or any error) into the MCP error result envelope. */
-export function toMcpErrorResult(err: unknown): McpErrorResult {
-  const kerr =
-    err instanceof KolmoPdfError
-      ? err
-      : new KolmoPdfError("api_task_error", {
-          message: err instanceof Error ? err.message : String(err),
-        });
-
-  const payload: McpErrorPayload = {
-    error_code: kerr.errorCode,
-    message: kerr.message,
-    http_status: kerr.httpStatus,
-    remediation: kerr.remediation,
-  };
-  if (kerr.pointsRequired !== undefined) payload.points_required = kerr.pointsRequired;
-  if (kerr.currentPoints !== undefined) payload.current_points = kerr.currentPoints;
-
-  return {
-    isError: true,
-    content: [{ type: "text", text: JSON.stringify(payload) }],
-  };
-}
-
-/** Whether an API failure with this code is auto-refunded server-side (§8). */
-export function isAutoRefunded(errorCode: string): boolean {
-  return (
-    errorCode === "task_creation_failed" ||
-    errorCode === "parse_error" ||
-    errorCode === "parse_file_invalid" ||
-    errorCode === "parse_timeout"
-  );
-}
-
-/** Map a raw API JSON failure body to a KolmoPdfError. */
-export function errorFromApiBody(
-  body: {
-    error_code?: string;
-    message?: string;
-    points_required?: number;
-    current_points?: number;
-  },
-  httpStatus?: number,
-): KolmoPdfError {
-  const code = body.error_code ?? "api_task_error";
-  return new KolmoPdfError(code, {
-    message: body.message,
-    httpStatus: httpStatus ?? null,
-    pointsRequired: body.points_required,
-    currentPoints: body.current_points,
-  });
-}

package/packages/mcp-server/src/extract.ts

@@ -1,102 +0,0 @@
-import { createWriteStream, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { pipeline } from "node:stream/promises";
-import { type Entry, type ZipFile, open as yauzlOpen } from "yauzl";
-
-export interface ExtractResult {
-  markdownPath: string | null;
-  imagesDir: string | null;
-  outputRoot: string;
-  files: string[];
-}
-
-export async function extractZip(zipPath: string, destDir: string): Promise<ExtractResult> {
-  mkdirSync(destDir, { recursive: true });
-
-  const zipFile = await openZip(zipPath);
-  const files: string[] = [];
-  let markdownPath: string | null = null;
-  let imagesDir: string | null = null;
-
-  for await (const entry of iterEntries(zipFile)) {
-    const entryPath = join(destDir, entry.fileName);
-
-    if (entry.fileName.endsWith("/")) {
-      mkdirSync(entryPath, { recursive: true });
-      if (entry.fileName.includes("images")) {
-        imagesDir = entryPath;
-      }
-      continue;
-    }
-
-    mkdirSync(dirname(entryPath), { recursive: true });
-    const readStream = await openReadStream(zipFile, entry);
-    const writeStream = createWriteStream(entryPath);
-    await pipeline(readStream, writeStream);
-    files.push(entryPath);
-
-    if (!markdownPath && /\.md$/i.test(entry.fileName)) {
-      markdownPath = entryPath;
-    }
-    if (!imagesDir && /images\//i.test(entry.fileName)) {
-      const prefix = entry.fileName.split("images/")[0] ?? "";
-      imagesDir = join(destDir, prefix, "images");
-    }
-  }
-
-  return { markdownPath, imagesDir, outputRoot: destDir, files };
-}
-function openZip(path: string): Promise<ZipFile> {
-  return new Promise((resolve, reject) => {
-    yauzlOpen(path, { lazyEntries: true }, (err, zf) => {
-      if (err || !zf) return reject(err ?? new Error("Failed to open zip"));
-      resolve(zf);
-    });
-  });
-}
-
-async function* iterEntries(zipFile: ZipFile): AsyncGenerator<Entry> {
-  let resolve: ((entry: Entry | null) => void) | null = null;
-  const queue: (Entry | null)[] = [];
-
-  zipFile.on("entry", (entry: Entry) => {
-    if (resolve) {
-      const r = resolve;
-      resolve = null;
-      r(entry);
-    } else {
-      queue.push(entry);
-    }
-  });
-  zipFile.on("end", () => {
-    if (resolve) {
-      const r = resolve;
-      resolve = null;
-      r(null);
-    } else {
-      queue.push(null);
-    }
-  });
-
-  zipFile.readEntry();
-  while (true) {
-    const entry =
-      queue.length > 0
-        ? (queue.shift() as Entry | null)
-        : await new Promise<Entry | null>((r) => {
-            resolve = r;
-          });
-    if (entry === null) break;
-    yield entry;
-    zipFile.readEntry();
-  }
-}
-
-function openReadStream(zipFile: ZipFile, entry: Entry): Promise<NodeJS.ReadableStream> {
-  return new Promise((resolve, reject) => {
-    zipFile.openReadStream(entry, (err, stream) => {
-      if (err || !stream) return reject(err ?? new Error("Failed to open entry stream"));
-      resolve(stream);
-    });
-  });
-}

package/packages/mcp-server/src/index.ts

@@ -1,142 +0,0 @@
-/**
- * @kolmopdf/mcp-server — stdio MCP server bootstrap (DEVELOPMENT.md §5.2).
- *
- * - Registers over the stdio transport.
- * - Does NOT validate the API key at startup; the key is read lazily so the
- *   server boots even with no network / no key. The first authenticated tool
- *   call surfaces a missing key as an MCP error (invalid_api_key).
- */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { KolmoPdfClient } from "./client.js";
-import { loadConfig } from "./config.js";
-import { type McpSuccessResult, type ToolContext, jsonResult } from "./context.js";
-import { KolmoPdfError, toMcpErrorResult } from "./errors.js";
-import {
-  checkBalanceDescription,
-  checkBalanceHandler,
-  checkBalanceInputSchema,
-  checkBalanceName,
-} from "./tools/check-balance.js";
-import {
-  convertDescription,
-  convertHandler,
-  convertInputSchema,
-  convertName,
-} from "./tools/convert.js";
-import {
-  estimateCostDescription,
-  estimateCostHandler,
-  estimateCostInputSchema,
-  estimateCostName,
-} from "./tools/estimate-cost.js";
-import {
-  getTaskStatusDescription,
-  getTaskStatusHandler,
-  getTaskStatusInputSchema,
-  getTaskStatusName,
-} from "./tools/get-task-status.js";
-import {
-  parsePdfDescription,
-  parsePdfHandler,
-  parsePdfInputSchema,
-  parsePdfName,
-} from "./tools/parse-pdf.js";
-import {
-  translatePdfDescription,
-  translatePdfHandler,
-  translatePdfInputSchema,
-  translatePdfName,
-} from "./tools/translate-pdf.js";
-
-const VERSION = "1.0.0";
-
-/** Build the per-call tool context with a lazily-constructed API client. */
-function buildContext(): ToolContext {
-  const config = loadConfig();
-  return {
-    config,
-    getClient(): KolmoPdfClient {
-      if (!config.apiKey) {
-        throw new KolmoPdfError("invalid_api_key");
-      }
-      return new KolmoPdfClient({
-        apiKey: config.apiKey,
-        baseUrl: config.baseUrl,
-        httpTimeoutMs: config.httpTimeoutMs,
-        uploadTimeoutMs: config.uploadTimeoutMs,
-      });
-    },
-  };
-}
-
-/** Wrap a typed handler so all thrown errors become MCP error results (§5.13). */
-function guard<A>(
-  handler: (args: A, ctx: ToolContext) => Promise<McpSuccessResult>,
-): (args: unknown) => Promise<CallToolResult> {
-  return async (args: unknown) => {
-    try {
-      return (await handler(args as A, buildContext())) as CallToolResult;
-    } catch (err) {
-      return toMcpErrorResult(err) as CallToolResult;
-    }
-  };
-}
-
-export function createServer(): McpServer {
-  const server = new McpServer({ name: "kolmopdf", version: VERSION });
-
-  server.registerTool(
-    parsePdfName,
-    { description: parsePdfDescription, inputSchema: parsePdfInputSchema.shape },
-    guard(parsePdfHandler),
-  );
-  server.registerTool(
-    translatePdfName,
-    { description: translatePdfDescription, inputSchema: translatePdfInputSchema.shape },
-    guard(translatePdfHandler),
-  );
-  server.registerTool(
-    convertName,
-    { description: convertDescription, inputSchema: convertInputSchema.shape },
-    guard(convertHandler),
-  );
-  server.registerTool(
-    estimateCostName,
-    { description: estimateCostDescription, inputSchema: estimateCostInputSchema.shape },
-    guard(estimateCostHandler),
-  );
-  server.registerTool(
-    checkBalanceName,
-    { description: checkBalanceDescription, inputSchema: checkBalanceInputSchema.shape },
-    guard(checkBalanceHandler),
-  );
-  server.registerTool(
-    getTaskStatusName,
-    { description: getTaskStatusDescription, inputSchema: getTaskStatusInputSchema.shape },
-    guard(getTaskStatusHandler),
-  );
-
-  return server;
-}
-
-async function main(): Promise<void> {
-  // Surface --version without booting the transport (TESTING_AND_USAGE.md §9).
-  if (process.argv.includes("--version") || process.argv.includes("-v")) {
-    process.stdout.write(`${VERSION}\n`);
-    return;
-  }
-  const server = createServer();
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}
-
-// `jsonResult` is part of the public surface used by tool handlers (M2+).
-export { jsonResult };
-
-main().catch((err) => {
-  const detail = err instanceof Error ? err.stack : String(err);
-  process.stderr.write(`[kolmopdf-mcp] fatal: ${detail}\n`);
-  process.exit(1);
-});

package/packages/mcp-server/src/pages.ts

@@ -1,16 +0,0 @@
-import { readFile, stat } from "node:fs/promises";
-import { PDFDocument } from "pdf-lib";
-
-export const MAX_PAGES = 800;
-export const MAX_FILE_BYTES = 300 * 1024 * 1024;
-
-export async function readPageCount(filePath: string): Promise<number> {
-  const data = await readFile(filePath);
-  const doc = await PDFDocument.load(data, { ignoreEncryption: true });
-  return doc.getPageCount();
-}
-
-export async function readFileSize(filePath: string): Promise<number> {
-  const s = await stat(filePath);
-  return s.size;
-}

package/packages/mcp-server/src/polling.ts

@@ -1,84 +0,0 @@
-import type { KolmoPdfClient, StatusResult } from "./client.js";
-import { KolmoPdfError } from "./errors.js";
-import { type ProgressReporter, humanizeStatus } from "./progress.js";
-
-export interface PollOptions {
-  pollIntervalMs: number;
-  maxPollMinutes: number;
-}
-
-export const TERMINAL_OK = "completed";
-export const TERMINAL_FAIL = "failed";
-export const IN_FLIGHT_STATUSES = new Set(["pending", "waiting", "processing"]);
-
-export const RETRY_POLICY = {
-  maxAttempts: 3,
-  baseDelayMs: 1000,
-  factor: 2,
-} as const;
-
-export function backoffDelayMs(attempt: number): number {
-  return RETRY_POLICY.baseDelayMs * RETRY_POLICY.factor ** (attempt - 1);
-}
-
-export function isRetryable(err: { httpStatus?: number | null; code?: string }): boolean {
-  const transientCodes = ["ECONNRESET", "ETIMEDOUT", "ECONNREFUSED", "EAI_AGAIN"];
-  if (err.code && transientCodes.includes(err.code)) return true;
-  if (typeof err.httpStatus === "number" && err.httpStatus >= 500) return true;
-  return false;
-}
-
-export interface PollContext {
-  client: KolmoPdfClient;
-  taskId: string;
-  options: PollOptions;
-  progress?: ProgressReporter;
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-async function fetchStatusWithRetry(client: KolmoPdfClient, taskId: string): Promise<StatusResult> {
-  for (let attempt = 1; attempt <= RETRY_POLICY.maxAttempts; attempt++) {
-    try {
-      return await client.getStatus(taskId);
-    } catch (err) {
-      const retryable =
-        err instanceof KolmoPdfError
-          ? isRetryable(err)
-          : isRetryable({ code: (err as NodeJS.ErrnoException).code });
-      if (!retryable || attempt === RETRY_POLICY.maxAttempts) throw err;
-      await sleep(backoffDelayMs(attempt));
-    }
-  }
-  throw new KolmoPdfError("client_network_error");
-}
-
-export async function pollUntilComplete(ctx: PollContext): Promise<StatusResult> {
-  const { client, taskId, options, progress } = ctx;
-  const deadline = Date.now() + options.maxPollMinutes * 60_000;
-
-  while (true) {
-    if (Date.now() > deadline) {
-      throw new KolmoPdfError("client_polling_timeout");
-    }
-
-    const result = await fetchStatusWithRetry(client, taskId);
-
-    if (result.status === TERMINAL_OK) {
-      await progress?.report(`[completed] Task ${taskId} done`);
-      return result;
-    }
-
-    if (result.status === TERMINAL_FAIL) {
-      throw new KolmoPdfError(result.error_code || "api_task_error", {
-        message: result.message || "Task failed",
-      });
-    }
-
-    const aheadTasks = result.queue_info?.ahead_tasks;
-    await progress?.report(humanizeStatus(result.status as string, aheadTasks));
-    await sleep(options.pollIntervalMs);
-  }
-}

package/packages/mcp-server/src/progress.ts

@@ -1,48 +0,0 @@
-/**
- * MCP progress-notification helper (DEVELOPMENT.md §5.11).
- *
- * `progress` must be monotonically increasing; `total` is omitted because the
- * API does not provide a precise percentage.
- */
-
-/** Minimal shape of the MCP request context used to emit notifications. */
-export interface ProgressSink {
-  /** Present only when the client supplied a progressToken in request `_meta`. */
-  progressToken?: string | number;
-  notify(notification: {
-    method: "notifications/progress";
-    params: {
-      progressToken: string | number;
-      progress: number;
-      message?: string;
-    };
-  }): Promise<void>;
-}
-
-/** Stateful emitter that guarantees a monotonically increasing counter. */
-export class ProgressReporter {
-  private counter = 0;
-
-  constructor(private readonly sink: ProgressSink | undefined) {}
-
-  async report(message: string): Promise<void> {
-    if (!this.sink || this.sink.progressToken === undefined) return;
-    this.counter += 1;
-    await this.sink.notify({
-      method: "notifications/progress",
-      params: {
-        progressToken: this.sink.progressToken,
-        progress: this.counter,
-        message,
-      },
-    });
-  }
-}
-
-/** Build a human-readable status line, e.g. "[waiting] 3 tasks ahead". */
-export function humanizeStatus(status: string, aheadTasks?: number): string {
-  if (status === "waiting" && typeof aheadTasks === "number") {
-    return `[waiting] ${aheadTasks} tasks ahead`;
-  }
-  return `[${status}]`;
-}

package/packages/mcp-server/src/tools/check-balance.ts

@@ -1,33 +0,0 @@
-import { z } from "zod";
-import { maskApiKey } from "../config.js";
-import type { McpSuccessResult, ToolContext } from "../context.js";
-import { jsonResult } from "../context.js";
-
-export const checkBalanceName = "kolmopdf_check_balance";
-
-export const checkBalanceDescription =
-  "Show the current KolmoPDF credit balance for the configured API key.";
-
-export const checkBalanceInputSchema = z.object({});
-
-export type CheckBalanceInput = z.infer<typeof checkBalanceInputSchema>;
-
-export interface CheckBalanceOutput {
-  points: number;
-  api_key_masked: string;
-}
-
-export async function checkBalanceHandler(
-  _args: CheckBalanceInput,
-  ctx: ToolContext,
-): Promise<McpSuccessResult> {
-  const client = ctx.getClient();
-  const balance = await client.getBalance();
-
-  const output: CheckBalanceOutput = {
-    points: balance.points,
-    api_key_masked: maskApiKey(ctx.config.apiKey || ""),
-  };
-
-  return jsonResult(output as unknown as Record<string, unknown>);
-}