@getwebp/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @getwebp/mcp-server
+
+MCP server for GetWebP — lets AI agents convert images to WebP directly from your editor or chat.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `convert_images` | Convert images (JPEG, PNG, BMP) to WebP with configurable quality |
+| `scan_images` | Scan a directory for convertible images and report potential savings |
+| `get_status` | Check license status, usage limits, and remaining quota |
+
+## Setup
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "getwebp": {
+      "command": "npx",
+      "args": ["-y", "@getwebp/mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add getwebp -- npx -y @getwebp/mcp-server
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "getwebp": {
+      "command": "npx",
+      "args": ["-y", "@getwebp/mcp-server"]
+    }
+  }
+}
+```
+
+### Windsurf / Other MCP Clients
+
+Use stdio transport with:
+- **Command:** `npx`
+- **Args:** `["-y", "@getwebp/mcp-server"]`
+
+## Free vs Pro
+
+| | Free | Pro |
+|---|---|---|
+| Conversions | 10 images / day | Unlimited |
+| Max file size | 5 MB | 50 MB |
+| Quality presets | Default only | Full control |
+
+## License Activation
+
+Activate your Pro license before starting the MCP server:
+
+```bash
+npx @getwebp/cli auth <your-license-key>
+```
+
+The MCP server reads the same local credential store as the CLI — no additional configuration needed.
+
+## License
+
+Proprietary. See [getwebp.com](https://getwebp.com) for details.

package/dist/index.js

@@ -0,0 +1,841 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// ../cli/src/utils/debug.ts
+var _debug = false;
+var _sink = (msg) => process.stderr.write(msg);
+function setDebugSink(sink) {
+  _sink = sink;
+}
+function debugLog(...args) {
+  if (_debug) _sink("[debug] " + args.join(" ") + "\n");
+}
+
+// src/tools/convert-images.ts
+import path6 from "node:path";
+import { z } from "zod";
+
+// ../cli/src/core/license.ts
+import jwt from "jsonwebtoken";
+
+// ../cli/src/core/config.ts
+import Conf from "conf";
+import crypto2 from "node:crypto";
+import { unlinkSync } from "node:fs";
+import os2 from "node:os";
+import path from "node:path";
+
+// ../cli/src/core/machine-id.ts
+import { execSync, exec } from "node:child_process";
+import crypto from "node:crypto";
+import os from "node:os";
+function getRawId() {
+  const platform = process.platform;
+  try {
+    if (platform === "darwin") {
+      const out = execSync("ioreg -rd1 -c IOPlatformExpertDevice", { encoding: "utf8" });
+      const match = out.match(/IOPlatformUUID[^=]+=\s*"([^"]+)"/);
+      if (match) return match[1].toLowerCase();
+    } else if (platform === "linux") {
+      const out = execSync("( cat /var/lib/dbus/machine-id /etc/machine-id 2>/dev/null || hostname ) | head -n 1", {
+        encoding: "utf8",
+        shell: "/bin/sh"
+      });
+      return out.trim();
+    } else if (platform === "win32") {
+      const out = execSync(
+        "REG QUERY HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Cryptography /v MachineGuid",
+        { encoding: "utf8" }
+      );
+      const match = out.match(/MachineGuid\s+REG_SZ\s+([^\r\n]+)/);
+      if (match) return match[1].trim();
+    }
+  } catch {
+  }
+  return `${os.hostname()}:${os.userInfo().username}`;
+}
+function hashId(raw) {
+  return crypto.createHash("sha256").update(raw).digest("hex");
+}
+function machineIdSync() {
+  return hashId(getRawId());
+}
+
+// ../cli/src/core/config.ts
+function getMachineKey() {
+  try {
+    const id = machineIdSync();
+    return crypto2.createHash("sha256").update(id).digest("hex");
+  } catch {
+    debugLog(
+      "warn: Could not read machine ID, falling back to hostname.",
+      "Token may become invalid if hostname changes."
+    );
+    return crypto2.createHash("sha256").update(`${os2.hostname()}:${os2.userInfo().username}`).digest("hex");
+  }
+}
+var _store = null;
+function getStore() {
+  if (!_store) {
+    const confOpts = {
+      projectName: "getwebp",
+      encryptionKey: getMachineKey(),
+      ...process.env.GETWEBP_CONFIG_DIR ? { cwd: process.env.GETWEBP_CONFIG_DIR } : {}
+    };
+    try {
+      _store = new Conf(confOpts);
+    } catch {
+      debugLog("warn: Corrupt config file detected, clearing and reinitialising.");
+      const configDir = process.env.GETWEBP_CONFIG_DIR ?? (process.platform === "darwin" ? path.join(os2.homedir(), "Library", "Preferences", "getwebp-nodejs") : path.join(os2.homedir(), ".config", "getwebp"));
+      try {
+        unlinkSync(path.join(configDir, "config.json"));
+      } catch {
+      }
+      _store = new Conf(confOpts);
+    }
+  }
+  return _store;
+}
+function getConfig() {
+  return getStore().store;
+}
+function saveConfig(data) {
+  const store = getStore();
+  for (const [key, value] of Object.entries(data)) {
+    if (value === void 0) {
+      store.delete(key);
+    } else {
+      store.set(key, value);
+    }
+  }
+}
+
+// ../cli/src/core/constants.ts
+import os3 from "node:os";
+var FREE_TIER = {
+  FILE_LIMIT: 20,
+  DELAY_MS: 3e3
+};
+var DEFAULTS = {
+  QUALITY: 80,
+  CONCURRENCY: Math.max(1, os3.cpus().length - 1)
+};
+var AUTO_QUALITY_SENTINEL = -1;
+var NETWORK = {
+  HEARTBEAT_TIMEOUT_MS: 3e3,
+  API_TIMEOUT_MS: 5e3,
+  DRAIN_TIMEOUT_MS: 3e3
+};
+
+// ../cli/src/core/heartbeat.ts
+var _promise = null;
+var API_BASE_URL = process.env.API_BASE_URL ?? "https://api.getwebp.com";
+function pingHeartbeat(token) {
+  const p = fetch(`${API_BASE_URL}/v1/ping`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}` },
+    signal: AbortSignal.timeout(NETWORK.HEARTBEAT_TIMEOUT_MS)
+  }).then(async (res) => {
+    if (res.status === 401 || res.status === 403) {
+      try {
+        saveConfig({ token: void 0 });
+      } catch {
+      }
+    }
+  }).catch(() => {
+  }).finally(() => {
+    if (_promise === p) _promise = null;
+  });
+  _promise = p;
+}
+
+// ../cli/src/core/license.ts
+var API_BASE_URL2 = process.env.API_BASE_URL ?? "https://api.getwebp.com";
+function getPublicKey() {
+  const key = "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAz41vwWfBT+qVpqXGz7sL\nzev2A4XL6Kp62fYM1vgzUUvZMfmKY9tMa2FYgasmh+l/J+5wa310ZZV9kp4cxhKc\nGC+lgTTL/sfauyzEjtY3ZDsYON0LOA6TPGYwIppsnmgYT5PS8lIsDL1gTaaskfoy\nTz3blsLS73DX6duqJxXLZxUlXrq9OdjQj9C8OYovNXgXDCc6miexDo70TCi0oHQq\n0tpKTngmAoGsGodK+7d2Etan5n8JjCQ6LnF+g8la1k1gwcyLLaTrK3cy3fGP4gAL\nDdmkyd8ELpUrebBTRtpE9Fyk979Qs4gwghx6ecpRgd3WT354/414s6K4OsElyTyT\npwIDAQAB\n-----END PUBLIC KEY-----\n";
+  if (!key) throw new Error("JWT_PUBLIC_KEY was not injected at build time");
+  return key;
+}
+async function checkLicense(warn) {
+  const config = getConfig();
+  if (!config?.token) return { valid: false, plan: "free" };
+  try {
+    const payload = verifyToken(config.token);
+    pingHeartbeat(config.token);
+    const exp = typeof payload === "object" && payload !== null && "exp" in payload ? payload.exp : void 0;
+    const rawPlan = typeof payload === "object" && payload !== null && "plan" in payload ? String(payload.plan) : "pro";
+    const plan = rawPlan === "starter" ? "starter" : "pro";
+    return {
+      valid: true,
+      plan,
+      expiresAt: exp ? new Date(exp * 1e3) : void 0
+    };
+  } catch (err) {
+    if (err instanceof Error && err.name === "TokenExpiredError") {
+      return { valid: false, plan: "free", expired: true };
+    }
+    if (err instanceof Error && err.message.includes("JWT_PUBLIC_KEY")) {
+      const w = warn ?? ((msg) => process.stderr.write(msg + "\n"));
+      w("warn: JWT public key not found. License validation skipped.");
+    }
+    return { valid: false, plan: "free" };
+  }
+}
+function verifyToken(token) {
+  return jwt.verify(token, getPublicKey(), { algorithms: ["RS256"] });
+}
+
+// ../cli/src/core/processor.ts
+import { encode as encodeWebp, decode as decodeWebp2 } from "@jsquash/webp";
+import { unlinkSync as unlinkSync2, constants as fsConstants } from "node:fs";
+import fs3 from "node:fs/promises";
+import path4 from "node:path";
+import pLimit from "p-limit";
+import { applySizeGuard } from "@getwebp/core/size-guard";
+import { findOptimalQuality } from "@getwebp/core/auto-quality";
+
+// ../cli/src/core/codecs.ts
+import { decode as decodeJpeg } from "@jsquash/jpeg";
+import { decode as decodePng } from "@jsquash/png";
+import { decode as decodeWebp } from "@jsquash/webp";
+import { decode as decodeAvifWasm } from "@jsquash/avif";
+import Bmp from "bmp-js";
+import fs from "node:fs/promises";
+import path2 from "node:path";
+async function decodeHeic(buffer) {
+  const heicDecode = (await import("heic-decode")).default;
+  const { width, height, data } = await heicDecode({ buffer: new Uint8Array(buffer) });
+  return new ImageData(
+    new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength),
+    width,
+    height
+  );
+}
+var decoders = {
+  ".jpg": decodeJpeg,
+  ".jpeg": decodeJpeg,
+  ".png": decodePng,
+  ".webp": decodeWebp,
+  ".avif": async (buf) => {
+    const result = await decodeAvifWasm(buf);
+    if (!result) throw new Error("AVIF decode returned null");
+    return result;
+  },
+  ".heic": decodeHeic,
+  ".heif": decodeHeic
+};
+var MAGIC_VALIDATORS = {
+  ".jpg": (b) => b[0] === 255 && b[1] === 216 && b[2] === 255,
+  ".jpeg": (b) => b[0] === 255 && b[1] === 216 && b[2] === 255,
+  ".png": (b) => b[0] === 137 && b[1] === 80 && b[2] === 78 && b[3] === 71,
+  ".webp": (b) => b.length > 11 && b[8] === 87 && b[9] === 69 && b[10] === 66 && b[11] === 80,
+  ".heic": (b) => b.length > 11 && b[4] === 102 && b[5] === 116 && b[6] === 121 && b[7] === 112 && (b[8] === 104 && b[9] === 101 && b[10] === 105 && b[11] === 99 || // "heic"
+  b[8] === 104 && b[9] === 101 && b[10] === 105 && b[11] === 102 || // "heif"
+  b[8] === 109 && b[9] === 105 && b[10] === 102 && b[11] === 49),
+  ".heif": (b) => b.length > 11 && b[4] === 102 && b[5] === 116 && b[6] === 121 && b[7] === 112 && (b[8] === 104 && b[9] === 101 && b[10] === 105 && b[11] === 99 || b[8] === 104 && b[9] === 101 && b[10] === 105 && b[11] === 102 || b[8] === 109 && b[9] === 105 && b[10] === 102 && b[11] === 49),
+  ".avif": (b) => b.length > 11 && b[4] === 102 && b[5] === 116 && b[6] === 121 && b[7] === 112 && (b[8] === 97 && b[9] === 118 && b[10] === 105 && b[11] === 102 || // "avif"
+  b[8] === 97 && b[9] === 118 && b[10] === 105 && b[11] === 115),
+  ".bmp": (b) => b[0] === 66 && b[1] === 77
+};
+var BMP_MAX_DIMENSION = 65535;
+async function decodeBmp(buffer) {
+  if (buffer.byteLength < 54) {
+    throw new Error("BMP file too small to contain a valid header");
+  }
+  const bmpWidth = buffer.readUInt32LE(18);
+  const bmpHeight = Math.abs(buffer.readInt32LE(22));
+  if (bmpWidth === 0 || bmpHeight === 0 || bmpWidth > BMP_MAX_DIMENSION || bmpHeight > BMP_MAX_DIMENSION) {
+    throw new Error(`BMP dimensions out of range: ${bmpWidth}x${bmpHeight}`);
+  }
+  const bmp = Bmp.decode(buffer);
+  const data = bmp.data;
+  for (let i = 0; i < data.length; i += 4) {
+    const tmp = data[i];
+    data[i] = data[i + 2];
+    data[i + 2] = tmp;
+  }
+  return new ImageData(new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength), bmp.width, bmp.height);
+}
+async function decodeImage(filePath) {
+  const ext = path2.extname(filePath).toLowerCase();
+  const buffer = await fs.readFile(filePath);
+  if (buffer.byteLength === 0) {
+    throw new Error(`File is empty (0 bytes): ${filePath}`);
+  }
+  const validate = MAGIC_VALIDATORS[ext];
+  if (validate && !validate(buffer)) {
+    throw new Error(`File header does not match expected ${ext} format: ${filePath}`);
+  }
+  debugLog("decode", ext, filePath);
+  if (ext === ".bmp") {
+    try {
+      return await decodeBmp(buffer);
+    } catch (err) {
+      throw new Error(`Failed to decode ${filePath} as BMP: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const decoder = decoders[ext];
+  if (!decoder) {
+    throw new Error(`Unsupported format: ${ext}`);
+  }
+  const arrayBuffer = buffer.byteOffset === 0 && buffer.byteLength === buffer.buffer.byteLength ? buffer.buffer : buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+  try {
+    return await decoder(arrayBuffer);
+  } catch (err) {
+    throw new Error(`Failed to decode ${filePath} as ${ext}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+// ../cli/src/core/file-scanner.ts
+import fs2 from "node:fs/promises";
+import path3 from "node:path";
+var IMAGE_EXTS = /* @__PURE__ */ new Set([".jpg", ".jpeg", ".png", ".bmp", ".webp", ".heic", ".heif", ".avif"]);
+var defaultWarn = (msg) => process.stderr.write(msg + "\n");
+async function collectImageFiles(input, recursive, warn = defaultWarn) {
+  const lstat = await fs2.lstat(input);
+  if (lstat.isSymbolicLink()) {
+    warn(`Warning: ${input} is a symlink, skipping`);
+    return [];
+  }
+  if (lstat.isFile()) return [input];
+  let entries;
+  try {
+    entries = await fs2.readdir(input, { withFileTypes: true });
+  } catch {
+    warn(`Warning: cannot read directory ${input}, skipping`);
+    return [];
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  const results = [];
+  const subdirPromises = [];
+  for (const entry of entries) {
+    const fullPath = path3.join(input, entry.name);
+    if (entry.isDirectory() && recursive && !entry.isSymbolicLink()) {
+      subdirPromises.push(collectImageFiles(fullPath, recursive, warn));
+    } else if (entry.isFile() && !entry.isSymbolicLink() && IMAGE_EXTS.has(path3.extname(entry.name).toLowerCase())) {
+      results.push(fullPath);
+    }
+  }
+  const subResults = await Promise.all(subdirPromises);
+  results.push(...subResults.flat());
+  return results.sort();
+}
+
+// ../cli/src/core/wasm-init.ts
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { init as initPngCodec } from "@jsquash/png/decode.js";
+import { init as initJpegDec } from "@jsquash/jpeg/decode.js";
+import { init as initWebpDec } from "@jsquash/webp/decode.js";
+import { init as initWebpEnc } from "@jsquash/webp/encode.js";
+import { init as initAvifDec } from "@jsquash/avif/decode.js";
+var _require = createRequire(import.meta.url);
+var initialized = false;
+async function initWasm() {
+  if (initialized) return;
+  initialized = true;
+  const pngWasm = new WebAssembly.Module(readFileSync(_require.resolve("@jsquash/png/codec/pkg/squoosh_png_bg.wasm")));
+  await initPngCodec(pngWasm);
+  const jpegWasm = new WebAssembly.Module(readFileSync(_require.resolve("@jsquash/jpeg/codec/dec/mozjpeg_dec.wasm")));
+  await initJpegDec(jpegWasm);
+  const webpDecWasm = new WebAssembly.Module(readFileSync(_require.resolve("@jsquash/webp/codec/dec/webp_dec.wasm")));
+  await initWebpDec(webpDecWasm);
+  const webpEncWasm = new WebAssembly.Module(readFileSync(_require.resolve("@jsquash/webp/codec/enc/webp_enc.wasm")));
+  await initWebpEnc(webpEncWasm);
+  const avifDecWasm = new WebAssembly.Module(readFileSync(_require.resolve("@jsquash/avif/codec/dec/avif_dec.wasm")));
+  await initAvifDec(avifDecWasm);
+}
+
+// ../cli/src/core/processor.ts
+var HEIC_AVIF_EXTS = /* @__PURE__ */ new Set([".heic", ".heif", ".avif"]);
+function isHeicOrAvif(filePath) {
+  return HEIC_AVIF_EXTS.has(path4.extname(filePath).toLowerCase());
+}
+async function processImages(options) {
+  const { input, output, quality, plan, out } = options;
+  const isFree = plan === "free";
+  const dryRun = options.dryRun ?? false;
+  const skipExisting = options.skipExisting ?? false;
+  debugLog("processImages", input, {
+    plan,
+    concurrency: options.concurrency,
+    recursive: options.recursive,
+    dryRun,
+    skipExisting
+  });
+  try {
+    await fs3.access(input);
+  } catch {
+    throw new Error(`Path not found: ${input}`);
+  }
+  await initWasm();
+  const recursive = options.recursive ?? false;
+  const files = await collectImageFiles(input, recursive, (msg) => out.warn(msg));
+  debugLog("collected", files.length, "files");
+  if (isFree && files.length > 0) {
+    out.warn("Free plan: max 20 files, 3s delay between each.");
+    out.warn("Upgrade at getwebp.com/pricing, then run: getwebp auth <your-key>");
+  }
+  const targets = isFree ? files.slice(0, FREE_TIER.FILE_LIMIT) : files;
+  const skipped = isFree ? Math.max(0, files.length - FREE_TIER.FILE_LIMIT) : 0;
+  const outputPaths = /* @__PURE__ */ new Map();
+  for (const file of targets) {
+    const dir = output ?? path4.dirname(file);
+    const outName = path4.basename(file, path4.extname(file)) + ".webp";
+    const outPath = path4.resolve(dir, outName);
+    const existing = outputPaths.get(outPath) ?? [];
+    existing.push(file);
+    outputPaths.set(outPath, existing);
+  }
+  for (const [outPath, sources] of outputPaths) {
+    if (sources.length > 1) {
+      out.warn(`Conflict: ${sources.join(", ")} all map to ${path4.basename(outPath)} \u2014 only the last processed will survive`);
+    }
+  }
+  if (!output && !dryRun) {
+    out.warn("No --output specified: converted files will be written next to source files.");
+  }
+  if (dryRun) {
+    const webpCount = targets.filter((f) => path4.extname(f).toLowerCase() === ".webp").length;
+    const nonWebpCount = targets.length - webpCount;
+    out.warn("Dry run \u2014 no files will be converted:");
+    for (const file of targets) {
+      out.warn(`  would convert: ${file}`);
+    }
+    out.warn(`Would process ${nonWebpCount} file(s) (${webpCount} already .webp, skipped)`);
+    return { results: [], skippedByLimit: 0 };
+  }
+  if (output) {
+    await fs3.mkdir(output, { recursive: true });
+    await fs3.access(output, fsConstants.W_OK);
+  }
+  const results = [];
+  const writingFiles = /* @__PURE__ */ new Set();
+  const shouldRegisterSigint = options.registerSigint ?? true;
+  const sigintHandler = () => {
+    for (const f of writingFiles) {
+      try {
+        unlinkSync2(f);
+      } catch {
+      }
+    }
+    out.warn(`Interrupted. ${results.length} file(s) completed, ${writingFiles.size} in-progress cleaned up.`);
+    process.exit(130);
+  };
+  if (shouldRegisterSigint) process.once("SIGINT", sigintHandler);
+  try {
+    if (isFree) {
+      for (let i = 0; i < targets.length; i++) {
+        const file = targets[i];
+        if (i === 1) {
+          out.warn("\u23F1 3s cooldown (Starter/Pro: instant) \u2014 getwebp.com/pricing");
+          await sleep(FREE_TIER.DELAY_MS);
+        } else if (i > 1) {
+          out.warn("\u23F1 3s...");
+          await sleep(FREE_TIER.DELAY_MS);
+        }
+        debugLog("converting", file);
+        const result = await convertFile(file, output ?? path4.dirname(file), quality, out, skipExisting, writingFiles);
+        debugLog("done", file, result.status);
+        results.push(result);
+      }
+    } else {
+      const MAX_CONCURRENCY = 32;
+      const rawConcurrency = Number(options.concurrency ?? DEFAULTS.CONCURRENCY);
+      const concurrency = Number.isNaN(rawConcurrency) || rawConcurrency < 1 ? DEFAULTS.CONCURRENCY : Math.min(Math.floor(rawConcurrency), MAX_CONCURRENCY);
+      const hasHeicOrAvif = targets.some(isHeicOrAvif);
+      const effectiveConcurrency = hasHeicOrAvif ? 1 : concurrency;
+      const limit = pLimit(effectiveConcurrency);
+      const uniqueDirs = new Set(targets.map((file) => output ?? path4.dirname(file)));
+      await Promise.all([...uniqueDirs].map((dir) => fs3.mkdir(dir, { recursive: true })));
+      const tasks = targets.map((file) => {
+        const outputDir = output ?? path4.dirname(file);
+        return limit(async () => {
+          debugLog("converting", file);
+          const result = await convertFile(file, outputDir, quality, out, skipExisting, writingFiles);
+          debugLog("done", file, result.status);
+          return result;
+        });
+      });
+      results.push(...await Promise.all(tasks));
+    }
+  } finally {
+    if (shouldRegisterSigint) process.removeListener("SIGINT", sigintHandler);
+  }
+  out.summary(results, { skipped, totalFound: files.length, plan });
+  return { results, skippedByLimit: skipped };
+}
+async function convertFile(filePath, outputDir, quality, out, skipExisting, writingFiles) {
+  const outName = path4.basename(filePath, path4.extname(filePath)) + ".webp";
+  const outPath = path4.join(outputDir, outName);
+  if (path4.extname(filePath).toLowerCase() === ".webp" && path4.normalize(outPath) === path4.normalize(filePath)) {
+    return { file: filePath, status: "skipped", reason: "existing" };
+  }
+  if (skipExisting) {
+    try {
+      await fs3.access(outPath);
+      return { file: filePath, status: "skipped", reason: "existing" };
+    } catch {
+    }
+  }
+  const spinner = out.startFile(filePath);
+  try {
+    const inputStat = await fs3.stat(filePath);
+    let imageData;
+    try {
+      imageData = await decodeImage(filePath);
+    } catch (err) {
+      spinner.fail();
+      const msg = err instanceof Error ? err.message : String(err);
+      return { file: filePath, status: "error", error: `Decode failed: ${msg}` };
+    }
+    let webpBuffer;
+    let finalQuality;
+    let qualityMode;
+    let ssimScore;
+    try {
+      if (quality === AUTO_QUALITY_SENTINEL) {
+        const codec = {
+          encode: (img, q) => encodeWebp(img, { quality: q }),
+          decode: (buf) => decodeWebp2(buf)
+        };
+        const result = await findOptimalQuality(imageData, inputStat.size, codec);
+        finalQuality = result.quality;
+        ssimScore = result.ssim;
+        qualityMode = "auto";
+        webpBuffer = result.buffer ?? await encodeWebp(imageData, { quality: finalQuality });
+      } else {
+        finalQuality = quality;
+        qualityMode = "fixed";
+        webpBuffer = await encodeWebp(imageData, { quality });
+      }
+    } catch (err) {
+      spinner.fail();
+      const msg = err instanceof Error ? err.message : String(err);
+      return { file: filePath, status: "error", error: `Encode failed: ${msg}` };
+    }
+    const originalBuffer = (await fs3.readFile(filePath)).buffer;
+    const isWebP = path4.extname(filePath).toLowerCase() === ".webp";
+    const guard = applySizeGuard({ originalBuffer, encodedBuffer: webpBuffer, isWebP });
+    const finalBuffer = guard.buffer;
+    const tmpPath = outPath + ".tmp";
+    if (process.platform === "win32" && tmpPath.length >= 260) {
+      spinner.fail();
+      return { file: filePath, status: "error", error: `Output path too long for Windows (${tmpPath.length} chars, max 260). Use a shorter output directory or enable LongPathsEnabled in Windows registry.` };
+    }
+    writingFiles.add(tmpPath);
+    await fs3.writeFile(tmpPath, new Uint8Array(finalBuffer));
+    await fs3.rename(tmpPath, outPath);
+    writingFiles.delete(tmpPath);
+    const newSize = finalBuffer.byteLength;
+    const savedRatio = 1 - newSize / inputStat.size;
+    spinner.succeed({ quality: finalQuality, qualityMode });
+    return {
+      file: filePath,
+      originalSize: inputStat.size,
+      newSize,
+      savedRatio,
+      quality: finalQuality,
+      qualityMode,
+      ssim: ssimScore,
+      status: "success"
+    };
+  } catch (err) {
+    writingFiles.delete(outPath + ".tmp");
+    spinner.fail();
+    const msg = err instanceof Error ? err.message : String(err);
+    return { file: filePath, status: "error", error: `Write failed: ${msg}` };
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/adapters/collector-output.ts
+var CollectorOutput = class {
+  warnings = [];
+  startFile(_file) {
+    return { succeed() {
+    }, fail() {
+    } };
+  }
+  warn(msg) {
+    this.warnings.push(msg);
+  }
+  summary(_results, _meta) {
+  }
+};
+
+// src/utils/tarpit-check.ts
+import fs4 from "node:fs";
+import path5 from "node:path";
+import os4 from "node:os";
+var USAGE_FILE = path5.join(os4.homedir(), ".getwebp", "usage.json");
+var WINDOW_MS = 6e4;
+var FREE_CALLS = 3;
+var TARPIT_DELAYS = [10, 20, 30];
+function readUsage() {
+  try {
+    const raw = fs4.readFileSync(USAGE_FILE, "utf-8");
+    const data = JSON.parse(raw);
+    if (Array.isArray(data.timestamps)) {
+      return data;
+    }
+  } catch {
+  }
+  return { timestamps: [] };
+}
+function writeUsage(data) {
+  const dir = path5.dirname(USAGE_FILE);
+  fs4.mkdirSync(dir, { recursive: true });
+  fs4.writeFileSync(USAGE_FILE, JSON.stringify(data, null, 2));
+}
+function getDelay(recentCount) {
+  if (recentCount <= FREE_CALLS) return 0;
+  const delayIndex = Math.min(recentCount - FREE_CALLS - 1, TARPIT_DELAYS.length - 1);
+  return TARPIT_DELAYS[delayIndex];
+}
+function checkTarpit() {
+  const now = Date.now();
+  const usage = readUsage();
+  const cutoff = now - WINDOW_MS;
+  usage.timestamps = usage.timestamps.filter((t) => t > cutoff);
+  usage.timestamps.push(now);
+  const recentCount = usage.timestamps.length;
+  const delay = getDelay(recentCount);
+  writeUsage(usage);
+  if (delay > 0) {
+    return {
+      throttled: true,
+      delay_seconds: delay,
+      recent_calls: recentCount,
+      upgrade_url: "https://getwebp.com/pricing",
+      message: `Free plan rate limit reached. ${recentCount} calls in 60s, ${delay}s cooldown required. Upgrade to Pro for unlimited instant conversions.`
+    };
+  }
+  return { throttled: false };
+}
+function getTarpitStatus() {
+  const now = Date.now();
+  const usage = readUsage();
+  const cutoff = now - WINDOW_MS;
+  const recentCalls = usage.timestamps.filter((t) => t > cutoff).length;
+  const nextDelay = getDelay(recentCalls + 1);
+  return { recent_calls: recentCalls, next_delay_seconds: nextDelay };
+}
+
+// src/tools/convert-images.ts
+var convertImagesSchema = z.object({
+  input: z.string().describe("Input file or directory path. Supports JPEG, PNG, BMP, WebP, HEIC, HEIF, AVIF formats."),
+  output: z.string().optional().describe("Output directory (default: write .webp next to source files)"),
+  quality: z.number().min(1).max(100).optional().default(80).describe("WebP quality 1-100 (default: 80)"),
+  recursive: z.boolean().optional().default(false).describe("Recursively process subdirectories"),
+  skip_existing: z.boolean().optional().default(false).describe("Skip files that already have a .webp version")
+});
+async function convertImages(params) {
+  const inputPath = path6.resolve(params.input);
+  const outputPath = params.output ? path6.resolve(params.output) : void 0;
+  const license = await checkLicense();
+  if (license.plan === "free") {
+    const tarpit = checkTarpit();
+    if (tarpit.throttled) {
+      return {
+        success: false,
+        error: "rate_limited",
+        plan: "free",
+        delay_seconds: tarpit.delay_seconds,
+        recent_calls: tarpit.recent_calls,
+        upgrade_url: tarpit.upgrade_url,
+        message: tarpit.message,
+        total: 0,
+        succeeded: 0,
+        failed: 0,
+        skipped: 0,
+        warnings: [],
+        results: []
+      };
+    }
+  }
+  const out = new CollectorOutput();
+  const fileResults = await processImages({
+    input: inputPath,
+    output: outputPath,
+    quality: params.quality,
+    plan: license.plan,
+    out,
+    recursive: params.recursive,
+    skipExisting: params.skip_existing,
+    registerSigint: false
+  });
+  const succeeded = fileResults.filter((r) => r.status === "success").length;
+  const failed = fileResults.filter((r) => r.status === "error").length;
+  const skipped = fileResults.filter((r) => r.status === "skipped").length;
+  const isFree = license.plan === "free";
+  const results = fileResults.map((r) => {
+    if (r.status === "success") {
+      return {
+        file: r.file,
+        status: "success",
+        original_size: r.originalSize,
+        new_size: r.newSize,
+        saved_ratio: r.savedRatio
+      };
+    }
+    if (r.status === "error") {
+      return { file: r.file, status: "error", error: r.error };
+    }
+    return { file: r.file, status: "skipped", reason: r.reason };
+  });
+  return {
+    success: failed === 0,
+    plan: license.plan,
+    total: fileResults.length,
+    succeeded,
+    failed,
+    skipped,
+    ...isFree && fileResults.length > 0 ? { upgrade_url: "https://getwebp.com/pricing" } : {},
+    warnings: out.warnings,
+    results
+  };
+}
+
+// src/tools/scan-images.ts
+import fs5 from "node:fs/promises";
+import path7 from "node:path";
+import { z as z2 } from "zod";
+var scanImagesSchema = z2.object({
+  path: z2.string().describe("Directory or file path to scan. Discovers JPEG, PNG, BMP, WebP, HEIC, HEIF, AVIF formats."),
+  recursive: z2.boolean().optional().default(false).describe("Recursively scan subdirectories")
+});
+function normalizeFormat(ext) {
+  if (ext === ".jpeg") return "jpg";
+  return ext.slice(1);
+}
+async function hasWebpSibling(filePath) {
+  const dir = path7.dirname(filePath);
+  const base = path7.basename(filePath, path7.extname(filePath));
+  const webpPath = path7.join(dir, base + ".webp");
+  try {
+    await fs5.access(webpPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function scanImages(params) {
+  const targetPath = path7.resolve(params.path);
+  const warnings = [];
+  const files = await collectImageFiles(targetPath, params.recursive, (msg) => warnings.push(msg));
+  const results = await Promise.all(
+    files.map(async (filePath) => {
+      const stat = await fs5.stat(filePath);
+      const ext = path7.extname(filePath).toLowerCase();
+      return {
+        path: filePath,
+        size: stat.size,
+        format: normalizeFormat(ext),
+        has_webp: ext === ".webp" ? true : await hasWebpSibling(filePath)
+      };
+    })
+  );
+  return {
+    total: results.length,
+    files: results
+  };
+}
+
+// src/tools/get-status.ts
+async function getStatus() {
+  const license = await checkLicense();
+  const isFree = license.plan === "free";
+  const tarpit = getTarpitStatus();
+  return {
+    activated: license.valid,
+    expired: license.expired ?? false,
+    plan: license.plan,
+    expires_at: license.expiresAt?.toISOString(),
+    limits: {
+      max_files_per_run: isFree ? FREE_TIER.FILE_LIMIT : null,
+      concurrent_workers: isFree ? 1 : DEFAULTS.CONCURRENCY,
+      cooldown_seconds: isFree ? FREE_TIER.DELAY_MS / 1e3 : 0
+    },
+    tarpit_recent_calls: tarpit.recent_calls,
+    tarpit_next_delay_seconds: tarpit.next_delay_seconds
+  };
+}
+
+// src/index.ts
+if (typeof globalThis.ImageData === "undefined") {
+  globalThis.ImageData = class ImageData {
+    data;
+    width;
+    height;
+    colorSpace = "srgb";
+    constructor(data, width, height) {
+      this.data = data;
+      this.width = width;
+      this.height = height ?? data.length / 4 / width;
+    }
+  };
+}
+setDebugSink(() => {
+});
+var server = new McpServer({
+  name: "getwebp",
+  version: "0.1.0"
+});
+server.tool(
+  "convert_images",
+  "Convert images (JPG, PNG, BMP, WebP) to optimized WebP format. Free plan: max 10 files per run with 3s delay between each (may take 30s+). Paid plans: unlimited files with parallel processing.",
+  {
+    input: convertImagesSchema.shape.input,
+    output: convertImagesSchema.shape.output,
+    quality: convertImagesSchema.shape.quality,
+    recursive: convertImagesSchema.shape.recursive,
+    skip_existing: convertImagesSchema.shape.skip_existing
+  },
+  async (params) => {
+    const result = await convertImages(params);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      isError: !result.success
+    };
+  }
+);
+server.tool(
+  "scan_images",
+  "Scan a directory for convertible image files (JPG, PNG, BMP, WebP). Returns file list with sizes, formats, and whether a .webp version already exists. Does not modify any files.",
+  {
+    path: scanImagesSchema.shape.path,
+    recursive: scanImagesSchema.shape.recursive
+  },
+  async (params) => {
+    const result = await scanImages(params);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_status",
+  "Check the current getwebp license status and plan limits. Returns activation state, plan tier, expiry date, and rate limits.",
+  {},
+  async () => {
+    const result = await getStatus();
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@getwebp/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for getwebp — convert images to WebP via AI agents",
+  "type": "module",
+  "bin": {
+    "getwebp-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "make build-mcp",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@jsquash/jpeg": "^1.5.0",
+    "@jsquash/png": "^3.1.0",
+    "@jsquash/webp": "^1.4.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "bmp-js": "^0.1.0",
+    "conf": "^13.0.0",
+    "jsonwebtoken": "^9.0.2",
+    "node-machine-id": "^1.1.12",
+    "p-limit": "^6.2.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.7",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.7.0"
+  }
+}