Universal Image Generator MCP Server

Instructions

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