ultimate-gemini-mcp 1.0.1__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__ = "1.0.1"
+__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,32 @@
+"""Configuration module for Ultimate Gemini MCP."""
+
+from .constants import (
+    ALL_MODELS,
+    ASPECT_RATIOS,
+    DEFAULT_GEMINI_MODEL,
+    DEFAULT_IMAGEN_MODEL,
+    GEMINI_MODELS,
+    IMAGE_FORMATS,
+    IMAGEN_MODELS,
+    MAX_BATCH_SIZE,
+    MAX_IMAGES_PER_REQUEST,
+    PERSON_GENERATION_OPTIONS,
+)
+from .settings import APIConfig, ServerConfig, Settings, get_settings
+
+__all__ = [
+    "ALL_MODELS",
+    "ASPECT_RATIOS",
+    "DEFAULT_GEMINI_MODEL",
+    "DEFAULT_IMAGEN_MODEL",
+    "GEMINI_MODELS",
+    "IMAGE_FORMATS",
+    "IMAGEN_MODELS",
+    "MAX_BATCH_SIZE",
+    "MAX_IMAGES_PER_REQUEST",
+    "PERSON_GENERATION_OPTIONS",
+    "APIConfig",
+    "ServerConfig",
+    "Settings",
+    "get_settings",
+]

src/config/constants.py

@@ -0,0 +1,77 @@
+"""
+Constants and model definitions for both Gemini and Imagen APIs.
+"""
+
+from typing import Final
+
+# API Endpoints
+GEMINI_API_BASE: Final[str] = "https://generativelanguage.googleapis.com/v1beta"
+IMAGEN_API_BASE: Final[str] = "https://generativelanguage.googleapis.com/v1beta"
+
+# Gemini Models (generateContent API)
+GEMINI_MODELS = {
+    "gemini-2.5-flash-image": "gemini-2.5-flash-image",
+    "gemini-flash-latest": "gemini-flash-latest",  # For prompt enhancement (non-image)
+}
+
+# Imagen Models (predict API)
+IMAGEN_MODELS = {
+    "imagen-4": "models/imagen-4.0-generate-001",
+    "imagen-4-fast": "models/imagen-4.0-fast-generate-001",
+    "imagen-4-ultra": "models/imagen-4.0-ultra-generate-001",
+}
+
+# All available models
+ALL_MODELS = {**GEMINI_MODELS, **IMAGEN_MODELS}
+
+# Default models
+DEFAULT_GEMINI_MODEL = "gemini-2.5-flash-image"
+DEFAULT_IMAGEN_MODEL = "imagen-4-ultra"
+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",
+}
+
+# Person generation options (Imagen API)
+PERSON_GENERATION_OPTIONS = [
+    "dont_allow",
+    "allow_adult",
+    "allow_all",
+]
+
+# Generation limits
+MAX_IMAGES_PER_REQUEST = 4
+MAX_BATCH_SIZE = 8
+MAX_PROMPT_LENGTH = 8192
+MAX_NEGATIVE_PROMPT_LENGTH = 1024
+
+# 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 = "generated_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 Optional
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from .constants import (
+    DEFAULT_ENHANCEMENT_MODEL,
+    DEFAULT_GEMINI_MODEL,
+    DEFAULT_IMAGEN_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_gemini_model: str = Field(
+        default=DEFAULT_GEMINI_MODEL, description="Default Gemini model"
+    )
+    default_imagen_model: str = Field(
+        default=DEFAULT_IMAGEN_MODEL, description="Default Imagen 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_output_format: str = Field(default="png", description="Default output format")
+
+    def __init__(self, **kwargs):
+        """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):
+        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: Optional[Settings] = 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,55 @@
+"""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_negative_prompt,
+    validate_number_of_images,
+    validate_person_generation,
+    validate_prompt,
+    validate_prompts_list,
+    validate_seed,
+)
+
+__all__ = [
+    # Exceptions
+    "UltimateGeminiError",
+    "ConfigurationError",
+    "ValidationError",
+    "APIError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ContentPolicyError",
+    "ImageProcessingError",
+    "FileOperationError",
+    # Validation
+    "validate_prompt",
+    "validate_negative_prompt",
+    "validate_model",
+    "validate_aspect_ratio",
+    "validate_number_of_images",
+    "validate_image_format",
+    "validate_person_generation",
+    "validate_seed",
+    "validate_file_path",
+    "validate_base64_image",
+    "validate_prompts_list",
+    "validate_batch_size",
+    "sanitize_filename",
+]

src/core/exceptions.py

@@ -0,0 +1,60 @@
+"""
+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,161 @@
+"""
+Input validation utilities.
+"""
+
+import base64
+import re
+from pathlib import Path
+from typing import Any
+
+from ..config.constants import (
+    ALL_MODELS,
+    ASPECT_RATIOS,
+    IMAGE_FORMATS,
+    MAX_IMAGES_PER_REQUEST,
+    MAX_NEGATIVE_PROMPT_LENGTH,
+    MAX_PROMPT_LENGTH,
+    PERSON_GENERATION_OPTIONS,
+)
+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_negative_prompt(negative_prompt: str | None) -> None:
+    """Validate negative prompt text."""
+    if negative_prompt and len(negative_prompt) > MAX_NEGATIVE_PROMPT_LENGTH:
+        raise ValidationError(
+            f"Negative prompt too long: {len(negative_prompt)} characters "
+            f"(max {MAX_NEGATIVE_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_number_of_images(num: int) -> None:
+    """Validate number of images to generate."""
+    if not isinstance(num, int) or num < 1:
+        raise ValidationError(f"Number of images must be at least 1, got {num}")
+
+    if num > MAX_IMAGES_PER_REQUEST:
+        raise ValidationError(
+            f"Number of images exceeds maximum: {num} > {MAX_IMAGES_PER_REQUEST}"
+        )
+
+
+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_person_generation(option: str) -> None:
+    """Validate person generation option."""
+    if option not in PERSON_GENERATION_OPTIONS:
+        available = ", ".join(PERSON_GENERATION_OPTIONS)
+        raise ValidationError(
+            f"Invalid person generation option '{option}'. Available: {available}"
+        )
+
+
+def validate_seed(seed: int | None) -> None:
+    """Validate seed value."""
+    if seed is not None:
+        if not isinstance(seed, int):
+            raise ValidationError(f"Seed must be an integer, got {type(seed).__name__}")
+        if seed < 0:
+            raise ValidationError(f"Seed must be non-negative, got {seed}")
+
+
+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}")
+
+    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}")
+
+
+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}")
+
+
+def sanitize_filename(filename: str) -> str:
+    """Sanitize filename to remove unsafe characters."""
+    # Remove or replace unsafe characters
+    safe_name = re.sub(r'[<>:"/\\|?*\x00-\x1f]', "_", filename)
+    # Remove leading/trailing dots and spaces
+    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}")