ultimate-gemini-mcp 1.5.1__tar.gz → 1.6.1__tar.gz

{ultimate_gemini_mcp-1.5.1 → ultimate_gemini_mcp-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultimate-gemini-mcp
-Version: 1.5.1
+Version: 1.6.1
 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
@@ -38,6 +38,8 @@ Description-Content-Type: text/markdown
 
 > The most comprehensive MCP server for AI image generation, unifying Google's Gemini 2.5 Flash Image and Imagen 4/Ultra models with advanced features.
 
+[![MCP Badge](https://lobehub.com/badge/mcp-full/anand-92-ultimate-image-gen-mcp)](https://lobehub.com/mcp/anand-92-ultimate-image-gen-mcp)
+
 ## ✨ Features
 
 ### Unified API Support
@@ -201,13 +203,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 +229,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 +249,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 +434,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 +467,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.5.1 → ultimate_gemini_mcp-1.6.1}/README.md

@@ -2,6 +2,8 @@
 
 > The most comprehensive MCP server for AI image generation, unifying Google's Gemini 2.5 Flash Image and Imagen 4/Ultra models with advanced features.
 
+[![MCP Badge](https://lobehub.com/badge/mcp-full/anand-92-ultimate-image-gen-mcp)](https://lobehub.com/mcp/anand-92-ultimate-image-gen-mcp)
+
 ## ✨ Features
 
 ### Unified API Support
@@ -165,13 +167,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 +193,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 +213,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 +398,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 +431,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.5.1 → ultimate_gemini_mcp-1.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ultimate-gemini-mcp"
-version = "1.5.1"
+version = "1.6.1"
 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.5.1 → ultimate_gemini_mcp-1.6.1}/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.5.1"
+__version__ = "1.6.1"
 __author__ = "Ultimate Gemini MCP"
 
 from .config import get_settings

{ultimate_gemini_mcp-1.5.1 → ultimate_gemini_mcp-1.6.1}/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.5.1 → ultimate_gemini_mcp-1.6.1}/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.5.1 → ultimate_gemini_mcp-1.6.1}/src/tools/batch_generate.py

@@ -133,6 +133,21 @@ def register_batch_generate_tool(mcp_server: Any) -> None:
 
         Returns:
             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(

{ultimate_gemini_mcp-1.5.1 → ultimate_gemini_mcp-1.6.1}/src/tools/generate_image.py

@@ -217,6 +217,27 @@ def register_generate_image_tool(mcp_server: Any) -> None:
 
         Returns:
             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(