image-processor-mcp 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Lint Code
+        run: npm run lint
+
+      - name: Build Project
+        run: npm run build

package/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install Dependencies
+        run: npm install
+
+      - name: Build Project
+        run: npm run build
+
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dhvanil Pansuriya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NPM_PUBLISH_GUIDE.md

@@ -0,0 +1,73 @@
+# Automated NPM Publishing Workflow
+
+This guide explains how to publish new versions of this MCP server to the NPM registry using GitHub Actions.
+
+## Prerequisites
+
+### Option A: Granular Access Token (Recommended for simplicity)
+
+1. **Generate Token**:
+   - Login to [npmjs.com](https://www.npmjs.com/).
+   - Navigate to **Access Tokens** > **Generate New Token** > **Granular Access Token**.
+   - **Name**: `GitHub-Actions-Image-Processor-MCP`.
+   - **Expiration**: Set as needed (e.g., 365 days).
+   - **Permissions**:
+     - **Read and Write** for the specific package.
+   - **Bypass 2FA**: Check this if your account has 2FA enabled, otherwise the automated workflow will fail.
+   - Copy the generated token.
+
+2. **Add GitHub Secret**:
+   - Go to your GitHub repository.
+   - Navigate to **Settings** > **Secrets and variables** > **Actions**.
+   - Click **New repository secret**.
+   - **Name**: `NPM_TOKEN`
+   - **Value**: Paste the token from NPM.
+
+### Option B: Trusted Publishing (OIDC) - More Secure
+
+1. **Configure NPM**:
+   - In your NPM package settings, navigate to **Publishing** > **Trusted Publishing**.
+   - Add a new GitHub Actions publisher.
+   - Provide your repository name.
+
+2. **Workflow Permissions**:
+   The `.github/workflows/publish.yml` already has:
+   ```yaml
+   permissions:
+     id-token: write
+     contents: read
+   ```
+
+---
+
+## How to Release a New Version
+
+The workflow triggers automatically when you push a new version tag (starting with `v`).
+
+### 1. Update Version
+Update the `version` field in your `package.json`.
+
+### 2. Commit and Push
+```bash
+git add package.json
+git commit -m "chore: bump version to 0.1.1"
+git push origin main
+```
+
+### 3. Create and Push a Version Tag
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+---
+
+## What Happens Behind the Scenes?
+
+1. GitHub Actions detects the new tag `v*`.
+2. A fresh Ubuntu runner is provisioned.
+3. The project is built using `npm run build`.
+4. The package is published to NPM using `NPM_TOKEN`.
+5. You will receive an email from NPM once the publish is successful.
+
+You can monitor progress in the **Actions** tab of your GitHub repository.

package/README.md

@@ -0,0 +1,81 @@
+# MCP Image Downloader
+
+An MCP server that provides tools for downloading, compressing, and optimizing images. Built using the Model Context Protocol (MCP), this server enables AI assistants to download images from URLs, compress and convert images with various format options, and batch process entire directories with auto-generated reports.
+
+## Features
+
+- Download images from URLs with proper error handling
+- Compress and convert single images with multiple output formats (WebP, AVIF, JPEG, PNG, TIFF, GIF, HEIF, JPEG 2000, JPEG XL, PDF)
+- Recursive compression to target file size
+- Lossless and lossy compression with configurable quality and CPU effort
+- Auto-resize oversized images
+- Batch process entire directories preserving folder structure
+- Filename and directory name normalization (replace chars, case conversion)
+- Auto-generated markdown compression reports with file tree, per-file details, and input vs output comparison
+
+## Available Tools
+
+#### download_image
+Downloads an image from a URL to a specified path.
+
+Parameters:
+- `url` (required): URL of the image to download
+- `outputPath` (required): Path where to save the image
+
+#### compress_image
+Compresses or converts a single image with format conversion, quality adjustment, resizing, and optional recursive compression.
+
+Parameters:
+- `inputPath` (required): Path to the input image
+- `outputPath` (required): Path to save the compressed image
+- `outputFormat` (optional): Output format - webp, avif, jpeg, png, tiff, gif, heif, jp2, jxl, pdf (default: webp)
+- `quality` (optional): Compression quality 1-100 (default: 85)
+- `lossless` (optional): Use lossless compression (default: false)
+- `effort` (optional): CPU effort 0-6 (default: 6)
+- `width` (optional): Exact target width
+- `height` (optional): Exact target height
+- `maxDimension` (optional): Auto-resize threshold in pixels (default: 2000)
+- `recursiveCompress` (optional): Re-compress until under target size (default: false)
+- `expectedSizeKB` (optional): Target file size in KB (default: 100)
+- `qualityStepDown` (optional): Quality decrease per iteration (default: 5)
+- `minimumQualityFloor` (optional): Minimum quality allowed (default: 10)
+
+#### compress_directory
+Batch compresses all images in a directory recursively, preserving folder structure, with an auto-generated report.
+
+Parameters:
+- `inputDir` (required): Input directory containing images
+- `outputDir` (required): Output directory for compressed images
+- `outputFormat` (optional): Output format (default: webp)
+- `quality` (optional): Compression quality 1-100 (default: 85)
+- `lossless` (optional): Use lossless compression (default: false)
+- `effort` (optional): CPU effort 0-6 (default: 6)
+- `maxDimension` (optional): Auto-resize threshold (default: 2000)
+- `normalizeFilename` (optional): Enable filename normalization
+- `filenameReplaceChars` (optional): Characters to replace with underscore (comma-separated)
+- `filenameCase` (optional): Filename case - lowercase, uppercase, original
+- `normalizeDirname` (optional): Enable directory name normalization
+- `dirnameReplaceChars` (optional): Characters to replace in directory names (comma-separated)
+- `dirnameCase` (optional): Directory name case
+- `recursiveCompress` (optional): Re-compress oversized outputs
+- `expectedSizeKB` (optional): Target file size in KB (default: 100)
+- `qualityStepDown` (optional): Quality decrease per iteration (default: 5)
+- `minimumQualityFloor` (optional): Minimum quality floor (default: 10)
+
+#### get_acknowledgement
+Returns all configuration defaults, supported input/output formats with descriptions, and detailed parameter explanations for every tool.
+
+Parameters: None
+
+## Requirements
+
+- Node.js 16 or higher
+- NPM or compatible package manager
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+Dhvanil Pansuriya

package/build/config/app.config.d.ts

@@ -0,0 +1,4 @@
+export declare const APP_CONFIG: {
+    name: string;
+    version: string;
+};

package/build/config/app.config.js

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

package/build/config/config.constants.d.ts

@@ -0,0 +1,24 @@
+export declare const DEFAULTS: {
+    quality: number;
+    lossless: boolean;
+    effort: number;
+    maxDimension: number;
+    expectedSizeKB: number;
+    qualityStepDown: number;
+    minimumQualityFloor: number;
+    outputFormat: string;
+    filenameCase: "lowercase";
+    dirnameCase: "lowercase";
+    filenameReplaceChars: string[];
+    dirnameReplaceChars: string[];
+};
+export declare const SUPPORTED_EXTENSIONS: string[];
+export declare const SUPPORTED_OUTPUT_FORMATS: string[];
+export interface ConfigDescription {
+    name: string;
+    default: string | number | boolean | string[];
+    description: string;
+}
+export declare const CONFIG_DESCRIPTIONS: ConfigDescription[];
+export declare const INPUT_EXTENSION_DESCRIPTIONS: Record<string, string>;
+export declare const OUTPUT_FORMAT_DESCRIPTIONS: Record<string, string>;

package/build/config/config.constants.js

@@ -0,0 +1,170 @@
+export const DEFAULTS = {
+    quality: 85,
+    lossless: false,
+    effort: 6,
+    maxDimension: 2000,
+    expectedSizeKB: 100,
+    qualityStepDown: 5,
+    minimumQualityFloor: 10,
+    outputFormat: 'webp',
+    filenameCase: 'lowercase',
+    dirnameCase: 'lowercase',
+    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 const CONFIG_DESCRIPTIONS = [
+    {
+        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 = {
+    '.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 = {
+    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.',
+};

package/build/controllers/tool.controller.d.ts

@@ -0,0 +1,48 @@
+import type { DownloadImageArgs, CompressImageArgs, CompressDirectoryArgs } from '../types.js';
+export declare class ToolController {
+    static handleDownloadImage(args: DownloadImageArgs): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+    static handleCompressImage(args: CompressImageArgs): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+    static handleCompressDirectory(args: CompressDirectoryArgs): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+    static handleGetAcknowledgement(): {
+        content: {
+            type: string;
+            text: string;
+        }[];
+    };
+}