@rog0x/mcp-image-tools 1.0.0

package/dist/tools/placeholder-generator.d.ts

@@ -0,0 +1,26 @@
+export interface PlaceholderConfig {
+    width: number;
+    height?: number;
+    backgroundColor?: string;
+    textColor?: string;
+    text?: string;
+    format?: "png" | "jpg" | "jpeg" | "gif" | "webp" | "svg";
+    font?: string;
+    fontSize?: number;
+}
+export interface PlaceholderResult {
+    url: string;
+    width: number;
+    height: number;
+    backgroundColor: string;
+    textColor: string;
+    text: string;
+    format: string;
+    htmlImg: string;
+    markdownImg: string;
+}
+export declare function generatePlaceholder(config: PlaceholderConfig): PlaceholderResult;
+export declare function generatePlaceholderSet(sizes: Array<{
+    width: number;
+    height?: number;
+}>, options?: Omit<PlaceholderConfig, "width" | "height">): PlaceholderResult[];

package/dist/tools/placeholder-generator.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePlaceholder = generatePlaceholder;
+exports.generatePlaceholderSet = generatePlaceholderSet;
+function generatePlaceholder(config) {
+    const width = Math.max(1, Math.min(config.width, 4000));
+    const height = config.height ? Math.max(1, Math.min(config.height, 4000)) : width;
+    const bgColor = (config.backgroundColor || "cccccc").replace(/^#/, "");
+    const txtColor = (config.textColor || "333333").replace(/^#/, "");
+    const format = config.format || "png";
+    const text = config.text || `${width}x${height}`;
+    // Build placehold.co URL
+    let url = `https://placehold.co/${width}x${height}/${bgColor}/${txtColor}`;
+    // Add format
+    url += `.${format}`;
+    // Add query params
+    const params = new URLSearchParams();
+    if (config.text) {
+        params.set("text", config.text);
+    }
+    if (config.font) {
+        params.set("font", config.font);
+    }
+    if (config.fontSize) {
+        params.set("font-size", config.fontSize.toString());
+    }
+    const queryString = params.toString();
+    if (queryString) {
+        url += `?${queryString}`;
+    }
+    const alt = `Placeholder ${width}x${height}`;
+    return {
+        url,
+        width,
+        height,
+        backgroundColor: `#${bgColor}`,
+        textColor: `#${txtColor}`,
+        text,
+        format,
+        htmlImg: `<img src="${url}" alt="${alt}" width="${width}" height="${height}" />`,
+        markdownImg: `![${alt}](${url})`,
+    };
+}
+function generatePlaceholderSet(sizes, options) {
+    return sizes.map((size) => generatePlaceholder({
+        ...options,
+        width: size.width,
+        height: size.height,
+    }));
+}

package/dist/tools/responsive-images.d.ts

@@ -0,0 +1,22 @@
+export interface ResponsiveConfig {
+    baseUrl: string;
+    alt?: string;
+    widths?: number[];
+    sizes?: string;
+    className?: string;
+    loading?: "lazy" | "eager";
+    formats?: string[];
+}
+export interface ResponsiveResult {
+    baseUrl: string;
+    variants: ImageVariant[];
+    srcsetAttr: string;
+    imgTag: string;
+    pictureTag: string;
+}
+export interface ImageVariant {
+    url: string;
+    width: number;
+    descriptor: string;
+}
+export declare function generateResponsiveImages(config: ResponsiveConfig): ResponsiveResult;

package/dist/tools/responsive-images.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateResponsiveImages = generateResponsiveImages;
+function inferImageFormat(url) {
+    const pathname = new URL(url).pathname.toLowerCase();
+    if (pathname.endsWith(".webp"))
+        return "webp";
+    if (pathname.endsWith(".avif"))
+        return "avif";
+    if (pathname.endsWith(".png"))
+        return "png";
+    if (pathname.endsWith(".gif"))
+        return "gif";
+    if (pathname.endsWith(".svg"))
+        return "svg";
+    return "jpeg";
+}
+function buildVariantUrl(baseUrl, width) {
+    // Append width parameter - handles both existing and new query strings
+    const url = new URL(baseUrl);
+    url.searchParams.set("w", width.toString());
+    return url.href;
+}
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/"/g, """)
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function generateResponsiveImages(config) {
+    const defaultWidths = [320, 640, 768, 1024, 1280, 1536, 1920];
+    const widths = config.widths || defaultWidths;
+    const alt = config.alt || "";
+    const sizes = config.sizes || "(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw";
+    const loading = config.loading || "lazy";
+    const className = config.className || "";
+    const formats = config.formats || ["webp", inferImageFormat(config.baseUrl)];
+    const sortedWidths = [...widths].sort((a, b) => a - b);
+    // Generate variants
+    const variants = sortedWidths.map((width) => ({
+        url: buildVariantUrl(config.baseUrl, width),
+        width,
+        descriptor: `${width}w`,
+    }));
+    // Build srcset attribute
+    const srcsetAttr = variants
+        .map((v) => `${v.url} ${v.descriptor}`)
+        .join(",\n    ");
+    // Build simple <img> tag with srcset
+    const classAttr = className ? ` class="${escapeHtml(className)}"` : "";
+    const imgTag = [
+        `<img`,
+        `  src="${escapeHtml(config.baseUrl)}"`,
+        `  srcset="${srcsetAttr}"`,
+        `  sizes="${escapeHtml(sizes)}"`,
+        `  alt="${escapeHtml(alt)}"`,
+        `  loading="${loading}"`,
+        className ? `  class="${escapeHtml(className)}"` : null,
+        `/>`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    // Build <picture> element with multiple formats
+    const sourceElements = formats.map((format) => {
+        const formatVariants = sortedWidths.map((width) => {
+            const url = new URL(config.baseUrl);
+            url.searchParams.set("w", width.toString());
+            url.searchParams.set("fm", format);
+            return `${url.href} ${width}w`;
+        });
+        const formatSrcset = formatVariants.join(",\n      ");
+        const mimeType = format === "jpg" || format === "jpeg"
+            ? "image/jpeg"
+            : format === "avif"
+                ? "image/avif"
+                : format === "webp"
+                    ? "image/webp"
+                    : format === "png"
+                        ? "image/png"
+                        : `image/${format}`;
+        return `  <source\n    type="${mimeType}"\n    srcset="${formatSrcset}"\n    sizes="${escapeHtml(sizes)}"\n  />`;
+    });
+    const pictureTag = [
+        `<picture${classAttr}>`,
+        ...sourceElements,
+        `  <img`,
+        `    src="${escapeHtml(config.baseUrl)}"`,
+        `    alt="${escapeHtml(alt)}"`,
+        `    loading="${loading}"`,
+        `  />`,
+        `</picture>`,
+    ].join("\n");
+    return {
+        baseUrl: config.baseUrl,
+        variants,
+        srcsetAttr,
+        imgTag,
+        pictureTag,
+    };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@rog0x/mcp-image-tools",
+  "version": "1.0.0",
+  "description": "MCP server providing image analysis tools for AI agents - metadata, favicons, OG images, placeholders, responsive markup",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-image-tools": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "ai",
+    "image-tools",
+    "metadata",
+    "favicon",
+    "og-image",
+    "responsive-images"
+  ],
+  "author": "rog0x",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rog0x/mcp-image-tools"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { getImageMetadata } from "./tools/image-meta.js";
+import { findFavicons } from "./tools/favicon-finder.js";
+import { extractOgImage } from "./tools/og-image.js";
+import { generatePlaceholder, generatePlaceholderSet } from "./tools/placeholder-generator.js";
+import { generateResponsiveImages } from "./tools/responsive-images.js";
+
+const server = new Server(
+  {
+    name: "mcp-image-tools",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "image_metadata",
+      description:
+        "Read image metadata from a URL via HTTP headers: content-type, file size, last-modified, etag, cache info. No image downloading required.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          url: {
+            type: "string",
+            description: "Direct URL to an image file",
+          },
+        },
+        required: ["url"],
+      },
+    },
+    {
+      name: "find_favicons",
+      description:
+        "Find all favicons for a website. Checks /favicon.ico, parses HTML link tags, and inspects manifest.json. Returns all found favicons with sizes and types.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          url: {
+            type: "string",
+            description: "Website URL to find favicons for (e.g. https://example.com)",
+          },
+        },
+        required: ["url"],
+      },
+    },
+    {
+      name: "extract_og_image",
+      description:
+        "Extract Open Graph image, Twitter card image, and Apple touch icon from any URL. Returns all social media preview images found on the page.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          url: {
+            type: "string",
+            description: "URL of the web page to extract images from",
+          },
+        },
+        required: ["url"],
+      },
+    },
+    {
+      name: "generate_placeholder",
+      description:
+        "Generate placeholder image URLs via placehold.co. Supports custom size, colors, text, format, and font. Returns URL plus ready-to-use HTML and Markdown markup.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          width: {
+            type: "number",
+            description: "Image width in pixels (1-4000)",
+          },
+          height: {
+            type: "number",
+            description: "Image height in pixels (1-4000). Defaults to same as width.",
+          },
+          backgroundColor: {
+            type: "string",
+            description: "Background color hex without # (e.g. 'cccccc'). Default: cccccc",
+          },
+          textColor: {
+            type: "string",
+            description: "Text color hex without # (e.g. '333333'). Default: 333333",
+          },
+          text: {
+            type: "string",
+            description: "Custom text to display on the image. Default: WIDTHxHEIGHT",
+          },
+          format: {
+            type: "string",
+            description: "Image format: png, jpg, jpeg, gif, webp, svg. Default: png",
+            enum: ["png", "jpg", "jpeg", "gif", "webp", "svg"],
+          },
+          font: {
+            type: "string",
+            description: "Font name (e.g. 'roboto', 'open-sans', 'montserrat')",
+          },
+          fontSize: {
+            type: "number",
+            description: "Font size in pixels",
+          },
+          sizes: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                width: { type: "number" },
+                height: { type: "number" },
+              },
+              required: ["width"],
+            },
+            description:
+              "Generate multiple placeholders at once. If provided, width/height params are ignored.",
+          },
+        },
+        required: ["width"],
+      },
+    },
+    {
+      name: "responsive_images",
+      description:
+        "Generate srcset and <picture> element HTML for responsive images. Given a base image URL, produces multiple size variants with proper HTML markup for responsive design.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          baseUrl: {
+            type: "string",
+            description: "Base image URL that accepts width/format query parameters",
+          },
+          alt: {
+            type: "string",
+            description: "Alt text for the image",
+          },
+          widths: {
+            type: "array",
+            items: { type: "number" },
+            description:
+              "Array of widths to generate (default: [320, 640, 768, 1024, 1280, 1536, 1920])",
+          },
+          sizes: {
+            type: "string",
+            description:
+              "CSS sizes attribute (default: '(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw')",
+          },
+          className: {
+            type: "string",
+            description: "CSS class name to add to the element",
+          },
+          loading: {
+            type: "string",
+            description: "Loading strategy: 'lazy' or 'eager' (default: lazy)",
+            enum: ["lazy", "eager"],
+          },
+          formats: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Image formats for <picture> sources (default: ['webp', auto-detected original format])",
+          },
+        },
+        required: ["baseUrl"],
+      },
+    },
+  ],
+}));
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "image_metadata": {
+        const result = await getImageMetadata(args?.url as string);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "find_favicons": {
+        const result = await findFavicons(args?.url as string);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "extract_og_image": {
+        const result = await extractOgImage(args?.url as string);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "generate_placeholder": {
+        const sizes = args?.sizes as Array<{ width: number; height?: number }> | undefined;
+        if (sizes && sizes.length > 0) {
+          const results = generatePlaceholderSet(sizes, {
+            backgroundColor: args?.backgroundColor as string | undefined,
+            textColor: args?.textColor as string | undefined,
+            text: args?.text as string | undefined,
+            format: args?.format as "png" | "jpg" | "jpeg" | "gif" | "webp" | "svg" | undefined,
+            font: args?.font as string | undefined,
+            fontSize: args?.fontSize as number | undefined,
+          });
+          return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+          };
+        }
+        const result = generatePlaceholder({
+          width: args?.width as number,
+          height: args?.height as number | undefined,
+          backgroundColor: args?.backgroundColor as string | undefined,
+          textColor: args?.textColor as string | undefined,
+          text: args?.text as string | undefined,
+          format: args?.format as "png" | "jpg" | "jpeg" | "gif" | "webp" | "svg" | undefined,
+          font: args?.font as string | undefined,
+          fontSize: args?.fontSize as number | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "responsive_images": {
+        const result = generateResponsiveImages({
+          baseUrl: args?.baseUrl as string,
+          alt: args?.alt as string | undefined,
+          widths: args?.widths as number[] | undefined,
+          sizes: args?.sizes as string | undefined,
+          className: args?.className as string | undefined,
+          loading: args?.loading as "lazy" | "eager" | undefined,
+          formats: args?.formats as string[] | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP Image Tools server running on stdio");
+}
+
+main().catch(console.error);