Universal Image Generator MCP Server

Instructions

    Args:
        encoded_image: Base64 encoded image data with header. Must be in format:
                    "data:image/[format];base64,[data]"
                    Where [format] can be: png, jpeg, jpg, gif, webp, etc.
        prompt: Text prompt describing the desired transformation or modifications
        
    Returns:
        Path to the transformed image file saved on the server
    

Implementation Reference

• src/universal_image_generator_mcp/server.py:264-306 (handler)

  The core handler function for the 'transform_image_from_encoded' MCP tool. It is registered via the @mcp.tool() decorator. Loads base64-encoded image, translates and enhances the prompt, invokes the image provider's transformation method, saves the result, and returns the file path (and optional remote URL).

  @mcp.tool()
  async def transform_image_from_encoded(encoded_image: str, prompt: str) -> str:
      """Transform an existing image based on the given text prompt using the configured image provider.
  
      Args:
          encoded_image: Base64 encoded image data with header. Must be in format:
                      "data:image/[format];base64,[data]"
                      Where [format] can be: png, jpeg, jpg, gif, webp, etc.
          prompt: Text prompt describing the desired transformation or modifications
          
      Returns:
          Path to the transformed image file saved on the server
      """
      try:
          provider = get_image_provider()
          logger.info(f"Processing transform_image_from_encoded request with {provider.get_name()}")
          logger.info(f"Transformation prompt: {prompt}")
  
          # Load and validate the image
          source_image, _ = await load_image_from_base64(encoded_image)
          
          # Translate the prompt for the provider
          translated_prompt = await translate_prompt_for_provider(prompt, provider)
          
          # Create detailed transformation prompt
          transformation_prompt = get_image_transformation_prompt(translated_prompt)
          
          # Process the transformation using the provider
          _, saved_path, remote_url = await provider.transform_image(source_image, transformation_prompt)
          
          logger.info(f"Image transformed and saved to: {saved_path}")
          
          # Prepare response with remote URL if available
          response = f"Image transformed and saved to: {saved_path}"
          if remote_url:
              response += f"\nRemote URL: {remote_url}"
          
          return response
          
      except Exception as e:
          error_msg = f"Error transforming image: {str(e)}"
          logger.error(error_msg)
          return error_msg

• src/universal_image_generator_mcp/server.py:264-264 (registration)

  The @mcp.tool() decorator registers the transform_image_from_encoded function as an MCP tool. Registration is conditional on the provider supporting image transformation (see lines 252-260).

  @mcp.tool()

• src/universal_image_generator_mcp/server.py:168-199 (helper)

  Helper function used by the handler to load and validate the base64-encoded input image into a PIL Image object.

  async def load_image_from_base64(encoded_image: str) -> Tuple[PIL.Image.Image, str]:
      """Load an image from a base64-encoded string.
      
      Args:
          encoded_image: Base64 encoded image data with header
          
      Returns:
          Tuple containing the PIL Image object and the image format
      """
      if not encoded_image.startswith('data:image/'):
          raise ValueError("Invalid image format. Expected data:image/[format];base64,[data]")
      
      try:
          # Extract the base64 data from the data URL
          image_format, image_data = encoded_image.split(';base64,')
          image_format = image_format.replace('data:', '')  # Get the MIME type e.g., "image/png"
          image_bytes = base64.b64decode(image_data)
          source_image = PIL.Image.open(BytesIO(image_bytes))
          logger.info(f"Successfully loaded image with format: {image_format}")
          return source_image, image_format
      except binascii.Error as e:
          logger.error(f"Error: Invalid base64 encoding: {str(e)}")
          raise ValueError("Invalid base64 encoding. Please provide a valid base64 encoded image.")
      except ValueError as e:
          logger.error(f"Error: Invalid image data format: {str(e)}")
          raise ValueError("Invalid image data format. Image must be in format 'data:image/[format];base64,[data]'")
      except PIL.UnidentifiedImageError:
          logger.error("Error: Could not identify image format")
          raise ValueError("Could not identify image format. Supported formats include PNG, JPEG, GIF, WebP.")
      except Exception as e:
          logger.error(f"Error: Could not load image: {str(e)}")
          raise