ultimate-gemini-mcp 3.0.7__py3-none-any.whl

src/__init__.py

@@ -0,0 +1,16 @@
+"""
+Ultimate Gemini MCP Server
+
+A unified MCP server that combines the best features from:
+- Gemini 2.5 Flash Image (with prompt enhancement)
+- Imagen 3, 4, and 4-Ultra
+- Advanced features: batch processing, editing, templates, and more
+"""
+
+__version__ = "3.0.7"
+__author__ = "Ultimate Gemini MCP"
+
+from .config import get_settings
+from .server import create_app, main
+
+__all__ = ["create_app", "main", "get_settings", "__version__"]

src/config/__init__.py

@@ -0,0 +1,44 @@
+"""Configuration module for Ultimate Gemini MCP."""
+
+from .constants import (
+    ALL_MODELS,
+    ASPECT_RATIOS,
+    DEFAULT_ENHANCEMENT_MODEL,
+    DEFAULT_IMAGE_SIZE,
+    DEFAULT_MODEL,
+    DEFAULT_OUTPUT_DIR,
+    DEFAULT_TIMEOUT,
+    GEMINI_MODELS,
+    IMAGE_FORMATS,
+    IMAGE_SIZES,
+    MAX_BATCH_SIZE,
+    MAX_HUMAN_IMAGES,
+    MAX_OBJECT_IMAGES,
+    MAX_PROMPT_LENGTH,
+    MAX_REFERENCE_IMAGES,
+    RESPONSE_MODALITIES,
+)
+from .settings import APIConfig, ServerConfig, Settings, get_settings
+
+__all__ = [
+    "ALL_MODELS",
+    "ASPECT_RATIOS",
+    "DEFAULT_ENHANCEMENT_MODEL",
+    "DEFAULT_IMAGE_SIZE",
+    "DEFAULT_MODEL",
+    "DEFAULT_OUTPUT_DIR",
+    "DEFAULT_TIMEOUT",
+    "GEMINI_MODELS",
+    "IMAGE_FORMATS",
+    "IMAGE_SIZES",
+    "MAX_BATCH_SIZE",
+    "MAX_HUMAN_IMAGES",
+    "MAX_OBJECT_IMAGES",
+    "MAX_PROMPT_LENGTH",
+    "MAX_REFERENCE_IMAGES",
+    "RESPONSE_MODALITIES",
+    "APIConfig",
+    "ServerConfig",
+    "Settings",
+    "get_settings",
+]

src/config/constants.py

@@ -0,0 +1,68 @@
+"""
+Constants and model definitions for Gemini 3 Pro Image API.
+"""
+
+from pathlib import Path
+
+# Gemini Models (using official Google GenAI SDK)
+GEMINI_MODELS = {
+    "gemini-3-pro-image-preview": "gemini-3-pro-image-preview",
+    "gemini-flash-latest": "gemini-flash-latest",  # For prompt enhancement (non-image)
+}
+
+# All available models
+ALL_MODELS = GEMINI_MODELS
+
+# Default models
+DEFAULT_MODEL = "gemini-3-pro-image-preview"
+DEFAULT_ENHANCEMENT_MODEL = "gemini-flash-latest"
+
+# Aspect ratios
+ASPECT_RATIOS = [
+    "1:1",  # Square
+    "2:3",  # Portrait
+    "3:2",  # Landscape
+    "3:4",  # Portrait
+    "4:3",  # Standard landscape
+    "4:5",  # Portrait
+    "5:4",  # Landscape
+    "9:16",  # Vertical mobile
+    "16:9",  # Widescreen
+    "21:9",  # Ultrawide
+]
+
+# Image formats
+IMAGE_FORMATS = {
+    "png": "image/png",
+    "jpeg": "image/jpeg",
+    "jpg": "image/jpeg",
+    "webp": "image/webp",
+}
+
+# Image sizes (Gemini 3 Pro Image)
+IMAGE_SIZES = ["1K", "2K", "4K"]
+DEFAULT_IMAGE_SIZE = "2K"
+
+# Reference images limits (Gemini 3 Pro Image)
+MAX_REFERENCE_IMAGES = 14
+MAX_OBJECT_IMAGES = 6
+MAX_HUMAN_IMAGES = 5
+
+# Response modalities
+RESPONSE_MODALITIES = ["TEXT", "IMAGE"]
+
+# Generation limits
+MAX_BATCH_SIZE = 8
+MAX_PROMPT_LENGTH = 8192
+
+# File size limits
+MAX_IMAGE_SIZE_MB = 20
+MAX_IMAGE_SIZE_BYTES = MAX_IMAGE_SIZE_MB * 1024 * 1024
+
+# Timeout settings (in seconds)
+DEFAULT_TIMEOUT = 60
+ENHANCEMENT_TIMEOUT = 30
+BATCH_TIMEOUT = 120
+
+# Output settings
+DEFAULT_OUTPUT_DIR = str(Path.home() / "gemini_images")

src/config/settings.py

@@ -0,0 +1,143 @@
+"""
+Configuration settings for the Ultimate Gemini MCP server.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from .constants import (
+    DEFAULT_ENHANCEMENT_MODEL,
+    DEFAULT_IMAGE_SIZE,
+    DEFAULT_MODEL,
+    DEFAULT_OUTPUT_DIR,
+    DEFAULT_TIMEOUT,
+    MAX_BATCH_SIZE,
+)
+
+
+class ServerConfig(BaseSettings):
+    """Server configuration settings."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # Server settings
+    transport: str = Field(default="stdio", description="Transport mode: stdio or http")
+    host: str = Field(default="localhost", description="Host for HTTP transport")
+    port: int = Field(default=8000, description="Port for HTTP transport")
+
+    # Logging settings
+    log_level: str = Field(default="INFO", description="Logging level")
+    log_format: str = Field(default="standard", description="Log format: standard, json, detailed")
+
+    # Output settings
+    output_dir: str = Field(
+        default=DEFAULT_OUTPUT_DIR, description="Directory for generated images"
+    )
+
+    @classmethod
+    def from_env(cls) -> "ServerConfig":
+        """Load configuration from environment variables."""
+        return cls()
+
+
+class APIConfig(BaseSettings):
+    """API configuration for Gemini and Imagen."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # API Keys
+    gemini_api_key: str = Field(
+        default="",
+        alias="GEMINI_API_KEY",
+        description="Gemini API key (also accepts GOOGLE_API_KEY)",
+    )
+
+    # Model settings
+    default_model: str = Field(
+        default=DEFAULT_MODEL, description="Default Gemini 3 Pro Image model"
+    )
+    enhancement_model: str = Field(
+        default=DEFAULT_ENHANCEMENT_MODEL, description="Model for prompt enhancement"
+    )
+
+    # Feature flags
+    enable_prompt_enhancement: bool = Field(
+        default=True, description="Enable automatic prompt enhancement"
+    )
+    enable_batch_processing: bool = Field(default=True, description="Enable batch processing")
+
+    # Request settings
+    request_timeout: int = Field(default=DEFAULT_TIMEOUT, description="API request timeout")
+    max_batch_size: int = Field(
+        default=MAX_BATCH_SIZE, description="Maximum batch size for parallel requests"
+    )
+    max_retries: int = Field(default=3, description="Maximum number of retries for failed requests")
+
+    # Image settings
+    default_aspect_ratio: str = Field(default="1:1", description="Default aspect ratio")
+    default_image_size: str = Field(
+        default=DEFAULT_IMAGE_SIZE, description="Default image size (1K, 2K, 4K)"
+    )
+    default_output_format: str = Field(default="png", description="Default output format")
+    enable_google_search: bool = Field(default=False, description="Enable Google Search grounding")
+    response_modalities: list[str] = Field(
+        default=["TEXT", "IMAGE"], description="Response modalities"
+    )
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize API configuration with fallback for API key."""
+        super().__init__(**kwargs)
+        # Fallback to GOOGLE_API_KEY if GEMINI_API_KEY not set
+        if not self.gemini_api_key:
+            self.gemini_api_key = os.getenv("GOOGLE_API_KEY", "")
+
+        if not self.gemini_api_key:
+            raise ValueError("GEMINI_API_KEY or GOOGLE_API_KEY environment variable is required")
+
+    @classmethod
+    def from_env(cls) -> "APIConfig":
+        """Load API configuration from environment variables."""
+        return cls()
+
+
+class Settings:
+    """Combined settings for the server."""
+
+    def __init__(self) -> None:
+        self.server = ServerConfig.from_env()
+        self.api = APIConfig.from_env()
+
+        # Ensure output directory exists
+        output_path = Path(self.server.output_dir)
+        output_path.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def output_dir(self) -> Path:
+        """Get output directory as Path object."""
+        return Path(self.server.output_dir)
+
+
+# Global settings instance (lazy initialization)
+_settings: Settings | None = None
+
+
+def get_settings() -> Settings:
+    """Get or create global settings instance."""
+    global _settings
+    if _settings is None:
+        _settings = Settings()
+    return _settings

src/core/__init__.py

@@ -0,0 +1,47 @@
+"""Core modules for Ultimate Gemini MCP."""
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ContentPolicyError,
+    FileOperationError,
+    ImageProcessingError,
+    RateLimitError,
+    UltimateGeminiError,
+    ValidationError,
+)
+from .validation import (
+    sanitize_filename,
+    validate_aspect_ratio,
+    validate_base64_image,
+    validate_batch_size,
+    validate_file_path,
+    validate_image_format,
+    validate_model,
+    validate_prompt,
+    validate_prompts_list,
+)
+
+__all__ = [
+    # Exceptions
+    "UltimateGeminiError",
+    "ConfigurationError",
+    "ValidationError",
+    "APIError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ContentPolicyError",
+    "ImageProcessingError",
+    "FileOperationError",
+    # Validation
+    "validate_prompt",
+    "validate_model",
+    "validate_aspect_ratio",
+    "validate_image_format",
+    "validate_file_path",
+    "validate_base64_image",
+    "validate_prompts_list",
+    "validate_batch_size",
+    "sanitize_filename",
+]

src/core/exceptions.py

@@ -0,0 +1,62 @@
+"""
+Custom exceptions for the Ultimate Gemini MCP server.
+"""
+
+
+class UltimateGeminiError(Exception):
+    """Base exception for all Ultimate Gemini MCP errors."""
+
+    pass
+
+
+class ConfigurationError(UltimateGeminiError):
+    """Raised when there's a configuration error."""
+
+    pass
+
+
+class ValidationError(UltimateGeminiError):
+    """Raised when input validation fails."""
+
+    pass
+
+
+class APIError(UltimateGeminiError):
+    """Raised when an API request fails."""
+
+    def __init__(
+        self, message: str, status_code: int | None = None, response_data: dict | None = None
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_data = response_data
+
+
+class AuthenticationError(APIError):
+    """Raised when API authentication fails."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """Raised when API rate limit is exceeded."""
+
+    pass
+
+
+class ContentPolicyError(APIError):
+    """Raised when content violates safety policies."""
+
+    pass
+
+
+class ImageProcessingError(UltimateGeminiError):
+    """Raised when image processing fails."""
+
+    pass
+
+
+class FileOperationError(UltimateGeminiError):
+    """Raised when file operations fail."""
+
+    pass

src/core/validation.py

@@ -0,0 +1,117 @@
+"""
+Input validation utilities.
+"""
+
+import base64
+import re
+from pathlib import Path
+
+from ..config.constants import (
+    ALL_MODELS,
+    ASPECT_RATIOS,
+    IMAGE_FORMATS,
+    MAX_PROMPT_LENGTH,
+)
+from .exceptions import ValidationError
+
+
+def validate_prompt(prompt: str) -> None:
+    """Validate prompt text."""
+    if not prompt or not prompt.strip():
+        raise ValidationError("Prompt cannot be empty")
+
+    if len(prompt) > MAX_PROMPT_LENGTH:
+        raise ValidationError(
+            f"Prompt too long: {len(prompt)} characters (max {MAX_PROMPT_LENGTH})"
+        )
+
+
+def validate_model(model: str) -> None:
+    """Validate model name."""
+    if model not in ALL_MODELS:
+        available = ", ".join(ALL_MODELS.keys())
+        raise ValidationError(f"Invalid model '{model}'. Available models: {available}")
+
+
+def validate_aspect_ratio(aspect_ratio: str) -> None:
+    """Validate aspect ratio."""
+    if aspect_ratio not in ASPECT_RATIOS:
+        available = ", ".join(ASPECT_RATIOS)
+        raise ValidationError(f"Invalid aspect ratio '{aspect_ratio}'. Available: {available}")
+
+
+def validate_image_format(format_str: str) -> None:
+    """Validate image format."""
+    if format_str.lower() not in IMAGE_FORMATS:
+        available = ", ".join(IMAGE_FORMATS.keys())
+        raise ValidationError(f"Invalid image format '{format_str}'. Available: {available}")
+
+
+def validate_file_path(path: str) -> Path:
+    """Validate and return file path."""
+    try:
+        file_path = Path(path).resolve()
+    except Exception as e:
+        raise ValidationError(f"Invalid file path '{path}': {e}") from e
+
+    if not file_path.exists():
+        raise ValidationError(f"File does not exist: {file_path}")
+
+    if not file_path.is_file():
+        raise ValidationError(f"Path is not a file: {file_path}")
+
+    return file_path
+
+
+def validate_base64_image(data: str) -> None:
+    """Validate base64-encoded image data."""
+    if not data:
+        raise ValidationError("Base64 image data cannot be empty")
+
+    try:
+        # Try to decode to verify it's valid base64
+        decoded = base64.b64decode(data, validate=True)
+        if len(decoded) == 0:
+            raise ValidationError("Decoded image data is empty")
+    except Exception as e:
+        raise ValidationError(f"Invalid base64 image data: {e}") from e
+
+
+def validate_prompts_list(prompts: list[str]) -> None:
+    """Validate list of prompts for batch processing."""
+    if not isinstance(prompts, list):
+        raise ValidationError("Prompts must be a list")
+
+    if not prompts:
+        raise ValidationError("Prompts list cannot be empty")
+
+    for i, prompt in enumerate(prompts):
+        if not isinstance(prompt, str):
+            raise ValidationError(f"Prompt at index {i} must be a string")
+        try:
+            validate_prompt(prompt)
+        except ValidationError as e:
+            raise ValidationError(f"Invalid prompt at index {i}: {e}") from e
+
+
+def sanitize_filename(filename: str) -> str:
+    """Sanitize filename to remove unsafe and special characters."""
+    # Replace all non-alphanumeric characters (except hyphens) with underscores
+    safe_name = re.sub(r"[^a-zA-Z0-9-]", "_", filename)
+    # Remove multiple consecutive underscores
+    safe_name = re.sub(r"_+", "_", safe_name)
+    # Remove leading/trailing underscores
+    safe_name = safe_name.strip("_")
+    # Ensure filename is not empty
+    if not safe_name:
+        safe_name = "image"
+    return safe_name
+
+
+def validate_batch_size(size: int, max_size: int) -> None:
+    """Validate batch size."""
+    if not isinstance(size, int) or size < 1:
+        raise ValidationError(f"Batch size must be at least 1, got {size}")
+
+    if size > max_size:
+        raise ValidationError(f"Batch size exceeds maximum: {size} > {max_size}")

src/server.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+Ultimate Gemini MCP Server - Main Entry Point
+
+Unified MCP server supporting:
+- Gemini 3 Pro Image (with 4K resolution, reasoning, prompt enhancement and editing)
+- Imagen 4, 4-Fast, and 4-Ultra (with advanced controls)
+- Batch processing, prompt templates, and comprehensive features
+"""
+
+import logging
+import sys
+
+from fastmcp import FastMCP
+
+from .config import ALL_MODELS, get_settings
+from .tools import register_batch_generate_tool, register_generate_image_tool
+
+# Set up logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    stream=sys.stderr,  # Important: use stderr for logging in MCP
+)
+
+logger = logging.getLogger(__name__)
+
+
+def create_app() -> FastMCP:
+    """
+    Create and configure the Ultimate Gemini MCP application.
+
+    This is the factory function used by FastMCP CLI.
+    """
+    logger.info("Initializing Ultimate Gemini MCP Server...")
+
+    try:
+        # Load settings (validates API key)
+        settings = get_settings()
+
+        logger.info(f"Output directory: {settings.output_dir}")
+        logger.info(f"Prompt enhancement: {settings.api.enable_prompt_enhancement}")
+        logger.info(f"Available models: {', '.join(ALL_MODELS.keys())}")
+
+        # Create FastMCP server
+        mcp = FastMCP(
+            "Ultimate Gemini MCP",
+            version="1.5.0",
+        )
+
+        # Register tools
+        register_generate_image_tool(mcp)
+        register_batch_generate_tool(mcp)
+
+        # Add resources
+        @mcp.resource("models://list")
+        def list_models() -> str:
+            """List all available image generation models."""
+            import json
+
+            models_info = {
+                "gemini": {
+                    "gemini-3-pro-image-preview": {
+                        "name": "Gemini 3 Pro Image",
+                        "description": "Advanced image generation with 4K resolution, reasoning, and editing",
+                        "features": [
+                            "Native 4K resolution",
+                            "Advanced reasoning capabilities",
+                            "Prompt enhancement",
+                            "Image editing",
+                            "Character consistency",
+                            "Multi-image blending",
+                            "World knowledge integration",
+                            "Grounded generation with Google Search",
+                        ],
+                        "default": True,
+                    }
+                },
+                "imagen": {
+                    "imagen-4": {
+                        "name": "Imagen 4",
+                        "description": "High-quality image generation with improved text rendering",
+                        "features": [
+                            "Enhanced quality",
+                            "Better text rendering",
+                            "Negative prompts",
+                            "Seed-based reproducibility",
+                            "Person generation controls",
+                            "Advanced controls",
+                        ],
+                    },
+                    "imagen-4-fast": {
+                        "name": "Imagen 4 Fast",
+                        "description": "Optimized for faster generation while maintaining good quality",
+                        "features": [
+                            "Faster generation speed",
+                            "Good quality output",
+                            "Negative prompts",
+                            "Seed-based reproducibility",
+                            "Person generation controls",
+                            "Cost-effective",
+                        ],
+                    },
+                    "imagen-4-ultra": {
+                        "name": "Imagen 4 Ultra",
+                        "description": "Highest quality with best prompt adherence",
+                        "features": [
+                            "Highest quality",
+                            "Best prompt adherence",
+                            "Professional results",
+                            "Enhanced text rendering",
+                            "Advanced controls",
+                        ],
+                    },
+                },
+            }
+
+            return json.dumps(models_info, indent=2)
+
+        @mcp.resource("settings://config")
+        def get_config() -> str:
+            """Get current server configuration."""
+            import json
+
+            config = {
+                "output_directory": str(settings.output_dir),
+                "prompt_enhancement_enabled": settings.api.enable_prompt_enhancement,
+                "batch_processing_enabled": settings.api.enable_batch_processing,
+                "default_model": settings.api.default_model,
+                "default_image_size": settings.api.default_image_size,
+                "max_batch_size": settings.api.max_batch_size,
+                "request_timeout": settings.api.request_timeout,
+                "default_aspect_ratio": settings.api.default_aspect_ratio,
+                "default_output_format": settings.api.default_output_format,
+            }
+
+            return json.dumps(config, indent=2)
+
+        logger.info("Ultimate Gemini MCP Server initialized successfully")
+        return mcp
+
+    except Exception as e:
+        logger.error(f"Failed to initialize server: {e}", exc_info=True)
+        raise
+
+
+def main() -> None:
+    """Main entry point for direct execution."""
+    try:
+        logger.info("Starting Ultimate Gemini MCP Server...")
+
+        # Create application
+        app = create_app()
+
+        # Run the server (FastMCP handles stdio transport)
+        logger.info("Server is ready and listening for MCP requests")
+        app.run()
+
+    except KeyboardInterrupt:
+        logger.info("Server shutdown requested by user")
+        sys.exit(0)
+    except Exception as e:
+        logger.error(f"Server error: {e}", exc_info=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

src/services/__init__.py

@@ -0,0 +1,13 @@
+"""Services module for Ultimate Gemini MCP."""
+
+from .gemini_client import GeminiClient
+from .image_service import ImageResult, ImageService
+from .prompt_enhancer import PromptEnhancer, create_prompt_enhancer
+
+__all__ = [
+    "GeminiClient",
+    "ImageService",
+    "ImageResult",
+    "PromptEnhancer",
+    "create_prompt_enhancer",
+]