omrify-mcp 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# omrify-mcp
+
+An MCP server that lets an AI coding agent turn images on your machine into public URLs.
+
+```
+Agent ──stdio──> omrify-mcp ──reads──> C:\project\assets\hero.png
+                     │
+                     └──POST bytes──> Omrify Worker  /api/upload
+                                           │ Cloudflare Images → WebP
+                                           │ put → R2 bucket
+                                           └──> https://cdn.example.com/…/hero.webp
+```
+
+The MCP process only reads files and forwards bytes. Conversion and storage
+credentials live on the Worker, so no API key ever sits in an MCP config or in
+another project. Image bytes never pass through the model as base64.
+
+## Tools
+
+| Tool              | What it does                                                       |
+| ----------------- | ------------------------------------------------------------------ |
+| `upload_image`    | One local file → hosted URL                                        |
+| `upload_images`   | Files and/or directories (`recursive` optional) → one URL per image |
+| `upload_from_url` | Download a remote image, re-encode it, re-host it                   |
+| `recent_uploads`  | Look up links from earlier uploads instead of re-uploading          |
+
+All upload tools accept `format` (`webp` \| `png` \| `jpeg` \| `original`),
+`quality` (1–100) and `maxDimension` (longest edge in px, `0` keeps the original).
+
+---
+
+# For users
+
+You need the upload token from whoever runs the Worker. Then add this to your MCP config —
+`~/.claude.json` for every project, or `.mcp.json` in one project root:
+
+```json
+{
+  "mcpServers": {
+    "omrify": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "omrify-mcp"],
+      "env": {
+        "OMRIFY_ENDPOINT": "https://<the-worker>.workers.dev/api/upload",
+        "OMRIFY_TOKEN": "<your token>"
+      }
+    }
+  }
+}
+```
+
+Restart your editor — MCP servers connect at session start. In Claude Code, `/mcp`
+should list `omrify` as connected with four tools. Then just ask:
+
+> “Upload `assets/logo.png` and use it as the hero background.”
+
+> **Don't commit `.mcp.json`** if you put your token in it. `~/.claude.json` is the
+> safer home.
+
+## Environment
+
+| Variable                 | Default                            | Purpose                       |
+| ------------------------ | ---------------------------------- | ----------------------------- |
+| `OMRIFY_ENDPOINT`        | `http://localhost:8080/api/upload` | Where uploads are POSTed      |
+| `OMRIFY_TOKEN`           | —                                  | The shared upload token       |
+| `OMRIFY_ROOT`            | process cwd                        | Base for relative paths       |
+| `OMRIFY_DEFAULT_FORMAT`  | `webp`                             | Default output format         |
+| `OMRIFY_DEFAULT_QUALITY` | `85`                               | Default lossy quality         |
+| `OMRIFY_MAX_DIMENSION`   | `0`                                | Default longest-edge cap in px |
+| `OMRIFY_HISTORY_FILE`    | `~/.omrify-mcp/uploads.json`       | Where `recent_uploads` reads  |
+
+---
+
+# For whoever runs the Worker
+
+## Deploy
+
+```bash
+npm run build
+npx wrangler deploy -c dist/server/wrangler.json
+```
+
+## Set the token
+
+One shared token that everybody uses:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"
+npx wrangler secret put MCP_UPLOAD_TOKEN
+```
+
+It takes effect immediately — no redeploy. To cut off access, `secret put` a new
+value; everyone then needs the new token, so hand it out somewhere you can update.
+
+`/api/upload` returns 503 while the token is unset — without one the endpoint
+would be an open proxy onto your storage.
+
+## Set up storage (R2)
+
+Uploads are stored in an R2 bucket bound as `UPLOADS`. Create it, expose it, and
+tell the Worker which origin serves it:
+
+```bash
+npx wrangler r2 bucket create omrify-uploads
+npx wrangler r2 bucket dev-url enable omrify-uploads   # prints https://pub-<id>.r2.dev
+npx wrangler secret put R2_PUBLIC_BASE                 # paste that origin
+```
+
+For a real deployment, attach a custom domain to the bucket in the Cloudflare
+dashboard and use that as `R2_PUBLIC_BASE` instead — the `r2.dev` dev URL is rate
+limited and not meant for production traffic.
+
+> **Why not imgbb?** It blocks by source IP, and Workers egress from shared
+> Cloudflare addresses that it rejects, so uploads failed at random with
+> `400 code 103` even with a valid key. R2 keeps the write inside Cloudflare.
+> imgbb remains only as a `npm run dev` fallback, where requests leave from your
+> own machine.
+
+## Health check
+
+```bash
+curl -H "Authorization: Bearer $OMRIFY_TOKEN" https://<the-worker>.workers.dev/api/upload
+# {"ok":true,"service":"omrify-upload","storage":"r2","r2Bucket":true,
+#  "r2PublicBase":true,"uploadToken":true,"cloudflareImages":true}
+```
+
+`storage` must read `r2`. If `r2Bucket` is true but `r2PublicBase` is false the
+endpoint 503s on upload, because stored objects would have no reachable URL.
+
+`cloudflareImages: false` is not fatal — uploads still succeed, but the bytes go up
+unconverted and results are flagged `converted: false`. Re-enable it by keeping the
+`images` binding in `wrangler.jsonc` and having Images available on the account.
+
+## Troubleshooting
+
+**Uploads fail at random with `502 ... imgbb ... code 103`.** `storage` is `imgbb`,
+not `r2` — the Worker has no bucket bound and fell back, and imgbb blocks Cloudflare's
+egress IPs. It hits every tool equally (`upload_image` as much as `upload_from_url`),
+and because some attempts get through it can look like only one of them is broken.
+Fix it with [Set up storage (R2)](#set-up-storage-r2) above. Note that R2 has to be
+enabled on the account in the Cloudflare dashboard first — `wrangler r2 bucket create`
+fails with `code: 10042` until it is.
+
+**`upload_from_url` says the source "returned text/html, not an image".** The link
+points at a gallery or share page rather than the file. Open it, right-click the
+image, and copy the direct image address.
+
+**`upload_from_url` gets a 403.** The host blocks hotlinking. Save the image locally
+and use `upload_image` instead.
+
+## Publishing
+
+```bash
+cd mcp
+npm publish --access public
+```
+
+Bump `version` first. `files` limits the tarball to `server.mjs` and this README.
+
+## Local development
+
+Point `OMRIFY_ENDPOINT` at `http://localhost:8080/api/upload` and run `npm run dev`
+in the repo root, with the token in `.dev.vars`. Note that `npm run dev` runs under
+plain Node, so there is neither an Images nor an R2 binding: uploads come back
+`converted: false` and fall back to imgbb via `VITE_IMGBB_API_KEY`. To exercise the
+real conversion and R2 path locally:
+
+```bash
+npm run build
+cd dist/server && npx wrangler dev -c wrangler.json --port 8789
+```
+
+## Notes
+
+- Max upload size is 100 MB on R2, 32 MB on the imgbb dev fallback.
+- R2 object keys are content-addressed, so re-uploading identical bytes reuses the
+  same URL instead of creating a duplicate.
+- `recent_uploads` is capped at 300 entries.
+- Animated GIF/WebP: the Worker path re-encodes a still frame. Use
+  `format: "original"` to upload an animation untouched.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "omrify-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP server that turns local image files into hosted, WebP-optimised URLs via an Omrify Cloudflare Worker.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "image",
+    "webp",
+    "upload",
+    "cloudflare"
+  ],
+  "license": "MIT",
+  "author": "Omar Khaled",
+  "homepage": "https://github.com/okhaled11/omrify/tree/main/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/okhaled11/omrify.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/okhaled11/omrify/issues"
+  },
+  "bin": {
+    "omrify-mcp": "server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.mjs

@@ -0,0 +1,488 @@
+#!/usr/bin/env node
+/**
+ * Omrify MCP server — stdio.
+ *
+ * Reads image files straight off the local disk (so bytes never travel through the
+ * model as base64) and POSTs them to the Omrify Cloudflare Worker at
+ * `POST /api/upload`, which re-encodes them and returns a public hosted URL.
+ *
+ * Configuration comes from the environment:
+ *   OMRIFY_ENDPOINT         upload endpoint       (default: http://localhost:8080/api/upload)
+ *   OMRIFY_TOKEN            must match MCP_UPLOAD_TOKEN on the Worker  (required)
+ *   OMRIFY_ROOT             base for relative paths (default: process.cwd())
+ *   OMRIFY_DEFAULT_FORMAT   webp | png | jpeg | original  (default: webp)
+ *   OMRIFY_DEFAULT_QUALITY  1-100                          (default: 85)
+ *   OMRIFY_MAX_DIMENSION    longest edge in px, 0 = keep   (default: 0)
+ */
+
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { basename, extname, isAbsolute, join, resolve } from "node:path";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+/* ───────────────────────── config ───────────────────────── */
+
+const CONFIG = {
+  endpoint: process.env.OMRIFY_ENDPOINT?.trim() || "http://localhost:8080/api/upload",
+  token: process.env.OMRIFY_TOKEN?.trim() || "",
+  root: process.env.OMRIFY_ROOT?.trim() || process.cwd(),
+  format: process.env.OMRIFY_DEFAULT_FORMAT?.trim() || "webp",
+  quality: Number(process.env.OMRIFY_DEFAULT_QUALITY) || 85,
+  maxDimension: Number(process.env.OMRIFY_MAX_DIMENSION) || 0,
+};
+
+/**
+ * Uploads log, so `recent_uploads` survives restarts. Kept in the user's home
+ * directory rather than beside this file — under `npx` the package lives in a
+ * read-only cache that is wiped between versions.
+ */
+const HISTORY_FILE =
+  process.env.OMRIFY_HISTORY_FILE?.trim() || path.join(os.homedir(), ".omrify-mcp", "uploads.json");
+const HISTORY_LIMIT = 300;
+
+const IMAGE_EXTS = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".webp",
+  ".gif",
+  ".bmp",
+  ".avif",
+  ".tif",
+  ".tiff",
+  ".svg",
+]);
+
+const MIME_BY_EXT = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".bmp": "image/bmp",
+  ".avif": "image/avif",
+  ".tif": "image/tiff",
+  ".tiff": "image/tiff",
+  ".svg": "image/svg+xml",
+};
+
+/** Reverse of MIME_BY_EXT — CDN image URLs are usually extensionless. */
+const EXT_BY_MIME = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/jpg": ".jpg",
+  "image/webp": ".webp",
+  "image/gif": ".gif",
+  "image/bmp": ".bmp",
+  "image/avif": ".avif",
+  "image/tiff": ".tif",
+  "image/svg+xml": ".svg",
+};
+
+/**
+ * Headers for fetching a remote image. Several hosts (Wikimedia among them) answer
+ * 403 to a request with no User-Agent, and some CDNs content-negotiate on Accept.
+ */
+const SOURCE_FETCH_HEADERS = {
+  "user-agent": "omrify-mcp (+https://github.com/okhaled11/omrify)",
+  accept: "image/*,*/*;q=0.8",
+};
+
+/** A wrong URL should fail fast rather than hang the tool call. */
+const SOURCE_FETCH_TIMEOUT_MS = 30_000;
+
+/* ───────────────────────── small utilities ───────────────────────── */
+
+class ToolError extends Error {}
+
+function formatBytes(n) {
+  if (!Number.isFinite(n)) return "?";
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+function savings(before, after) {
+  if (!before || !after || after >= before) return "";
+  // Floor, so a 99.6% saving never reads as a misleading "-100%".
+  return `  (-${Math.floor((1 - after / before) * 100)}%)`;
+}
+
+/** Resolve a user-supplied path against OMRIFY_ROOT and confirm it exists. */
+async function resolveExisting(inputPath) {
+  const full = isAbsolute(inputPath) ? resolve(inputPath) : resolve(CONFIG.root, inputPath);
+  try {
+    return { path: full, stats: await stat(full) };
+  } catch {
+    throw new ToolError(`No such file or directory: ${full}`);
+  }
+}
+
+/** Expand a mix of files and directories into a flat list of image file paths. */
+async function collectImages(paths, recursive) {
+  const found = [];
+  for (const input of paths) {
+    const { path: full, stats } = await resolveExisting(input);
+    if (stats.isDirectory()) {
+      found.push(...(await walkDirectory(full, recursive)));
+    } else {
+      found.push(full);
+    }
+  }
+  // Directories can overlap; keep the first occurrence of each file.
+  return [...new Set(found)];
+}
+
+async function walkDirectory(dir, recursive) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const out = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (recursive && entry.name !== "node_modules" && !entry.name.startsWith(".")) {
+        out.push(...(await walkDirectory(full, recursive)));
+      }
+    } else if (IMAGE_EXTS.has(extname(entry.name).toLowerCase())) {
+      out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+/* ───────────────────────── history ───────────────────────── */
+
+async function readHistory() {
+  try {
+    return JSON.parse(await readFile(HISTORY_FILE, "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+async function recordUploads(entries) {
+  if (!entries.length) return;
+  try {
+    const history = await readHistory();
+    await mkdir(path.dirname(HISTORY_FILE), { recursive: true });
+    await writeFile(
+      HISTORY_FILE,
+      JSON.stringify([...entries, ...history].slice(0, HISTORY_LIMIT), null, 2),
+    );
+  } catch {
+    /* the log is a convenience — never fail an upload over it */
+  }
+}
+
+/* ───────────────────────── upload ───────────────────────── */
+
+/** POST raw bytes to the Worker and normalise its JSON reply. */
+async function uploadBytes(bytes, fileName, options) {
+  if (!CONFIG.token) {
+    throw new ToolError(
+      "OMRIFY_TOKEN is not set for this MCP server. Add it to the server's env block and make it " +
+        "match MCP_UPLOAD_TOKEN on the Worker (.dev.vars locally, `wrangler secret put` in production).",
+    );
+  }
+
+  const form = new FormData();
+  const mime = MIME_BY_EXT[extname(fileName).toLowerCase()] || "application/octet-stream";
+  form.append("image", new Blob([bytes], { type: mime }), fileName);
+  form.append("name", options.name || fileName);
+  form.append("format", options.format ?? CONFIG.format);
+  form.append("quality", String(options.quality ?? CONFIG.quality));
+  form.append("maxDimension", String(options.maxDimension ?? CONFIG.maxDimension));
+
+  let res;
+  try {
+    res = await fetch(CONFIG.endpoint, {
+      method: "POST",
+      headers: { authorization: `Bearer ${CONFIG.token}` },
+      body: form,
+    });
+  } catch (error) {
+    throw new ToolError(
+      `Could not reach ${CONFIG.endpoint} (${error?.message ?? "network error"}). ` +
+        "Is the Omrify app running (`npm run dev`) or deployed at OMRIFY_ENDPOINT?",
+    );
+  }
+
+  const payload = await res.json().catch(() => null);
+  if (!res.ok || !payload?.ok) {
+    throw new ToolError(
+      `Upload failed (${res.status}): ${payload?.error ?? (await res.text().catch(() => ""))}`,
+    );
+  }
+  return payload;
+}
+
+/**
+ * Download a remote image, failing loudly on the things that silently produced a
+ * broken upload before: a non-image response body, an empty body, or a hang.
+ */
+async function fetchImage(url) {
+  let res;
+  try {
+    res = await fetch(url, {
+      headers: SOURCE_FETCH_HEADERS,
+      redirect: "follow",
+      signal: AbortSignal.timeout(SOURCE_FETCH_TIMEOUT_MS),
+    });
+  } catch (error) {
+    if (error?.name === "TimeoutError" || error?.name === "AbortError") {
+      throw new ToolError(`${url} did not respond within ${SOURCE_FETCH_TIMEOUT_MS / 1000}s.`);
+    }
+    throw new ToolError(`Could not fetch ${url}: ${error?.message ?? "network error"}`);
+  }
+
+  if (!res.ok) {
+    throw new ToolError(
+      `Source responded ${res.status} for ${url}.` +
+        (res.status === 403 || res.status === 401
+          ? " The host is blocking direct downloads (hotlink protection) — save the image and use upload_image instead."
+          : ""),
+    );
+  }
+
+  const contentType = (res.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+  // A share/gallery page returns HTML; uploading that would produce a corrupt "image".
+  if (contentType && !contentType.startsWith("image/")) {
+    throw new ToolError(
+      `${url} returned ${contentType}, not an image. That is usually a gallery or share page — ` +
+        "open it and copy the direct image URL (the one ending in .jpg/.png/.webp).",
+    );
+  }
+
+  const data = new Uint8Array(await res.arrayBuffer());
+  if (!data.length) throw new ToolError(`${url} returned an empty response body.`);
+  return { data, contentType };
+}
+
+/**
+ * Name for a downloaded image. The server's content type wins over the URL, because
+ * CDN URLs are routinely extensionless (`/photo-1493246507139?w=400`) or carry an
+ * extension that disagrees with the bytes actually served.
+ */
+function remoteFileName(url, contentType) {
+  let fromPath = "";
+  try {
+    fromPath = decodeURIComponent(basename(new URL(url).pathname));
+  } catch {
+    /* undecodable path — fall through to the default stem */
+  }
+
+  const urlExt = extname(fromPath).toLowerCase();
+  const stem = (urlExt ? fromPath.slice(0, -urlExt.length) : fromPath) || "image";
+  const ext = EXT_BY_MIME[contentType] ?? (urlExt || ".png");
+  return `${stem}${ext}`;
+}
+
+async function uploadOne(sourcePath, options) {
+  const { path: full, stats } = await resolveExisting(sourcePath);
+  if (stats.isDirectory())
+    throw new ToolError(`${full} is a directory — use upload_images instead.`);
+
+  const result = await uploadBytes(await readFile(full), basename(full), options);
+  return { ...result, source: full };
+}
+
+/* ───────────────────────── rendering ───────────────────────── */
+
+function describe(result) {
+  const dimensions = result.width && result.height ? `  ${result.width}×${result.height}` : "";
+  const note = result.converted ? "" : "  [not re-encoded — Cloudflare Images unavailable]";
+  return (
+    `✔ ${basename(result.source ?? result.name)} → ${result.name}\n` +
+    `  ${formatBytes(result.originalSize)} → ${formatBytes(result.size)}${savings(result.originalSize, result.size)}${dimensions}${note}\n` +
+    `  ${result.url}`
+  );
+}
+
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+function errorResult(error) {
+  return {
+    content: [{ type: "text", text: `✖ ${error?.message ?? String(error)}` }],
+    isError: true,
+  };
+}
+
+/** Run `worker` over `items` with a small concurrency cap, preserving input order. */
+async function mapLimit(items, limit, worker) {
+  const results = new Array(items.length);
+  let cursor = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, async () => {
+      while (cursor < items.length) {
+        const index = cursor++;
+        try {
+          results[index] = { ok: true, value: await worker(items[index]) };
+        } catch (error) {
+          results[index] = { ok: false, error, item: items[index] };
+        }
+      }
+    }),
+  );
+  return results;
+}
+
+/* ───────────────────────── tools ───────────────────────── */
+
+const optionShape = {
+  format: z
+    .enum(["webp", "png", "jpeg", "original"])
+    .optional()
+    .describe(`Output format. Default ${CONFIG.format}. "original" skips re-encoding.`),
+  quality: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe(`Lossy quality 1-100. Default ${CONFIG.quality}.`),
+  maxDimension: z
+    .number()
+    .int()
+    .min(0)
+    .max(10000)
+    .optional()
+    .describe(`Scale down so the longest edge fits this many px. 0 keeps the original size.`),
+};
+
+const server = new McpServer({ name: "omrify", version: "1.0.0" });
+
+server.registerTool(
+  "upload_image",
+  {
+    title: "Upload an image and get a hosted URL",
+    description:
+      "Convert a local image to WebP (via the Omrify Cloudflare Worker) and upload it, returning a public URL " +
+      "ready to paste into code. Use this whenever an image on disk needs to become a link.",
+    inputSchema: {
+      path: z
+        .string()
+        .describe("Path to the image. Absolute, or relative to the current project directory."),
+      name: z.string().optional().describe("Override the uploaded file name."),
+      ...optionShape,
+    },
+  },
+  async ({ path, ...options }) => {
+    try {
+      const result = await uploadOne(path, options);
+      await recordUploads([{ ...result, at: new Date().toISOString() }]);
+      return textResult(describe(result));
+    } catch (error) {
+      return errorResult(error);
+    }
+  },
+);
+
+server.registerTool(
+  "upload_images",
+  {
+    title: "Upload several images at once",
+    description:
+      "Batch version of upload_image. Accepts any mix of file paths and directories (directories expand to the " +
+      "image files inside) and returns one hosted URL per image.",
+    inputSchema: {
+      paths: z.array(z.string()).min(1).describe("File and/or directory paths."),
+      recursive: z.boolean().optional().describe("Descend into subdirectories. Default false."),
+      ...optionShape,
+    },
+  },
+  async ({ paths, recursive = false, ...options }) => {
+    try {
+      const files = await collectImages(paths, recursive);
+      if (!files.length) return textResult("No image files found in the given paths.");
+
+      const outcomes = await mapLimit(files, 4, (file) => uploadOne(file, options));
+      const succeeded = outcomes.filter((o) => o.ok).map((o) => o.value);
+      await recordUploads(succeeded.map((r) => ({ ...r, at: new Date().toISOString() })));
+
+      const lines = outcomes.map((o) =>
+        o.ok ? describe(o.value) : `✖ ${basename(o.item)} — ${o.error?.message ?? "failed"}`,
+      );
+      const urls = succeeded.map((r) => `${r.name}: ${r.url}`).join("\n");
+
+      return textResult(
+        `${succeeded.length}/${files.length} uploaded.\n\n${lines.join("\n\n")}` +
+          (urls ? `\n\n--- URLs ---\n${urls}` : ""),
+      );
+    } catch (error) {
+      return errorResult(error);
+    }
+  },
+);
+
+server.registerTool(
+  "upload_from_url",
+  {
+    title: "Re-host an image from a URL",
+    description:
+      "Download an image from a remote URL, convert it, and re-upload it so it is served from a stable link " +
+      "you control rather than the original host.",
+    inputSchema: {
+      url: z.string().url().describe("Public URL of the source image."),
+      name: z.string().optional().describe("Override the uploaded file name."),
+      ...optionShape,
+    },
+  },
+  async ({ url, name, ...options }) => {
+    try {
+      const bytes = await fetchImage(url);
+      const result = {
+        ...(await uploadBytes(bytes.data, name || remoteFileName(url, bytes.contentType), options)),
+        source: url,
+      };
+      await recordUploads([{ ...result, at: new Date().toISOString() }]);
+      return textResult(describe(result));
+    } catch (error) {
+      return errorResult(error);
+    }
+  },
+);
+
+server.registerTool(
+  "recent_uploads",
+  {
+    title: "List previously uploaded images",
+    description:
+      "Look up links from earlier uploads instead of re-uploading the same file. Useful when you need a URL " +
+      "again later in a session or in a different project.",
+    inputSchema: {
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("How many entries to return. Default 20."),
+      search: z
+        .string()
+        .optional()
+        .describe("Case-insensitive filter on file name or source path."),
+    },
+  },
+  async ({ limit = 20, search }) => {
+    const history = await readHistory();
+    const needle = search?.toLowerCase();
+    const matches = (
+      needle
+        ? history.filter((e) => `${e.name} ${e.source ?? ""}`.toLowerCase().includes(needle))
+        : history
+    ).slice(0, limit);
+
+    if (!matches.length)
+      return textResult(search ? `No uploads matching "${search}".` : "No uploads recorded yet.");
+    return textResult(matches.map((e) => `${e.name}  (${e.at})\n  ${e.url}`).join("\n\n"));
+  },
+);
+
+/* ───────────────────────── start ───────────────────────── */
+
+await server.connect(new StdioServerTransport());