placeholder-image-mcp 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# placeholder-image-mcp
+
+Generates PNG placeholder images with colored background and text. Support batch generate.
+
+## Installation
+
+```bash
+git clone https://github.com/RainbowCockroach/placeholder-image-mcp.git
+cd placeholder-image-mcp
+npm install
+npm run build
+```
+
+Then register it as an MCP server in your agent's config (check the documentation in of your AI agent). Or just ask it to install this MCP for you. It's good at doing that.
+
+## Usage
+
+Once connected, just ask your agent to generate placeholder images. It will call the tool automatically.
+
+**Examples:**
+
+- "Create 64x64 image and save it to desktop"
+- "Create three placeholder banners at 100x100 with text "frog", save to {some folder}"
+- "Create 200x200 pink image, show its dimension"
+
+Two calling modes:
+
+### Individual images
+
+Each image has its own size, text, color, and output path:
+
+```json
+{
+  "images": [
+    { "width": 800, "height": 600, "text": "ss", "path": "hero.png" },
+    {
+      "width": 400,
+      "height": 300,
+      "text": "Frog",
+      "color": "#1a874f",
+      "path": "frog.png"
+    }
+  ]
+}
+```
+
+### Batch (same config, multiple files)
+
+One config applied to multiple paths — each file gets a different random color:
+
+```json
+{
+  "config": { "width": 600, "height": 400, "text": "Yayaya" },
+  "paths": ["is-cucumber.png", "fruit.png", "or-veggie.png"]
+}
+```
+
+## Parameters
+
+| Parameter | Type   | Required | Description                                                                                                           |
+| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `width`   | number | yes      | Width in pixels (1–8192)                                                                                              |
+| `height`  | number | yes      | Height in pixels (1–8192)                                                                                             |
+| `text`    | string | no       | Centered text. Use `"ss"` to show dimensions (e.g. `800×600`). Blank by default.                                      |
+| `color`   | string | no       | Hex background color (e.g. `#A8D8EA`). Omit for random.                                                               |
+| `path`    | string | yes      | Output path. Relative paths resolve against the `CLAUDE_CWD` env var if set, otherwise the process working directory. |
+
+## Color palette
+
+30 soft pastel colors chosen to look good as backgrounds:
+
+```
+#A8D8EA  #AA96DA  #FCBAD3  #FFFFD2  #B5EAD7  #E2F0CB  #C7CEEA
+#FFB7B2  #FFDAC1  #F0E6EF  #95B8D1  #DDA0DD  #98D8C8  #F7DC6F
+#AED6F1  #D5AAFF  #85E3FF  #BAFFC9  #FFE156  #FF9AA2  #D4A5A5
+#A0CED9  #FFC75F  #C3B1E1  #B4F8C8  #FFE5B4  #E0BBE4  #957DAD
+#D291BC  #FEC8D8
+```
+
+Text is automatically black or white based on WCAG 2.0 contrast ratio.

package/dist/colors.d.ts

@@ -0,0 +1,22 @@
+export declare const PALETTE: readonly ["#A8D8EA", "#AA96DA", "#FCBAD3", "#FFFFD2", "#B5EAD7", "#E2F0CB", "#C7CEEA", "#FFB7B2", "#FFDAC1", "#F0E6EF", "#95B8D1", "#DDA0DD", "#98D8C8", "#F7DC6F", "#AED6F1", "#D5AAFF", "#85E3FF", "#BAFFC9", "#FFE156", "#FF9AA2", "#D4A5A5", "#A0CED9", "#FFC75F", "#C3B1E1", "#B4F8C8", "#FFE5B4", "#E0BBE4", "#957DAD", "#D291BC", "#FEC8D8"];
+/**
+ * Parse a hex color string to RGB components.
+ */
+export declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Compute relative luminance per WCAG 2.0.
+ * Returns a value between 0 (black) and 1 (white).
+ */
+export declare function relativeLuminance(hex: string): number;
+/**
+ * Pick a high-contrast text color (black or white) for the given background.
+ */
+export declare function contrastTextColor(bgHex: string): string;
+/**
+ * Pick a random color from the palette, optionally excluding certain colors.
+ */
+export declare function randomColor(exclude?: Set<string>): string;

package/dist/colors.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PALETTE = void 0;
+exports.hexToRgb = hexToRgb;
+exports.relativeLuminance = relativeLuminance;
+exports.contrastTextColor = contrastTextColor;
+exports.randomColor = randomColor;
+// Curated palette of easy-on-the-eyes colors
+// Muted pastels and soft tones that work well as placeholder backgrounds
+exports.PALETTE = [
+    "#A8D8EA", // soft sky blue
+    "#AA96DA", // lavender
+    "#FCBAD3", // soft pink
+    "#FFFFD2", // cream yellow
+    "#B5EAD7", // mint green
+    "#E2F0CB", // light lime
+    "#C7CEEA", // periwinkle
+    "#FFB7B2", // salmon pink
+    "#FFDAC1", // peach
+    "#F0E6EF", // pale mauve
+    "#95B8D1", // steel blue
+    "#DDA0DD", // plum
+    "#98D8C8", // seafoam
+    "#F7DC6F", // soft gold
+    "#AED6F1", // light cornflower
+    "#D5AAFF", // soft violet
+    "#85E3FF", // baby blue
+    "#BAFFC9", // light mint
+    "#FFE156", // warm yellow
+    "#FF9AA2", // rose
+    "#D4A5A5", // dusty rose
+    "#A0CED9", // powder blue
+    "#FFC75F", // mango
+    "#C3B1E1", // wisteria
+    "#B4F8C8", // spring green
+    "#FFE5B4", // bisque
+    "#E0BBE4", // thistle
+    "#957DAD", // muted purple
+    "#D291BC", // orchid pink
+    "#FEC8D8", // blush
+];
+/**
+ * Parse a hex color string to RGB components.
+ */
+function hexToRgb(hex) {
+    const clean = hex.replace("#", "");
+    return {
+        r: parseInt(clean.substring(0, 2), 16),
+        g: parseInt(clean.substring(2, 4), 16),
+        b: parseInt(clean.substring(4, 6), 16),
+    };
+}
+/**
+ * Compute relative luminance per WCAG 2.0.
+ * Returns a value between 0 (black) and 1 (white).
+ */
+function relativeLuminance(hex) {
+    const { r, g, b } = hexToRgb(hex);
+    const [rs, gs, bs] = [r / 255, g / 255, b / 255].map((c) => c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+    return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+/**
+ * Pick a high-contrast text color (black or white) for the given background.
+ */
+function contrastTextColor(bgHex) {
+    return relativeLuminance(bgHex) > 0.4 ? "#222222" : "#FFFFFF";
+}
+/**
+ * Pick a random color from the palette, optionally excluding certain colors.
+ */
+function randomColor(exclude) {
+    const available = exclude
+        ? exports.PALETTE.filter((c) => !exclude.has(c))
+        : [...exports.PALETTE];
+    if (available.length === 0) {
+        // All colors used — reset and allow duplicates
+        return exports.PALETTE[Math.floor(Math.random() * exports.PALETTE.length)];
+    }
+    return available[Math.floor(Math.random() * available.length)];
+}

package/dist/generate.d.ts

@@ -0,0 +1,33 @@
+export interface ImageConfig {
+    width: number;
+    height: number;
+    text?: string;
+    color?: string;
+    path: string;
+}
+/**
+ * Generate a single placeholder image and save it to disk.
+ */
+export declare function generateImage(config: ImageConfig, assignedColor?: string): Promise<{
+    path: string;
+    color: string;
+    width: number;
+    height: number;
+}>;
+/**
+ * Generate multiple placeholder images.
+ * - If `images` is provided: each entry is a full config.
+ * - If `config` + `count` + `paths` is provided: generate `count` images
+ *   from one config template, each with a different random color.
+ */
+export declare function generateImages(params: {
+    images: ImageConfig[];
+} | {
+    config: Omit<ImageConfig, "path">;
+    paths: string[];
+}): Promise<{
+    path: string;
+    color: string;
+    width: number;
+    height: number;
+}[]>;

package/dist/generate.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateImage = generateImage;
+exports.generateImages = generateImages;
+const sharp_1 = __importDefault(require("sharp"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const colors_js_1 = require("./colors.js");
+/**
+ * Resolve a file path relative to the Claude Code project directory.
+ * - If the path is absolute, use it as-is
+ * - If relative, resolve it relative to CLAUDE_CWD env var (if set) or process.cwd()
+ */
+function resolvePath(filePath) {
+    if (path_1.default.isAbsolute(filePath)) {
+        return filePath;
+    }
+    // Use CLAUDE_CWD if set (for multi-folder workspaces or future enhancements)
+    // Otherwise use process.cwd()
+    const baseDir = process.env.CLAUDE_CWD || process.cwd();
+    return path_1.default.resolve(baseDir, filePath);
+}
+/**
+ * Escape special XML characters for safe SVG embedding.
+ */
+function escapeXml(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * Build an SVG string for the placeholder image.
+ */
+function buildSvg(width, height, bgColor, text) {
+    const textColor = (0, colors_js_1.contrastTextColor)(bgColor);
+    // Scale font size relative to image dimensions
+    const minDim = Math.min(width, height);
+    let fontSize = Math.max(12, Math.floor(minDim / 8));
+    // For long text, shrink font to fit within ~80% of width
+    if (text.length > 0) {
+        const maxTextWidth = width * 0.8;
+        const estimatedCharWidth = fontSize * 0.6;
+        const estimatedTextWidth = text.length * estimatedCharWidth;
+        if (estimatedTextWidth > maxTextWidth) {
+            fontSize = Math.max(10, Math.floor(maxTextWidth / (text.length * 0.6)));
+        }
+    }
+    let textElement = "";
+    if (text.length > 0) {
+        textElement = `
+    <text
+      x="50%" y="50%"
+      dominant-baseline="central"
+      text-anchor="middle"
+      font-family="Arial, Helvetica, sans-serif"
+      font-size="${fontSize}"
+      font-weight="600"
+      fill="${textColor}"
+    >${escapeXml(text)}</text>`;
+    }
+    return `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">
+  <rect width="100%" height="100%" fill="${bgColor}"/>
+  ${textElement}
+</svg>`;
+}
+/**
+ * Generate a single placeholder image and save it to disk.
+ */
+async function generateImage(config, assignedColor) {
+    const bgColor = config.color || assignedColor || (0, colors_js_1.randomColor)();
+    // Resolve text
+    let displayText = "";
+    if (config.text === "ss") {
+        displayText = `${config.width}\u00D7${config.height}`;
+    }
+    else if (config.text !== undefined && config.text !== "") {
+        displayText = config.text;
+    }
+    const svg = buildSvg(config.width, config.height, bgColor, displayText);
+    // Ensure output directory exists
+    const outputPath = resolvePath(config.path);
+    const dir = path_1.default.dirname(outputPath);
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    await (0, sharp_1.default)(Buffer.from(svg)).png().toFile(outputPath);
+    return {
+        path: outputPath,
+        color: bgColor,
+        width: config.width,
+        height: config.height,
+    };
+}
+/**
+ * Generate multiple placeholder images.
+ * - If `images` is provided: each entry is a full config.
+ * - If `config` + `count` + `paths` is provided: generate `count` images
+ *   from one config template, each with a different random color.
+ */
+async function generateImages(params) {
+    const usedColors = new Set();
+    if ("images" in params) {
+        const results = await Promise.all(params.images.map((img) => {
+            const color = img.color || (0, colors_js_1.randomColor)(usedColors);
+            usedColors.add(color);
+            return generateImage(img, color);
+        }));
+        return results;
+    }
+    // Batch mode: one config, multiple paths
+    const { config, paths } = params;
+    const results = await Promise.all(paths.map((p) => {
+        const color = config.color || (0, colors_js_1.randomColor)(usedColors);
+        usedColors.add(color);
+        return generateImage({ ...config, path: p }, color);
+    }));
+    return results;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const generate_js_1 = require("./generate.js");
+const ImageConfigSchema = zod_1.z.object({
+    width: zod_1.z.number().int().min(1).max(8192).describe("Image width in pixels"),
+    height: zod_1.z.number().int().min(1).max(8192).describe("Image height in pixels"),
+    text: zod_1.z
+        .string()
+        .optional()
+        .describe('Text to display centered on image. Use "ss" to show dimensions (e.g. "800×600"). Omit or "" for blank.'),
+    color: zod_1.z
+        .string()
+        .regex(/^#[0-9a-fA-F]{6}$/)
+        .optional()
+        .describe("Background color as hex (e.g. #A8D8EA). Omit for random from curated palette."),
+    path: zod_1.z.string().describe("Output file path for the PNG"),
+});
+const server = new mcp_js_1.McpServer({
+    name: "placeholder-image",
+    version: "1.0.0",
+});
+server.tool("generate_placeholder", "Generate one or more placeholder PNG images with colored backgrounds and optional centered text. Supports two modes: (1) provide an array of individual image configs, or (2) provide a single config template with multiple output paths to generate batch images with different random colors.", {
+    images: zod_1.z
+        .array(ImageConfigSchema)
+        .optional()
+        .describe("Array of image configurations. Each gets its own size, text, color, and output path."),
+    config: zod_1.z
+        .object({
+        width: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(8192)
+            .describe("Image width in pixels"),
+        height: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(8192)
+            .describe("Image height in pixels"),
+        text: zod_1.z
+            .string()
+            .optional()
+            .describe('Text to display centered on image. Use "ss" to show dimensions. Omit or "" for blank.'),
+        color: zod_1.z
+            .string()
+            .regex(/^#[0-9a-fA-F]{6}$/)
+            .optional()
+            .describe("Background color as hex. Omit for random (each image gets a different color)."),
+    })
+        .optional()
+        .describe("Single config template for batch mode. Use with `paths` to generate multiple images."),
+    paths: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe("Output file paths for batch mode. Each path produces one image with a different random color."),
+}, async (params) => {
+    try {
+        // Validate: must provide either `images` or `config` + `paths`
+        if (params.images && params.images.length > 0) {
+            const results = await (0, generate_js_1.generateImages)({
+                images: params.images,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Generated ${results.length} image(s):\n${results
+                            .map((r) => `  - ${r.path} (${r.width}x${r.height}, ${r.color})`)
+                            .join("\n")}`,
+                    },
+                ],
+            };
+        }
+        if (params.config && params.paths && params.paths.length > 0) {
+            const results = await (0, generate_js_1.generateImages)({
+                config: params.config,
+                paths: params.paths,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Generated ${results.length} image(s):\n${results
+                            .map((r) => `  - ${r.path} (${r.width}x${r.height}, ${r.color})`)
+                            .join("\n")}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Error: Provide either `images` (array of configs) or `config` + `paths` (batch mode).",
+                },
+            ],
+            isError: true,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error generating images: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "placeholder-image-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for generating placeholder PNG images",
+  "main": "dist/index.js",
+  "bin": {
+    "placeholder-image-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RainbowCockroach/placeholder-image-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "placeholder",
+    "image",
+    "png"
+  ],
+  "author": "RGB Cockroach",
+  "license": "ISC",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/RainbowCockroach/placeholder-image-mcp/issues"
+  },
+  "homepage": "https://github.com/RainbowCockroach/placeholder-image-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "sharp": "^0.34.5",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  }
+}