roundcut-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Araluma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# roundcut-mcp
+
+Local image tools for AI agents, as an [MCP](https://modelcontextprotocol.io) server.
+Circle crop, crop, resize, compress and convert JPG, PNG, WebP and AVIF on your own
+machine with [sharp](https://sharp.pixelplumbing.com). No network calls, no accounts,
+no upload: the files never leave the disk.
+
+Made by [RoundCut](https://roundcut.app), the free image tools site (29 languages).
+
+## Install
+
+Node 20 or newer.
+
+```bash
+npx roundcut-mcp
+```
+
+### Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "roundcut": { "command": "npx", "args": ["-y", "roundcut-mcp"] }
+  }
+}
+```
+
+Claude Code: `claude mcp add roundcut -- npx -y roundcut-mcp`
+
+### Cursor, Windsurf, VS Code
+
+Same shape: a stdio server, command `npx`, args `-y roundcut-mcp`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `image_info` | Format, dimensions, alpha, EXIF orientation. |
+| `circle_crop` | Round profile picture: centered square plus a circular transparent mask. `size`, `format` (png default), `background` for jpeg. |
+| `crop_image` | Pixel box (`left`, `top`, `width`, `height`) or a centered `aspect` such as `1:1`, `4:5`, `16:9`. |
+| `resize_image` | By `width`, `height` or `percent`. Keeps the aspect ratio, never enlarges unless `enlarge: true`. Lanczos3. |
+| `compress_image` | Smaller file, same format. `quality` for jpg/webp/avif (mozjpeg for jpg), lossless recompression for png. |
+| `convert_image` | To `jpeg`, `png`, `webp` or `avif`. Input may also be GIF, TIFF or HEIC. Transparency kept, or flattened onto `background` for jpeg. |
+| `roundcut_web_tools` | Links to the browser tools this server does not run locally: background remover, AI upscaler, batch convert, JPG to PDF. |
+
+Every tool takes an `input` path and writes next to it by default
+(`photo.jpg` becomes `photo-circle.png`, `photo-resized.jpg`, `photo.webp`), or to `output`.
+Results carry a text summary, a `resource_link` to the file, structured JSON
+(`output`, `format`, `width`, `height`, `bytes`, `inputBytes`) and a small JPEG preview
+(`preview: false` to skip it).
+
+Example, from a chat client with the server attached:
+
+> Make `~/Pictures/me.jpg` a 512 px round avatar as WebP.
+
+calls `circle_crop` with `{ "input": "~/Pictures/me.jpg", "size": 512, "format": "webp" }`
+and answers with the file path, the dimensions and the byte count.
+
+## Limits
+
+- Inputs above 80 megapixels are refused, so a stray call cannot allocate gigabytes.
+- EXIF orientation is applied on read; the output is upright and carries no EXIF.
+- jpeg has no alpha: transparent areas are flattened onto `background` (white by default).
+
+## Develop
+
+```bash
+npm install
+npm test        # builds, then node --test
+```
+
+`src/engine.ts` is the pure image layer (tested directly). `src/index.ts` adapts it to MCP tools.
+
+## License
+
+MIT. Copyright Araluma.

package/dist/engine.d.ts

@@ -0,0 +1,86 @@
+import { type Metadata, type Sharp } from "sharp";
+export type Format = "jpeg" | "png" | "webp" | "avif";
+export declare const FORMATS: readonly ["jpeg", "png", "webp", "avif"];
+export interface Report {
+    output: string;
+    format: Format;
+    width: number;
+    height: number;
+    bytes: number;
+    inputBytes: number;
+}
+export declare function readInput(input: string): Promise<{
+    buf: Buffer;
+    bytes: number;
+    abs: string;
+}>;
+export declare function formatOf(meta: Metadata): Format;
+/** Default output path: same directory, same stem, a suffix, the target extension. */
+export declare function outputPathFor(inputAbs: string, suffix: string, format: Format, explicit?: string): string;
+export interface EncodeOptions {
+    /** 1..100 for the lossy formats; png ignores it. Default 80. */
+    quality?: number;
+    /** CSS color used to flatten alpha when the output is jpeg. Default white. */
+    background?: string;
+}
+/** Apply the output encoder. jpeg has no alpha, so transparent pixels are
+ *  flattened onto `background` instead of turning black. */
+export declare function encode(img: Sharp, format: Format, opts?: EncodeOptions): Sharp;
+export declare function info(input: string): Promise<{
+    path: string;
+    bytes: number;
+    format: keyof import("sharp").FormatEnum;
+    width: number;
+    height: number;
+    hasAlpha: boolean;
+    orientation: number;
+    space: keyof import("sharp").ColourspaceEnum;
+}>;
+export interface CircleCropOptions extends EncodeOptions {
+    output?: string;
+    /** Default png, which keeps the transparent corners. */
+    format?: Format;
+    /** Output side in px. Default: the largest centered square of the input. */
+    size?: number;
+}
+/** Center square, then a circular alpha mask. png/webp/avif keep the
+ *  transparency; jpeg gets the corners flattened onto `background`. */
+export declare function circleCrop(input: string, o?: CircleCropOptions): Promise<Report>;
+export interface CropOptions extends EncodeOptions {
+    output?: string;
+    format?: Format;
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    /** "1:1", "16:9", "4:5": a centered crop to that ratio, overriding the pixel box. */
+    aspect?: string;
+}
+export declare function crop(input: string, o?: CropOptions): Promise<Report>;
+export interface ResizeOptions extends EncodeOptions {
+    output?: string;
+    format?: Format;
+    width?: number;
+    height?: number;
+    /** 1..400, relative to the input size. */
+    percent?: number;
+    /** Default inside: keeps the aspect ratio and never crops. */
+    fit?: "inside" | "cover" | "fill";
+    /** Default false: never upscale. */
+    enlarge?: boolean;
+}
+export declare function resize(input: string, o?: ResizeOptions): Promise<Report>;
+export interface CompressOptions extends EncodeOptions {
+    output?: string;
+}
+/** Same format in and out, smaller file. png is lossless; the others use `quality`. */
+export declare function compress(input: string, o?: CompressOptions): Promise<Report>;
+export interface ConvertOptions extends EncodeOptions {
+    output?: string;
+}
+export declare function convert(input: string, format: Format, o?: ConvertOptions): Promise<Report>;
+/** A small JPEG preview for chat clients that render image content. */
+export declare function preview(file: string, max?: number): Promise<{
+    data: string;
+    mimeType: "image/jpeg";
+}>;

package/dist/engine.js

@@ -0,0 +1,172 @@
+/**
+ * Pure image operations on top of sharp. No MCP here: every function takes a
+ * path, returns a small report, and is unit-tested directly. The MCP layer
+ * (index.ts) only adapts these to tool calls.
+ */
+import { access, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import sharp from "sharp";
+export const FORMATS = ["jpeg", "png", "webp", "avif"];
+const EXT = { jpeg: ".jpg", png: ".png", webp: ".webp", avif: ".avif" };
+/** Pixel ceiling per image. 80 MP covers every phone camera; beyond that sharp
+ *  would happily allocate gigabytes for a single call issued by an LLM. */
+const MAX_PIXELS = 80_000_000;
+export async function readInput(input) {
+    const abs = path.resolve(input);
+    await access(abs);
+    const s = await stat(abs);
+    if (!s.isFile())
+        throw new Error(`not a file: ${abs}`);
+    return { buf: await readFile(abs), bytes: s.size, abs };
+}
+function open(buf) {
+    return sharp(buf, { limitInputPixels: MAX_PIXELS, failOn: "error" });
+}
+export function formatOf(meta) {
+    const f = meta.format;
+    if (f === "jpeg" || f === "png" || f === "webp")
+        return f;
+    // sharp reports AVIF as heif + av1 compression; HEIC is heif + hevc.
+    if (f === "heif" && meta.compression === "av1")
+        return "avif";
+    // HEIC, TIFF, GIF, SVG decode fine but have no matching web encoder: use PNG.
+    return "png";
+}
+/** Default output path: same directory, same stem, a suffix, the target extension. */
+export function outputPathFor(inputAbs, suffix, format, explicit) {
+    if (explicit)
+        return path.resolve(explicit);
+    const dir = path.dirname(inputAbs);
+    const stem = path.basename(inputAbs, path.extname(inputAbs));
+    return path.join(dir, `${stem}${suffix}${EXT[format]}`);
+}
+/** Apply the output encoder. jpeg has no alpha, so transparent pixels are
+ *  flattened onto `background` instead of turning black. */
+export function encode(img, format, opts = {}) {
+    const q = opts.quality ?? 80;
+    switch (format) {
+        case "jpeg":
+            return img.flatten({ background: opts.background ?? "#ffffff" }).jpeg({ quality: q, mozjpeg: true });
+        case "png":
+            return img.png({ compressionLevel: 9, effort: 7 });
+        case "webp":
+            return img.webp({ quality: q });
+        case "avif":
+            return img.avif({ quality: q, effort: 4 });
+    }
+}
+async function finish(img, format, opts, output, inputBytes) {
+    const { data, info } = await encode(img, format, opts).toBuffer({ resolveWithObject: true });
+    await writeFile(output, data);
+    return { output, format, width: info.width, height: info.height, bytes: data.length, inputBytes };
+}
+export async function info(input) {
+    const { buf, bytes, abs } = await readInput(input);
+    const m = await open(buf).metadata();
+    return {
+        path: abs,
+        bytes,
+        format: m.format,
+        width: m.width,
+        height: m.height,
+        hasAlpha: m.hasAlpha ?? false,
+        orientation: m.orientation ?? 1,
+        space: m.space,
+    };
+}
+/** Center square, then a circular alpha mask. png/webp/avif keep the
+ *  transparency; jpeg gets the corners flattened onto `background`. */
+export async function circleCrop(input, o = {}) {
+    const { buf, bytes, abs } = await readInput(input);
+    const format = o.format ?? "png";
+    const base = open(buf).rotate();
+    const m = await base.metadata();
+    const side = Math.min(m.width ?? 0, m.height ?? 0);
+    if (!side)
+        throw new Error("could not read image dimensions");
+    const size = o.size ?? side;
+    const r = size / 2;
+    const mask = Buffer.from(`<svg width="${size}" height="${size}"><circle cx="${r}" cy="${r}" r="${r}"/></svg>`);
+    // sharp applies composite LAST in its pipeline, after flatten: masking and
+    // jpeg-flattening in one pass would flatten first and leave the corners
+    // transparent, which jpeg then paints black. Two passes keep the order honest.
+    const masked = await base
+        .resize(size, size, { fit: "cover", position: "centre", kernel: "lanczos3" })
+        .ensureAlpha()
+        .composite([{ input: mask, blend: "dest-in" }])
+        .png()
+        .toBuffer();
+    return finish(open(masked), format, o, outputPathFor(abs, "-circle", format, o.output), bytes);
+}
+export async function crop(input, o = {}) {
+    const { buf, bytes, abs } = await readInput(input);
+    const base = open(buf).rotate();
+    const m = await base.metadata();
+    const W = m.width ?? 0;
+    const H = m.height ?? 0;
+    const format = o.format ?? formatOf(m);
+    let region;
+    if (o.aspect) {
+        const [aw, ah] = o.aspect.split(":").map(Number);
+        if (!aw || !ah)
+            throw new Error(`bad aspect "${o.aspect}", expected like 16:9`);
+        let w = W;
+        let h = Math.round((W * ah) / aw);
+        if (h > H) {
+            h = H;
+            w = Math.round((H * aw) / ah);
+        }
+        region = { left: Math.floor((W - w) / 2), top: Math.floor((H - h) / 2), width: w, height: h };
+    }
+    else {
+        const { left = 0, top = 0, width, height } = o;
+        if (!width || !height)
+            throw new Error("crop needs width and height, or an aspect");
+        if (left + width > W || top + height > H)
+            throw new Error(`crop box exceeds the ${W}x${H} image`);
+        region = { left, top, width, height };
+    }
+    return finish(base.extract(region), format, o, outputPathFor(abs, "-crop", format, o.output), bytes);
+}
+export async function resize(input, o = {}) {
+    const { buf, bytes, abs } = await readInput(input);
+    const base = open(buf).rotate();
+    const m = await base.metadata();
+    const format = o.format ?? formatOf(m);
+    let width = o.width;
+    let height = o.height;
+    if (o.percent) {
+        width = Math.round(((m.width ?? 0) * o.percent) / 100);
+        height = Math.round(((m.height ?? 0) * o.percent) / 100);
+    }
+    if (!width && !height)
+        throw new Error("resize needs width, height or percent");
+    const img = base.resize({
+        width,
+        height,
+        fit: o.fit ?? "inside",
+        kernel: "lanczos3",
+        withoutEnlargement: !(o.enlarge ?? false),
+    });
+    return finish(img, format, o, outputPathFor(abs, "-resized", format, o.output), bytes);
+}
+/** Same format in and out, smaller file. png is lossless; the others use `quality`. */
+export async function compress(input, o = {}) {
+    const { buf, bytes, abs } = await readInput(input);
+    const base = open(buf).rotate();
+    const format = formatOf(await base.metadata());
+    return finish(base, format, o, outputPathFor(abs, "-compressed", format, o.output), bytes);
+}
+export async function convert(input, format, o = {}) {
+    const { buf, bytes, abs } = await readInput(input);
+    return finish(open(buf).rotate(), format, o, outputPathFor(abs, "", format, o.output), bytes);
+}
+/** A small JPEG preview for chat clients that render image content. */
+export async function preview(file, max = 320) {
+    const buf = await sharp(file, { limitInputPixels: MAX_PIXELS })
+        .resize({ width: max, height: max, fit: "inside", withoutEnlargement: true })
+        .flatten({ background: "#ffffff" })
+        .jpeg({ quality: 70 })
+        .toBuffer();
+    return { data: buf.toString("base64"), mimeType: "image/jpeg" };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * roundcut-mcp: local image tools as MCP tools, by RoundCut (https://roundcut.app).
+ * stdio transport. stdout is the protocol channel: log only through console.error.
+ */
+import { McpServer } from "@modelcontextprotocol/server";
+export declare function buildServer(): McpServer;

package/dist/index.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * roundcut-mcp: local image tools as MCP tools, by RoundCut (https://roundcut.app).
+ * stdio transport. stdout is the protocol channel: log only through console.error.
+ */
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod/v4";
+import { FORMATS, circleCrop, compress, convert, crop, info, preview, resize } from "./engine.js";
+const VERSION = "0.1.0";
+const SITE = "https://roundcut.app";
+const format = z.enum(FORMATS);
+const quality = z.number().int().min(1).max(100).optional().describe("Lossy quality 1-100 (default 80). Ignored for png.");
+const background = z.string().optional().describe("CSS color used to flatten transparency when the output is jpeg (default #ffffff).");
+const output = z.string().optional().describe("Output file path. Default: next to the input, with a suffix and the right extension.");
+const withPreview = z.boolean().optional().describe("Attach a small JPEG preview to the result (default true).");
+function sizeDelta(r) {
+    if (!r.inputBytes)
+        return "";
+    const d = Math.round((1 - r.bytes / r.inputBytes) * 100);
+    return d >= 0 ? `${d}% smaller than` : `${-d}% larger than`;
+}
+async function result(r, wantPreview, line) {
+    const text = [
+        line,
+        r.output,
+        `${r.width}x${r.height} ${r.format}, ${r.bytes.toLocaleString()} bytes (${sizeDelta(r)} the ${r.inputBytes.toLocaleString()}-byte input)`,
+    ].join("\n");
+    const content = [
+        { type: "text", text },
+        { type: "resource_link", uri: `file://${r.output}`, name: r.output.split("/").pop() ?? r.output, mimeType: `image/${r.format}` },
+    ];
+    if (wantPreview ?? true)
+        content.push({ type: "image", ...(await preview(r.output)) });
+    return { content, structuredContent: { ...r } };
+}
+function fail(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: msg }], isError: true };
+}
+export function buildServer() {
+    const server = new McpServer({ name: "roundcut-mcp", version: VERSION });
+    server.registerTool("image_info", {
+        title: "Image info",
+        description: "Read format, dimensions, alpha and EXIF orientation of an image file.",
+        inputSchema: z.object({ input: z.string().describe("Path to a JPG, PNG, WebP, AVIF, GIF, TIFF or HEIC file.") }),
+        annotations: { readOnlyHint: true },
+    }, async ({ input }) => {
+        try {
+            const i = await info(input);
+            return { content: [{ type: "text", text: JSON.stringify(i, null, 2) }], structuredContent: i };
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("circle_crop", {
+        title: "Circle crop",
+        description: "Make a round profile picture: center-square crop plus a circular transparent mask. png (default), webp and avif keep the transparent corners; jpeg flattens them onto a background color.",
+        inputSchema: z.object({
+            input: z.string(),
+            output,
+            size: z.number().int().min(16).max(8192).optional().describe("Output side in pixels (default: the largest centered square)."),
+            format: format.optional(),
+            quality,
+            background,
+            preview: withPreview,
+        }),
+    }, async ({ input, preview: p, ...o }) => {
+        try {
+            return await result(await circleCrop(input, o), p, "Circle crop done.");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("crop_image", {
+        title: "Crop image",
+        description: "Crop to a pixel box (left, top, width, height) or to a centered aspect ratio such as 1:1, 4:5 or 16:9.",
+        inputSchema: z.object({
+            input: z.string(),
+            output,
+            left: z.number().int().min(0).optional(),
+            top: z.number().int().min(0).optional(),
+            width: z.number().int().min(1).optional(),
+            height: z.number().int().min(1).optional(),
+            aspect: z.string().regex(/^\d+:\d+$/).optional().describe("Centered crop to this ratio, e.g. 16:9. Overrides the pixel box."),
+            format: format.optional(),
+            quality,
+            background,
+            preview: withPreview,
+        }),
+    }, async ({ input, preview: p, ...o }) => {
+        try {
+            return await result(await crop(input, o), p, "Crop done.");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("resize_image", {
+        title: "Resize image",
+        description: "Resize by width, height or percent. Keeps the aspect ratio (fit=inside) and never enlarges unless enlarge=true. Lanczos3 resampling.",
+        inputSchema: z.object({
+            input: z.string(),
+            output,
+            width: z.number().int().min(1).max(16384).optional(),
+            height: z.number().int().min(1).max(16384).optional(),
+            percent: z.number().min(1).max(400).optional(),
+            fit: z.enum(["inside", "cover", "fill"]).optional(),
+            enlarge: z.boolean().optional(),
+            format: format.optional(),
+            quality,
+            background,
+            preview: withPreview,
+        }),
+    }, async ({ input, preview: p, ...o }) => {
+        try {
+            return await result(await resize(input, o), p, "Resize done.");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("compress_image", {
+        title: "Compress image",
+        description: "Smaller file, same format. jpg/webp/avif re-encode at `quality` (default 80, mozjpeg for jpg); png is recompressed losslessly.",
+        inputSchema: z.object({ input: z.string(), output, quality, preview: withPreview }),
+    }, async ({ input, preview: p, ...o }) => {
+        try {
+            return await result(await compress(input, o), p, "Compress done.");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("convert_image", {
+        title: "Convert image",
+        description: "Convert between jpeg, png, webp and avif (the input may also be GIF, TIFF or HEIC). Transparency is kept except for jpeg, which is flattened onto `background`.",
+        inputSchema: z.object({ input: z.string(), format, output, quality, background, preview: withPreview }),
+    }, async ({ input, format: f, preview: p, ...o }) => {
+        try {
+            return await result(await convert(input, f, o), p, `Converted to ${f}.`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("roundcut_web_tools", {
+        title: "RoundCut web tools",
+        description: "Links to the RoundCut browser tools for what this server does not do locally: AI background removal, AI upscaling, batch conversion and image-to-PDF. Free, 29 languages.",
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, async () => ({
+        content: [
+            {
+                type: "text",
+                text: [
+                    `Background remover: ${SITE}/background-remover/`,
+                    `AI upscaler: ${SITE}/upscale-2x/`,
+                    `Batch convert: ${SITE}/convert/`,
+                    `JPG to PDF: ${SITE}/jpg-to-pdf/`,
+                    `All tools: ${SITE}/`,
+                ].join("\n"),
+            },
+        ],
+    }));
+    return server;
+}
+const entry = process.argv[1] ? process.argv[1].split("/").pop() ?? "" : "";
+if (entry && import.meta.url.endsWith(entry)) {
+    const handle = serveStdio(buildServer);
+    process.on("SIGINT", () => {
+        void handle.close();
+    });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "roundcut-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for local image tools by RoundCut: circle crop, crop, resize, compress and convert JPG, PNG, WebP and AVIF with sharp. No network, no accounts.",
+  "mcpName": "io.github.araluma/roundcut-mcp",
+  "type": "module",
+  "bin": { "roundcut-mcp": "./dist/index.js" },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist", "src", "server.json"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": ["mcp", "model-context-protocol", "image", "resize", "compress", "convert", "crop", "circle-crop", "avatar", "webp", "avif", "sharp", "roundcut"],
+  "author": "Araluma <dev@araluma.com>",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/Araluma/roundcut-mcp.git" },
+  "bugs": { "url": "https://github.com/Araluma/roundcut-mcp/issues" },
+  "homepage": "https://roundcut.app",
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "sharp": "^0.35.4",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": { "@types/node": "^24.0.0", "typescript": "^5.7.0" }
+}

package/server.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.araluma/roundcut-mcp",
+  "description": "Local image tools: circle crop, crop, resize, compress and convert JPG/PNG/WebP/AVIF with sharp. No network.",
+  "repository": { "url": "https://github.com/Araluma/roundcut-mcp", "source": "github" },
+  "version": "0.1.0",
+  "websiteUrl": "https://roundcut.app",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "roundcut-mcp",
+      "version": "0.1.0",
+      "transport": { "type": "stdio" }
+    }
+  ]
+}

package/src/engine.ts

@@ -0,0 +1,234 @@
+/**
+ * Pure image operations on top of sharp. No MCP here: every function takes a
+ * path, returns a small report, and is unit-tested directly. The MCP layer
+ * (index.ts) only adapts these to tool calls.
+ */
+import { access, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import sharp, { type Metadata, type Region, type Sharp } from "sharp";
+
+export type Format = "jpeg" | "png" | "webp" | "avif";
+export const FORMATS = ["jpeg", "png", "webp", "avif"] as const;
+const EXT: Record<Format, string> = { jpeg: ".jpg", png: ".png", webp: ".webp", avif: ".avif" };
+
+/** Pixel ceiling per image. 80 MP covers every phone camera; beyond that sharp
+ *  would happily allocate gigabytes for a single call issued by an LLM. */
+const MAX_PIXELS = 80_000_000;
+
+export interface Report {
+  output: string;
+  format: Format;
+  width: number;
+  height: number;
+  bytes: number;
+  inputBytes: number;
+}
+
+export async function readInput(input: string): Promise<{ buf: Buffer; bytes: number; abs: string }> {
+  const abs = path.resolve(input);
+  await access(abs);
+  const s = await stat(abs);
+  if (!s.isFile()) throw new Error(`not a file: ${abs}`);
+  return { buf: await readFile(abs), bytes: s.size, abs };
+}
+
+function open(buf: Buffer): Sharp {
+  return sharp(buf, { limitInputPixels: MAX_PIXELS, failOn: "error" });
+}
+
+export function formatOf(meta: Metadata): Format {
+  const f = meta.format;
+  if (f === "jpeg" || f === "png" || f === "webp") return f;
+  // sharp reports AVIF as heif + av1 compression; HEIC is heif + hevc.
+  if (f === "heif" && meta.compression === "av1") return "avif";
+  // HEIC, TIFF, GIF, SVG decode fine but have no matching web encoder: use PNG.
+  return "png";
+}
+
+/** Default output path: same directory, same stem, a suffix, the target extension. */
+export function outputPathFor(inputAbs: string, suffix: string, format: Format, explicit?: string): string {
+  if (explicit) return path.resolve(explicit);
+  const dir = path.dirname(inputAbs);
+  const stem = path.basename(inputAbs, path.extname(inputAbs));
+  return path.join(dir, `${stem}${suffix}${EXT[format]}`);
+}
+
+export interface EncodeOptions {
+  /** 1..100 for the lossy formats; png ignores it. Default 80. */
+  quality?: number;
+  /** CSS color used to flatten alpha when the output is jpeg. Default white. */
+  background?: string;
+}
+
+/** Apply the output encoder. jpeg has no alpha, so transparent pixels are
+ *  flattened onto `background` instead of turning black. */
+export function encode(img: Sharp, format: Format, opts: EncodeOptions = {}): Sharp {
+  const q = opts.quality ?? 80;
+  switch (format) {
+    case "jpeg":
+      return img.flatten({ background: opts.background ?? "#ffffff" }).jpeg({ quality: q, mozjpeg: true });
+    case "png":
+      return img.png({ compressionLevel: 9, effort: 7 });
+    case "webp":
+      return img.webp({ quality: q });
+    case "avif":
+      return img.avif({ quality: q, effort: 4 });
+  }
+}
+
+async function finish(img: Sharp, format: Format, opts: EncodeOptions, output: string, inputBytes: number): Promise<Report> {
+  const { data, info } = await encode(img, format, opts).toBuffer({ resolveWithObject: true });
+  await writeFile(output, data);
+  return { output, format, width: info.width, height: info.height, bytes: data.length, inputBytes };
+}
+
+export async function info(input: string) {
+  const { buf, bytes, abs } = await readInput(input);
+  const m = await open(buf).metadata();
+  return {
+    path: abs,
+    bytes,
+    format: m.format,
+    width: m.width,
+    height: m.height,
+    hasAlpha: m.hasAlpha ?? false,
+    orientation: m.orientation ?? 1,
+    space: m.space,
+  };
+}
+
+export interface CircleCropOptions extends EncodeOptions {
+  output?: string;
+  /** Default png, which keeps the transparent corners. */
+  format?: Format;
+  /** Output side in px. Default: the largest centered square of the input. */
+  size?: number;
+}
+
+/** Center square, then a circular alpha mask. png/webp/avif keep the
+ *  transparency; jpeg gets the corners flattened onto `background`. */
+export async function circleCrop(input: string, o: CircleCropOptions = {}): Promise<Report> {
+  const { buf, bytes, abs } = await readInput(input);
+  const format = o.format ?? "png";
+  const base = open(buf).rotate();
+  const m = await base.metadata();
+  const side = Math.min(m.width ?? 0, m.height ?? 0);
+  if (!side) throw new Error("could not read image dimensions");
+  const size = o.size ?? side;
+  const r = size / 2;
+  const mask = Buffer.from(`<svg width="${size}" height="${size}"><circle cx="${r}" cy="${r}" r="${r}"/></svg>`);
+  // sharp applies composite LAST in its pipeline, after flatten: masking and
+  // jpeg-flattening in one pass would flatten first and leave the corners
+  // transparent, which jpeg then paints black. Two passes keep the order honest.
+  const masked = await base
+    .resize(size, size, { fit: "cover", position: "centre", kernel: "lanczos3" })
+    .ensureAlpha()
+    .composite([{ input: mask, blend: "dest-in" }])
+    .png()
+    .toBuffer();
+  return finish(open(masked), format, o, outputPathFor(abs, "-circle", format, o.output), bytes);
+}
+
+export interface CropOptions extends EncodeOptions {
+  output?: string;
+  format?: Format;
+  left?: number;
+  top?: number;
+  width?: number;
+  height?: number;
+  /** "1:1", "16:9", "4:5": a centered crop to that ratio, overriding the pixel box. */
+  aspect?: string;
+}
+
+export async function crop(input: string, o: CropOptions = {}): Promise<Report> {
+  const { buf, bytes, abs } = await readInput(input);
+  const base = open(buf).rotate();
+  const m = await base.metadata();
+  const W = m.width ?? 0;
+  const H = m.height ?? 0;
+  const format = o.format ?? formatOf(m);
+  let region: Region;
+  if (o.aspect) {
+    const [aw, ah] = o.aspect.split(":").map(Number);
+    if (!aw || !ah) throw new Error(`bad aspect "${o.aspect}", expected like 16:9`);
+    let w = W;
+    let h = Math.round((W * ah) / aw);
+    if (h > H) {
+      h = H;
+      w = Math.round((H * aw) / ah);
+    }
+    region = { left: Math.floor((W - w) / 2), top: Math.floor((H - h) / 2), width: w, height: h };
+  } else {
+    const { left = 0, top = 0, width, height } = o;
+    if (!width || !height) throw new Error("crop needs width and height, or an aspect");
+    if (left + width > W || top + height > H) throw new Error(`crop box exceeds the ${W}x${H} image`);
+    region = { left, top, width, height };
+  }
+  return finish(base.extract(region), format, o, outputPathFor(abs, "-crop", format, o.output), bytes);
+}
+
+export interface ResizeOptions extends EncodeOptions {
+  output?: string;
+  format?: Format;
+  width?: number;
+  height?: number;
+  /** 1..400, relative to the input size. */
+  percent?: number;
+  /** Default inside: keeps the aspect ratio and never crops. */
+  fit?: "inside" | "cover" | "fill";
+  /** Default false: never upscale. */
+  enlarge?: boolean;
+}
+
+export async function resize(input: string, o: ResizeOptions = {}): Promise<Report> {
+  const { buf, bytes, abs } = await readInput(input);
+  const base = open(buf).rotate();
+  const m = await base.metadata();
+  const format = o.format ?? formatOf(m);
+  let width = o.width;
+  let height = o.height;
+  if (o.percent) {
+    width = Math.round(((m.width ?? 0) * o.percent) / 100);
+    height = Math.round(((m.height ?? 0) * o.percent) / 100);
+  }
+  if (!width && !height) throw new Error("resize needs width, height or percent");
+  const img = base.resize({
+    width,
+    height,
+    fit: o.fit ?? "inside",
+    kernel: "lanczos3",
+    withoutEnlargement: !(o.enlarge ?? false),
+  });
+  return finish(img, format, o, outputPathFor(abs, "-resized", format, o.output), bytes);
+}
+
+export interface CompressOptions extends EncodeOptions {
+  output?: string;
+}
+
+/** Same format in and out, smaller file. png is lossless; the others use `quality`. */
+export async function compress(input: string, o: CompressOptions = {}): Promise<Report> {
+  const { buf, bytes, abs } = await readInput(input);
+  const base = open(buf).rotate();
+  const format = formatOf(await base.metadata());
+  return finish(base, format, o, outputPathFor(abs, "-compressed", format, o.output), bytes);
+}
+
+export interface ConvertOptions extends EncodeOptions {
+  output?: string;
+}
+
+export async function convert(input: string, format: Format, o: ConvertOptions = {}): Promise<Report> {
+  const { buf, bytes, abs } = await readInput(input);
+  return finish(open(buf).rotate(), format, o, outputPathFor(abs, "", format, o.output), bytes);
+}
+
+/** A small JPEG preview for chat clients that render image content. */
+export async function preview(file: string, max = 320): Promise<{ data: string; mimeType: "image/jpeg" }> {
+  const buf = await sharp(file, { limitInputPixels: MAX_PIXELS })
+    .resize({ width: max, height: max, fit: "inside", withoutEnlargement: true })
+    .flatten({ background: "#ffffff" })
+    .jpeg({ quality: 70 })
+    .toBuffer();
+  return { data: buf.toString("base64"), mimeType: "image/jpeg" };
+}

package/src/index.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * roundcut-mcp: local image tools as MCP tools, by RoundCut (https://roundcut.app).
+ * stdio transport. stdout is the protocol channel: log only through console.error.
+ */
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod/v4";
+import { FORMATS, circleCrop, compress, convert, crop, info, preview, resize, type Report } from "./engine.js";
+
+const VERSION = "0.1.0";
+const SITE = "https://roundcut.app";
+
+const format = z.enum(FORMATS);
+const quality = z.number().int().min(1).max(100).optional().describe("Lossy quality 1-100 (default 80). Ignored for png.");
+const background = z.string().optional().describe("CSS color used to flatten transparency when the output is jpeg (default #ffffff).");
+const output = z.string().optional().describe("Output file path. Default: next to the input, with a suffix and the right extension.");
+const withPreview = z.boolean().optional().describe("Attach a small JPEG preview to the result (default true).");
+
+type Content =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: "image/jpeg" }
+  | { type: "resource_link"; uri: string; name: string; mimeType: string };
+
+function sizeDelta(r: Report): string {
+  if (!r.inputBytes) return "";
+  const d = Math.round((1 - r.bytes / r.inputBytes) * 100);
+  return d >= 0 ? `${d}% smaller than` : `${-d}% larger than`;
+}
+
+async function result(r: Report, wantPreview: boolean | undefined, line: string) {
+  const text = [
+    line,
+    r.output,
+    `${r.width}x${r.height} ${r.format}, ${r.bytes.toLocaleString()} bytes (${sizeDelta(r)} the ${r.inputBytes.toLocaleString()}-byte input)`,
+  ].join("\n");
+  const content: Content[] = [
+    { type: "text", text },
+    { type: "resource_link", uri: `file://${r.output}`, name: r.output.split("/").pop() ?? r.output, mimeType: `image/${r.format}` },
+  ];
+  if (wantPreview ?? true) content.push({ type: "image", ...(await preview(r.output)) });
+  return { content, structuredContent: { ...r } };
+}
+
+function fail(err: unknown) {
+  const msg = err instanceof Error ? err.message : String(err);
+  return { content: [{ type: "text" as const, text: msg }], isError: true as const };
+}
+
+export function buildServer(): McpServer {
+  const server = new McpServer({ name: "roundcut-mcp", version: VERSION });
+
+  server.registerTool(
+    "image_info",
+    {
+      title: "Image info",
+      description: "Read format, dimensions, alpha and EXIF orientation of an image file.",
+      inputSchema: z.object({ input: z.string().describe("Path to a JPG, PNG, WebP, AVIF, GIF, TIFF or HEIC file.") }),
+      annotations: { readOnlyHint: true },
+    },
+    async ({ input }) => {
+      try {
+        const i = await info(input);
+        return { content: [{ type: "text", text: JSON.stringify(i, null, 2) }], structuredContent: i };
+      } catch (e) {
+        return fail(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "circle_crop",
+    {
+      title: "Circle crop",
+      description:
+        "Make a round profile picture: center-square crop plus a circular transparent mask. png (default), webp and avif keep the transparent corners; jpeg flattens them onto a background color.",
+      inputSchema: z.object({
+        input: z.string(),
+        output,
+        size: z.number().int().min(16).max(8192).optional().describe("Output side in pixels (default: the largest centered square)."),
+        format: format.optional(),
+        quality,
+        background,
+        preview: withPreview,
+      }),
+    },
+    async ({ input, preview: p, ...o }) => {
+      try {
+        return await result(await circleCrop(input, o), p, "Circle crop done.");
+      } catch (e) {
+        return fail(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "crop_image",
+    {
+      title: "Crop image",
+      description: "Crop to a pixel box (left, top, width, height) or to a centered aspect ratio such as 1:1, 4:5 or 16:9.",
+      inputSchema: z.object({
+        input: z.string(),
+        output,
+        left: z.number().int().min(0).optional(),
+        top: z.number().int().min(0).optional(),
+        width: z.number().int().min(1).optional(),
+        height: z.number().int().min(1).optional(),
+        aspect: z.string().regex(/^\d+:\d+$/).optional().describe("Centered crop to this ratio, e.g. 16:9. Overrides the pixel box."),
+        format: format.optional(),
+        quality,
+        background,
+        preview: withPreview,
+      }),
+    },
+    async ({ input, preview: p, ...o }) => {
+      try {
+        return await result(await crop(input, o), p, "Crop done.");
+      } catch (e) {
+        return fail(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "resize_image",
+    {
+      title: "Resize image",
+      description: "Resize by width, height or percent. Keeps the aspect ratio (fit=inside) and never enlarges unless enlarge=true. Lanczos3 resampling.",
+      inputSchema: z.object({
+        input: z.string(),
+        output,
+        width: z.number().int().min(1).max(16384).optional(),
+        height: z.number().int().min(1).max(16384).optional(),
+        percent: z.number().min(1).max(400).optional(),
+        fit: z.enum(["inside", "cover", "fill"]).optional(),
+        enlarge: z.boolean().optional(),
+        format: format.optional(),
+        quality,
+        background,
+        preview: withPreview,
+      }),
+    },
+    async ({ input, preview: p, ...o }) => {
+      try {
+        return await result(await resize(input, o), p, "Resize done.");
+      } catch (e) {
+        return fail(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "compress_image",
+    {
+      title: "Compress image",
+      description: "Smaller file, same format. jpg/webp/avif re-encode at `quality` (default 80, mozjpeg for jpg); png is recompressed losslessly.",
+      inputSchema: z.object({ input: z.string(), output, quality, preview: withPreview }),
+    },
+    async ({ input, preview: p, ...o }) => {
+      try {
+        return await result(await compress(input, o), p, "Compress done.");
+      } catch (e) {
+        return fail(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "convert_image",
+    {
+      title: "Convert image",
+      description: "Convert between jpeg, png, webp and avif (the input may also be GIF, TIFF or HEIC). Transparency is kept except for jpeg, which is flattened onto `background`.",
+      inputSchema: z.object({ input: z.string(), format, output, quality, background, preview: withPreview }),
+    },
+    async ({ input, format: f, preview: p, ...o }) => {
+      try {
+        return await result(await convert(input, f, o), p, `Converted to ${f}.`);
+      } catch (e) {
+        return fail(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "roundcut_web_tools",
+    {
+      title: "RoundCut web tools",
+      description:
+        "Links to the RoundCut browser tools for what this server does not do locally: AI background removal, AI upscaling, batch conversion and image-to-PDF. Free, 29 languages.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: true },
+    },
+    async () => ({
+      content: [
+        {
+          type: "text",
+          text: [
+            `Background remover: ${SITE}/background-remover/`,
+            `AI upscaler: ${SITE}/upscale-2x/`,
+            `Batch convert: ${SITE}/convert/`,
+            `JPG to PDF: ${SITE}/jpg-to-pdf/`,
+            `All tools: ${SITE}/`,
+          ].join("\n"),
+        },
+      ],
+    }),
+  );
+
+  return server;
+}
+
+const entry = process.argv[1] ? process.argv[1].split("/").pop() ?? "" : "";
+if (entry && import.meta.url.endsWith(entry)) {
+  const handle = serveStdio(buildServer);
+  process.on("SIGINT", () => {
+    void handle.close();
+  });
+}