imgcli-mcp 0.2.0

package/README.md

@@ -0,0 +1,93 @@
+# imgcli-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that exposes
+[imgcli](https://github.com/swperb/imgcli) as native tools for AI agents, so a
+model can convert and process images by calling tools instead of shelling out.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `convert_image` | Convert / resize / crop / rotate / filter / composite an image. Args: `input`, `output`, optional `filters` (ffmpeg-style chain), `quality`, `overwrite`. Returns imgcli's JSON result. |
+| `probe_image` | Return an image's width/height/channels without converting. |
+| `list_filters` | List the full filter catalogue. |
+
+All arguments are passed to imgcli as an argv array (no shell), so there is no
+shell-injection surface.
+
+## Prerequisites
+
+The `imgcli` binary must be installed:
+
+```sh
+brew install swperb/tap/imgcli      # or build from source: make && sudo make install
+```
+
+If it isn't on `PATH`, set `IMGCLI_BIN` to its absolute path.
+
+## Run
+
+```sh
+npm install      # builds dist/ via the prepare script
+npm start        # stdio MCP server
+# or, once published to npm:
+npx imgcli-mcp
+```
+
+## Configure in a client
+
+Claude Desktop / Cursor / any MCP client (`mcpServers` config):
+
+```json
+{
+  "mcpServers": {
+    "imgcli": {
+      "command": "npx",
+      "args": ["-y", "imgcli-mcp"],
+      "env": { "IMGCLI_BIN": "imgcli" }
+    }
+  }
+}
+```
+
+Or point `command` at `node` and `args` at the built `dist/index.js` for a local checkout.
+
+## Example calls
+
+```jsonc
+// convert_image
+{ "input": "photo.jpg", "output": "thumb.png", "filters": "scale=256:-1,grayscale" }
+// -> {"ok":true,"output":"thumb.png","width":256,"height":171,"format":"png","bytes":34122}
+
+// probe_image
+{ "input": "photo.jpg" }
+// -> {"ok":true,"inputs":[{"path":"photo.jpg","width":4000,"height":3000,"channels":4}]}
+```
+
+## Publishing
+
+Two stages — **npm first**, then the **MCP registry** (the registry verifies the
+npm package's `mcpName` field against the server `name`).
+
+```sh
+# 1. Publish to npm (needs `npm login`). Package is public via publishConfig.
+cd mcp
+npm publish
+
+# 2. Publish metadata to the MCP registry
+brew install mcp-publisher          # (or download from the registry's GitHub releases)
+mcp-publisher login github          # device-flow auth as the io.github.swperb owner
+mcp-publisher validate              # optional: check server.json
+mcp-publisher publish               # publishes server.json
+
+# verify
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.swperb/imgcli"
+```
+
+Ownership is proven by `mcpName` in `package.json` matching `name` in
+`server.json` (`io.github.swperb/imgcli`). On every release keep three versions
+in sync: `package.json` `version`, `server.json` `version`, and the
+`server.json` `packages[].version`.
+
+> The MCP registry is in preview; data resets can occur, so be ready to
+> re-publish. There is no self-service unpublish — publish a new version to update.

package/dist/index.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * imgcli-mcp — an MCP server that exposes the `imgcli` command-line image tool
+ * as native tools for AI agents (Claude Desktop, Cursor, etc.).
+ *
+ * Tools: convert_image, probe_image, list_filters.
+ *
+ * The `imgcli` binary must be installed and on PATH (brew install swperb/tap/imgcli)
+ * or pointed to via the IMGCLI_BIN environment variable. Arguments are passed as
+ * an argv array (execFile, no shell) so there is no shell-injection surface.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { execFile } from "node:child_process";
+const BIN = process.env.IMGCLI_BIN || "imgcli";
+function run(args) {
+    return new Promise((resolve) => {
+        execFile(BIN, args, { timeout: 60_000, maxBuffer: 8 * 1024 * 1024 }, (err, stdout, stderr) => {
+            const code = err && typeof err.code === "number"
+                ? (err.code)
+                : err ? 1 : 0;
+            resolve({ code, stdout: stdout ?? "", stderr: stderr ?? "" });
+        });
+    });
+}
+/** Parse imgcli's JSON line from stdout (success) or stderr (error). */
+function parseJsonLine(text) {
+    const line = text.trim().split("\n").filter(Boolean).pop();
+    if (!line)
+        return null;
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+const server = new McpServer({ name: "imgcli", version: "0.2.0" });
+server.registerTool("convert_image", {
+    title: "Convert / process an image",
+    description: "Convert, resize, crop, rotate, filter, or composite an image with imgcli. " +
+        "Output format is chosen from the output file extension (png/jpg/jpeg/bmp/tga/ppm). " +
+        "Use `filters` for an ffmpeg-style comma-separated chain, e.g. " +
+        '"scale=800:-1,grayscale,gblur=2". Call list_filters for the full catalogue.',
+    inputSchema: {
+        input: z.string().describe("Path to the input image file (or a generator like 'testsrc=640x480')."),
+        output: z.string().describe("Path to write; the extension picks the format (png/jpg/bmp/tga/ppm)."),
+        filters: z.string().optional().describe('Filtergraph, e.g. "scale=512:-1,grayscale". Omit for a plain format conversion.'),
+        quality: z.number().int().min(1).max(100).optional().describe("JPEG quality 1-100 (default 90; ignored for non-JPEG)."),
+        overwrite: z.boolean().optional().describe("Overwrite the output if it exists (default true)."),
+    },
+}, async ({ input, output, filters, quality, overwrite }) => {
+    const args = ["--json", "-i", input];
+    if (filters)
+        args.push("-vf", filters);
+    if (quality != null)
+        args.push("-q", String(quality));
+    args.push(overwrite === false ? "-n" : "-y", output);
+    const { code, stdout, stderr } = await run(args);
+    const result = parseJsonLine(code === 0 ? stdout : stderr) ?? {
+        ok: false,
+        error: (stderr || stdout || `imgcli exited with code ${code}`).trim(),
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        isError: code !== 0,
+    };
+});
+server.registerTool("probe_image", {
+    title: "Probe image dimensions",
+    description: "Return the width, height, and channel count of an image without converting it.",
+    inputSchema: { input: z.string().describe("Path to the input image file.") },
+}, async ({ input }) => {
+    const { code, stdout, stderr } = await run(["--json", "-info", "-i", input]);
+    const result = parseJsonLine(code === 0 ? stdout : stderr) ?? {
+        ok: false,
+        error: (stderr || stdout || `imgcli exited with code ${code}`).trim(),
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result) }], isError: code !== 0 };
+});
+server.registerTool("list_filters", {
+    title: "List available filters",
+    description: "List the full imgcli filter catalogue (geometry, colour, convolution, compositing).",
+    inputSchema: {},
+}, async () => {
+    const { stdout } = await run(["-filters"]);
+    return { content: [{ type: "text", text: stdout.trim() || "no output" }] };
+});
+async function main() {
+    await server.connect(new StdioServerTransport());
+    // stderr is safe for logs; stdout is reserved for the MCP protocol.
+    process.stderr.write(`imgcli-mcp ready (binary: ${BIN})\n`);
+}
+main().catch((e) => {
+    process.stderr.write(`imgcli-mcp fatal: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "imgcli-mcp",
+  "version": "0.2.0",
+  "mcpName": "io.github.swperb/imgcli",
+  "description": "MCP server exposing imgcli — convert, resize, crop, filter & composite images as native agent tools",
+  "keywords": ["mcp", "model-context-protocol", "image", "image-conversion", "imgcli", "resize", "convert", "ffmpeg", "imagemagick", "agent", "tool"],
+  "homepage": "https://github.com/swperb/imgcli/tree/main/mcp",
+  "repository": { "type": "git", "url": "git+https://github.com/swperb/imgcli.git", "directory": "mcp" },
+  "license": "MIT",
+  "author": "swperb",
+  "bugs": { "url": "https://github.com/swperb/imgcli/issues" },
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "bin": { "imgcli-mcp": "dist/index.js" },
+  "files": ["dist", "README.md", "server.json"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^20.14.0"
+  }
+}

package/server.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.swperb/imgcli",
+  "description": "Convert, resize, crop, filter & composite images via the imgcli CLI (lightweight, no deps)",
+  "version": "0.2.0",
+  "repository": {
+    "url": "https://github.com/swperb/imgcli",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "imgcli-mcp",
+      "version": "0.2.0",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        {
+          "name": "IMGCLI_BIN",
+          "description": "Path to the imgcli binary if not on PATH (e.g. after `brew install swperb/tap/imgcli`).",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}