ultimate-gemini-mcp 1.0.19__tar.gz → 1.6.0__tar.gz

{ultimate_gemini_mcp-1.0.19 → ultimate_gemini_mcp-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultimate-gemini-mcp
-Version: 1.0.19
+Version: 1.6.0
 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
@@ -201,13 +201,25 @@ Add to your `claude_desktop_config.json`:
       "command": "uvx",
       "args": ["ultimate-gemini-mcp"],
       "env": {
-        "GEMINI_API_KEY": "your-api-key-here"
+        "GEMINI_API_KEY": "your-api-key-here",
+        "OUTPUT_DIR": "/path/to/your/images"
       }
     }
   }
 }
 ```
 
+**Important Notes:**
+
+1. **OUTPUT_DIR is required** when using `uvx` to avoid read-only file system errors. Set it to an absolute path where you want generated images saved:
+   - **macOS**: `"/Users/yourusername/gemini_images"`
+   - **Windows**: `"C:\\Users\\YourUsername\\gemini_images"`
+
+2. **uvx path issues on macOS**: If you get `spawn uvx ENOENT` errors, use the full path to uvx:
+   ```json
+   "command": "/Users/yourusername/.local/bin/uvx"
+   ```
+
 **Config file locations:**
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
@@ -215,10 +227,15 @@ Add to your `claude_desktop_config.json`:
 ### With Claude Code (VS Code)
 
 ```bash
-# Add MCP server to Claude Code
-claude mcp add ultimate-gemini --env GEMINI_API_KEY=your-api-key -- uvx ultimate-gemini-mcp
+# Add MCP server to Claude Code (with required OUTPUT_DIR)
+claude mcp add ultimate-gemini \
+  --env GEMINI_API_KEY=your-api-key \
+  --env OUTPUT_DIR=/path/to/your/images \
+  -- uvx ultimate-gemini-mcp
 ```
 
+**Note**: Replace `/path/to/your/images` with an absolute path to where you want images saved.
+
 ### With Cursor
 
 Add to Cursor's MCP configuration (`.cursor/mcp.json`):
@@ -230,13 +247,16 @@ Add to Cursor's MCP configuration (`.cursor/mcp.json`):
       "command": "uvx",
       "args": ["ultimate-gemini-mcp"],
       "env": {
-        "GEMINI_API_KEY": "your-api-key-here"
+        "GEMINI_API_KEY": "your-api-key-here",
+        "OUTPUT_DIR": "/path/to/your/images"
       }
     }
   }
 }
 ```
 
+**Note**: Set `OUTPUT_DIR` to an absolute path where you want generated images saved.
+
 ## 🎯 Available Models
 
 ### Gemini Models
@@ -412,6 +432,24 @@ View current server configuration.
 
 ## 🐛 Troubleshooting
 
+### "spawn uvx ENOENT" error
+- **Cause**: Claude Desktop cannot find the `uvx` command in its PATH
+- **Solution**: Use the full path to uvx in your config:
+  ```json
+  "command": "/Users/yourusername/.local/bin/uvx"
+  ```
+- Find your uvx location with: `which uvx`
+
+### "[Errno 30] Read-only file system: 'generated_images'"
+- **Cause**: When using `uvx`, the default directory is in a read-only cache location
+- **Solution**: Add `OUTPUT_DIR` to your MCP config:
+  ```json
+  "env": {
+    "GEMINI_API_KEY": "your-key",
+    "OUTPUT_DIR": "/Users/yourusername/gemini_images"
+  }
+  ```
+
 ### "GEMINI_API_KEY not found"
 - Add your API key to `.env` or environment variables
 - Get a free key at [Google AI Studio](https://makersuite.google.com/app/apikey)
@@ -427,6 +465,7 @@ View current server configuration.
 ### Images not saving
 - Check that OUTPUT_DIR exists and is writable
 - Verify you have sufficient disk space
+- Create the directory manually: `mkdir -p /path/to/your/images`
 
 ## 🤝 Contributing
 

{ultimate_gemini_mcp-1.0.19 → ultimate_gemini_mcp-1.6.0}/README.md

@@ -165,13 +165,25 @@ Add to your `claude_desktop_config.json`:
       "command": "uvx",
       "args": ["ultimate-gemini-mcp"],
       "env": {
-        "GEMINI_API_KEY": "your-api-key-here"
+        "GEMINI_API_KEY": "your-api-key-here",
+        "OUTPUT_DIR": "/path/to/your/images"
       }
     }
   }
 }
 ```
 
+**Important Notes:**
+
+1. **OUTPUT_DIR is required** when using `uvx` to avoid read-only file system errors. Set it to an absolute path where you want generated images saved:
+   - **macOS**: `"/Users/yourusername/gemini_images"`
+   - **Windows**: `"C:\\Users\\YourUsername\\gemini_images"`
+
+2. **uvx path issues on macOS**: If you get `spawn uvx ENOENT` errors, use the full path to uvx:
+   ```json
+   "command": "/Users/yourusername/.local/bin/uvx"
+   ```
+
 **Config file locations:**
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
@@ -179,10 +191,15 @@ Add to your `claude_desktop_config.json`:
 ### With Claude Code (VS Code)
 
 ```bash
-# Add MCP server to Claude Code
-claude mcp add ultimate-gemini --env GEMINI_API_KEY=your-api-key -- uvx ultimate-gemini-mcp
+# Add MCP server to Claude Code (with required OUTPUT_DIR)
+claude mcp add ultimate-gemini \
+  --env GEMINI_API_KEY=your-api-key \
+  --env OUTPUT_DIR=/path/to/your/images \
+  -- uvx ultimate-gemini-mcp
 ```
 
+**Note**: Replace `/path/to/your/images` with an absolute path to where you want images saved.
+
 ### With Cursor
 
 Add to Cursor's MCP configuration (`.cursor/mcp.json`):
@@ -194,13 +211,16 @@ Add to Cursor's MCP configuration (`.cursor/mcp.json`):
       "command": "uvx",
       "args": ["ultimate-gemini-mcp"],
       "env": {
-        "GEMINI_API_KEY": "your-api-key-here"
+        "GEMINI_API_KEY": "your-api-key-here",
+        "OUTPUT_DIR": "/path/to/your/images"
       }
     }
   }
 }
 ```
 
+**Note**: Set `OUTPUT_DIR` to an absolute path where you want generated images saved.
+
 ## 🎯 Available Models
 
 ### Gemini Models
@@ -376,6 +396,24 @@ View current server configuration.
 
 ## 🐛 Troubleshooting
 
+### "spawn uvx ENOENT" error
+- **Cause**: Claude Desktop cannot find the `uvx` command in its PATH
+- **Solution**: Use the full path to uvx in your config:
+  ```json
+  "command": "/Users/yourusername/.local/bin/uvx"
+  ```
+- Find your uvx location with: `which uvx`
+
+### "[Errno 30] Read-only file system: 'generated_images'"
+- **Cause**: When using `uvx`, the default directory is in a read-only cache location
+- **Solution**: Add `OUTPUT_DIR` to your MCP config:
+  ```json
+  "env": {
+    "GEMINI_API_KEY": "your-key",
+    "OUTPUT_DIR": "/Users/yourusername/gemini_images"
+  }
+  ```
+
 ### "GEMINI_API_KEY not found"
 - Add your API key to `.env` or environment variables
 - Get a free key at [Google AI Studio](https://makersuite.google.com/app/apikey)
@@ -391,6 +429,7 @@ View current server configuration.
 ### Images not saving
 - Check that OUTPUT_DIR exists and is writable
 - Verify you have sufficient disk space
+- Create the directory manually: `mkdir -p /path/to/your/images`
 
 ## 🤝 Contributing
 

{ultimate_gemini_mcp-1.0.19 → ultimate_gemini_mcp-1.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ultimate-gemini-mcp"
-version = "1.0.19"
+version = "1.6.0"
 description = "Ultimate image generation MCP server unifying Gemini 2.5 Flash Image and Imagen 4/Fast/Ultra with advanced features"
 readme = "README.md"
 requires-python = ">=3.11"

{ultimate_gemini_mcp-1.0.19 → ultimate_gemini_mcp-1.6.0}/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.0.19"
+__version__ = "1.6.0"
 __author__ = "Ultimate Gemini MCP"
 
 from .config import get_settings

{ultimate_gemini_mcp-1.0.19 → ultimate_gemini_mcp-1.6.0}/src/config/constants.py

@@ -74,4 +74,4 @@ ENHANCEMENT_TIMEOUT = 30
 BATCH_TIMEOUT = 120
 
 # Output settings
-DEFAULT_OUTPUT_DIR = "/tmp/generated_images"
+DEFAULT_OUTPUT_DIR = "generated_images"

{ultimate_gemini_mcp-1.0.19 → ultimate_gemini_mcp-1.6.0}/src/core/validation.py

@@ -124,11 +124,13 @@ def validate_prompts_list(prompts: list[str]) -> None:
 
 
 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(". ")
+    """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"

{ultimate_gemini_mcp-1.0.19 → ultimate_gemini_mcp-1.6.0}/src/server.py

@@ -45,7 +45,7 @@ def create_app() -> FastMCP:
         # Create FastMCP server
         mcp = FastMCP(
             "Ultimate Gemini MCP",
-            version="1.0.0",
+            version="1.5.0",
         )
 
         # Register tools
@@ -53,27 +53,6 @@ def create_app() -> FastMCP:
         register_batch_generate_tool(mcp)
 
         # Add resources
-        @mcp.resource("image://latest", mime_type="image/png")
-        def get_latest_image() -> bytes:
-            """
-            Get the most recently generated image.
-
-            Returns:
-                Binary PNG image data
-            """
-            if not settings.output_dir.exists():
-                raise FileNotFoundError("No images have been generated yet")
-
-            # Find most recent PNG file
-            images = sorted(
-                settings.output_dir.glob("*.png"), key=lambda p: p.stat().st_mtime, reverse=True
-            )
-
-            if not images:
-                raise FileNotFoundError("No images found in output directory")
-
-            return images[0].read_bytes()
-
         @mcp.resource("models://list")
         def list_models() -> str:
             """List all available image generation models."""

{ultimate_gemini_mcp-1.0.19 → ultimate_gemini_mcp-1.6.0}/src/services/image_service.py

@@ -54,12 +54,14 @@ class ImageResult:
             raise ImageProcessingError(f"Failed to save image: {e}") from e
 
     def _generate_filename(self) -> str:
-        """Generate descriptive filename."""
+        """Generate clean, short filename."""
         timestamp = self.timestamp.strftime("%Y%m%d_%H%M%S")
-        # Sanitize prompt for filename
-        prompt_snippet = sanitize_filename(self.prompt[:50])
+        # 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-")
+        # 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 ""
-        return f"{self.model}_{timestamp}_{prompt_snippet}{index_str}.png"
+        return f"{model_short}_{timestamp}_{prompt_snippet}{index_str}.png"
 
     def get_size(self) -> int:
         """Get image size in bytes."""

{ultimate_gemini_mcp-1.0.19 → ultimate_gemini_mcp-1.6.0}/src/tools/batch_generate.py

@@ -115,7 +115,6 @@ def register_batch_generate_tool(mcp_server: Any) -> None:
         output_format: str = "png",
         batch_size: int | None = None,
         negative_prompt: str | None = None,
-        save_to_disk: bool = True,
     ) -> str:
         """
         Generate multiple images from a list of prompts efficiently.
@@ -131,13 +130,24 @@ def register_batch_generate_tool(mcp_server: Any) -> None:
             output_format: Image format for all images (default: png)
             batch_size: Parallel batch size (default: from config)
             negative_prompt: Negative prompt for Imagen models (optional)
-            save_to_disk: Save images to disk and return file paths (default: True).
-                         When True: Returns file paths only (efficient for MCP clients).
-                         When False: Returns base64 image data (for cloud/serverless).
 
         Returns:
-            JSON string with batch results and either file paths (save_to_disk=True)
-            or base64 image data (save_to_disk=False)
+            JSON string with batch results including individual image paths
+
+        IMPORTANT - AI Assistant Instructions:
+        After batch generation completes, you MUST:
+        1. Parse the JSON response to extract file paths from result["results"][i]["images"][0]["path"]
+        2. Show the user a summary of all generated images with their file paths
+        3. Optionally display one or more images using the Read tool
+        4. Let the user know the total count of successful vs failed generations
+
+        Example response to user:
+        "Successfully generated 3 images:
+        1. /path/to/image1.png - [description]
+        2. /path/to/image2.png - [description]
+        3. /path/to/image3.png - [description]"
+
+        DO NOT just say "batch generation completed" without listing the file paths!
         """
         try:
             result = await batch_generate_images(
@@ -148,7 +158,6 @@ def register_batch_generate_tool(mcp_server: Any) -> None:
                 output_format=output_format,
                 batch_size=batch_size,
                 negative_prompt=negative_prompt,
-                save_to_disk=save_to_disk,
             )
 
             return json.dumps(result, indent=2)

{ultimate_gemini_mcp-1.0.19 → ultimate_gemini_mcp-1.6.0}/src/tools/generate_image.py

@@ -153,19 +153,10 @@ async def generate_image_tool(
             }
 
             if save_to_disk:
-                # Try to save to output directory, but don't fail if it errors
-                try:
-                    file_path = result.save(settings.output_dir)
-                    image_info["path"] = str(file_path)
-                    image_info["filename"] = file_path.name
-                    logger.info(f"Saved image to {file_path}")
-                except Exception as e:
-                    logger.warning(f"Failed to save image to disk: {e}")
-                    image_info["save_error"] = str(e)
-            else:
-                # Only include base64 data when not saving to disk (cloud/serverless scenarios)
-                # This prevents token overflow for MCP clients with file system access
-                image_info["image_base64"] = result.image_data
+                # Save to output directory
+                file_path = result.save(settings.output_dir)
+                image_info["path"] = str(file_path)
+                image_info["filename"] = file_path.name
 
             # Add enhanced prompt info
             if "enhanced_prompt" in result.metadata:
@@ -196,7 +187,6 @@ def register_generate_image_tool(mcp_server: Any) -> None:
         use_world_knowledge: bool = False,
         negative_prompt: str | None = None,
         seed: int | None = None,
-        save_to_disk: bool = True,
     ) -> str:
         """
         Generate images using Google's Gemini or Imagen models.
@@ -218,9 +208,6 @@ def register_generate_image_tool(mcp_server: Any) -> None:
             use_world_knowledge: Use real-world knowledge (Gemini only)
             negative_prompt: What to avoid in the image (Imagen only)
             seed: Random seed for reproducibility (NOT SUPPORTED - will be ignored)
-            save_to_disk: Save images to disk and return file paths (default: True).
-                         When True: Returns file paths only (efficient for MCP clients).
-                         When False: Returns base64 image data (for cloud/serverless).
 
         Available models:
         - gemini-2.5-flash-image (default)
@@ -229,8 +216,28 @@ def register_generate_image_tool(mcp_server: Any) -> None:
         - imagen-4-ultra
 
         Returns:
-            JSON string with generation results and either file paths (save_to_disk=True)
-            or base64 image data (save_to_disk=False)
+            JSON string with generation results and file paths
+
+        IMPORTANT - AI Assistant Instructions:
+        After generating an image, you MUST:
+        1. Parse the JSON response to extract the file path from result["images"][0]["path"]
+        2. Inform the user of the EXACT file path where the image was saved
+        3. Use the Read tool to load and display the image to the user
+        4. Optionally: Use bash to open the image in the default viewer:
+           - macOS: `open /path/to/image.png`
+           - Linux: `xdg-open /path/to/image.png`
+           - Windows: `start /path/to/image.png`
+
+        Example workflow:
+        ```
+        1. Call generate_image tool
+        2. Parse response JSON to get file_path
+        3. Tell user: "Image saved to: /Users/name/gemini_images/image.png"
+        4. Call Read tool with the file_path to display the image
+        5. Optionally call Bash with `open /path/to/image.png` to open in Preview
+        ```
+
+        DO NOT just say "image generated successfully" without showing the path and image!
         """
         try:
             result = await generate_image_tool(
@@ -246,7 +253,6 @@ def register_generate_image_tool(mcp_server: Any) -> None:
                 use_world_knowledge=use_world_knowledge,
                 negative_prompt=negative_prompt,
                 seed=seed,
-                save_to_disk=save_to_disk,
             )
 
             return json.dumps(result, indent=2)

ultimate_gemini_mcp-1.0.19/.genkit/traces_idx/genkit.metadata

@@ -1 +0,0 @@
-{"version":"1.21.0"}