ultimate-gemini-mcp 1.6.1__py3-none-any.whl → 1.6.2__py3-none-any.whl

src/__init__.py

@@ -7,7 +7,7 @@ A unified MCP server that combines the best features from:
 - Advanced features: batch processing, editing, templates, and more
 """
 
-__version__ = "1.6.1"
+__version__ = "1.6.2"
 __author__ = "Ultimate Gemini MCP"
 
 from .config import get_settings

src/config/__init__.py

@@ -10,6 +10,7 @@ from .constants import (
     IMAGEN_MODELS,
     MAX_BATCH_SIZE,
     MAX_IMAGES_PER_REQUEST,
+    MODEL_METADATA,
     PERSON_GENERATION_OPTIONS,
 )
 from .settings import APIConfig, ServerConfig, Settings, get_settings
@@ -24,6 +25,7 @@ __all__ = [
     "IMAGEN_MODELS",
     "MAX_BATCH_SIZE",
     "MAX_IMAGES_PER_REQUEST",
+    "MODEL_METADATA",
     "PERSON_GENERATION_OPTIONS",
     "APIConfig",
     "ServerConfig",

src/config/constants.py

@@ -75,3 +75,58 @@ BATCH_TIMEOUT = 120
 
 # Output settings
 DEFAULT_OUTPUT_DIR = "generated_images"
+
+# Model metadata for MCP resources
+MODEL_METADATA = {
+    "gemini": {
+        "gemini-2.5-flash-image": {
+            "name": "Gemini 2.5 Flash Image",
+            "description": "Advanced image generation with editing and prompt enhancement",
+            "features": [
+                "Prompt enhancement",
+                "Image editing",
+                "Character consistency",
+                "Multi-image blending",
+                "World knowledge integration",
+            ],
+            "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",
+            ],
+        },
+    },
+}

src/core/validation.py

@@ -126,9 +126,9 @@ def validate_prompts_list(prompts: list[str]) -> None:
 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)
+    safe_name = re.sub(r"[^a-zA-Z0-9-]", "_", filename)
     # Remove multiple consecutive underscores
-    safe_name = re.sub(r'_+', '_', safe_name)
+    safe_name = re.sub(r"_+", "_", safe_name)
     # Remove leading/trailing underscores
     safe_name = safe_name.strip("_")
     # Ensure filename is not empty

src/server.py

@@ -8,12 +8,15 @@ Unified MCP server supporting:
 - Batch processing, prompt templates, and comprehensive features
 """
 
+import json
 import logging
 import sys
+from functools import lru_cache
+from typing import TypedDict
 
 from fastmcp import FastMCP
 
-from .config import ALL_MODELS, get_settings
+from .config import ALL_MODELS, MODEL_METADATA, get_settings
 from .tools import register_batch_generate_tool, register_generate_image_tool
 
 # Set up logging
@@ -26,6 +29,45 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 
+class PromptMessage(TypedDict):
+    """Type definition for MCP prompt messages."""
+
+    role: str
+    content: str
+
+
+def _validate_prompt_messages(messages: list[PromptMessage]) -> list[PromptMessage]:
+    """
+    Validate prompt message structure for MCP compliance.
+
+    Args:
+        messages: List of message dictionaries with 'role' and 'content' keys
+
+    Returns:
+        Validated messages (same as input if valid)
+
+    Raises:
+        ValueError: If message structure is invalid or types are incorrect
+    """
+    for msg in messages:
+        if "role" not in msg or "content" not in msg:
+            raise ValueError(f"Invalid prompt message structure: {msg}")
+        if not isinstance(msg["role"], str) or not isinstance(msg["content"], str):
+            raise ValueError(f"Prompt message role and content must be strings: {msg}")
+    return messages
+
+
+@lru_cache(maxsize=1)
+def _get_models_json() -> str:
+    """
+    Get models information as JSON (cached).
+
+    This function is cached because the models list is static.
+    Uses MODEL_METADATA from constants.py as the single source of truth.
+    """
+    return json.dumps(MODEL_METADATA, indent=2)
+
+
 def create_app() -> FastMCP:
     """
     Create and configure the Ultimate Gemini MCP application.
@@ -52,73 +94,99 @@ def create_app() -> FastMCP:
         register_generate_image_tool(mcp)
         register_batch_generate_tool(mcp)
 
+        # Add prompts
+        @mcp.prompt()
+        def quick_image_generation() -> list[PromptMessage]:
+            """Quick start: Generate a single image with Gemini."""
+            return _validate_prompt_messages(
+                [
+                    {
+                        "role": "user",
+                        "content": "Generate an image of a serene mountain landscape at sunset using the default Gemini model.",
+                    }
+                ]
+            )
+
+        @mcp.prompt()
+        def high_quality_image() -> list[PromptMessage]:
+            """Generate a high-quality image using Imagen 4 Ultra."""
+            return _validate_prompt_messages(
+                [
+                    {
+                        "role": "user",
+                        "content": "Generate a professional quality image of a futuristic cityscape with neon lights using the imagen-4-ultra model.",
+                    }
+                ]
+            )
+
+        @mcp.prompt()
+        def image_with_negative_prompt() -> list[PromptMessage]:
+            """Generate an image using negative prompts (Imagen only)."""
+            return _validate_prompt_messages(
+                [
+                    {
+                        "role": "user",
+                        "content": "Generate an image of a beautiful garden with flowers using imagen-4. Make sure there are no people or animals in the image.",
+                    }
+                ]
+            )
+
+        @mcp.prompt()
+        def batch_image_generation() -> list[PromptMessage]:
+            """Generate multiple images from a list of prompts."""
+            return _validate_prompt_messages(
+                [
+                    {
+                        "role": "user",
+                        "content": "Generate images for these three scenes: a cat on a windowsill, a dog in a park, and a bird in a tree.",
+                    }
+                ]
+            )
+
+        @mcp.prompt()
+        def edit_existing_image() -> list[PromptMessage]:
+            """Edit an existing image using Gemini (requires input image)."""
+            return _validate_prompt_messages(
+                [
+                    {
+                        "role": "user",
+                        "content": "I have an image at ~/Pictures/photo.jpg. Can you edit it to change the time of day to sunset?",
+                    }
+                ]
+            )
+
+        @mcp.prompt()
+        def character_consistency() -> list[PromptMessage]:
+            """Generate images with character consistency across multiple scenes (Gemini only, multi-step)."""
+            return _validate_prompt_messages(
+                [
+                    {
+                        "role": "user",
+                        "content": "First, generate an image of a cartoon wizard character studying in a library with maintain_character_consistency enabled. Then, generate a second image of the same wizard character exploring a magical forest, also with maintain_character_consistency enabled to keep the character's appearance consistent between scenes.",
+                    }
+                ]
+            )
+
         # Add resources
-        @mcp.resource("models://list")
+        @mcp.resource(
+            "models://list",
+            name="Available Models",
+            description="List all available image generation models with their features and capabilities",
+            mime_type="application/json",
+        )
         def list_models() -> str:
             """List all available image generation models."""
-            import json
-
-            models_info = {
-                "gemini": {
-                    "gemini-2.5-flash-image": {
-                        "name": "Gemini 2.5 Flash Image",
-                        "description": "Advanced image generation with editing and prompt enhancement",
-                        "features": [
-                            "Prompt enhancement",
-                            "Image editing",
-                            "Character consistency",
-                            "Multi-image blending",
-                            "World knowledge integration",
-                        ],
-                        "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 _get_models_json()
 
-            return json.dumps(models_info, indent=2)
-
-        @mcp.resource("settings://config")
+        @mcp.resource(
+            "settings://config",
+            name="Server Configuration",
+            description="Shows current server configuration including output directory, timeout settings, batch size limits, and default parameters",
+            mime_type="application/json",
+        )
         def get_config() -> str:
             """Get current server configuration."""
-            import json
-
+            # Note: Settings are not cached because they could change based on environment
             config = {
                 "output_directory": str(settings.output_dir),
                 "prompt_enhancement_enabled": settings.api.enable_prompt_enhancement,

src/services/image_service.py

@@ -57,7 +57,9 @@ class ImageResult:
         """Generate clean, short filename."""
         timestamp = self.timestamp.strftime("%Y%m%d_%H%M%S")
         # Shorten model name (e.g., gemini-2.5-flash-image -> gemini-flash)
-        model_short = self.model.replace("gemini-2.5-flash-image", "gemini-flash").replace("imagen-4-", "img4-")
+        model_short = self.model.replace("gemini-2.5-flash-image", "gemini-flash").replace(
+            "imagen-4-", "img4-"
+        )
         # Sanitize and shorten prompt (max 30 chars)
         prompt_snippet = sanitize_filename(self.prompt[:30])
         index_str = f"_{self.index + 1}" if self.index > 0 else ""

{ultimate_gemini_mcp-1.6.1.dist-info → ultimate_gemini_mcp-1.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultimate-gemini-mcp
-Version: 1.6.1
+Version: 1.6.2
 Summary: Ultimate image generation MCP server unifying Gemini 2.5 Flash Image and Imagen 4/Fast/Ultra with advanced features
 Project-URL: Homepage, https://github.com/anand-92/ultimate-image-gen-mcp
 Project-URL: Repository, https://github.com/anand-92/ultimate-image-gen-mcp
@@ -61,7 +61,7 @@ Description-Content-Type: text/markdown
 - Comprehensive error handling and validation
 - Configurable settings via environment variables
 - Detailed logging and debugging
-- MCP resources for configuration and model information
+- MCP prompts, tools, and resources for complete MCP integration
 
 ## 🎬 Showcase - See It In Action
 
@@ -143,10 +143,14 @@ a maine coon cat blended with spiderman raimi suit version
 2. **Model Variety**: Compare Imagen 4, Imagen 4 Ultra, and Gemini 2.5 Flash results side-by-side
 3. **AI Enhancement Magic**: See how prompt enhancement adds lighting, composition, and technical details
 4. **Consistent Quality**: All images feature dramatic chiaroscuro lighting, atmospheric effects, and hyper-detailed textures
+
 5. **Model-Specific Strengths**:
-   - Imagen 4 Ultra: Maximum quality and material detail
-   - Gemini 2.5 Flash: Dynamic poses and creative interpretations
-   - Imagen 4: Balanced speed and quality
+   - **Imagen 4 Ultra**: Maximum quality and material detail - best for final production work
+   - **Imagen 4**: Balanced quality with good performance - the standard choice
+   - **Imagen 4 Fast**: Optimized speed while maintaining quality - perfect for rapid iteration and prototyping
+   - **Gemini 2.5 Flash**: Dynamic poses and creative interpretations with editing capabilities
+
+**Note**: The showcase above demonstrates `imagen-4`, `imagen-4-ultra`, and `gemini-2.5-flash-image`. All Imagen models (including `imagen-4-fast`) produce similar quality outputs, with the main difference being generation speed.
 
 ## 🚀 Quick Start
 
@@ -384,13 +388,75 @@ Running with the same seed will produce the same image.
 | `MAX_BATCH_SIZE` | Maximum parallel batch size | `8` |
 | `LOG_LEVEL` | Logging level | `INFO` |
 
+## 💬 Prompts
+
+The server provides several ready-to-use prompt templates to help you get started. These can be selected in your MCP client (Claude Desktop, Cursor, etc.) for instant use.
+
+### `quick_image_generation`
+**Description**: Quick start - Generate a single image with Gemini.
+
+**What it does**: Creates a serene mountain landscape at sunset using the default Gemini model with prompt enhancement enabled.
+
+**Usage in Claude Desktop**: Select this prompt to get started immediately with a basic image generation.
+
+### `high_quality_image`
+**Description**: Generate a high-quality image using Imagen 4 Ultra.
+
+**What it does**: Creates a professional quality futuristic cityscape with neon lights using Imagen's highest quality model.
+
+**Usage example**: Perfect when you need the absolute best quality for professional work or final presentations.
+
+### `image_with_negative_prompt`
+**Description**: Generate an image using negative prompts (Imagen only).
+
+**What it does**: Creates a beautiful garden with flowers while explicitly avoiding people or animals using Imagen's negative prompt feature.
+
+**Usage example**: Use this when you want precise control over what NOT to include in your images.
+
+### `batch_image_generation`
+**Description**: Generate multiple images from a list of prompts.
+
+**What it does**: Creates three different images (cat on windowsill, dog in park, bird in tree) in a single request.
+
+**Usage example**: Ideal for generating multiple related images at once, like social media content or design variations.
+
+### `edit_existing_image`
+**Description**: Edit an existing image using Gemini (requires input image).
+
+**What it does**: Takes an existing image and modifies it to change the time of day to sunset.
+
+**Usage example**: Select this prompt and update the path to your own image file (e.g., ~/Pictures/photo.jpg) to edit it.
+
+### `character_consistency`
+**Description**: Generate images with character consistency across multiple scenes (Gemini only, multi-step).
+
+**What it does**: First generates a wizard character in a library, then generates the same wizard in a different scene (magical forest) while maintaining consistent character appearance.
+
+**Usage example**: Perfect for creating consistent character designs across multiple images for storytelling, character sheets, or animation concepts.
+
 ## 📚 MCP Resources
 
-### `models://list`
-View all available models with descriptions and features.
+Resources provide read-only access to server information and can be attached as context in your MCP client.
+
+### `models://list` - Available Models
+**URI**: `models://list`
+**Type**: application/json
+**Description**: Lists all available image generation models (Gemini and Imagen) with their features, capabilities, and descriptions.
+
+**Use this when you need to**:
+- Check which models are available
+- Understand model capabilities
+- See model-specific features
+
+### `settings://config` - Server Configuration
+**URI**: `settings://config`
+**Type**: application/json
+**Description**: Shows current server configuration including output directory, timeout settings, batch size limits, and default parameters.
 
-### `settings://config`
-View current server configuration.
+**Use this when you need to**:
+- Check where images are being saved
+- Verify prompt enhancement is enabled
+- See current timeout and batch settings
 
 ## 🎭 Use Cases
 

{ultimate_gemini_mcp-1.6.1.dist-info → ultimate_gemini_mcp-1.6.2.dist-info}/RECORD

@@ -1,21 +1,21 @@
-src/__init__.py,sha256=-pG7_5PkC32LJjdJT2Ueqqk2HX66FhXfWbaJxRdmLOA,435
-src/server.py,sha256=hyXuhS1h6DN2EiGle8giEPSV1UB3ba7t4do_2olTK3A,5862
-src/config/__init__.py,sha256=hL0recV_ycXBEGCym7BqwyaPCnQHy8o429pBirnBeiA,704
-src/config/constants.py,sha256=ue4dT6wFwCzAgDWvSt8RnbdaoaGHY8c7SViNxI-P73w,1870
+src/__init__.py,sha256=jG_iqkolbdWR4FZOnC98ZIc3gGf0npnnYUdXFiCQem0,435
+src/server.py,sha256=4GH2lgv_mb6I5DQta4t4-wXe1pQegnXeTj6ynnwlT7E,8319
+src/config/__init__.py,sha256=nKsm-7I6lQnImjjhBEkgaHduvCNQbff7LRXBR80HRuE,746
+src/config/constants.py,sha256=8kbpO_Wag1RQA4YBD4fo2rNBkP-Fg6nT2xHA-WKdgz0,3703
 src/config/settings.py,sha256=uTxxblnyqmglz1COd3QxjC2w3o6l51S9MTanP4HBrgE,4257
 src/core/__init__.py,sha256=PQKMAY5eYIEO1oS_hrzeuDgRopl76Wn6NLfhtXBX92I,1200
 src/core/exceptions.py,sha256=NVb4tpwoX_DR-Wp8r73brXvZhEP35SUMyuEis8llFR0,1211
-src/core/validation.py,sha256=ZlKDcviKQvZLCfOALSIn7sOOt1DxNlchPq0YhJJMqKI,4887
+src/core/validation.py,sha256=5OZU7M5_4GoM52NeNozURHe6sF7cIpZBEuyuS95aiLE,4887
 src/services/__init__.py,sha256=n6FVDj052zvTerDFJSjaiLIycWGePm8Wr6dabbvd9o0,395
 src/services/gemini_client.py,sha256=VPuBPDHhAag_8xBqzMuVIEWVG0BINXOHkwKIALzcFAk,8324
-src/services/image_service.py,sha256=6eqp7dukRPfIgHs4sBvfxZ7hsc8E6LrvPx_RdU_h1OM,7300
+src/services/image_service.py,sha256=27Pirtr23H8U8rDKpeUMhV4XtyUgUPc56otQy043tZU,7322
 src/services/imagen_client.py,sha256=mvwbmtYQHqpKKM36tp8JPZTjxav5eeeist37lRJsv4k,6122
 src/services/prompt_enhancer.py,sha256=J_0s1EVmXdPAhjZPM4hL1vk9YiawqfH_ogF89VrFkW8,4776
 src/tools/__init__.py,sha256=zBfAjFT51LvvD7WXTfDYiyJstRdphr2ChddAmGMZxkI,346
 src/tools/batch_generate.py,sha256=R_aqngSCwg3QAprPHe_0uqH_KJ35G6DoSVA9CU3KkZk,5744
 src/tools/generate_image.py,sha256=wNN1w_KlMpqDP80EhNiDzvEvPozCOFweY9y4w9NtWac,9458
-ultimate_gemini_mcp-1.6.1.dist-info/METADATA,sha256=oybKglSmqi_v3zJDCfF3h4NOZnZnhIFDgHnLR5E-Z9E,17729
-ultimate_gemini_mcp-1.6.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ultimate_gemini_mcp-1.6.1.dist-info/entry_points.txt,sha256=-BeRTT4oR05e-YnF1ZNbNxlaekD4LsWhD-Zy_1dyRnc,56
-ultimate_gemini_mcp-1.6.1.dist-info/licenses/LICENSE,sha256=ilyzUnN0QHYtYGJks-NFUwiniNu08IedLmn_muRqa0o,1480
-ultimate_gemini_mcp-1.6.1.dist-info/RECORD,,
+ultimate_gemini_mcp-1.6.2.dist-info/METADATA,sha256=g8pUyqkmyrrS9pL_NgCuLbItefOdkv6yZyt-wDSuyeM,21253
+ultimate_gemini_mcp-1.6.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ultimate_gemini_mcp-1.6.2.dist-info/entry_points.txt,sha256=-BeRTT4oR05e-YnF1ZNbNxlaekD4LsWhD-Zy_1dyRnc,56
+ultimate_gemini_mcp-1.6.2.dist-info/licenses/LICENSE,sha256=ilyzUnN0QHYtYGJks-NFUwiniNu08IedLmn_muRqa0o,1480
+ultimate_gemini_mcp-1.6.2.dist-info/RECORD,,