Fix OpenAI/Gemini image generation and add Claude Code MCP support

- Update environment variables to provider-namespaced format (PROVIDERS__*__*)
- Switch Gemini provider from Generative AI API to Vertex AI with service account auth
- Fix gpt-image-1 model capabilities (remove unsupported style parameter)
- Add Claude Code MCP integration with start-mcp.sh script
- Update Docker configuration and documentation with Vertex AI setup instructions

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: rlorenzo

.env.example

@@ -15,9 +15,10 @@ PROVIDERS__OPENAI__TIMEOUT=300.0
 PROVIDERS__OPENAI__MAX_RETRIES=3
 PROVIDERS__OPENAI__ENABLED=true
 
-# Gemini Provider (default disabled)
-PROVIDERS__GEMINI__API_KEY=your-gemini-api-key-here
-PROVIDERS__GEMINI__BASE_URL=https://generativelanguage.googleapis.com/v1beta/
+# Gemini Provider (requires Vertex AI setup)
+# For Imagen models, use path to Google Cloud service account JSON file
+PROVIDERS__GEMINI__API_KEY=/path/to/your/vertex-ai-key.json
+PROVIDERS__GEMINI__BASE_URL=https://us-central1-aiplatform.googleapis.com/v1
 PROVIDERS__GEMINI__TIMEOUT=300.0
 PROVIDERS__GEMINI__MAX_RETRIES=3
 PROVIDERS__GEMINI__ENABLED=false

.gitignore

@@ -10,3 +10,18 @@ desktop.ini
 .coverage
 .cache/
 *.log
+
+# Google Cloud service account keys
+vertex-ai-key.json
+*-key.json
+*-service-account.json
+vertex-ai-*.json
+service-account-*.json
+
+# Generated images and storage
+storage/
+logs/
+
+# Auto-generated monitoring configuration
+monitoring/
+redis.conf

Dockerfile

@@ -16,8 +16,8 @@ WORKDIR /app
 # Copy dependency files
 COPY pyproject.toml uv.lock ./
 
-# Install dependencies
-RUN uv sync --frozen --no-dev
+# Install dependencies (include all groups for proper functionality)
+RUN uv sync --frozen
 
 # Production stage
 FROM python:3.11-slim
@@ -43,7 +43,8 @@ COPY . .
 RUN mkdir -p /app/storage/images /app/storage/cache /app/storage/logs && \
     chown -R appuser:appuser /app
 
-# Set environment variables
+# Set environment variables for virtual environment activation
+ENV VIRTUAL_ENV="/app/.venv"
 ENV PATH="/app/.venv/bin:$PATH"
 ENV PYTHONPATH="/app"
 ENV PYTHONDONTWRITEBYTECODE=1

README.md

@@ -112,7 +112,7 @@ The AI ecosystem has evolved to include powerful language models from multiple p
 - Python 3.10+
 - [UV package manager](https://docs.astral.sh/uv/)
 - OpenAI API key (for OpenAI models)
-- Google Gemini API key (for Gemini models, optional)
+- Google Cloud service account with Vertex AI access (for Imagen models, optional)
 
 ### Installation
 
@@ -128,11 +128,18 @@ The AI ecosystem has evolved to include powerful language models from multiple p
 2. **Configure environment**:
    ```bash
    cp .env.example .env
-   # Edit .env and add your API keys:
+   # Edit .env and add your credentials:
    # - PROVIDERS__OPENAI__API_KEY for OpenAI models
-   # - PROVIDERS__GEMINI__API_KEY for Gemini models (optional)
+   # - PROVIDERS__GEMINI__API_KEY for Imagen models (path to service account JSON file)
    ```
 
+   **For Imagen models (Vertex AI setup)**:
+   1. Go to [Google Cloud Console](https://console.cloud.google.com)
+   2. Enable Vertex AI API for your project
+   3. Create a service account with "Vertex AI User" role
+   4. Download the JSON key file to your project directory
+   5. Set `PROVIDERS__GEMINI__API_KEY` to the path of your JSON file
+
 3. **Test the setup**:
    ```bash
    uv run python scripts/dev.py setup
@@ -154,6 +161,9 @@ The AI ecosystem has evolved to include powerful language models from multiple p
 
 # Production deployment with monitoring
 ./run.sh prod
+
+# Stop all services
+./run.sh stop
 ```
 
 #### Manual Execution
@@ -218,13 +228,28 @@ This server works with **any MCP-compatible chatbot client**. Here are configura
         "image-gen-mcp"
       ],
       "env": {
-        "OPENAI_API_KEY": "your-api-key-here"
+        "PROVIDERS__OPENAI__API_KEY": "your-api-key-here"
       }
     }
   }
 }
 ```
 
+##### Claude Code (Anthropic CLI)
+```bash
+# First, create the startup script (one-time setup)
+# This is already included in the repository as start-mcp.sh
+
+# Add MCP server with API key
+claude mcp add image-gen-mcp /path/to/image-gen-mcp/start-mcp.sh -e PROVIDERS__OPENAI__API_KEY=your-api-key-here
+
+# Or add without API key if it's in your .env file
+claude mcp add image-gen-mcp /path/to/image-gen-mcp/start-mcp.sh
+
+# Verify setup
+claude mcp list
+```
+
 ##### Continue.dev (VS Code Extension)
 ```json
 {
@@ -233,7 +258,7 @@ This server works with **any MCP-compatible chatbot client**. Here are configura
       "command": "uv",
       "args": ["--directory", "/path/to/image-gen-mcp", "run", "image-gen-mcp"],
       "env": {
-        "OPENAI_API_KEY": "your-api-key-here"
+        "PROVIDERS__OPENAI__API_KEY": "your-api-key-here"
       }
     }
   }
@@ -360,9 +385,10 @@ PROVIDERS__OPENAI__TIMEOUT=300.0
 PROVIDERS__OPENAI__MAX_RETRIES=3
 PROVIDERS__OPENAI__ENABLED=true
 
-# Gemini Provider (default disabled)
-PROVIDERS__GEMINI__API_KEY=your-gemini-api-key-here
-PROVIDERS__GEMINI__BASE_URL=https://generativelanguage.googleapis.com/v1beta/
+# Gemini Provider (requires Vertex AI setup)
+# For Imagen models, use path to Google Cloud service account JSON file
+PROVIDERS__GEMINI__API_KEY=/path/to/your/vertex-ai-key.json
+PROVIDERS__GEMINI__BASE_URL=https://us-central1-aiplatform.googleapis.com/v1
 PROVIDERS__GEMINI__TIMEOUT=300.0
 PROVIDERS__GEMINI__MAX_RETRIES=3
 PROVIDERS__GEMINI__ENABLED=false

deploy/vps-setup.sh

@@ -306,7 +306,7 @@ create_env_template() {
 
     cat > /opt/gpt-image-mcp/.env.example <<EOF
 # OpenAI Configuration
-OPENAI_API_KEY=your-openai-api-key-here
+PROVIDERS__OPENAI__API_KEY=your-openai-api-key-here
 OPENAI_ORGANIZATION=
 OPENAI_BASE_URL=https://api.openai.com/v1
 

docker-compose.dev.yml

@@ -1,5 +1,3 @@
-version: '3.8'
-
 services:
   # Main application - Development version
   gpt-image-mcp-dev:
@@ -9,7 +7,8 @@ services:
     ports:
       - "3001:3001"  # Expose directly for development
     environment:
-      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - PROVIDERS__OPENAI__API_KEY=${PROVIDERS__OPENAI__API_KEY}
+      - PROVIDERS__GEMINI__API_KEY=${PROVIDERS__GEMINI__API_KEY:-}
       - REDIS_URL=redis://redis:6379/0
       - STORAGE_BASE_PATH=/app/storage
       - CACHE_ENABLED=true
@@ -19,7 +18,8 @@ services:
     volumes:
       - ./storage:/app/storage
       - ./logs:/app/logs
-      - .:/app  # Mount source code for development
+      # Mount only the source code, not the entire app directory (preserves .venv)
+      - ./gpt_image_mcp:/app/gpt_image_mcp
     depends_on:
       - redis
     networks:
@@ -39,7 +39,8 @@ services:
     container_name: gpt-image-mcp-stdio
     restart: "no"  # Don't restart automatically for stdio
     environment:
-      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - PROVIDERS__OPENAI__API_KEY=${PROVIDERS__OPENAI__API_KEY}
+      - PROVIDERS__GEMINI__API_KEY=${PROVIDERS__GEMINI__API_KEY:-}
       - REDIS_URL=redis://redis:6379/0
       - STORAGE_BASE_PATH=/app/storage
       - CACHE_ENABLED=true
@@ -48,7 +49,8 @@ services:
     volumes:
       - ./storage:/app/storage
       - ./logs:/app/logs
-      - .:/app
+      # Mount only the source code, not the entire app directory (preserves .venv)
+      - ./gpt_image_mcp:/app/gpt_image_mcp
     depends_on:
       - redis
     networks:

docker-compose.prod.yml

@@ -1,5 +1,3 @@
-version: '3.8'
-
 services:
   # Main application
   gpt-image-mcp:
@@ -9,7 +7,8 @@ services:
     ports:
       - "127.0.0.1:3001:3001"  # Bind to localhost only, nginx will proxy
     environment:
-      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - PROVIDERS__OPENAI__API_KEY=${PROVIDERS__OPENAI__API_KEY}
+      - PROVIDERS__GEMINI__API_KEY=${PROVIDERS__GEMINI__API_KEY:-}
       - REDIS_URL=redis://redis:6379/0
       - STORAGE_BASE_PATH=/app/storage
       - CACHE_ENABLED=true

docs/multi_provider_api_guide.md

@@ -36,7 +36,7 @@ Creates an image given a prompt.
 ```bash
 curl https://api.openai.com/v1/images/generations \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Authorization: Bearer $PROVIDERS__OPENAI__API_KEY" \
   -d '{
     "model": "gpt-image-1",
     "prompt": "A cute baby sea otter",
@@ -65,36 +65,52 @@ Creates an edited or extended image given source images and a prompt. Only suppo
 | `output_format` | string | No | Output format for `gpt-image-1` |
 | `background` | string | No | Background setting for `gpt-image-1` |
 
-## Google Gemini Images API (OpenAI Compatible)
+## Google Vertex AI Images API (Imagen Models)
 
 ### Create Image
 
-**Endpoint**: `POST https://generativelanguage.googleapis.com/v1beta/openai/images/generations`
+**Endpoint**: `POST https://us-central1-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/us-central1/publishers/google/models/{MODEL_ID}:predict`
 
-Creates an image using Google's Imagen models through OpenAI compatibility mode.
+Creates an image using Google's Imagen models through Vertex AI API with service account authentication.
 
 #### Request Body
 
+**Format**: Vertex AI prediction format with instances and parameters.
+
+**Instances**:
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `prompt` | string | Yes | Text description of the desired image |
-| `model` | string | No | Model to use: `imagen-4`, `imagen-4-ultra`, or `imagen-3` |
-| `n` | integer | No | Number of images to generate (1-8) |
+
+**Parameters**:
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sampleCount` | integer | No | Number of images to generate (1-4) |
 | `aspectRatio` | string | No | Aspect ratio: `1:1`, `9:16`, `16:9`, `3:4`, `4:3` |
-| `outputFormat` | string | No | Output format: `png`, `jpeg` |
-| `safety` | string | No | Safety filter level: `strict`, `moderate`, `permissive` |
+
+**Available Models**:
+- `imagen-4.0-generate-preview-06-06` (Imagen-4)
+- `imagen-3.0-generate-002` (Imagen-3)
 
 #### Example Request
 
+**Note**: Gemini/Imagen models now use Vertex AI API with service account authentication.
+
 ```bash
-curl https://generativelanguage.googleapis.com/v1beta/openai/images/generations \
+# First, get access token from service account
+ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
+
+curl https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/imagen-4.0-generate-preview-06-06:predict \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GEMINI_API_KEY" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
   -d '{
-    "model": "imagen-4",
-    "prompt": "A beautiful sunset over mountains",
-    "n": 1,
-    "aspectRatio": "16:9"
+    "instances": [{
+      "prompt": "A beautiful sunset over mountains"
+    }],
+    "parameters": {
+      "sampleCount": 1,
+      "aspectRatio": "16:9"
+    }
   }'
 ```
 

docs/openai_images_api_guide.md

@@ -36,7 +36,7 @@ Creates an image given a prompt. [Learn more](https://platform.openai.com/docs/g
 ```bash
 curl https://api.openai.com/v1/images/generations \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Authorization: Bearer $PROVIDERS__OPENAI__API_KEY" \
   -d '{
     "model": "gpt-image-1",
     "prompt": "A cute baby sea otter",
@@ -84,7 +84,7 @@ Creates an edited or extended image given source images and a prompt. Only suppo
 
 ```bash
 curl -X POST "https://api.openai.com/v1/images/edits" \
-  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Authorization: Bearer $PROVIDERS__OPENAI__API_KEY" \
   -F "model=gpt-image-1" \
   -F "image[]=@body-lotion.png" \
   -F "image[]=@bath-bomb.png" \

gpt_image_mcp/config/settings.py

@@ -272,6 +272,9 @@ class Settings(BaseSettings):
         env_file_alternates=[".env.local", ".env.production"],
     )
 
+    # Provider settings (main structure for environment variables)
+    providers: ProvidersSettings = Field(default_factory=ProvidersSettings)
+
     # Direct settings for backwards compatibility
     openai: OpenAISettings | None = Field(default=None)
     gemini: GeminiSettings | None = Field(default=None)
@@ -285,16 +288,6 @@ def from_env(cls):
         """Load settings from environment variables and .env files."""
         return cls()
 
-    # Backward compatibility property for providers access
-    @property
-    def providers(self) -> ProvidersSettings:
-        """Provide access to providers settings for backwards compatibility."""
-        return ProvidersSettings(
-            openai=self.openai,
-            gemini=self.gemini,
-            enabled_providers=self._get_enabled_providers(),
-            default_provider=self._get_default_provider(),
-        )
 
     def _get_enabled_providers(self) -> list[str]:
         """Get list of enabled providers."""