image-processor-mcp 0.1.0

package/build/services/image.services.js

@@ -0,0 +1,99 @@
+import sharp from 'sharp';
+import { FileService } from './file.services.js';
+import { DEFAULTS } from '../config/config.constants.js';
+export class ImageService {
+    static async compressImage(inputPath, outputPath, options) {
+        const { quality = DEFAULTS.quality, lossless = DEFAULTS.lossless, effort = DEFAULTS.effort, width, height, maxDimension = DEFAULTS.maxDimension, recursiveCompress = false, expectedSizeKB = DEFAULTS.expectedSizeKB, qualityStepDown = DEFAULTS.qualityStepDown, minimumQualityFloor = DEFAULTS.minimumQualityFloor, outputFormat = DEFAULTS.outputFormat, } = options;
+        try {
+            const originalSize = await FileService.getFileSize(inputPath);
+            const metadata = await sharp(inputPath).metadata();
+            const imgWidth = metadata.width || 0;
+            const imgHeight = metadata.height || 0;
+            let resizeOptions = {};
+            if (width || height) {
+                resizeOptions = { ...(width ? { width } : {}), ...(height ? { height } : {}) };
+            }
+            else if (imgWidth > maxDimension || imgHeight > maxDimension) {
+                const ratio = Math.min(maxDimension / imgWidth, maxDimension / imgHeight);
+                resizeOptions = {
+                    width: Math.round(imgWidth * ratio),
+                    height: Math.round(imgHeight * ratio),
+                };
+            }
+            let currentQuality = quality;
+            let iterations = 0;
+            let compressedSize = 0;
+            const qualitySteps = [];
+            while (true) {
+                let pipeline = sharp(inputPath);
+                if (Object.keys(resizeOptions).length > 0) {
+                    pipeline = pipeline.resize(resizeOptions.width, resizeOptions.height, {
+                        fit: 'inside',
+                        withoutEnlargement: true,
+                    });
+                }
+                pipeline = this.applyFormat(pipeline, outputFormat, { quality: currentQuality, lossless, effort });
+                await pipeline.toFile(outputPath);
+                compressedSize = await FileService.getFileSize(outputPath);
+                iterations++;
+                qualitySteps.push(currentQuality);
+                const compressedKB = compressedSize / 1024;
+                if (recursiveCompress && compressedKB > expectedSizeKB && currentQuality - qualityStepDown >= minimumQualityFloor) {
+                    currentQuality -= qualityStepDown;
+                }
+                else {
+                    break;
+                }
+            }
+            const compressionRatio = originalSize > 0
+                ? parseFloat(((originalSize - compressedSize) / originalSize * 100).toFixed(2))
+                : 0;
+            return {
+                inputPath,
+                outputPath,
+                originalSize,
+                compressedSize,
+                compressionRatio,
+                success: true,
+                iterations,
+                qualitySteps,
+                finalQuality: qualitySteps[qualitySteps.length - 1],
+                exceededTarget: recursiveCompress && (compressedSize / 1024) > expectedSizeKB,
+            };
+        }
+        catch (error) {
+            return {
+                inputPath,
+                outputPath,
+                originalSize: 0,
+                compressedSize: 0,
+                compressionRatio: 0,
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+                iterations: 0,
+                qualitySteps: [],
+                finalQuality: 0,
+                exceededTarget: false,
+            };
+        }
+    }
+    static applyFormat(pipeline, format, options) {
+        const { quality, lossless, effort } = options;
+        switch (format) {
+            case 'webp':
+                return pipeline.webp({ quality, lossless, effort, smartSubsample: true, alphaQuality: 90 });
+            case 'avif':
+                return pipeline.avif({ quality, lossless, effort });
+            case 'jpeg':
+                return pipeline.jpeg({ quality, mozjpeg: true });
+            case 'png':
+                return pipeline.png({ compressionLevel: 9 });
+            case 'tiff':
+                return pipeline.tiff({ quality, compression: 'lzw' });
+            case 'gif':
+                return pipeline.gif();
+            default:
+                return pipeline.webp({ quality, lossless });
+        }
+    }
+}

package/build/services/report.services.d.ts

@@ -0,0 +1,4 @@
+import type { CompressionResult } from '../types.js';
+export declare class ReportService {
+    static generateReport(results: CompressionResult[], inputDir: string, outputDir: string, outputFormat: string, startTime: number, duration: number, skippedFiles?: string[]): Promise<string>;
+}

package/build/services/report.services.js

@@ -0,0 +1,121 @@
+import path from 'path';
+import fs from 'fs-extra';
+import { FileService } from './file.services.js';
+import { APP_CONFIG } from '../config/app.config.js';
+import { SUPPORTED_OUTPUT_FORMATS } from '../config/config.constants.js';
+export class ReportService {
+    static async generateReport(results, inputDir, outputDir, outputFormat, startTime, duration, skippedFiles = []) {
+        const reportDir = path.join(outputDir, 'report');
+        await fs.ensureDir(reportDir);
+        const now = new Date();
+        const pad = (n) => String(n).padStart(2, '0');
+        const timestamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`;
+        const reportFilename = `scan-report-${timestamp}.md`;
+        const reportPath = path.join(reportDir, reportFilename);
+        const successful = results.filter(r => r.success);
+        const failed = results.filter(r => !r.success);
+        const totalOriginalSize = results.reduce((s, r) => s + r.originalSize, 0);
+        const totalCompressedSize = results.reduce((s, r) => s + r.compressedSize, 0);
+        const overallReduction = totalOriginalSize > 0
+            ? ((totalOriginalSize - totalCompressedSize) / totalOriginalSize * 100).toFixed(2)
+            : '0.00';
+        const lines = [];
+        lines.push('# Compression Report');
+        lines.push('');
+        lines.push('**MCP Server:** ' + APP_CONFIG.name + ' v' + APP_CONFIG.version);
+        lines.push('**Generated:** ' + now.toLocaleString());
+        lines.push('');
+        lines.push('**Duration:** ' + (duration / 1000).toFixed(2) + 's');
+        lines.push('');
+        if (results.length > 0 && skippedFiles.length === 0) {
+            const extensions = ['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.tiff', '.webp', `.${outputFormat}`];
+            const outputFiles = await FileService.scanFiles(outputDir, outputDir, extensions);
+            const tree = FileService.buildTree(outputFiles, outputDir);
+            const treeLines = FileService.formatTreeMarkdown(tree);
+            lines.push('## Summary');
+            lines.push('');
+            lines.push('| Metric | Value |');
+            lines.push('|--------|-------|');
+            lines.push(`| Total files | ${results.length} |`);
+            lines.push(`| Successful | ${successful.length} |`);
+            lines.push(`| Failed | ${failed.length} |`);
+            lines.push(`| Total original size | ${FileService.formatBytes(totalOriginalSize)} |`);
+            lines.push(`| Total compressed size | ${FileService.formatBytes(totalCompressedSize)} |`);
+            lines.push(`| Overall reduction | ${overallReduction}% |`);
+            lines.push('');
+            lines.push('## File Tree');
+            lines.push('');
+            lines.push('```');
+            lines.push(...treeLines);
+            lines.push('```');
+            lines.push('');
+            lines.push('## File Details');
+            lines.push('');
+            const uniqueResults = new Map();
+            for (const r of successful) {
+                uniqueResults.set(r.outputPath, r);
+            }
+            for (const r of uniqueResults.values()) {
+                const relPath = path.relative(outputDir, r.outputPath);
+                const outKB = (r.compressedSize / 1024).toFixed(2);
+                const inKB = (r.originalSize / 1024).toFixed(2);
+                const warning = r.exceededTarget ? ' ⚠ EXCEEDS LIMIT' : '';
+                lines.push(`### ${relPath}`);
+                lines.push(`- Input: ${path.basename(r.inputPath)} | ${inKB} KB`);
+                lines.push(`- Output: ${path.basename(r.outputPath)} | ${outKB} KB${warning}`);
+                lines.push(`- Compression: ${r.compressionRatio}%`);
+                if (r.iterations > 1) {
+                    lines.push(`- Iterations: ${r.iterations} | Quality steps: ${r.qualitySteps.join(' → ')} → ${r.finalQuality}`);
+                }
+                lines.push('');
+            }
+            if (failed.length > 0) {
+                lines.push('## Failed Files');
+                lines.push('');
+                for (const r of failed) {
+                    const relPath = path.relative(inputDir, r.inputPath);
+                    lines.push(`- ${relPath}: ${r.error}`);
+                }
+                lines.push('');
+            }
+            if (successful.length > 0) {
+                lines.push('## Input vs Output Comparison');
+                lines.push('');
+                lines.push('| File | Input Size | Output Size | Compression | Status |');
+                lines.push('|------|-----------|------------|-------------|--------|');
+                for (const r of uniqueResults.values()) {
+                    const relPath = path.relative(outputDir, r.outputPath);
+                    const warn = (r.compressedSize / 1024) > 100 ? ' ⚠' : '';
+                    lines.push(`| ${relPath} | ${FileService.formatBytes(r.originalSize)} | ${FileService.formatBytes(r.compressedSize)} | ${r.compressionRatio}% | ✅${warn} |`);
+                }
+                lines.push('');
+            }
+        }
+        if (skippedFiles.length > 0) {
+            const altFormats = SUPPORTED_OUTPUT_FORMATS.filter(f => f !== outputFormat);
+            const formatsList = altFormats.map(f => '`' + f + '`').join(', ');
+            lines.push('### ⚠ Notice');
+            lines.push('');
+            lines.push(`The following **${skippedFiles.length}** file(s) already have the \`.${outputFormat}\` extension and were **skipped** from compression:`);
+            lines.push('');
+            lines.push('> To compress these files:');
+            lines.push('> - **Option 1:** Delete the existing `.${outputFormat}` files from the input directory, then run again');
+            lines.push(`> - **Option 2:** Choose a different output format (e.g., ${formatsList}) instead of \`${outputFormat}\``);
+            lines.push('');
+            for (const f of skippedFiles) {
+                lines.push(`- \`${path.relative(path.resolve(inputDir), f)}\``);
+            }
+            lines.push('');
+        }
+        lines.push('');
+        lines.push('---');
+        lines.push('---');
+        lines.push('');
+        lines.push('**Developed by Dhvanil Pansuriya**');
+        lines.push('');
+        lines.push('[GitHub](https://github.com/pansuriyadhvanil/) · [LinkedIn](https://linkedin.com/in/dhvanil-pansuriya/)');
+        lines.push('');
+        await fs.writeFile(reportPath, lines.join('\n'), 'utf-8');
+        return reportPath;
+    }
+}

package/build/types.d.ts

@@ -0,0 +1,82 @@
+export interface DownloadImageArgs {
+    url: string;
+    outputPath: string;
+}
+export interface CompressImageArgs {
+    inputPath: string;
+    outputPath: string;
+    outputFormat?: string;
+    quality?: number;
+    lossless?: boolean;
+    effort?: number;
+    width?: number;
+    height?: number;
+    maxDimension?: number;
+    recursiveCompress?: boolean;
+    expectedSizeKB?: number;
+    qualityStepDown?: number;
+    minimumQualityFloor?: number;
+}
+export interface CompressDirectoryArgs {
+    inputDir: string;
+    outputDir: string;
+    outputFormat?: string;
+    quality?: number;
+    lossless?: boolean;
+    effort?: number;
+    maxDimension?: number;
+    normalizeFilename?: boolean;
+    filenameReplaceChars?: string;
+    filenameCase?: string;
+    normalizeDirname?: boolean;
+    dirnameReplaceChars?: string;
+    dirnameCase?: string;
+    recursiveCompress?: boolean;
+    expectedSizeKB?: number;
+    qualityStepDown?: number;
+    minimumQualityFloor?: number;
+}
+export interface FileNamingOptions {
+    enabled: boolean;
+    replaceChars: string[];
+    case: 'lowercase' | 'uppercase' | 'original';
+}
+export interface CompressionResult {
+    inputPath: string;
+    outputPath: string;
+    originalSize: number;
+    compressedSize: number;
+    compressionRatio: number;
+    success: boolean;
+    error?: string;
+    iterations: number;
+    qualitySteps: number[];
+    finalQuality: number;
+    exceededTarget: boolean;
+}
+export interface ScanFile {
+    fullPath: string;
+    relativePath: string;
+    size: number;
+    ext: string;
+    nameWithoutExt: string;
+}
+export interface TreeNode {
+    name: string;
+    type: 'directory' | 'file';
+    children?: TreeNode[];
+    size?: number;
+}
+export interface CompressOptions {
+    quality?: number;
+    lossless?: boolean;
+    effort?: number;
+    width?: number;
+    height?: number;
+    maxDimension?: number;
+    recursiveCompress?: boolean;
+    expectedSizeKB?: number;
+    qualityStepDown?: number;
+    minimumQualityFloor?: number;
+    outputFormat?: string;
+}

package/build/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "image-processor-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server for downloading, compressing, and optimizing images with batch directory processing and auto-generated reports",
+  "main": "build/index.js",
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc --noEmit",
+    "start": "node build/index.js"
+  },
+  "author": "Dhvanil Pansuriya",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pansuriyadhvanil/mcp-image-downloader.git"
+  },
+  "keywords": [
+    "mcp",
+    "image",
+    "downloader",
+    "compressor",
+    "optimizer",
+    "sharp",
+    "webp",
+    "avif",
+    "batch"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "axios": "^1.6.2",
+    "sharp": "^0.33.1",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^20.10.5",
+    "@types/fs-extra": "^11.0.4"
+  }
+}

package/src/config/app.config.ts

@@ -0,0 +1,4 @@
+export const APP_CONFIG = {
+  name: 'image-processor-mcp',
+  version: '0.1.0',
+};

package/src/config/config.constants.ts

@@ -0,0 +1,181 @@
+export const DEFAULTS = {
+  quality: 85,
+  lossless: false,
+  effort: 6,
+  maxDimension: 2000,
+  expectedSizeKB: 100,
+  qualityStepDown: 5,
+  minimumQualityFloor: 10,
+  outputFormat: 'webp',
+  filenameCase: 'lowercase' as const,
+  dirnameCase: 'lowercase' as const,
+  filenameReplaceChars: [' ', '-', '.', '&'],
+  dirnameReplaceChars: [' ', '-', '.', '&'],
+};
+
+export const SUPPORTED_EXTENSIONS = [
+  '.jpg', '.jpeg', '.png', '.gif', '.bmp', '.tiff', '.tif',
+  '.webp', '.avif', '.svg', '.heic', '.heif', '.ico', '.cur',
+  '.jp2', '.j2k', '.jpf', '.jpx', '.jpm', '.mj2',
+  '.jxr', '.wdp', '.hdp',
+  '.psd', '.psb',
+  '.dds',
+  '.tga', '.vda', '.icb', '.vst',
+  '.pbm', '.pgm', '.ppm', '.pnm', '.pfm',
+  '.exr',
+  '.hdr', '.hrd',
+  '.pic', '.pict', '.pct',
+  '.xbm', '.xpm',
+  '.wal',
+  '.cut',
+  '.ras', '.sun',
+  '.sgi', '.rgb', '.rgba', '.bw',
+  '.pcx',
+  '.pcd',
+  '.iff', '.lbm',
+];
+
+export const SUPPORTED_OUTPUT_FORMATS = [
+  'webp', 'avif', 'jpeg', 'png', 'tiff', 'gif',
+  'heif', 'jp2', 'jxl', 'pdf',
+];
+
+export interface ConfigDescription {
+  name: string;
+  default: string | number | boolean | string[];
+  description: string;
+}
+
+export const CONFIG_DESCRIPTIONS: ConfigDescription[] = [
+  {
+    name: 'quality',
+    default: DEFAULTS.quality,
+    description: 'Compression quality level for lossy formats (1-100). Higher values preserve more detail but produce larger files. Used for JPEG, WebP, AVIF, and HEIF output.',
+  },
+  {
+    name: 'lossless',
+    default: DEFAULTS.lossless,
+    description: 'When true, uses lossless compression. File sizes will be larger but pixel data is preserved exactly. Supported for WebP, PNG, GIF, and AVIF formats.',
+  },
+  {
+    name: 'effort',
+    default: DEFAULTS.effort,
+    description: 'CPU effort level (0-6). Higher values produce better compression ratios but take significantly longer to process. Level 6 gives the smallest file size.',
+  },
+  {
+    name: 'maxDimension',
+    default: DEFAULTS.maxDimension,
+    description: 'Maximum width or height in pixels. Images exceeding this threshold are automatically resized down to fit while maintaining aspect ratio. Set to a high value to effectively disable.',
+  },
+  {
+    name: 'expectedSizeKB',
+    default: DEFAULTS.expectedSizeKB,
+    description: 'Target file size in KB for recursive compression. If the compressed output exceeds this size, quality is reduced iteratively until the target is met or minimumQualityFloor is reached.',
+  },
+  {
+    name: 'qualityStepDown',
+    default: DEFAULTS.qualityStepDown,
+    description: 'Amount to reduce quality by in each recursive compression iteration. Larger values reach target size faster but risk visible quality degradation.',
+  },
+  {
+    name: 'minimumQualityFloor',
+    default: DEFAULTS.minimumQualityFloor,
+    description: 'Lowest quality value (1-100) allowed during recursive compression. Prevents excessive degradation even if the target file size is not reached.',
+  },
+  {
+    name: 'outputFormat',
+    default: DEFAULTS.outputFormat,
+    description: 'Default output image format. WebP offers excellent compression with good quality. AVIF gives better compression but slower encoding. JPEG offers universal compatibility.',
+  },
+  {
+    name: 'filenameCase',
+    default: DEFAULTS.filenameCase,
+    description: 'Case conversion applied to filenames when normalization is enabled. lowercase converts all to lower, uppercase converts all to UPPER, original leaves them as-is.',
+  },
+  {
+    name: 'dirnameCase',
+    default: DEFAULTS.dirnameCase,
+    description: 'Case conversion applied to directory names when normalization is enabled. Same options as filenameCase: lowercase, uppercase, or original.',
+  },
+  {
+    name: 'filenameReplaceChars',
+    default: DEFAULTS.filenameReplaceChars,
+    description: 'Array of characters replaced with underscores in filenames when normalization is enabled. Helps create web-safe filenames by removing spaces and special characters.',
+  },
+  {
+    name: 'dirnameReplaceChars',
+    default: DEFAULTS.dirnameReplaceChars,
+    description: 'Array of characters replaced with underscores in directory names when normalization is enabled. Helps create web-safe directory names.',
+  },
+];
+
+export const INPUT_EXTENSION_DESCRIPTIONS: Record<string, string> = {
+  '.jpg': 'JPEG image (Joint Photographic Experts Group)',
+  '.jpeg': 'JPEG image (alternative extension)',
+  '.png': 'PNG image (Portable Network Graphics)',
+  '.gif': 'GIF image (Graphics Interchange Format)',
+  '.bmp': 'BMP image (Bitmap)',
+  '.tiff': 'TIFF image (Tagged Image File Format)',
+  '.tif': 'TIFF image (alternative extension)',
+  '.webp': 'WebP image (Google web format)',
+  '.avif': 'AVIF image (AV1 Image File Format)',
+  '.svg': 'SVG vector image (Scalable Vector Graphics)',
+  '.heic': 'HEIC image (High Efficiency Image Container)',
+  '.heif': 'HEIF image (High Efficiency Image File Format)',
+  '.ico': 'ICO icon file (Windows icon)',
+  '.cur': 'CUR cursor file (Windows cursor)',
+  '.jp2': 'JPEG 2000 image',
+  '.j2k': 'JPEG 2000 image (alternative extension)',
+  '.jpf': 'JPEG 2000 image (alternative extension)',
+  '.jpx': 'JPEG 2000 extended image',
+  '.jpm': 'JPEG 2000 compound image',
+  '.mj2': 'Motion JPEG 2000',
+  '.jxr': 'JPEG XR image (Microsoft HD Photo)',
+  '.wdp': 'Windows Media Photo (JPEG XR)',
+  '.hdp': 'HD Photo (JPEG XR)',
+  '.psd': 'Photoshop document',
+  '.psb': 'Photoshop large document',
+  '.dds': 'DirectDraw Surface texture',
+  '.tga': 'Targa image',
+  '.vda': 'Targa image (alternative extension)',
+  '.icb': 'Targa image (alternative extension)',
+  '.vst': 'Targa image (alternative extension)',
+  '.pbm': 'Portable Bitmap (black and white)',
+  '.pgm': 'Portable Graymap (grayscale)',
+  '.ppm': 'Portable Pixmap (color)',
+  '.pnm': 'Portable Anymap (generic PPM/PGM/PBM)',
+  '.pfm': 'Portable FloatMap (HDR)',
+  '.exr': 'OpenEXR HDR image (Industrial Light & Magic)',
+  '.hdr': 'Radiance HDR image',
+  '.hrd': 'Radiance HDR image (alternative extension)',
+  '.pic': 'PICT image (Apple QuickDraw)',
+  '.pict': 'PICT image (alternative extension)',
+  '.pct': 'PICT image (alternative extension)',
+  '.xbm': 'X BitMap (X11)',
+  '.xpm': 'X PixMap (X11)',
+  '.wal': 'Quake 2 texture (WAL format)',
+  '.cut': 'CUT image (Dr. Halo)',
+  '.ras': 'Sun Raster image',
+  '.sun': 'Sun Raster image (alternative extension)',
+  '.sgi': 'SGI image (Silicon Graphics)',
+  '.rgb': 'SGI RGB image',
+  '.rgba': 'SGI RGBA image',
+  '.bw': 'SGI black and white image',
+  '.pcx': 'PCX image (ZSoft PC Paintbrush)',
+  '.pcd': 'PhotoCD image (Kodak)',
+  '.iff': 'IFF image (Amiga Interchange File Format)',
+  '.lbm': 'IFF image (alternative extension)',
+};
+
+export const OUTPUT_FORMAT_DESCRIPTIONS: Record<string, string> = {
+  webp: 'Google WebP. Modern format with excellent lossy and lossless compression. Best all-around choice for web use. Supports transparency.',
+  avif: 'AVIF based on AV1 codec. Superior compression ratios (30-50% smaller than JPEG) but slower encoding. Best for modern browsers.',
+  jpeg: 'JPEG. Universal compatibility with all devices and software. Good for photographs. Does not support transparency.',
+  png: 'PNG. Lossless compression with full transparency support. Best for graphics, logos, screenshots, and images requiring sharp edges.',
+  tiff: 'TIFF. High-quality format commonly used in print and publishing. Supports layers and multiple pages. Largest file sizes.',
+  gif: 'GIF. Supports animation and transparency. Limited to 256 colors. Best for simple animations and low-color graphics.',
+  heif: 'HEIF (High Efficiency Image File Format). Modern format using HEVC codec. Better compression than JPEG. Apple ecosystem support.',
+  jp2: 'JPEG 2000. Wavelet-based compression with excellent quality. Used in medical imaging and digital cinema. Not widely supported in browsers.',
+  jxl: 'JPEG XL. Next-gen format designed to replace JPEG. Lossless re-encoding of existing JPEGs. Excellent compression. Growing browser support.',
+  pdf: 'PDF (Portable Document Format). Converts images to PDF pages. Useful for document creation and archiving.',
+};