ToolBox MCP Server

Implementation Reference

• src/tools/image_tool.ts:170-219 (handler)

  The primary handler function for the image_tool. It parses arguments, determines source type (file/dir), sets default outputs, invokes processing functions, and returns JSON results or error.

  export default async function (request: any) {
    try {
      const { sourcePath, outputPath: userOutputPath, quality, compressionLevel, resize, format, recursive, backupDir } = request.params.arguments;
  
      const sourcePathStat = await stat(sourcePath);
  
      let outputPath;
      if (userOutputPath) {
          outputPath = userOutputPath;
      } else {
          if (sourcePathStat.isFile()) {
              const parsedPath = path.parse(sourcePath);
              const outputFormat = format || parsedPath.ext.slice(1);
              outputPath = path.join(parsedPath.dir, `${parsedPath.name}.processed.${outputFormat}`);
          } else { // is directory
              outputPath = `${sourcePath}_processed`;
          }
      }
  
      const options = { quality, compressionLevel, resize, format, recursive, backupDir };
  
      let results;
      if (sourcePathStat.isFile()) {
        results = [await processImage(sourcePath, outputPath, options)];
      } else if (sourcePathStat.isDirectory()) {
        results = await processDirectory(sourcePath, outputPath, options);
      } else {
        throw new Error("Source path must be a file or directory");
      }
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(results, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error: ${error instanceof Error ? error.message : String(error)}`
          }
        ],
        isError: true
      };
    }
  }

• src/tools/image_tool.ts:10-67 (schema)

  The input schema for image_tool, specifying name, description, parameters like sourcePath, outputPath, quality, resize, format, recursive processing, and backup options.

  export const schema = {
    name: "image_tool",
    description: "A powerful image processing tool that supports format conversion, resizing, quality compression, and can batch process directories.",
    type: "object",
    properties: {
      sourcePath: {
        type: "string",
        description: "Source file or directory path"
      },
      outputPath: {
        type: "string",
        description: "Output directory path. Defaults to a new file (e.g., 'source.processed.jpg') or a new directory (e.g., 'source_processed')."
      },
      quality: {
        type: "number",
        description: "Compression quality for JPEG/WebP/AVIF/TIFF (1-100, defaults to 80)",
        minimum: 1,
        maximum: 100,
        default: 80
      },
      compressionLevel: {
          type: "number",
          description: "PNG compression level (0-9, defaults to 6)",
          minimum: 0,
          maximum: 9,
          default: 6
      },
      resize: {
        type: "object",
        description: "Resize options",
        properties: {
          width: {
            type: "number",
            description: "Width"
          },
          height: {
            type: "number",
            description: "Height"
          }
        }
      },
      format: {
        type: "string",
        enum: ["jpeg", "png", "webp", "avif", "tiff", "gif"],
        description: "Output format (optional, keeps original if not specified)"
      },
      recursive: {
        type: "boolean",
        description: "Process subdirectories recursively",
        default: false
      },
      backupDir: {
        type: "string",
        description: "Backup directory path (optional)"
      }
    },
    required: ["sourcePath"]
  };

• src/tools/image_tool.ts:69-130 (helper)

  Helper function to process individual image files: handles backups, resizing, format conversion using Sharp, and in-place processing if needed.

  async function processImage(inputPath: string, outputPath: string, options: any) {
    let tempFilePath: string | null = null;
    try {
      const { quality, compressionLevel, resize, format, backupDir } = options;
  
      if (backupDir) {
        const backupPath = path.join(backupDir, path.basename(inputPath));
        await mkdir(backupDir, { recursive: true });
        fs.copyFileSync(inputPath, backupPath);
      }
  
      let sharpImage = sharp(inputPath);
  
      if (resize) {
        sharpImage = sharpImage.resize(resize.width, resize.height);
      }
      
      const targetFormat = format || path.extname(inputPath).substring(1);
  
      switch (targetFormat) {
          case 'jpeg':
              sharpImage = sharpImage.jpeg({ quality: quality || 80 });
              break;
          case 'png':
              sharpImage = sharpImage.png({ compressionLevel: compressionLevel || 6 });
              break;
          case 'webp':
              sharpImage = sharpImage.webp({ quality: quality || 80 });
              break;
          case 'avif':
              sharpImage = sharpImage.avif({ quality: quality || 80 });
              break;
          case 'tiff':
              sharpImage = sharpImage.tiff({ quality: quality || 80 });
              break;
          case 'gif':
              sharpImage = sharpImage.gif();
              break;
      }
  
      // Ensure output directory exists
      await mkdir(path.dirname(outputPath), { recursive: true });
  
      if (inputPath === outputPath) {
        // This case should be avoided by the new default path logic, but kept for safety
        tempFilePath = path.join(path.dirname(inputPath), `temp_${path.basename(inputPath)}`);
        await sharpImage.toFile(tempFilePath);
        fs.renameSync(tempFilePath, inputPath);
      } else {
        await sharpImage.toFile(outputPath);
      }
  
      return { success: true, input: inputPath, output: outputPath };
    } catch (error) {
      console.error(`Error processing image ${inputPath}:`, error);
      if (tempFilePath && fs.existsSync(tempFilePath)) {
        fs.unlinkSync(tempFilePath);
      }
      const errorMessage = error instanceof Error ? error.message : String(error);
      return { success: false, input: inputPath, error: errorMessage };
    }
  }

• src/tools/image_tool.ts:132-168 (helper)

  Helper function for batch processing directories recursively, identifying image files and applying processImage to each.

  async function processDirectory(sourcePath: string, outputPath: string, options: any) {
    try {
      const { recursive, backupDir, format } = options;
      await mkdir(outputPath, { recursive: true });
      const files = await readdir(sourcePath);
  
      const results = [];
      for (const file of files) {
        const filePath = path.join(sourcePath, file);
        const fileStat = await stat(filePath);
  
        if (fileStat.isFile() && /\.(jpg|jpeg|png|webp|avif|tiff|gif)$/i.test(file)) {
          const parsedPath = path.parse(file);
          const outputFileName = format ? `${parsedPath.name}.${format}` : file;
          const outputFilePath = path.join(outputPath, outputFileName);
  
          if (backupDir) {
            const backupPath = path.join(backupDir, file);
            await mkdir(path.dirname(backupPath), { recursive: true });
            fs.copyFileSync(filePath, backupPath);
          }
          const result = await processImage(filePath, outputFilePath, options);
          results.push(result);
        } else if (fileStat.isDirectory() && recursive) {
          const subDirectoryName = path.basename(file);
          const subDirectoryOutputPath = path.join(outputPath, subDirectoryName);
          const subDirectoryResults = await processDirectory(filePath, subDirectoryOutputPath, options);
          results.push(...subDirectoryResults);
        }
      }
      return results;
    } catch (error) {
      console.error(`Error processing directory ${sourcePath}:`, error);
      const errorMessage = error instanceof Error ? error.message : String(error);
      return [{ success: false, input: sourcePath, error: errorMessage }];
    }
  }