@obrahaus/fileforge-mcp 2.2.0

package/dist/index.js

@@ -0,0 +1,1380 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+var DEFAULT_BASE_URL = "https://fileforge-api.obrahaus.com/v1";
+var ConfigError = class extends Error {
+};
+function loadConfig(env = process.env) {
+  const apiKey = (env.FILEFORGE_API_KEY ?? "").trim();
+  if (!apiKey) {
+    throw new ConfigError(
+      'FILEFORGE_API_KEY is not set. Add it to your MCP client config, e.g. {"command":"npx","args":["-y","@obrahaus/fileforge-mcp"],"env":{"FILEFORGE_API_KEY":"ff_live_..."}}. Create a key at your FileForge account \u2192 Settings \u2192 API keys.'
+    );
+  }
+  if (!/^ff_live_[0-9A-Za-z]{8,}$/.test(apiKey)) {
+    throw new ConfigError(
+      'FILEFORGE_API_KEY does not look like a FileForge key (expected "ff_live_\u2026"). Double-check the value.'
+    );
+  }
+  const rawBaseUrl = (env.FILEFORGE_API_BASE_URL ?? "").trim();
+  const baseUrl = stripTrailingSlash(rawBaseUrl.length > 0 ? rawBaseUrl : DEFAULT_BASE_URL);
+  if (!/^https?:\/\/.+/i.test(baseUrl)) {
+    throw new ConfigError(
+      `FILEFORGE_API_BASE_URL must be an http(s) URL (got "${baseUrl}"). Omit it to use the default ${DEFAULT_BASE_URL}.`
+    );
+  }
+  return {
+    apiKey,
+    baseUrl,
+    defaultPreset: env.FILEFORGE_DEFAULT_PRESET?.trim() || void 0,
+    maxPollSeconds: clampInt(env.FF_MCP_MAX_POLL_SECONDS, 300, 1, 3600),
+    maxInlineBytes: clampInt(env.FF_MCP_MAX_INLINE_BYTES, 5 * 1024 * 1024, 0, 64 * 1024 * 1024),
+    // URL / base64 sources are buffered in memory before upload, so cap them by
+    // default (override per-deployment). Large files should use a local `path`,
+    // which streams to storage with flat memory.
+    maxDownloadUrlBytes: clampInt(env.FF_MCP_MAX_DOWNLOAD_URL_BYTES, 100 * 1024 * 1024, 1, Number.MAX_SAFE_INTEGER),
+    outputDir: env.FF_MCP_OUTPUT_DIR?.trim() || void 0,
+    controlTimeoutMs: clampInt(env.FF_MCP_HTTP_TIMEOUT_MS, 3e4, 1e3, 6e5),
+    streamTimeoutMs: clampInt(env.FF_MCP_STREAM_TIMEOUT_MS, 6e5, 5e3, 36e5),
+    logLevel: parseLogLevel(env.FF_MCP_LOG_LEVEL)
+  };
+}
+function stripTrailingSlash(s) {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+function clampInt(raw, fallback, lo, hi) {
+  if (raw === void 0 || raw === "") return fallback;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(lo, Math.min(hi, n));
+}
+function parseLogLevel(raw) {
+  const v = (raw ?? "info").toLowerCase();
+  return v === "debug" || v === "info" || v === "warn" || v === "error" ? v : "info";
+}
+
+// src/errors.ts
+var ToolError = class extends Error {
+  code;
+  retryAfterSeconds;
+  constructor(code, message, retryAfterSeconds) {
+    super(message);
+    this.name = "ToolError";
+    this.code = code;
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+};
+function friendlyApiError(status, body, ctx) {
+  const code = body?.error ?? body?.code ?? `http_${status}`;
+  const apiMsg = body?.message ?? `request failed with HTTP ${status}`;
+  switch (code) {
+    case "unauthorized":
+      return new ToolError(code, "FileForge rejected the API key (401). Check FILEFORGE_API_KEY is a valid, non-revoked ff_live_ key.");
+    case "forbidden":
+    case "pro_option":
+      return new ToolError(code, `${apiMsg} This requires a Forge Pro plan. Use a Pro API key or drop the Pro-only option/target.`);
+    case "unsupported_pair":
+      return new ToolError(code, ctx?.validTargets?.length ? `${apiMsg} Valid targets for this source: ${ctx.validTargets.join(", ")}. Call list_formats to confirm.` : `${apiMsg} Call list_formats to see valid target formats for this source.`);
+    case "unknown_preset":
+      return new ToolError(code, `${apiMsg} Call list_formats to see valid preset ids for this source\u2192target pair.`);
+    case "unknown_option":
+    case "invalid_value":
+    case "not_applicable":
+      return new ToolError(code, `${apiMsg} Call list_formats to see the valid options (with ranges) for this target.`);
+    case "file_too_large":
+      return new ToolError(code, ctx?.tierMaxMb ? `File too large: your plan allows up to ${ctx.tierMaxMb} MB${ctx.fileMb ? ` and this file is ${ctx.fileMb} MB` : ""}. Upgrade or use a smaller file.` : `${apiMsg}`);
+    case "mime_mismatch":
+      return new ToolError(code, `${apiMsg} The file's real content type didn't match its extension \u2014 make sure the file isn't renamed/corrupt.`);
+    case "malware_detected":
+      return new ToolError(code, "The file failed the virus scan and was rejected. It was not converted.");
+    case "scan_size_limit_exceeded":
+      return new ToolError(code, "The file is larger than the antivirus scanner accepts, so it could not be processed.");
+    case "rate_limited":
+      return new ToolError(code, `Rate limit hit. ${ctx?.retryAfterSeconds ? `Retry after ${ctx.retryAfterSeconds}s.` : "Wait a bit and retry."}`, ctx?.retryAfterSeconds);
+    case "maintenance":
+      return new ToolError(code, "FileForge is in maintenance mode right now. Retry shortly.");
+    default:
+      if (status === 429) return new ToolError("rate_limited", `Rate limit hit (429). ${ctx?.retryAfterSeconds ? `Retry after ${ctx.retryAfterSeconds}s.` : "Wait and retry."}`, ctx?.retryAfterSeconds);
+      if (status >= 500) return new ToolError(code, `FileForge had a server error (${status}). Retry shortly.`);
+      return new ToolError(code, apiMsg);
+  }
+}
+
+// src/client.ts
+var FileForgeClient = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  getFormats() {
+    return this.req("GET", "/formats");
+  }
+  presignUpload(body) {
+    return this.req("POST", "/files/presign-upload", body);
+  }
+  finalize(fileId, body) {
+    return this.req("POST", `/files/${fileId}/finalize`, body);
+  }
+  createConversion(body) {
+    return this.req("POST", "/conversions", body);
+  }
+  getConversion(id) {
+    return this.req("GET", `/conversions/${id}`);
+  }
+  createBulk(body) {
+    return this.req("POST", "/conversions/bulk", body);
+  }
+  async req(method, path, jsonBody) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.cfg.controlTimeoutMs);
+    let res;
+    try {
+      res = await fetch(this.cfg.baseUrl + path, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.cfg.apiKey}`,
+          Accept: "application/json",
+          ...jsonBody !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        body: jsonBody !== void 0 ? JSON.stringify(jsonBody) : void 0,
+        signal: ctrl.signal
+      });
+    } catch (e) {
+      throw new ToolError("network_error", `could not reach FileForge at ${this.cfg.baseUrl} \u2014 ${e instanceof Error ? e.message : String(e)}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    const data = text ? safeParse(text) : null;
+    if (!res.ok) {
+      const retryAfter = parseRetryAfterSeconds(res.headers.get("retry-after"));
+      throw friendlyApiError(res.status, data, { retryAfterSeconds: retryAfter });
+    }
+    return data;
+  }
+};
+function safeParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { message: text.slice(0, 300) };
+  }
+}
+function parseRetryAfterSeconds(value) {
+  if (!value) return void 0;
+  const delta = Number(value);
+  if (Number.isFinite(delta)) return delta >= 0 ? delta : void 0;
+  const at = Date.parse(value);
+  if (Number.isFinite(at)) return Math.max(0, Math.ceil((at - Date.now()) / 1e3));
+  return void 0;
+}
+
+// src/log.ts
+var ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+var threshold = ORDER.info;
+function setLogLevel(level) {
+  threshold = ORDER[level];
+}
+function log(level, message, extra) {
+  if (ORDER[level] < threshold) return;
+  const suffix = extra ? " " + safeJson(extra) : "";
+  process.stderr.write(`[fileforge-mcp] ${level}: ${message}${suffix}
+`);
+}
+function safeJson(o) {
+  try {
+    return JSON.stringify(o);
+  } catch {
+    return "[unserializable]";
+  }
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/list-formats.ts
+import { z as z2 } from "zod";
+
+// src/tools/shared.ts
+import { z } from "zod";
+
+// ../../packages/config/src/tiers.ts
+var TIERS = {
+  free: {
+    daily_limit: 5,
+    max_file_mb: 10,
+    ttl_hours: 24,
+    bulk_max: 1,
+    priority: 5,
+    allow_metadata_preserve: false
+  },
+  pro: {
+    daily_limit: null,
+    max_file_mb: 500,
+    ttl_hours: 24 * 7,
+    bulk_max: 20,
+    priority: 1,
+    allow_metadata_preserve: true
+  },
+  max: {
+    daily_limit: null,
+    max_file_mb: 2048,
+    ttl_hours: 24 * 30,
+    bulk_max: 100,
+    priority: 1,
+    allow_metadata_preserve: true
+  }
+};
+
+// ../../packages/config/src/formats.ts
+var IMAGE_PRESETS = [
+  { id: "web", label: "Web (q=82)", params: { quality: 82 } },
+  { id: "high", label: "High quality (q=92)", params: { quality: 92 } },
+  { id: "lossless", label: "Lossless / max", params: { quality: 100 } }
+];
+var ICO_PRESETS = [{ id: "standard", label: "Standard", params: {} }];
+var AUDIO_LOSSY_PRESETS = [
+  { id: "low", label: "Low (96 kbps)", params: { bitrate: "96k" } },
+  { id: "web", label: "Web (128 kbps)", params: { bitrate: "128k" } },
+  { id: "high", label: "High (192 kbps)", params: { bitrate: "192k" } },
+  { id: "very-high", label: "Very high (320 kbps)", params: { bitrate: "320k" } }
+];
+var AUDIO_LOSSLESS_PRESETS = [
+  { id: "standard", label: "Standard (44.1 kHz)", params: { sample_rate: 44100 } },
+  { id: "studio", label: "Studio (48 kHz)", params: { sample_rate: 48e3 } }
+];
+var FLAC_PRESETS = [
+  { id: "fast", label: "Fast (level 5)", params: { compression: 5 } },
+  { id: "best", label: "Best (level 8)", params: { compression: 8 } }
+];
+var VIDEO_PRESETS = [
+  { id: "web-720p", label: "720p web", params: { resolution: "1280x720", crf: 23, preset: "p4" } },
+  { id: "web-1080p", label: "1080p web", params: { resolution: "1920x1080", crf: 22, preset: "p4" } },
+  { id: "high-1080p", label: "1080p high", params: { resolution: "1920x1080", crf: 18, preset: "p5" } }
+];
+var DOCUMENT_PRESETS = [
+  { id: "standard", label: "Standard", params: {} }
+];
+var PDF_PRESETS = [
+  { id: "standard", label: "Standard", params: {} },
+  { id: "linearize", label: "Linearized (web-optimized)", params: { linearize: true } }
+];
+var ARCHIVE_PRESETS = [
+  { id: "fast", label: "Fast (level 1)", params: { compression: 1 } },
+  { id: "standard", label: "Standard (level 5)", params: { compression: 5 } },
+  { id: "best", label: "Best (level 9)", params: { compression: 9 } }
+];
+var IMAGE_TARGETS = ["png", "jpg", "webp", "gif", "tiff", "avif", "ico"];
+function imageTargetsFor(sourceSlug) {
+  const out = {};
+  for (const t of IMAGE_TARGETS) {
+    if (t === sourceSlug) continue;
+    out[t] = {
+      worker: "image",
+      freeAllowed: true,
+      presets: t === "ico" ? ICO_PRESETS : IMAGE_PRESETS
+    };
+  }
+  return out;
+}
+function audioEntry(target, opts) {
+  let presets;
+  if (target === "flac") presets = FLAC_PRESETS;
+  else if (target === "wav") presets = AUDIO_LOSSLESS_PRESETS;
+  else presets = AUDIO_LOSSY_PRESETS;
+  return { worker: "audio", freeAllowed: opts.freeAllowed, presets };
+}
+function audioTargetsFor(source) {
+  const free = /* @__PURE__ */ new Set(["mp3", "wav", "ogg", "opus"]);
+  const all = ["mp3", "wav", "ogg", "opus", "flac", "aac", "m4a"];
+  const out = {};
+  for (const t of all) {
+    if (t === source) continue;
+    out[t] = audioEntry(t, { freeAllowed: free.has(t) });
+  }
+  return out;
+}
+function videoTargetsFor(source) {
+  const free = /* @__PURE__ */ new Set(["mp4", "webm"]);
+  const all = ["mp4", "webm", "mov", "mkv"];
+  const out = {};
+  for (const t of all) {
+    if (t === source) continue;
+    out[t] = { worker: "video", freeAllowed: free.has(t), presets: VIDEO_PRESETS };
+  }
+  return out;
+}
+var DOC_FAMILY = ["pdf", "docx", "doc", "odt", "rtf", "txt", "html", "md"];
+function documentTargetsFor(source) {
+  const free = /* @__PURE__ */ new Set(["txt", "md", "html", "pdf"]);
+  const out = {};
+  for (const t of DOC_FAMILY) {
+    if (t === source) continue;
+    out[t] = {
+      worker: "document",
+      freeAllowed: free.has(t),
+      presets: t === "pdf" ? PDF_PRESETS : DOCUMENT_PRESETS
+    };
+  }
+  return out;
+}
+function spreadsheetTargets() {
+  return {
+    pdf: { worker: "document", freeAllowed: false, presets: PDF_PRESETS }
+  };
+}
+function presentationTargets() {
+  return {
+    pdf: { worker: "document", freeAllowed: false, presets: PDF_PRESETS }
+  };
+}
+var ARCHIVE_FAMILY = ["zip", "7z", "tar", "tar.gz", "tar.bz2"];
+function archiveTargetsFor(source) {
+  const free = /* @__PURE__ */ new Set(["zip", "tar", "tar.gz", "tar.bz2"]);
+  const out = {};
+  for (const t of ARCHIVE_FAMILY) {
+    if (t === source) continue;
+    out[t] = {
+      worker: "archive",
+      freeAllowed: free.has(t),
+      presets: ARCHIVE_PRESETS
+    };
+  }
+  return out;
+}
+var FORMATS = {
+  // Image — PNG/JPEG/WebP/GIF/TIFF/AVIF interconvert + ICO favicon output.
+  // SVG is raster-in only (no SVG target). 'jpg' is the slug for image/jpeg.
+  "image/png": imageTargetsFor("png"),
+  "image/jpeg": imageTargetsFor("jpg"),
+  "image/webp": imageTargetsFor("webp"),
+  "image/gif": imageTargetsFor("gif"),
+  "image/tiff": imageTargetsFor("tiff"),
+  "image/avif": imageTargetsFor("avif"),
+  "image/svg+xml": imageTargetsFor(null),
+  // Audio
+  "audio/mpeg": audioTargetsFor("mp3"),
+  "audio/wav": audioTargetsFor("wav"),
+  "audio/flac": audioTargetsFor("flac"),
+  "audio/ogg": audioTargetsFor("ogg"),
+  "audio/opus": audioTargetsFor("opus"),
+  "audio/aac": audioTargetsFor("aac"),
+  "audio/mp4": audioTargetsFor("m4a"),
+  // Video
+  "video/mp4": videoTargetsFor("mp4"),
+  "video/webm": videoTargetsFor("webm"),
+  "video/quicktime": videoTargetsFor("mov"),
+  "video/x-matroska": videoTargetsFor("mkv"),
+  // Document — word-processor family
+  "application/pdf": documentTargetsFor("pdf"),
+  "application/msword": documentTargetsFor("doc"),
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": documentTargetsFor("docx"),
+  "application/vnd.oasis.opendocument.text": documentTargetsFor("odt"),
+  "application/rtf": documentTargetsFor("rtf"),
+  "text/plain": documentTargetsFor("txt"),
+  "text/html": documentTargetsFor("html"),
+  "text/markdown": documentTargetsFor("md"),
+  // Spreadsheets and presentations: PDF-only output lane (Pro).
+  "application/vnd.ms-excel": spreadsheetTargets(),
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": spreadsheetTargets(),
+  "application/vnd.oasis.opendocument.spreadsheet": spreadsheetTargets(),
+  "application/vnd.ms-powerpoint": presentationTargets(),
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation": presentationTargets(),
+  "application/vnd.oasis.opendocument.presentation": presentationTargets(),
+  // Archive family — repack, content-passthrough.
+  "application/zip": archiveTargetsFor("zip"),
+  "application/x-7z-compressed": archiveTargetsFor("7z"),
+  "application/x-tar": archiveTargetsFor("tar"),
+  "application/gzip": archiveTargetsFor("tar.gz"),
+  "application/x-gzip": archiveTargetsFor("tar.gz"),
+  "application/x-bzip2": archiveTargetsFor("tar.bz2"),
+  "application/vnd.rar": archiveTargetsFor("rar"),
+  "application/x-rar-compressed": archiveTargetsFor("rar")
+};
+var MIME_ALIASES = {
+  // Image
+  "image/jpg": "image/jpeg",
+  "image/pjpeg": "image/jpeg",
+  "image/x-png": "image/png",
+  "image/tif": "image/tiff",
+  "image/x-tiff": "image/tiff",
+  "image/svg": "image/svg+xml",
+  // Audio
+  "audio/mp3": "audio/mpeg",
+  "audio/mpeg3": "audio/mpeg",
+  "audio/x-mpeg": "audio/mpeg",
+  "audio/x-wav": "audio/wav",
+  "audio/wave": "audio/wav",
+  "audio/vnd.wave": "audio/wav",
+  "audio/x-flac": "audio/flac",
+  "audio/x-aac": "audio/aac",
+  "audio/x-m4a": "audio/mp4",
+  "audio/m4a": "audio/mp4",
+  "audio/x-ogg": "audio/ogg",
+  // Video
+  "video/x-matroska-3d": "video/x-matroska",
+  "video/x-quicktime": "video/quicktime",
+  // Document — common aliases that file-type / browsers emit.
+  "application/x-pdf": "application/pdf",
+  "text/x-markdown": "text/markdown",
+  "text/x-md": "text/markdown",
+  "application/x-rtf": "application/rtf",
+  "text/rtf": "application/rtf",
+  // Archive
+  "application/x-zip-compressed": "application/zip",
+  "application/x-7z": "application/x-7z-compressed",
+  "application/x-gtar": "application/x-tar",
+  "application/x-bzip": "application/x-bzip2",
+  "application/bzip2": "application/x-bzip2",
+  "application/x-rar": "application/vnd.rar"
+};
+function canonicalMime(mime) {
+  return MIME_ALIASES[mime] ?? mime;
+}
+function lookupFormat(sourceMime, targetFormat) {
+  const targets = FORMATS[canonicalMime(sourceMime)];
+  if (!targets) return null;
+  return targets[targetFormat] ?? null;
+}
+function findPreset(entry, presetId) {
+  return entry.presets.find((p) => p.id === presetId) ?? null;
+}
+
+// ../../packages/config/src/options.ts
+var SECRET_OPTION_KEYS = /* @__PURE__ */ new Set(["password", "pdf_password"]);
+var PRINTABLE_ASCII = /^[\x20-\x7E]+$/;
+var IMAGE_OPTIONS = [
+  { key: "width", label: "Width (px)", type: "integer", min: 1, max: 3e4, group: "Resize", help: "Output width in pixels", excludeTargets: ["ico"] },
+  { key: "height", label: "Height (px)", type: "integer", min: 1, max: 3e4, group: "Resize", help: "Output height in pixels", excludeTargets: ["ico"] },
+  {
+    key: "fit",
+    label: "Resize fit",
+    type: "enum",
+    values: ["inside", "outside", "cover", "contain", "fill"],
+    default: "inside",
+    group: "Resize",
+    help: "How the image fits the width/height box",
+    excludeTargets: ["ico"]
+  },
+  { key: "rotate", label: "Rotate", type: "enum", values: ["0", "90", "180", "270"], default: "0", group: "Transform" },
+  { key: "flip", label: "Flip (vertical)", type: "boolean", group: "Transform" },
+  { key: "flop", label: "Flop (horizontal)", type: "boolean", group: "Transform" },
+  { key: "grayscale", label: "Grayscale", type: "boolean", group: "Color" },
+  { key: "quality", label: "Quality", type: "integer", min: 1, max: 100, step: 1, group: "Quality", help: "Overrides the preset quality", excludeTargets: ["ico"] },
+  { key: "dpi", label: "DPI", type: "integer", min: 1, max: 2400, group: "Metadata", excludeTargets: ["ico"] },
+  {
+    key: "sizes",
+    label: "Icon sizes",
+    type: "string",
+    default: "16,32,48",
+    pattern: "^(16|32|48|64|128|256)(,(16|32|48|64|128|256))*$",
+    maxLength: 64,
+    group: "Favicon",
+    help: "Comma-separated icon sizes: 16,32,48,64,128,256",
+    targets: ["ico"]
+  }
+];
+var AUDIO_OPTIONS = [
+  { key: "channels", label: "Channels", type: "enum", values: ["mono", "stereo"], group: "Audio" },
+  { key: "normalize", label: "Normalize loudness", type: "boolean", group: "Audio", help: "EBU R128 loudness normalization" },
+  { key: "trim_start", label: "Trim start (sec)", type: "number", min: 0, max: 86400, group: "Trim" },
+  { key: "trim_end", label: "Trim end (sec)", type: "number", min: 0, max: 86400, group: "Trim", help: "Must be greater than trim start" }
+];
+var VIDEO_OPTIONS = [
+  { key: "fps", label: "Frame rate (fps)", type: "integer", min: 1, max: 120, group: "Video" },
+  { key: "mute", label: "Mute (remove audio)", type: "boolean", group: "Audio" },
+  { key: "rotate", label: "Rotate", type: "enum", values: ["0", "90", "180", "270"], default: "0", group: "Transform" },
+  { key: "trim_start", label: "Trim start (sec)", type: "number", min: 0, max: 86400, group: "Trim" },
+  { key: "trim_end", label: "Trim end (sec)", type: "number", min: 0, max: 86400, group: "Trim", help: "Must be greater than trim start" }
+];
+var DOCUMENT_OPTIONS = [
+  {
+    key: "page_range",
+    label: "Page range",
+    type: "string",
+    pattern: "^[0-9]+(-[0-9]+)?(,[0-9]+(-[0-9]+)?)*$",
+    maxLength: 64,
+    group: "PDF",
+    help: "Pages to keep, e.g. 1-3,5 (PDF output only)",
+    targets: ["pdf"]
+  },
+  {
+    key: "password",
+    label: "Password (encrypt)",
+    type: "string",
+    maxLength: 128,
+    proOnly: true,
+    group: "PDF",
+    help: "Encrypt the output PDF (AES-256)",
+    targets: ["pdf"]
+  }
+];
+var ARCHIVE_OPTIONS = [
+  {
+    key: "password",
+    label: "Password (encrypt)",
+    type: "string",
+    maxLength: 128,
+    proOnly: true,
+    group: "Security",
+    help: "Produce an AES-256 encrypted archive",
+    targets: ["zip", "7z"]
+  }
+];
+var OPTION_SPECS = {
+  image: IMAGE_OPTIONS,
+  audio: AUDIO_OPTIONS,
+  video: VIDEO_OPTIONS,
+  document: DOCUMENT_OPTIONS,
+  archive: ARCHIVE_OPTIONS
+};
+function appliesTo(spec, target) {
+  if (spec.targets && spec.targets.length > 0) return spec.targets.includes(target);
+  if (spec.excludeTargets && spec.excludeTargets.length > 0) return !spec.excludeTargets.includes(target);
+  return true;
+}
+var INVALID = Symbol("invalid");
+function coerce(spec, raw) {
+  switch (spec.type) {
+    case "integer": {
+      let n;
+      if (typeof raw === "number" && Number.isInteger(raw)) n = raw;
+      else if (typeof raw === "string" && /^-?\d+$/.test(raw)) n = Number.parseInt(raw, 10);
+      else return INVALID;
+      if (spec.min !== void 0 && n < spec.min) return INVALID;
+      if (spec.max !== void 0 && n > spec.max) return INVALID;
+      return n;
+    }
+    case "number": {
+      let n;
+      if (typeof raw === "number" && Number.isFinite(raw)) n = raw;
+      else if (typeof raw === "string" && /^-?\d+(\.\d+)?$/.test(raw)) n = Number.parseFloat(raw);
+      else return INVALID;
+      if (spec.min !== void 0 && n < spec.min) return INVALID;
+      if (spec.max !== void 0 && n > spec.max) return INVALID;
+      return n;
+    }
+    case "boolean": {
+      if (typeof raw === "boolean") return raw;
+      if (raw === "true") return true;
+      if (raw === "false") return false;
+      return INVALID;
+    }
+    case "enum": {
+      if (typeof raw !== "string") return INVALID;
+      return spec.values?.includes(raw) ? raw : INVALID;
+    }
+    case "string": {
+      if (typeof raw !== "string") return INVALID;
+      if (raw.length === 0) return INVALID;
+      if (spec.maxLength !== void 0 && raw.length > spec.maxLength) return INVALID;
+      if (spec.pattern) {
+        if (!new RegExp(spec.pattern).test(raw)) return INVALID;
+      } else if (!PRINTABLE_ASCII.test(raw)) {
+        return INVALID;
+      }
+      return raw;
+    }
+    default:
+      return INVALID;
+  }
+}
+function validateOptions(worker, target, submitted, opts) {
+  if (submitted === void 0 || submitted === null) return { ok: true, value: {} };
+  if (typeof submitted !== "object" || Array.isArray(submitted)) {
+    return { ok: false, code: "invalid_value", message: "options must be an object", key: "" };
+  }
+  const specs = OPTION_SPECS[worker] ?? [];
+  const byKey = new Map(specs.map((s) => [s.key, s]));
+  const out = {};
+  for (const [key, raw] of Object.entries(submitted)) {
+    if (raw === void 0 || raw === null || raw === "") continue;
+    const spec = byKey.get(key);
+    if (!spec) return { ok: false, code: "unknown_option", message: `unknown option "${key}"`, key };
+    if (!appliesTo(spec, target)) {
+      return { ok: false, code: "not_applicable", message: `option "${key}" is not available for target ${target}`, key };
+    }
+    if (spec.proOnly && !opts.isPro) {
+      return { ok: false, code: "pro_option", message: `option "${key}" is a Forge Pro feature`, key };
+    }
+    const value = coerce(spec, raw);
+    if (value === INVALID) {
+      return { ok: false, code: "invalid_value", message: `invalid value for option "${key}"`, key };
+    }
+    out[key] = value;
+  }
+  if (out.trim_start !== void 0 && out.trim_end !== void 0 && Number(out.trim_end) <= Number(out.trim_start)) {
+    return { ok: false, code: "invalid_value", message: "trim_end must be greater than trim_start", key: "trim_end" };
+  }
+  return { ok: true, value: out };
+}
+function stripSecretOptions(options) {
+  const safe = {};
+  let secured = false;
+  for (const [k, v] of Object.entries(options ?? {})) {
+    if (SECRET_OPTION_KEYS.has(k)) secured = true;
+    else safe[k] = v;
+  }
+  return { safe, secured };
+}
+
+// src/mime.ts
+import { basename, extname } from "node:path";
+var EXT_MIME = {
+  // image
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  gif: "image/gif",
+  tif: "image/tiff",
+  tiff: "image/tiff",
+  avif: "image/avif",
+  svg: "image/svg+xml",
+  ico: "image/vnd.microsoft.icon",
+  bmp: "image/bmp",
+  // audio
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  flac: "audio/flac",
+  ogg: "audio/ogg",
+  opus: "audio/opus",
+  aac: "audio/aac",
+  m4a: "audio/mp4",
+  // video
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mov: "video/quicktime",
+  mkv: "video/x-matroska",
+  // documents
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  odt: "application/vnd.oasis.opendocument.text",
+  rtf: "application/rtf",
+  txt: "text/plain",
+  html: "text/html",
+  htm: "text/html",
+  md: "text/markdown",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ods: "application/vnd.oasis.opendocument.spreadsheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  odp: "application/vnd.oasis.opendocument.presentation",
+  // archives
+  zip: "application/zip",
+  "7z": "application/x-7z-compressed",
+  tar: "application/x-tar",
+  gz: "application/gzip",
+  tgz: "application/gzip",
+  bz2: "application/x-bzip2",
+  rar: "application/vnd.rar"
+};
+function mimeFromFilename(filename) {
+  const lower = basename(filename).toLowerCase();
+  if (lower.endsWith(".tar.gz")) return "application/gzip";
+  if (lower.endsWith(".tar.bz2")) return "application/x-bzip2";
+  const ext = extname(lower).replace(/^\./, "");
+  const mime = EXT_MIME[ext];
+  return mime ? canonicalMime(mime) : "application/octet-stream";
+}
+function filenameFromUrl(url, fallback = "download") {
+  try {
+    const u = new URL(url);
+    const last = u.pathname.split("/").filter(Boolean).pop();
+    if (last) return decodeURIComponent(last);
+  } catch {
+  }
+  return fallback;
+}
+
+// src/tools/shared.ts
+var sourceShape = z.object({
+  path: z.string().optional().describe("Absolute or cwd-relative path to a local file (stdio transport)."),
+  url: z.string().optional().describe("http(s) URL the server fetches."),
+  bytes: z.string().optional().describe("Base64-encoded file contents."),
+  filename: z.string().optional().describe("File name; required with bytes (and useful with url) to name the output and infer type.")
+}).describe("The input file \u2014 provide exactly one of path, url, or bytes.");
+var outputShape = z.object({
+  path: z.string().optional().describe("Where to write the result (stdio). Defaults next to a path-input as <stem>.<target>."),
+  overwrite: z.boolean().optional().describe("Overwrite an existing output file (default false \u2192 a de-duped name is used)."),
+  return_bytes: z.boolean().optional().describe("Also return the result as base64 (only when under the inline size cap).")
+}).describe("Where/how to return the result.");
+var optionsShape = z.record(z.union([z.string(), z.number(), z.boolean()])).describe('Per-conversion options validated by FileForge, e.g. {"width":800,"quality":90} or {"page_range":"1-3"}. See list_formats.');
+async function runTool(fn) {
+  try {
+    const result = await fn();
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  } catch (e) {
+    const code = e instanceof ToolError ? e.code : "error";
+    const msg = e instanceof Error ? e.message : String(e);
+    return { content: [{ type: "text", text: `Error (${code}): ${msg}` }], isError: true };
+  }
+}
+function resolveSourceMime(inputPath, sourceFormat) {
+  if (inputPath) return canonicalMime(mimeFromFilename(inputPath));
+  if (sourceFormat) {
+    if (sourceFormat.includes("/")) return canonicalMime(sourceFormat);
+    return canonicalMime(mimeFromFilename(`x.${sourceFormat.replace(/^\./, "")}`));
+  }
+  return void 0;
+}
+function normalizeOption(o) {
+  return {
+    key: o.key,
+    label: o.label,
+    type: o.type,
+    ...o.values ? { values: o.values } : {},
+    ...o.min !== void 0 ? { min: o.min } : {},
+    ...o.max !== void 0 ? { max: o.max } : {},
+    ...o.step !== void 0 ? { step: o.step } : {},
+    ...o.default !== void 0 ? { default: o.default } : {},
+    pro_only: Boolean(o.proOnly),
+    ...o.group ? { group: o.group } : {},
+    ...o.help ? { help: o.help } : {}
+  };
+}
+
+// src/tools/list-formats.ts
+function registerListFormats(server, ctx) {
+  server.registerTool(
+    "list_formats",
+    {
+      title: "List conversion formats & options",
+      description: "Discover which file conversions FileForge supports and the options each accepts. Call this BEFORE convert_file when unsure whether a source\u2192target pair is allowed, what preset ids exist, or what tuning options (quality, resize, bitrate, page_range, \u2026) are valid. Results are filtered to your API key tier, so anything returned here is usable by convert_file \u2014 it is the substitute for reading the REST docs.",
+      inputSchema: {
+        input_path: z2.string().optional().describe("A local file whose source type is sniffed from its extension (stdio)."),
+        source_format: z2.string().optional().describe("Extension like 'png' or MIME like 'image/png'. Provide this OR input_path; omit both for the full matrix."),
+        target_format: z2.string().optional().describe("Optional filter: only return pairs producing this slug, e.g. 'webp'.")
+      }
+    },
+    async (args) => runTool(async () => {
+      const { formats } = await ctx.client.getFormats();
+      const entriesFor = (mime) => Object.entries(formats[mime] ?? {}).map(([target, e]) => ({
+        target_format: target,
+        worker: e.worker,
+        free_allowed: e.freeAllowed,
+        presets: e.presets.map((p) => ({ id: p.id, label: p.label })),
+        options: (e.options ?? []).map(normalizeOption)
+      }));
+      const sourceMime = resolveSourceMime(args.input_path, args.source_format);
+      if (sourceMime) {
+        if (!formats[sourceMime]) {
+          return {
+            source_mime: sourceMime,
+            targets: [],
+            note: "No conversions available from this source on your tier.",
+            known_sources: Object.keys(formats)
+          };
+        }
+        let targets = entriesFor(sourceMime);
+        if (args.target_format) targets = targets.filter((t) => t.target_format === args.target_format);
+        return { source_mime: sourceMime, targets };
+      }
+      return { sources: Object.fromEntries(Object.keys(formats).map((m) => [m, entriesFor(m)])) };
+    })
+  );
+}
+
+// src/tools/convert-file.ts
+import { z as z3 } from "zod";
+
+// src/flow.ts
+import { stat as stat2 } from "node:fs/promises";
+import { basename as basename3, resolve as resolvePath } from "node:path";
+
+// src/httpio.ts
+import { createReadStream, createWriteStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { request as httpsRequest } from "node:https";
+import { request as httpRequest } from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+function requester(urlStr) {
+  const url = new URL(urlStr);
+  return { url, fn: url.protocol === "http:" ? httpRequest : httpsRequest };
+}
+async function putToPresigned(uploadUrl, body, contentType, contentLength, timeoutMs) {
+  const { url, fn } = requester(uploadUrl);
+  const opts = {
+    method: "PUT",
+    headers: { "Content-Type": contentType, "Content-Length": String(contentLength) },
+    timeout: timeoutMs
+  };
+  await new Promise((resolveP, rejectP) => {
+    const req = fn(url, opts, (res) => {
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => {
+        const code = res.statusCode ?? 0;
+        if (code >= 200 && code < 300) return resolveP();
+        rejectP(new ToolError("upload_failed", `upload PUT failed (HTTP ${code}): ${Buffer.concat(chunks).toString("utf8").slice(0, 300)}`));
+      });
+    });
+    req.on("error", (e) => rejectP(new ToolError("upload_failed", `upload PUT error: ${e.message}`)));
+    req.on("timeout", () => req.destroy(new ToolError("upload_failed", `upload PUT timed out after ${timeoutMs}ms`)));
+    if (body.buffer) {
+      req.end(body.buffer);
+    } else if (body.filePath) {
+      const rs = createReadStream(body.filePath);
+      rs.on("error", (e) => {
+        req.destroy();
+        rejectP(new ToolError("upload_failed", `read error: ${e.message}`));
+      });
+      rs.pipe(req);
+    } else {
+      req.destroy();
+      rejectP(new ToolError("upload_failed", "no upload body provided"));
+    }
+  });
+}
+async function downloadToFile(url, destPath, timeoutMs, opts = {}) {
+  const res = await fetchWithTimeout(url, timeoutMs);
+  if (!res.ok || !res.body) {
+    throw new ToolError("download_failed", `download failed (HTTP ${res.status})`);
+  }
+  try {
+    await pipeline(
+      Readable.fromWeb(res.body),
+      createWriteStream(destPath, { flags: opts.exclusive ? "wx" : "w" })
+    );
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      throw new ToolError("output_exists", `output file already exists: ${destPath} (set output.overwrite to replace it).`);
+    }
+    throw e;
+  }
+  return (await stat(destPath)).size;
+}
+async function downloadToBuffer(url, maxBytes, timeoutMs, opts = {}) {
+  const res = await fetchWithTimeout(url, timeoutMs, opts.noRedirect ? "error" : "follow");
+  if (!res.ok || !res.body) throw new ToolError("download_failed", `fetch failed (HTTP ${res.status})`);
+  const declared = Number(res.headers.get("content-length") ?? "0");
+  if (maxBytes > 0 && declared > maxBytes) {
+    throw new ToolError("source_too_large", `source is ${declared} bytes, over the ${maxBytes}-byte limit`);
+  }
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of Readable.fromWeb(res.body)) {
+    const buf = chunk;
+    total += buf.length;
+    if (maxBytes > 0 && total > maxBytes) {
+      throw new ToolError("source_too_large", `source exceeds the ${maxBytes}-byte limit`);
+    }
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks);
+}
+async function fetchWithTimeout(url, timeoutMs, redirect = "follow") {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    return await fetch(url, { signal: ctrl.signal, redirect });
+  } catch (e) {
+    throw new ToolError("download_failed", `request error: ${e instanceof Error ? e.message : String(e)}`);
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// src/paths.ts
+import { existsSync } from "node:fs";
+import { basename as basename2, dirname, extname as extname2, isAbsolute, join, relative, resolve } from "node:path";
+function resolveOutputPath(opts) {
+  const { explicitPath, sourcePath, outputDir, targetFormat, sourceFilename } = opts;
+  if (explicitPath) return resolve(process.cwd(), explicitPath);
+  const stem = stripExt(basename2(sourceFilename)) || "output";
+  const filename = `${stem}.${targetFormat}`;
+  if (sourcePath) return join(dirname(resolve(process.cwd(), sourcePath)), filename);
+  if (outputDir) return join(resolve(process.cwd(), outputDir), filename);
+  return null;
+}
+function dedupePath(path, overwrite, exists = existsSync) {
+  if (overwrite || !exists(path)) return path;
+  const dir = dirname(path);
+  const ext = extname2(path);
+  const stem = basename2(path, ext);
+  for (let i = 1; i < 1e4; i++) {
+    const candidate = join(dir, `${stem}-${i}${ext}`);
+    if (!exists(candidate)) return candidate;
+  }
+  throw new ToolError("output_exists", `could not find a free output filename next to ${path}`);
+}
+function assertWithin(baseDir, target) {
+  if (!baseDir) return;
+  const base = resolve(process.cwd(), baseDir);
+  const rel = relative(base, resolve(target));
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new ToolError("path_traversal", `output path ${target} escapes the allowed directory ${baseDir}`);
+  }
+}
+function stripExt(name) {
+  return name.replace(/\.[^./]+$/, "");
+}
+
+// src/ssrf.ts
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+async function assertPublicHttpUrl(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new ToolError("blocked_url", `source.url is not a valid URL: ${raw}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new ToolError("blocked_url", `only http(s) source URLs are allowed (got "${url.protocol}").`);
+  }
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  let addresses;
+  if (isIP(host)) {
+    addresses = [host];
+  } else {
+    if (isBlockedHostname(host)) {
+      throw new ToolError("blocked_url", `source URL host is not allowed: ${host}`);
+    }
+    try {
+      addresses = (await lookup(host, { all: true })).map((r) => r.address);
+    } catch {
+      throw new ToolError("blocked_url", `could not resolve source URL host: ${host}`);
+    }
+  }
+  for (const addr of addresses) {
+    if (isPrivateAddress(addr)) {
+      throw new ToolError("blocked_url", `source URL resolves to a private/reserved address (${addr}); refusing to fetch.`);
+    }
+  }
+}
+function isBlockedHostname(host) {
+  const h = host.toLowerCase();
+  return h === "localhost" || h.endsWith(".localhost") || h.endsWith(".local") || h.endsWith(".internal");
+}
+function isPrivateAddress(ip) {
+  const kind = isIP(ip);
+  if (kind === 4) return isPrivateV4(ip);
+  if (kind === 6) return isPrivateV6(ip);
+  return true;
+}
+function isPrivateV4(ip) {
+  const parts = ip.split(".").map((n) => Number.parseInt(n, 10));
+  if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
+  const [a, b] = parts;
+  if (a === 0 || a === 10 || a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a === 192 && b === 0) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  if (a >= 224) return true;
+  return false;
+}
+function isPrivateV6(ip) {
+  const a = ip.toLowerCase();
+  if (a === "::1" || a === "::") return true;
+  if (a.startsWith("fe80") || a.startsWith("fc") || a.startsWith("fd")) return true;
+  if (a.startsWith("ff")) return true;
+  const mapped = a.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped) return isPrivateV4(mapped[1]);
+  return false;
+}
+
+// src/flow.ts
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+function preflight(sourceMime, target, options) {
+  const entry = lookupFormat(sourceMime, target);
+  const known = FORMATS[sourceMime];
+  if (known && !entry) {
+    throw new ToolError("unsupported_pair", `Cannot convert ${sourceMime} \u2192 ${target}. Valid targets: ${Object.keys(known).join(", ")}. Use list_formats to confirm.`);
+  }
+  if (entry && options && Object.keys(options).length > 0) {
+    const v = validateOptions(entry.worker, target, options, { isPro: true });
+    if (!v.ok) throw new ToolError(v.code, `${v.message}. Use list_formats to see valid options for ${target}.`);
+  }
+  return entry;
+}
+async function convertOne(client, cfg, params) {
+  const src = await resolveSource(params.source, cfg);
+  const sourceMime = canonicalMime(src.declaredMime);
+  const target = params.target_format;
+  const entry = preflight(sourceMime, target, params.options);
+  const presetId = pickPreset(entry, sourceMime, target, params.preset, cfg);
+  const presign = await client.presignUpload({ filename: src.filename, size: src.size, mime: src.declaredMime });
+  await putToPresigned(
+    presign.upload_url,
+    src.filePath ? { filePath: src.filePath } : { buffer: src.buffer },
+    src.declaredMime,
+    src.size,
+    cfg.streamTimeoutMs
+  );
+  const finalized = await client.finalize(presign.file_id, {
+    storage_key: presign.storage_key,
+    original_name: src.filename,
+    declared_mime: src.declaredMime
+  });
+  const created = await client.createConversion({
+    input_file_id: finalized.id,
+    target_format: target,
+    preset: { id: presetId },
+    options: params.options,
+    preserve_metadata: params.preserve_metadata
+  });
+  log("debug", "conversion created", { id: created.id, target, preset: presetId, options: Object.keys(stripSecretOptions(params.options ?? {}).safe) });
+  const { conv, timedOut } = await pollConversion(client, created.id, params.timeout_seconds, cfg);
+  if (timedOut) {
+    return {
+      conversion_id: created.id,
+      status: "processing",
+      target_format: target,
+      progress_pct: conv?.progress_pct ?? null,
+      hint: "The conversion is still running. Call get_conversion_status with this conversion_id (and an output.path) to fetch the result when it finishes \u2014 no need to re-upload."
+    };
+  }
+  if (conv.status !== "completed") {
+    throw new ToolError(conv.error_code ?? "conversion_failed", `Conversion ${conv.status}: ${conv.error_message ?? "no detail"}`);
+  }
+  return finishCompleted(conv, cfg, {
+    target_format: target,
+    output: params.output,
+    sourceWasLocalPath: src.sourceWasLocalPath,
+    sourcePath: src.filePath,
+    sourceFilename: src.filename,
+    outputDir: params.outputDir
+  });
+}
+async function convertMany(client, cfg, items, opts) {
+  const prepared = await mapLimit(items, 4, async (p, i) => {
+    const src = await resolveSource(p.source, cfg);
+    const sourceMime = canonicalMime(src.declaredMime);
+    const entry = preflight(sourceMime, p.target_format, p.options);
+    const presetId = pickPreset(entry, sourceMime, p.target_format, p.preset, cfg);
+    const presign = await client.presignUpload({ filename: src.filename, size: src.size, mime: src.declaredMime });
+    await putToPresigned(presign.upload_url, src.filePath ? { filePath: src.filePath } : { buffer: src.buffer }, src.declaredMime, src.size, cfg.streamTimeoutMs);
+    const finalized = await client.finalize(presign.file_id, { storage_key: presign.storage_key, original_name: src.filename, declared_mime: src.declaredMime });
+    return { index: i, src, params: p, presetId, input_file_id: finalized.id };
+  });
+  const bulk = await client.createBulk({
+    items: prepared.map((x) => ({
+      input_file_id: x.input_file_id,
+      target_format: x.params.target_format,
+      preset: { id: x.presetId },
+      options: x.params.options,
+      preserve_metadata: x.params.preserve_metadata
+    }))
+  });
+  const idByIndex = new Map(prepared.map((x, i) => [i, bulk.items[i]?.conversion_id]));
+  const deadline = Date.now() + clampTimeout(opts.timeout_seconds ?? 600, cfg) * 1e3;
+  const results = [];
+  let completed = 0;
+  let failed = 0;
+  for (const x of prepared) {
+    const convId = idByIndex.get(x.index);
+    if (!convId) {
+      failed++;
+      results.push({ status: "failed", error_code: "no_conversion_id", source: describeSource(x.src) });
+      continue;
+    }
+    const { conv, timedOut } = await pollConversion(client, convId, Math.max(1, Math.ceil((deadline - Date.now()) / 1e3)), cfg);
+    if (timedOut) {
+      results.push({ conversion_id: convId, status: "processing", source: describeSource(x.src), hint: "still running; poll get_conversion_status" });
+      continue;
+    }
+    if (conv.status === "completed") {
+      try {
+        const out = await finishCompleted(conv, cfg, {
+          target_format: x.params.target_format,
+          output: x.params.output,
+          sourceWasLocalPath: x.src.sourceWasLocalPath,
+          sourcePath: x.src.filePath,
+          sourceFilename: x.src.filename,
+          outputDir: opts.outputDir,
+          overwrite: opts.overwrite
+        });
+        completed++;
+        results.push({ ...out, source: describeSource(x.src) });
+      } catch (e) {
+        failed++;
+        results.push({ conversion_id: convId, status: "failed", error_code: e instanceof ToolError ? e.code : "download_failed", error_message: e instanceof Error ? e.message : String(e) });
+      }
+    } else {
+      failed++;
+      results.push({ conversion_id: convId, status: conv.status, error_code: conv.error_code, error_message: conv.error_message, source: describeSource(x.src) });
+    }
+  }
+  return { bulk_id: bulk.bulk_id, total: bulk.total, completed, failed, results };
+}
+async function fetchStatus(client, cfg, conversionId, output) {
+  const conv = await client.getConversion(conversionId);
+  const base = {
+    id: conv.id,
+    status: conv.status,
+    progress_pct: conv.progress_pct ?? null,
+    worker_type: conv.worker_type,
+    source_format: conv.source_format,
+    target_format: conv.target_format,
+    error_code: conv.error_code ?? void 0,
+    error_message: conv.error_message ?? void 0,
+    duration_ms: conv.duration_ms ?? void 0
+  };
+  if (conv.status === "completed" && (output?.path || output?.return_bytes)) {
+    const fin = await finishCompleted(conv, cfg, {
+      target_format: conv.target_format,
+      output,
+      sourceWasLocalPath: Boolean(output?.path),
+      sourceFilename: `download.${conv.target_format}`
+    });
+    return { ...base, ...fin };
+  }
+  if (conv.status === "completed" && conv.output) {
+    return { ...base, download_url: conv.output.download_url, expires_in: conv.output.expires_in };
+  }
+  return base;
+}
+async function finishCompleted(conv, cfg, o) {
+  if (!conv.output?.download_url) {
+    throw new ToolError("no_output", "conversion completed but no download URL was returned");
+  }
+  const overwrite = o.output?.overwrite ?? o.overwrite ?? false;
+  let outPath = resolveOutputPath({
+    explicitPath: o.output?.path,
+    sourcePath: o.sourceWasLocalPath ? o.sourcePath : void 0,
+    outputDir: o.outputDir,
+    targetFormat: o.target_format,
+    sourceFilename: o.sourceFilename
+  });
+  if (outPath) {
+    if (o.outputDir && !o.output?.path) assertWithin(o.outputDir, outPath);
+    outPath = dedupePath(outPath, overwrite);
+    const bytes = await downloadToFile(conv.output.download_url, outPath, cfg.streamTimeoutMs, { exclusive: !overwrite });
+    const res2 = {
+      conversion_id: conv.id,
+      status: "completed",
+      target_format: o.target_format,
+      duration_ms: conv.duration_ms ?? null,
+      output_path: outPath,
+      bytes
+    };
+    if (o.output?.return_bytes) await attachBytes(res2, conv.output.download_url, cfg);
+    return res2;
+  }
+  const res = {
+    conversion_id: conv.id,
+    status: "completed",
+    target_format: o.target_format,
+    duration_ms: conv.duration_ms ?? null,
+    download_url: conv.output.download_url,
+    expires_in: conv.output.expires_in
+  };
+  if (o.output?.return_bytes) await attachBytes(res, conv.output.download_url, cfg);
+  return res;
+}
+async function attachBytes(res, url, cfg) {
+  try {
+    const buf = await downloadToBuffer(url, cfg.maxInlineBytes, cfg.streamTimeoutMs);
+    res.output_base64 = buf.toString("base64");
+    res.bytes = buf.length;
+  } catch (e) {
+    if (e instanceof ToolError && e.code === "source_too_large") {
+      res.note = `output too large to inline as base64 (cap ${cfg.maxInlineBytes} bytes); use output_path or download_url instead`;
+    } else {
+      res.note = `could not inline output as base64 (${e instanceof Error ? e.message : String(e)}); use output_path or download_url instead`;
+    }
+    log("debug", "inline bytes skipped", { reason: e instanceof Error ? e.message : String(e) });
+  }
+}
+async function pollConversion(client, id, timeoutSeconds, cfg) {
+  const deadline = Date.now() + clampTimeout(timeoutSeconds ?? 120, cfg) * 1e3;
+  let delay = 1e3;
+  let last = null;
+  while (Date.now() < deadline) {
+    last = await client.getConversion(id);
+    if (TERMINAL.has(last.status)) return { conv: last, timedOut: false };
+    const jitter = Math.floor(Math.random() * 250);
+    await sleep(Math.min(delay, Math.max(0, deadline - Date.now())) + jitter);
+    delay = Math.min(5e3, Math.floor(delay * 1.5));
+  }
+  return { conv: last, timedOut: true };
+}
+function clampTimeout(seconds, cfg) {
+  return Math.max(1, Math.min(seconds, cfg.maxPollSeconds));
+}
+function pickPreset(entry, _sourceMime, _target, explicit, cfg) {
+  if (explicit) return explicit;
+  if (cfg.defaultPreset && entry && findPreset(entry, cfg.defaultPreset)) return cfg.defaultPreset;
+  if (entry && entry.presets.length > 0) return entry.presets[0].id;
+  return cfg.defaultPreset ?? "standard";
+}
+async function resolveSource(source, cfg) {
+  const provided = [source.path, source.url, source.bytes].filter((v) => v !== void 0 && v !== "");
+  if (provided.length !== 1) {
+    throw new ToolError("invalid_source", "Provide exactly one of source.path, source.url, or source.bytes.");
+  }
+  if (source.path) {
+    const abs = resolvePath(process.cwd(), source.path);
+    const st = await stat2(abs).catch(() => null);
+    if (!st || !st.isFile()) throw new ToolError("source_not_found", `No file at ${source.path}`);
+    const filename = source.filename ?? basename3(abs);
+    return { filePath: abs, size: st.size, filename, declaredMime: mimeFromFilename(filename), sourceWasLocalPath: true };
+  }
+  if (source.url) {
+    await assertPublicHttpUrl(source.url);
+    const buffer2 = await downloadToBuffer(source.url, cfg.maxDownloadUrlBytes, cfg.streamTimeoutMs, { noRedirect: true });
+    const filename = source.filename ?? filenameFromUrl(source.url);
+    return { buffer: buffer2, size: buffer2.length, filename, declaredMime: mimeFromFilename(filename), sourceWasLocalPath: false };
+  }
+  if (!source.filename) throw new ToolError("invalid_source", "source.filename is required when supplying source.bytes (used to name the output and infer the type).");
+  const b64 = source.bytes.replace(/\s+/g, "");
+  if (b64.length === 0 || b64.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(b64)) {
+    throw new ToolError("invalid_source", "source.bytes is not valid base64.");
+  }
+  const buffer = Buffer.from(b64, "base64");
+  if (buffer.length === 0) throw new ToolError("invalid_source", "source.bytes decoded to 0 bytes.");
+  return { buffer, size: buffer.length, filename: source.filename, declaredMime: mimeFromFilename(source.filename), sourceWasLocalPath: false };
+}
+function describeSource(src) {
+  return src.filePath ?? src.filename;
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, Math.max(0, ms)));
+}
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const i = next++;
+      out[i] = await fn(items[i], i);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
+  return out;
+}
+
+// src/tools/convert-file.ts
+function registerConvertFile(server, ctx) {
+  server.registerTool(
+    "convert_file",
+    {
+      title: "Convert a file",
+      description: 'Convert ONE file end-to-end and get the result back in a single call \u2014 the primary, do-everything tool. Supply the file as a local path (default), an http(s) URL, or base64 bytes; FileForge runs upload \u2192 virus-scan \u2192 convert \u2192 download internally so you never touch the REST flow. Use list_formats first if unsure which target_format/preset/options are valid. On a slow conversion that outlasts the wait, this returns status "processing" with a conversion_id you can resume via get_conversion_status (no re-upload).',
+      inputSchema: {
+        source: sourceShape,
+        target_format: z3.string().describe("Target format slug, e.g. 'jpg', 'webp', 'mp3', 'pdf', 'ico'."),
+        preset: z3.string().optional().describe("Preset id (e.g. 'web','high','standard'). Defaults to the first preset for the pair."),
+        options: optionsShape.optional(),
+        preserve_metadata: z3.boolean().optional().describe("Keep EXIF/ID3 metadata (Forge Pro; default false)."),
+        output: outputShape.optional(),
+        timeout_seconds: z3.number().optional().describe("Max seconds to wait for completion (default 120; capped by the server).")
+      }
+    },
+    async (args) => runTool(
+      () => convertOne(ctx.client, ctx.config, {
+        source: args.source,
+        target_format: args.target_format,
+        preset: args.preset,
+        options: args.options,
+        preserve_metadata: args.preserve_metadata,
+        output: args.output,
+        timeout_seconds: args.timeout_seconds
+      })
+    )
+  );
+}
+
+// src/tools/get-conversion-status.ts
+import { z as z4 } from "zod";
+function registerGetConversionStatus(server, ctx) {
+  server.registerTool(
+    "get_conversion_status",
+    {
+      title: "Get conversion status",
+      description: 'Check a conversion you already started \u2014 use it when convert_file returned status "processing" because the job outlasted the wait, or to re-fetch a completed result whose download URL expired (~5 min). Returns progress and, when finished, a fresh download URL or writes the output to a path you choose. Lets a long job survive across turns without re-uploading.',
+      inputSchema: {
+        conversion_id: z4.string().describe("The conversion id from a prior convert_file / convert_files call."),
+        output: outputShape.optional().describe("When provided and the job is complete, download the result (stdio) or inline it.")
+      }
+    },
+    async (args) => runTool(() => fetchStatus(ctx.client, ctx.config, args.conversion_id, args.output))
+  );
+}
+
+// src/tools/convert-files.ts
+import { z as z5 } from "zod";
+function registerConvertFiles(server, ctx) {
+  server.registerTool(
+    "convert_files",
+    {
+      title: "Convert many files (bulk)",
+      description: "Convert MANY files in one call (Forge Pro \u2014 the Free tier bulk limit is 1). Each item gets its own target/preset/options. Files are uploaded, submitted as a single bulk job, polled together, and downloaded. Use this instead of looping convert_file when you have several files. If your key is not Pro, this surfaces the Pro requirement instead of silently falling back.",
+      inputSchema: {
+        items: z5.array(
+          z5.object({
+            source: sourceShape,
+            target_format: z5.string(),
+            preset: z5.string().optional(),
+            options: optionsShape.optional(),
+            preserve_metadata: z5.boolean().optional(),
+            output: z5.object({ path: z5.string().optional() }).optional()
+          })
+        ).min(1).describe("1..tier.bulk_max items (Free 1, Pro 20)."),
+        output_dir: z5.string().optional().describe("Base directory for item outputs that omit their own path (stdio)."),
+        overwrite: z5.boolean().optional().describe("Overwrite existing outputs (default false)."),
+        timeout_seconds: z5.number().optional().describe("Max seconds to wait for the whole batch (default 600; capped).")
+      }
+    },
+    async (args) => runTool(
+      () => convertMany(
+        ctx.client,
+        ctx.config,
+        args.items.map((it) => ({
+          source: it.source,
+          target_format: it.target_format,
+          preset: it.preset,
+          options: it.options,
+          preserve_metadata: it.preserve_metadata,
+          output: it.output
+        })),
+        { timeout_seconds: args.timeout_seconds, outputDir: args.output_dir, overwrite: args.overwrite }
+      )
+    )
+  );
+}
+
+// src/server.ts
+var SERVER_NAME = "fileforge";
+var SERVER_VERSION = "2.2.0";
+function buildServer(ctx) {
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+  registerListFormats(server, ctx);
+  registerConvertFile(server, ctx);
+  registerGetConversionStatus(server, ctx);
+  registerConvertFiles(server, ctx);
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  let config;
+  try {
+    config = loadConfig();
+  } catch (e) {
+    const msg = e instanceof ConfigError ? e.message : e instanceof Error ? e.message : String(e);
+    process.stderr.write(`[fileforge-mcp] config error: ${msg}
+`);
+    process.exit(1);
+  }
+  setLogLevel(config.logLevel);
+  const client = new FileForgeClient(config);
+  const server = buildServer({ client, config });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log("info", `fileforge-mcp v${SERVER_VERSION} ready on stdio`, { baseUrl: config.baseUrl });
+}
+main().catch((e) => {
+  process.stderr.write(`[fileforge-mcp] fatal: ${e?.stack ?? e}
+`);
+  process.exit(1);
+});