@rog0x/mcp-image-tools 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# mcp-image-tools
+
+MCP server providing image analysis tools for AI agents. Metadata inspection only -- no image processing or manipulation.
+
+## Tools
+
+### image_metadata
+Read image metadata from a URL using HTTP headers. Returns content-type, file size, last-modified, etag, and cache info without downloading the full image.
+
+### find_favicons
+Find all favicons for any website. Checks `/favicon.ico`, parses HTML `<link>` tags, and inspects `manifest.json`. Returns all discovered favicons with sizes and types.
+
+### extract_og_image
+Extract Open Graph image, Twitter card image, and Apple touch icon from any URL. Useful for generating link previews.
+
+### generate_placeholder
+Generate placeholder image URLs via the placehold.co API. Supports custom dimensions, colors, text, format, and font. Returns the URL plus ready-to-use HTML and Markdown markup. Can generate multiple sizes at once.
+
+### responsive_images
+Generate `srcset` and `<picture>` element HTML for responsive images. Given a base image URL, produces multiple size variants with proper markup for responsive design, including multi-format `<source>` elements.
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Usage with Claude Desktop
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "image-tools": {
+      "command": "node",
+      "args": ["path/to/mcp-image-tools/dist/index.js"]
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const image_meta_js_1 = require("./tools/image-meta.js");
+const favicon_finder_js_1 = require("./tools/favicon-finder.js");
+const og_image_js_1 = require("./tools/og-image.js");
+const placeholder_generator_js_1 = require("./tools/placeholder-generator.js");
+const responsive_images_js_1 = require("./tools/responsive-images.js");
+const server = new index_js_1.Server({
+    name: "mcp-image-tools",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(types_js_1.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",
+                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",
+                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",
+                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",
+                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",
+                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(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "image_metadata": {
+                const result = await (0, image_meta_js_1.getImageMetadata)(args?.url);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "find_favicons": {
+                const result = await (0, favicon_finder_js_1.findFavicons)(args?.url);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "extract_og_image": {
+                const result = await (0, og_image_js_1.extractOgImage)(args?.url);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "generate_placeholder": {
+                const sizes = args?.sizes;
+                if (sizes && sizes.length > 0) {
+                    const results = (0, placeholder_generator_js_1.generatePlaceholderSet)(sizes, {
+                        backgroundColor: args?.backgroundColor,
+                        textColor: args?.textColor,
+                        text: args?.text,
+                        format: args?.format,
+                        font: args?.font,
+                        fontSize: args?.fontSize,
+                    });
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+                    };
+                }
+                const result = (0, placeholder_generator_js_1.generatePlaceholder)({
+                    width: args?.width,
+                    height: args?.height,
+                    backgroundColor: args?.backgroundColor,
+                    textColor: args?.textColor,
+                    text: args?.text,
+                    format: args?.format,
+                    font: args?.font,
+                    fontSize: args?.fontSize,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "responsive_images": {
+                const result = (0, responsive_images_js_1.generateResponsiveImages)({
+                    baseUrl: args?.baseUrl,
+                    alt: args?.alt,
+                    widths: args?.widths,
+                    sizes: args?.sizes,
+                    className: args?.className,
+                    loading: args?.loading,
+                    formats: args?.formats,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        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 stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Image Tools server running on stdio");
+}
+main().catch(console.error);

package/dist/tools/favicon-finder.d.ts

@@ -0,0 +1,12 @@
+export interface FaviconResult {
+    domain: string;
+    favicons: FaviconEntry[];
+    checkedLocations: string[];
+}
+export interface FaviconEntry {
+    url: string;
+    source: string;
+    type: string | null;
+    sizes: string | null;
+}
+export declare function findFavicons(websiteUrl: string): Promise<FaviconResult>;

package/dist/tools/favicon-finder.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findFavicons = findFavicons;
+async function fetchText(url, timeoutMs = 10000) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            redirect: "follow",
+            headers: { "User-Agent": "MCP-Image-Tools/1.0" },
+        });
+        if (!response.ok)
+            return { text: "", ok: false };
+        const text = await response.text();
+        return { text, ok: true };
+    }
+    catch {
+        return { text: "", ok: false };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function checkUrl(url, timeoutMs = 8000) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: "HEAD",
+            signal: controller.signal,
+            redirect: "follow",
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function extractLinkTags(html, baseUrl) {
+    const entries = [];
+    // Match <link> tags with rel containing "icon" or "apple-touch-icon"
+    const linkRegex = /<link\s+[^>]*>/gi;
+    let match;
+    while ((match = linkRegex.exec(html)) !== null) {
+        const tag = match[0];
+        const relMatch = tag.match(/rel\s*=\s*["']([^"']+)["']/i);
+        if (!relMatch)
+            continue;
+        const rel = relMatch[1].toLowerCase();
+        if (!rel.includes("icon"))
+            continue;
+        const hrefMatch = tag.match(/href\s*=\s*["']([^"']+)["']/i);
+        if (!hrefMatch)
+            continue;
+        const href = hrefMatch[1];
+        const typeMatch = tag.match(/type\s*=\s*["']([^"']+)["']/i);
+        const sizesMatch = tag.match(/sizes\s*=\s*["']([^"']+)["']/i);
+        let resolvedUrl;
+        try {
+            resolvedUrl = new URL(href, baseUrl).href;
+        }
+        catch {
+            continue;
+        }
+        entries.push({
+            url: resolvedUrl,
+            source: `HTML link[rel="${rel}"]`,
+            type: typeMatch ? typeMatch[1] : null,
+            sizes: sizesMatch ? sizesMatch[1] : null,
+        });
+    }
+    return entries;
+}
+function extractManifestIcons(manifestJson, baseUrl) {
+    const entries = [];
+    try {
+        const manifest = JSON.parse(manifestJson);
+        const icons = manifest.icons;
+        if (!Array.isArray(icons))
+            return entries;
+        for (const icon of icons) {
+            if (!icon.src)
+                continue;
+            let resolvedUrl;
+            try {
+                resolvedUrl = new URL(icon.src, baseUrl).href;
+            }
+            catch {
+                continue;
+            }
+            entries.push({
+                url: resolvedUrl,
+                source: "manifest.json",
+                type: icon.type || null,
+                sizes: icon.sizes || null,
+            });
+        }
+    }
+    catch {
+        // Invalid JSON
+    }
+    return entries;
+}
+async function findFavicons(websiteUrl) {
+    const parsed = new URL(websiteUrl);
+    const origin = parsed.origin;
+    const domain = parsed.hostname;
+    const checkedLocations = [];
+    const favicons = [];
+    const seenUrls = new Set();
+    function addFavicon(entry) {
+        if (!seenUrls.has(entry.url)) {
+            seenUrls.add(entry.url);
+            favicons.push(entry);
+        }
+    }
+    // 1. Check /favicon.ico
+    const faviconIcoUrl = `${origin}/favicon.ico`;
+    checkedLocations.push(faviconIcoUrl);
+    const icoExists = await checkUrl(faviconIcoUrl);
+    if (icoExists) {
+        addFavicon({
+            url: faviconIcoUrl,
+            source: "default /favicon.ico",
+            type: "image/x-icon",
+            sizes: null,
+        });
+    }
+    // 2. Parse HTML for link tags
+    checkedLocations.push(websiteUrl);
+    const { text: html, ok: htmlOk } = await fetchText(websiteUrl);
+    if (htmlOk) {
+        const htmlFavicons = extractLinkTags(html, websiteUrl);
+        for (const f of htmlFavicons) {
+            addFavicon(f);
+        }
+        // 3. Check for manifest.json reference
+        const manifestMatch = html.match(/<link\s+[^>]*rel\s*=\s*["']manifest["'][^>]*href\s*=\s*["']([^"']+)["']/i)
+            || html.match(/<link\s+[^>]*href\s*=\s*["']([^"']+)["'][^>]*rel\s*=\s*["']manifest["']/i);
+        if (manifestMatch) {
+            let manifestUrl;
+            try {
+                manifestUrl = new URL(manifestMatch[1], websiteUrl).href;
+            }
+            catch {
+                manifestUrl = "";
+            }
+            if (manifestUrl) {
+                checkedLocations.push(manifestUrl);
+                const { text: manifestText, ok: manifestOk } = await fetchText(manifestUrl);
+                if (manifestOk) {
+                    const manifestIcons = extractManifestIcons(manifestText, manifestUrl);
+                    for (const f of manifestIcons) {
+                        addFavicon(f);
+                    }
+                }
+            }
+        }
+    }
+    // 4. Check common manifest location
+    const defaultManifest = `${origin}/manifest.json`;
+    if (!checkedLocations.includes(defaultManifest)) {
+        checkedLocations.push(defaultManifest);
+        const { text: manifestText, ok: manifestOk } = await fetchText(defaultManifest);
+        if (manifestOk) {
+            const manifestIcons = extractManifestIcons(manifestText, defaultManifest);
+            for (const f of manifestIcons) {
+                addFavicon(f);
+            }
+        }
+    }
+    return { domain, favicons, checkedLocations };
+}

package/dist/tools/image-meta.d.ts

@@ -0,0 +1,14 @@
+export interface ImageMetadata {
+    url: string;
+    contentType: string | null;
+    fileSize: number | null;
+    fileSizeFormatted: string | null;
+    lastModified: string | null;
+    etag: string | null;
+    cacheControl: string | null;
+    acceptRanges: string | null;
+    server: string | null;
+    accessTime: string;
+    statusCode: number;
+}
+export declare function getImageMetadata(url: string): Promise<ImageMetadata>;

package/dist/tools/image-meta.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getImageMetadata = getImageMetadata;
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return "0 B";
+    const units = ["B", "KB", "MB", "GB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    return `${(bytes / Math.pow(1024, i)).toFixed(2)} ${units[i]}`;
+}
+async function getImageMetadata(url) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15000);
+    try {
+        // Use HEAD request first to avoid downloading the entire image
+        let response = await fetch(url, {
+            method: "HEAD",
+            signal: controller.signal,
+            redirect: "follow",
+        });
+        // Some servers reject HEAD, fall back to GET with range
+        if (response.status === 405 || response.status === 403) {
+            response = await fetch(url, {
+                method: "GET",
+                headers: { Range: "bytes=0-0" },
+                signal: controller.signal,
+                redirect: "follow",
+            });
+        }
+        const headers = response.headers;
+        const contentLength = headers.get("content-length");
+        const fileSize = contentLength ? parseInt(contentLength, 10) : null;
+        return {
+            url,
+            contentType: headers.get("content-type"),
+            fileSize,
+            fileSizeFormatted: fileSize !== null ? formatBytes(fileSize) : null,
+            lastModified: headers.get("last-modified"),
+            etag: headers.get("etag"),
+            cacheControl: headers.get("cache-control"),
+            acceptRanges: headers.get("accept-ranges"),
+            server: headers.get("server"),
+            accessTime: new Date().toISOString(),
+            statusCode: response.status,
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/tools/og-image.d.ts

@@ -0,0 +1,18 @@
+export interface OgImageResult {
+    url: string;
+    ogImage: string | null;
+    ogImageAlt: string | null;
+    ogImageWidth: string | null;
+    ogImageHeight: string | null;
+    ogImageType: string | null;
+    twitterImage: string | null;
+    twitterCard: string | null;
+    appleTouchIcon: string | null;
+    allImages: ImageEntry[];
+}
+export interface ImageEntry {
+    url: string;
+    source: string;
+    alt: string | null;
+}
+export declare function extractOgImage(url: string): Promise<OgImageResult>;

package/dist/tools/og-image.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractOgImage = extractOgImage;
+function extractMetaContent(html, property) {
+    // Match both property="..." and name="..." attributes
+    const patterns = [
+        new RegExp(`<meta\\s+[^>]*property\\s*=\\s*["']${escapeRegex(property)}["'][^>]*content\\s*=\\s*["']([^"']+)["']`, "i"),
+        new RegExp(`<meta\\s+[^>]*content\\s*=\\s*["']([^"']+)["'][^>]*property\\s*=\\s*["']${escapeRegex(property)}["']`, "i"),
+        new RegExp(`<meta\\s+[^>]*name\\s*=\\s*["']${escapeRegex(property)}["'][^>]*content\\s*=\\s*["']([^"']+)["']`, "i"),
+        new RegExp(`<meta\\s+[^>]*content\\s*=\\s*["']([^"']+)["'][^>]*name\\s*=\\s*["']${escapeRegex(property)}["']`, "i"),
+    ];
+    for (const pattern of patterns) {
+        const match = html.match(pattern);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function extractAppleTouchIcon(html, baseUrl) {
+    const match = html.match(/<link\s+[^>]*rel\s*=\s*["']apple-touch-icon["'][^>]*href\s*=\s*["']([^"']+)["']/i)
+        || html.match(/<link\s+[^>]*href\s*=\s*["']([^"']+)["'][^>]*rel\s*=\s*["']apple-touch-icon["']/i);
+    if (match) {
+        try {
+            return new URL(match[1], baseUrl).href;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function resolveUrl(href, baseUrl) {
+    if (!href)
+        return null;
+    try {
+        return new URL(href, baseUrl).href;
+    }
+    catch {
+        return null;
+    }
+}
+async function extractOgImage(url) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15000);
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            redirect: "follow",
+            headers: { "User-Agent": "MCP-Image-Tools/1.0" },
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        const html = await response.text();
+        const allImages = [];
+        // Extract OG image properties
+        const ogImage = resolveUrl(extractMetaContent(html, "og:image"), url);
+        const ogImageAlt = extractMetaContent(html, "og:image:alt");
+        const ogImageWidth = extractMetaContent(html, "og:image:width");
+        const ogImageHeight = extractMetaContent(html, "og:image:height");
+        const ogImageType = extractMetaContent(html, "og:image:type");
+        if (ogImage) {
+            allImages.push({ url: ogImage, source: "og:image", alt: ogImageAlt });
+        }
+        // Extract Twitter card image
+        const twitterImage = resolveUrl(extractMetaContent(html, "twitter:image"), url);
+        const twitterCard = extractMetaContent(html, "twitter:card");
+        if (twitterImage && twitterImage !== ogImage) {
+            allImages.push({ url: twitterImage, source: "twitter:image", alt: null });
+        }
+        // Extract Apple touch icon
+        const appleTouchIcon = extractAppleTouchIcon(html, url);
+        if (appleTouchIcon) {
+            allImages.push({ url: appleTouchIcon, source: "apple-touch-icon", alt: null });
+        }
+        return {
+            url,
+            ogImage,
+            ogImageAlt,
+            ogImageWidth,
+            ogImageHeight,
+            ogImageType,
+            twitterImage,
+            twitterCard,
+            appleTouchIcon,
+            allImages,
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}