extract_image_from_file

Instructions

Implementation Reference

• src/image-utils.ts:111-227 (handler)

  Core implementation of the extractImageFromFile handler: reads file, checks size, resizes to max 512x512, determines MIME type, compresses, encodes to base64, returns MCP response with metadata and image.

  export async function extractImageFromFile(params: ExtractImageFromFileParams): Promise<McpToolResponse> {
    try {
      const { file_path, resize, max_width, max_height } = params;
      
      // Check if file exists
      if (!fs.existsSync(file_path)) {
        return {
          content: [{ type: "text", text: `Error: File ${file_path} does not exist` }],
          isError: true
        };
      }
      
      // Read file
      let imageBuffer = fs.readFileSync(file_path);
      
      // Check size
      if (imageBuffer.length > MAX_IMAGE_SIZE) {
        return {
          content: [{ type: "text", text: `Error: Image size exceeds maximum allowed size of ${MAX_IMAGE_SIZE} bytes` }],
          isError: true
        };
      }
      
      // Process the image
      let metadata = await sharp(imageBuffer).metadata();
      
      // Always resize to ensure the base64 representation is reasonable
      // This will help avoid consuming too much of the context window
      if (metadata.width && metadata.height) {
        // Use provided dimensions or fallback to defaults for optimal LLM context usage
        const targetWidth = Math.min(metadata.width, DEFAULT_MAX_WIDTH);
        const targetHeight = Math.min(metadata.height, DEFAULT_MAX_HEIGHT);
        
        // Only resize if needed
        if (metadata.width > targetWidth || metadata.height > targetHeight) {
          imageBuffer = await sharp(imageBuffer)
            .resize({
              width: targetWidth,
              height: targetHeight,
              fit: 'inside',
              withoutEnlargement: true
            })
            .toBuffer();
          
          // Update metadata after resize
          metadata = await sharp(imageBuffer).metadata();
        }
      }
  
      // Determine mime type based on file extension
      const fileExt = path.extname(file_path).toLowerCase();
      let mimeType = 'image/jpeg';
      let format = 'jpeg';
      
      if (fileExt === '.png') {
        mimeType = 'image/png';
        format = 'png';
      }
      else if (fileExt === '.jpg' || fileExt === '.jpeg') {
        mimeType = 'image/jpeg';
        format = 'jpeg';
      }
      else if (fileExt === '.gif') {
        mimeType = 'image/gif';
        format = 'gif';
      }
      else if (fileExt === '.webp') {
        mimeType = 'image/webp';
        format = 'webp';
      }
      else if (fileExt === '.svg') {
        mimeType = 'image/svg+xml';
        format = 'svg';
      }
      else if (fileExt === '.avif') {
        mimeType = 'image/avif';
        format = 'avif';
      }
      
      // Compress the image based on its format
      try {
        imageBuffer = await compressImage(imageBuffer, format);
      } catch (compressionError) {
        console.warn('Compression warning, using original image:', compressionError);
        // Continue with the original image if compression fails
      }
      
      // Convert to base64
      const base64 = imageBuffer.toString('base64');
  
      // Return both text and image content
      return {
        content: [
          { 
            type: "text", 
            text: JSON.stringify({
              width: metadata.width,
              height: metadata.height,
              format: metadata.format,
              size: imageBuffer.length
            })
          },
          {
            type: "image",
            data: base64,
            mimeType: mimeType
          }
        ]
      };
    } catch (error: unknown) {
      console.error('Error processing image file:', error);
      return {
        content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
        isError: true
      };
    }
  }

• src/image-utils.ts:29-34 (schema)

  TypeScript type definition for the input parameters of extractImageFromFile.

  export type ExtractImageFromFileParams = {
    file_path: string;
    resize: boolean;
    max_width: number;
    max_height: number;
  };

• src/index.ts:22-35 (registration)

  MCP tool registration for 'extract_image_from_file': defines name, description, Zod input schema, and thin async handler that calls the core extractImageFromFile function.

  server.tool(
    "extract_image_from_file",
    "Extract and analyze images from local file paths. Supports visual content understanding, OCR text extraction, and object recognition for screenshots, photos, diagrams, and documents.",
    {
      file_path: z.string().describe("Path to the image file to analyze (supports screenshots, photos, diagrams, and documents in PNG, JPG, GIF, WebP formats)"),
      resize: z.boolean().default(true).describe("For backward compatibility only. Images are always automatically resized to optimal dimensions (max 512x512) for LLM analysis"),
      max_width: z.number().default(512).describe("For backward compatibility only. Default maximum width is now 512px"),
      max_height: z.number().default(512).describe("For backward compatibility only. Default maximum height is now 512px")
    },
    async (args, extra) => {
      const result = await extractImageFromFile(args);
      return result;
    }
  );

• src/image-utils.ts:78-108 (helper)

  Supporting helper function for compressing images using sharp based on detected format.

  async function compressImage(imageBuffer: Buffer, formatStr: string): Promise<Buffer> {
    const sharpInstance = sharp(imageBuffer);
    const format = formatStr.toLowerCase() as SupportedFormat;
    
    // Check if format is supported
    if (format in COMPRESSION_OPTIONS) {
      const options = COMPRESSION_OPTIONS[format];
      
      // Use specific methods based on format
      switch (format) {
        case 'jpeg':
        case 'jpg':
          return await sharpInstance.jpeg(options as any).toBuffer();
        case 'png':
          return await sharpInstance.png(options as any).toBuffer();
        case 'webp':
          return await sharpInstance.webp(options as any).toBuffer();
        case 'avif':
          return await sharpInstance.avif(options as any).toBuffer();
        case 'tiff':
          return await sharpInstance.tiff(options as any).toBuffer();
        // For formats without specific compression options
        case 'gif':
        case 'svg':
          return await sharpInstance.toBuffer();
      }
    }
    
    // Default to jpeg if format not supported
    return await sharpInstance.jpeg(COMPRESSION_OPTIONS.jpeg as any).toBuffer();
  }