google-flow-mcp 0.1.0__tar.gz

google_flow_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "claude/**"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install package with dev dependencies
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v --tb=short tests/

google_flow_mcp-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.egg
+.pytest_cache/
+.ruff_cache/
+google_flow_outputs/
+*.mp4
+*.png
+*.jpg
+*.jpeg

google_flow_mcp-0.1.0/LICENSE

@@ -0,0 +1,139 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any Contribution
+      embodied within the Work constitutes direct or contributory patent
+      infringement, then any patent licenses granted to You under this License
+      for that Work shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file, you must include a
+          readable copy of the attribution notices contained within such
+          NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) shall any Contributor be liable to You for damages,
+      including any direct, indirect, special, incidental, or exemplary
+      damages of any character arising as a result of this License or out
+      of the use or inability to use the Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer, and
+      charge a fee for, acceptance of support, warranty, indemnity, or
+      other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer such
+      obligations only on Your own behalf and on Your sole responsibility.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Joshua Daniel
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

google_flow_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: google-flow-mcp
+Version: 0.1.0
+Summary: MCP server giving Claude Desktop access to Google AI image and video generation
+Project-URL: Homepage, https://github.com/joshuadaniel-8090/google-flow-mcp
+Project-URL: Issues, https://github.com/joshuadaniel-8090/google-flow-mcp/issues
+License: Apache-2.0
+License-File: LICENSE
+Keywords: claude,google-ai,image-generation,imagen,mcp,veo,video-generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pillow>=10.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Google Flow MCP
+
+A Python MCP server that gives **Claude Desktop** direct access to Google AI's latest image and video generation models.
+
+| Capability | Model | Tier |
+|---|---|---|
+| High-quality image generation & editing | **Nano Banana Pro** (`gemini-3-pro-image`) | Free |
+| Fast image generation | **Nano Banana 2** (`gemini-3.1-flash-image`) | Free |
+| Cinematic video with native audio | **Veo 3.1** (`veo-3.1-generate-preview`) | Paid |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `flow_generate_image` | Text → 1–4 images, up to 4K, choice of model |
+| `flow_edit_image` | Edit an image with natural language (inpaint, outpaint, bg-swap) |
+| `flow_generate_image_with_references` | Generate guided by up to 14 reference images |
+| `flow_generate_video` | Text → cinematic video, optional anchor frame |
+| `flow_extend_video` | Extend an existing Veo clip |
+| `flow_image_to_video` | Full pipeline: Nano Banana Pro image → Veo 3.1 video |
+
+## Prerequisites
+
+- Python 3.10 or newer
+- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or `pip`
+- A Google AI Studio API key — get one free at [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
+
+## Installation
+
+```bash
+# Using uv (recommended — no virtual env setup needed)
+uvx google-flow-mcp
+
+# Or install with pip
+pip install google-flow-mcp
+```
+
+## Claude Desktop Configuration
+
+Add the following to your Claude Desktop config file:
+
+```json
+{
+  "mcpServers": {
+    "google-flow": {
+      "command": "uvx",
+      "args": ["google-flow-mcp"],
+      "env": {
+        "GOOGLE_API_KEY": "YOUR_GOOGLE_AI_STUDIO_KEY"
+      }
+    }
+  }
+}
+```
+
+### Config file locations
+
+| Platform | Path |
+|---|---|
+| **Windows Store** | `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json` |
+| **Windows Direct** | `%APPDATA%\Claude\claude_desktop_config.json` |
+| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Linux** | `~/.config/Claude/claude_desktop_config.json` |
+
+After editing the config, **restart Claude Desktop**.
+
+## Output Directory
+
+Generated files are saved to `~/google_flow_outputs/` by default.
+
+Override with the `FLOW_OUTPUT_DIR` environment variable:
+
+```json
+"env": {
+  "GOOGLE_API_KEY": "YOUR_KEY",
+  "FLOW_OUTPUT_DIR": "/Users/you/Pictures/ai-outputs"
+}
+```
+
+## Usage Examples
+
+Once connected, ask Claude naturally:
+
+- *"Generate a photo-realistic image of a neon-lit Tokyo alley at night"*
+- *"Edit this image to remove the background and replace it with a forest"*
+- *"Generate a video of a rocket launching from a desert at dusk with dramatic audio"*
+- *"Create an anchor image of ocean waves, then animate it into a video"*
+
+## Important Notes
+
+- **Image generation** (Nano Banana Pro / Nano Banana 2) works on the **free tier**.
+- **Video generation** (Veo 3.1) requires a **paid Google AI API plan**.
+- All Veo videos are **SynthID-watermarked** by Google.
+- Generated videos are stored on Google's servers for **2 days** after creation.
+- Video generation typically takes **1–4 minutes** — Claude will wait automatically.
+
+## Development
+
+```bash
+git clone https://github.com/joshuadaniel-8090/google-flow-mcp
+cd google-flow-mcp
+pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

google_flow_mcp-0.1.0/README.md

@@ -0,0 +1,108 @@
+# Google Flow MCP
+
+A Python MCP server that gives **Claude Desktop** direct access to Google AI's latest image and video generation models.
+
+| Capability | Model | Tier |
+|---|---|---|
+| High-quality image generation & editing | **Nano Banana Pro** (`gemini-3-pro-image`) | Free |
+| Fast image generation | **Nano Banana 2** (`gemini-3.1-flash-image`) | Free |
+| Cinematic video with native audio | **Veo 3.1** (`veo-3.1-generate-preview`) | Paid |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `flow_generate_image` | Text → 1–4 images, up to 4K, choice of model |
+| `flow_edit_image` | Edit an image with natural language (inpaint, outpaint, bg-swap) |
+| `flow_generate_image_with_references` | Generate guided by up to 14 reference images |
+| `flow_generate_video` | Text → cinematic video, optional anchor frame |
+| `flow_extend_video` | Extend an existing Veo clip |
+| `flow_image_to_video` | Full pipeline: Nano Banana Pro image → Veo 3.1 video |
+
+## Prerequisites
+
+- Python 3.10 or newer
+- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or `pip`
+- A Google AI Studio API key — get one free at [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
+
+## Installation
+
+```bash
+# Using uv (recommended — no virtual env setup needed)
+uvx google-flow-mcp
+
+# Or install with pip
+pip install google-flow-mcp
+```
+
+## Claude Desktop Configuration
+
+Add the following to your Claude Desktop config file:
+
+```json
+{
+  "mcpServers": {
+    "google-flow": {
+      "command": "uvx",
+      "args": ["google-flow-mcp"],
+      "env": {
+        "GOOGLE_API_KEY": "YOUR_GOOGLE_AI_STUDIO_KEY"
+      }
+    }
+  }
+}
+```
+
+### Config file locations
+
+| Platform | Path |
+|---|---|
+| **Windows Store** | `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json` |
+| **Windows Direct** | `%APPDATA%\Claude\claude_desktop_config.json` |
+| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Linux** | `~/.config/Claude/claude_desktop_config.json` |
+
+After editing the config, **restart Claude Desktop**.
+
+## Output Directory
+
+Generated files are saved to `~/google_flow_outputs/` by default.
+
+Override with the `FLOW_OUTPUT_DIR` environment variable:
+
+```json
+"env": {
+  "GOOGLE_API_KEY": "YOUR_KEY",
+  "FLOW_OUTPUT_DIR": "/Users/you/Pictures/ai-outputs"
+}
+```
+
+## Usage Examples
+
+Once connected, ask Claude naturally:
+
+- *"Generate a photo-realistic image of a neon-lit Tokyo alley at night"*
+- *"Edit this image to remove the background and replace it with a forest"*
+- *"Generate a video of a rocket launching from a desert at dusk with dramatic audio"*
+- *"Create an anchor image of ocean waves, then animate it into a video"*
+
+## Important Notes
+
+- **Image generation** (Nano Banana Pro / Nano Banana 2) works on the **free tier**.
+- **Video generation** (Veo 3.1) requires a **paid Google AI API plan**.
+- All Veo videos are **SynthID-watermarked** by Google.
+- Generated videos are stored on Google's servers for **2 days** after creation.
+- Video generation typically takes **1–4 minutes** — Claude will wait automatically.
+
+## Development
+
+```bash
+git clone https://github.com/joshuadaniel-8090/google-flow-mcp
+cd google-flow-mcp
+pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

google_flow_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "google-flow-mcp"
+version = "0.1.0"
+description = "MCP server giving Claude Desktop access to Google AI image and video generation"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+keywords = ["mcp", "google-ai", "imagen", "veo", "claude", "image-generation", "video-generation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "google-genai>=1.0.0",
+    "Pillow>=10.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-mock>=3.12.0",
+]
+
+[project.scripts]
+google-flow-mcp = "google_flow_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/joshuadaniel-8090/google-flow-mcp"
+Issues = "https://github.com/joshuadaniel-8090/google-flow-mcp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/google_flow_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

google_flow_mcp-0.1.0/src/google_flow_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Google Flow MCP — Google AI image and video generation for Claude Desktop."""
+
+__version__ = "0.1.0"

google_flow_mcp-0.1.0/src/google_flow_mcp/server.py

@@ -0,0 +1,551 @@
+"""Google Flow MCP server — 6 tools for Google AI image and video generation."""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import mimetypes
+import os
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from google import genai
+from google.genai import types
+from mcp.server.fastmcp import FastMCP
+from PIL import Image as PILImage
+
+# ── Constants ────────────────────────────────────────────────────────────────
+
+MODEL_IMAGE_PRO = "gemini-3-pro-image"        # Nano Banana Pro
+MODEL_IMAGE_FLASH = "gemini-3.1-flash-image"  # Nano Banana 2
+MODEL_VIDEO = "veo-3.1-generate-preview"      # Veo 3.1
+
+VIDEO_POLL_INTERVAL = 10   # seconds between Veo status polls
+VIDEO_POLL_TIMEOUT = 600   # 10-minute max wait for video generation
+
+# ── FastMCP Instance ─────────────────────────────────────────────────────────
+
+mcp = FastMCP(
+    name="google-flow-mcp",
+    instructions=(
+        "Provides 6 tools for Google AI image and video generation. "
+        "Image tools use Nano Banana Pro (gemini-3-pro-image, high quality) or "
+        "Nano Banana 2 (gemini-3.1-flash-image, fast). "
+        "Video tools use Veo 3.1 (veo-3.1-generate-preview) with native audio. "
+        "Image generation works on the free tier. "
+        "Video generation requires a paid Google AI API plan. "
+        "Outputs are saved to ~/google_flow_outputs/ by default (override with FLOW_OUTPUT_DIR)."
+    ),
+)
+
+# ── Client ────────────────────────────────────────────────────────────────────
+
+_client: genai.Client | None = None
+
+
+def _get_client() -> genai.Client:
+    api_key = os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY")
+    if not api_key:
+        raise EnvironmentError(
+            "GOOGLE_API_KEY environment variable is required. "
+            "Get a free key at https://aistudio.google.com/apikey"
+        )
+    return genai.Client(api_key=api_key)
+
+
+def get_client() -> genai.Client:
+    global _client
+    if _client is None:
+        _client = _get_client()
+    return _client
+
+
+# ── File Helpers ──────────────────────────────────────────────────────────────
+
+
+def _output_dir() -> Path:
+    base = os.environ.get("FLOW_OUTPUT_DIR") or str(Path.home() / "google_flow_outputs")
+    path = Path(base)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _timestamped(prefix: str, ext: str, out: Optional[Path] = None) -> Path:
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    return (out or _output_dir()) / f"{prefix}_{ts}.{ext}"
+
+
+def _save_image(image_obj, path: Path) -> None:
+    """Save a generated image to disk, handling multiple SDK response shapes."""
+    if hasattr(image_obj, "save"):
+        image_obj.save(str(path))
+    elif getattr(image_obj, "image_bytes", None):
+        PILImage.open(io.BytesIO(image_obj.image_bytes)).save(str(path))
+    elif getattr(image_obj, "_image_bytes", None):
+        PILImage.open(io.BytesIO(image_obj._image_bytes)).save(str(path))
+    else:
+        raise RuntimeError(f"Cannot save image of type {type(image_obj).__name__}")
+
+
+def _load_image_bytes(path: str) -> bytes:
+    with open(path, "rb") as f:
+        return f.read()
+
+
+def _mime(path: str) -> str:
+    mime, _ = mimetypes.guess_type(path)
+    return mime or "image/png"
+
+
+def _resolve_image_model(model: str) -> str:
+    return MODEL_IMAGE_FLASH if model.lower() in ("flash", "2") else MODEL_IMAGE_PRO
+
+
+async def _poll_operation(client: genai.Client, operation) -> object:
+    """Poll a Veo long-running operation until done or timeout."""
+    deadline = time.monotonic() + VIDEO_POLL_TIMEOUT
+    while not operation.done:
+        if time.monotonic() > deadline:
+            raise TimeoutError(
+                f"Video generation timed out after {VIDEO_POLL_TIMEOUT // 60} minutes. "
+                "Try a shorter duration or check the Google AI console."
+            )
+        await asyncio.sleep(VIDEO_POLL_INTERVAL)
+        operation = await client.aio.operations.get(operation)
+    if getattr(operation, "error", None) and operation.error.message:
+        raise RuntimeError(f"Video generation failed: {operation.error.message}")
+    return operation
+
+
+def _collect_video_results(operation, out: Path, ts: str) -> tuple[list[str], list[str]]:
+    """Extract saved paths and/or URIs from a completed video operation."""
+    saved, uris = [], []
+    videos = getattr(operation.response, "generated_videos", [])
+    for i, gen_video in enumerate(videos):
+        vid = gen_video.video
+        vid_bytes = getattr(vid, "video_bytes", None)
+        uri = getattr(vid, "uri", None)
+        if vid_bytes:
+            path = out / f"flow_video_{ts}_{i}.mp4"
+            path.write_bytes(vid_bytes)
+            saved.append(str(path))
+        elif uri:
+            uris.append(uri)
+    return saved, uris
+
+
+def _format_video_result(saved: list[str], uris: list[str]) -> str:
+    parts = []
+    if saved:
+        parts.append("Saved videos:\n" + "\n".join(saved))
+    if uris:
+        parts.append(
+            "Video URI(s) (available for 2 days on Google servers):\n" + "\n".join(uris)
+        )
+    parts.append("Note: All Veo videos are SynthID-watermarked by Google.")
+    return "\n\n".join(parts)
+
+
+# ── Tool 1: Text → Image ─────────────────────────────────────────────────────
+
+
+@mcp.tool()
+async def flow_generate_image(
+    prompt: str,
+    model: str = "pro",
+    number_of_images: int = 1,
+    aspect_ratio: str = "1:1",
+    negative_prompt: Optional[str] = None,
+    output_dir: Optional[str] = None,
+) -> str:
+    """
+    Generate 1–4 images from a text prompt using Google AI.
+
+    Args:
+        prompt: Detailed description of the image(s) to create.
+        model: 'pro' for Nano Banana Pro (high quality) or 'flash' for Nano Banana 2 (fast).
+        number_of_images: How many images to generate (1–4).
+        aspect_ratio: '1:1', '3:4', '4:3', '9:16', or '16:9'.
+        negative_prompt: What to exclude from the generated images.
+        output_dir: Override the output directory (default: ~/google_flow_outputs).
+
+    Returns:
+        Paths to the saved image files.
+    """
+    client = get_client()
+    model_id = _resolve_image_model(model)
+    n = max(1, min(4, number_of_images))
+    out = Path(output_dir) if output_dir else _output_dir()
+    out.mkdir(parents=True, exist_ok=True)
+
+    response = await client.aio.models.generate_images(
+        model=model_id,
+        prompt=prompt,
+        config=types.GenerateImagesConfig(
+            number_of_images=n,
+            aspect_ratio=aspect_ratio,
+            negative_prompt=negative_prompt,
+        ),
+    )
+
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    paths = []
+    for i, gen_img in enumerate(response.generated_images):
+        path = out / f"flow_image_{ts}_{i}.png"
+        _save_image(gen_img.image, path)
+        paths.append(str(path))
+
+    return f"Generated {len(paths)} image(s):\n" + "\n".join(paths)
+
+
+# ── Tool 2: Edit Image ────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+async def flow_edit_image(
+    image_path: str,
+    prompt: str,
+    edit_mode: str = "inpaint_insertion",
+    model: str = "pro",
+    mask_mode: str = "MASK_MODE_BACKGROUND",
+    output_dir: Optional[str] = None,
+) -> str:
+    """
+    Edit an existing image using a natural language instruction.
+
+    Args:
+        image_path: Absolute path to the source image file.
+        prompt: Natural language description of the edit to apply.
+        edit_mode: 'inpaint_insertion' (add), 'inpaint_removal' (remove),
+                   'outpaint' (expand canvas), 'bgswap' (replace background).
+        model: 'pro' for Nano Banana Pro or 'flash' for Nano Banana 2.
+        mask_mode: Auto-mask strategy — 'MASK_MODE_BACKGROUND', 'MASK_MODE_FOREGROUND',
+                   or 'MASK_MODE_SEMANTIC'.
+        output_dir: Override the output directory (default: ~/google_flow_outputs).
+
+    Returns:
+        Path to the edited image file.
+    """
+    client = get_client()
+    model_id = _resolve_image_model(model)
+    out = Path(output_dir) if output_dir else _output_dir()
+    out.mkdir(parents=True, exist_ok=True)
+
+    _edit_mode_map = {
+        "inpaint_insertion": "EDIT_MODE_INPAINT_INSERTION",
+        "inpaint_removal": "EDIT_MODE_INPAINT_REMOVAL",
+        "outpaint": "EDIT_MODE_OUTPAINT",
+        "bgswap": "EDIT_MODE_BGSWAP",
+    }
+    sdk_edit_mode = _edit_mode_map.get(edit_mode, edit_mode)
+
+    raw_ref = types.RawReferenceImage(
+        reference_id=0,
+        reference_image=types.Image(
+            image_bytes=_load_image_bytes(image_path),
+            mime_type=_mime(image_path),
+        ),
+    )
+    mask_ref = types.MaskReferenceImage(
+        reference_id=1,
+        config=types.MaskReferenceConfig(mask_mode=mask_mode),
+    )
+
+    response = await client.aio.models.edit_image(
+        model=model_id,
+        prompt=prompt,
+        reference_images=[raw_ref, mask_ref],
+        config=types.EditImageConfig(
+            edit_mode=sdk_edit_mode,
+            number_of_images=1,
+        ),
+    )
+
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    path = out / f"flow_edit_{ts}.png"
+    _save_image(response.generated_images[0].image, path)
+    return f"Edited image saved to:\n{path}"
+
+
+# ── Tool 3: Generate with Reference Images ────────────────────────────────────
+
+
+@mcp.tool()
+async def flow_generate_image_with_references(
+    prompt: str,
+    reference_image_paths: list[str],
+    model: str = "pro",
+    aspect_ratio: str = "1:1",
+    number_of_images: int = 1,
+    output_dir: Optional[str] = None,
+) -> str:
+    """
+    Generate an image guided by up to 14 reference images.
+
+    The model uses the reference images for style, composition, and subject guidance
+    while following the text prompt.
+
+    Args:
+        prompt: Description of the image to generate.
+        reference_image_paths: List of paths to reference image files (max 14).
+        model: 'pro' for Nano Banana Pro or 'flash' for Nano Banana 2.
+        aspect_ratio: '1:1', '3:4', '4:3', '9:16', or '16:9'.
+        number_of_images: How many images to generate (1–4).
+        output_dir: Override the output directory (default: ~/google_flow_outputs).
+
+    Returns:
+        Paths to the generated image files.
+    """
+    if len(reference_image_paths) > 14:
+        raise ValueError(
+            f"Maximum 14 reference images allowed; got {len(reference_image_paths)}."
+        )
+    if not reference_image_paths:
+        raise ValueError("At least one reference image path is required.")
+
+    client = get_client()
+    model_id = _resolve_image_model(model)
+    n = max(1, min(4, number_of_images))
+    out = Path(output_dir) if output_dir else _output_dir()
+    out.mkdir(parents=True, exist_ok=True)
+
+    reference_images = [
+        types.RawReferenceImage(
+            reference_id=i,
+            reference_image=types.Image(
+                image_bytes=_load_image_bytes(ref_path),
+                mime_type=_mime(ref_path),
+            ),
+        )
+        for i, ref_path in enumerate(reference_image_paths)
+    ]
+
+    response = await client.aio.models.generate_images(
+        model=model_id,
+        prompt=prompt,
+        reference_images=reference_images,
+        config=types.GenerateImagesConfig(
+            number_of_images=n,
+            aspect_ratio=aspect_ratio,
+        ),
+    )
+
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    paths = []
+    for i, gen_img in enumerate(response.generated_images):
+        path = out / f"flow_ref_image_{ts}_{i}.png"
+        _save_image(gen_img.image, path)
+        paths.append(str(path))
+
+    return (
+        f"Generated {len(paths)} image(s) using {len(reference_image_paths)} reference(s):\n"
+        + "\n".join(paths)
+    )
+
+
+# ── Tool 4: Text → Video ─────────────────────────────────────────────────────
+
+
+@mcp.tool()
+async def flow_generate_video(
+    prompt: str,
+    duration_seconds: int = 8,
+    aspect_ratio: str = "16:9",
+    negative_prompt: Optional[str] = None,
+    anchor_frame_path: Optional[str] = None,
+    enhance_prompt: bool = True,
+    output_dir: Optional[str] = None,
+) -> str:
+    """
+    Generate a cinematic video with native audio from a text prompt using Veo 3.1.
+
+    Requires a paid Google AI API plan. Generated videos are SynthID-watermarked
+    and stored on Google servers for 2 days.
+
+    Args:
+        prompt: Cinematic description of the video — include camera movement, lighting,
+                subject action, and mood for best results.
+        duration_seconds: Video duration in seconds (typically 5–8).
+        aspect_ratio: '16:9' for landscape or '9:16' for portrait/mobile.
+        negative_prompt: What to exclude from the video.
+        anchor_frame_path: Optional path to an image to use as the first frame.
+        enhance_prompt: Whether to allow Veo to rewrite/enhance your prompt.
+        output_dir: Override the output directory (default: ~/google_flow_outputs).
+
+    Returns:
+        Paths or URIs to the generated video(s).
+    """
+    client = get_client()
+    out = Path(output_dir) if output_dir else _output_dir()
+    out.mkdir(parents=True, exist_ok=True)
+
+    config = types.GenerateVideosConfig(
+        duration_seconds=duration_seconds,
+        aspect_ratio=aspect_ratio,
+        negative_prompt=negative_prompt,
+        enhance_prompt=enhance_prompt,
+    )
+
+    kwargs: dict = dict(model=MODEL_VIDEO, prompt=prompt, config=config)
+
+    if anchor_frame_path:
+        kwargs["image"] = types.Image(
+            image_bytes=_load_image_bytes(anchor_frame_path),
+            mime_type=_mime(anchor_frame_path),
+        )
+
+    operation = await client.aio.models.generate_videos(**kwargs)
+    operation = await _poll_operation(client, operation)
+
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    saved, uris = _collect_video_results(operation, out, ts)
+    return _format_video_result(saved, uris)
+
+
+# ── Tool 5: Extend Video ──────────────────────────────────────────────────────
+
+
+@mcp.tool()
+async def flow_extend_video(
+    video_path: str,
+    prompt: str,
+    duration_seconds: int = 8,
+    aspect_ratio: str = "16:9",
+    output_dir: Optional[str] = None,
+) -> str:
+    """
+    Extend an existing Veo 3.1 video clip with additional generated content.
+
+    Requires a paid Google AI API plan. The extended video is SynthID-watermarked.
+
+    Args:
+        video_path: Absolute path to the source MP4 video file to extend.
+        prompt: Description of how to continue the video after the source clip ends.
+        duration_seconds: Duration of the generated extension in seconds (typically 5–8).
+        aspect_ratio: Must match the source video — '16:9' or '9:16'.
+        output_dir: Override the output directory (default: ~/google_flow_outputs).
+
+    Returns:
+        Path or URI to the extended video.
+    """
+    client = get_client()
+    out = Path(output_dir) if output_dir else _output_dir()
+    out.mkdir(parents=True, exist_ok=True)
+
+    with open(video_path, "rb") as f:
+        video_bytes = f.read()
+
+    operation = await client.aio.models.generate_videos(
+        model=MODEL_VIDEO,
+        prompt=prompt,
+        video=types.Video(video_bytes=video_bytes, mime_type="video/mp4"),
+        config=types.GenerateVideosConfig(
+            duration_seconds=duration_seconds,
+            aspect_ratio=aspect_ratio,
+        ),
+    )
+    operation = await _poll_operation(client, operation)
+
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    saved, uris = _collect_video_results(operation, out, ts)
+    return _format_video_result(saved, uris)
+
+
+# ── Tool 6: Image → Video Pipeline ───────────────────────────────────────────
+
+
+@mcp.tool()
+async def flow_image_to_video(
+    video_prompt: str,
+    image_prompt: Optional[str] = None,
+    image_path: Optional[str] = None,
+    image_model: str = "pro",
+    duration_seconds: int = 8,
+    aspect_ratio: str = "16:9",
+    negative_prompt: Optional[str] = None,
+    output_dir: Optional[str] = None,
+) -> str:
+    """
+    Full pipeline: generate or use an image with Nano Banana Pro, then animate it with Veo 3.1.
+
+    Provide either image_prompt (to generate a new anchor image) or image_path (to use an
+    existing image). The anchor image becomes the first frame of the video.
+
+    Requires a paid Google AI API plan for the video step.
+
+    Args:
+        video_prompt: Cinematic description of the video animation — how the scene moves.
+        image_prompt: Text prompt to generate the anchor image (if image_path is not given).
+        image_path: Path to an existing image to use as the anchor frame.
+        image_model: 'pro' (Nano Banana Pro, recommended) or 'flash' (Nano Banana 2).
+        duration_seconds: Video duration in seconds (typically 5–8).
+        aspect_ratio: '16:9' for landscape or '9:16' for portrait.
+        negative_prompt: What to exclude from both the image and video.
+        output_dir: Override the output directory (default: ~/google_flow_outputs).
+
+    Returns:
+        Paths to the generated anchor image and the final video.
+    """
+    if not image_prompt and not image_path:
+        raise ValueError("Provide either image_prompt or image_path.")
+
+    client = get_client()
+    out = Path(output_dir) if output_dir else _output_dir()
+    out.mkdir(parents=True, exist_ok=True)
+    results: list[str] = []
+
+    # Step 1 — Generate or load the anchor image
+    if image_path:
+        anchor_path = image_path
+    else:
+        model_id = _resolve_image_model(image_model)
+        img_response = await client.aio.models.generate_images(
+            model=model_id,
+            prompt=image_prompt,
+            config=types.GenerateImagesConfig(
+                number_of_images=1,
+                aspect_ratio=aspect_ratio,
+                negative_prompt=negative_prompt,
+            ),
+        )
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+        anchor = out / f"flow_anchor_{ts}.png"
+        _save_image(img_response.generated_images[0].image, anchor)
+        anchor_path = str(anchor)
+        results.append(f"Anchor image:\n{anchor_path}")
+
+    # Step 2 — Animate with Veo 3.1
+    operation = await client.aio.models.generate_videos(
+        model=MODEL_VIDEO,
+        prompt=video_prompt,
+        image=types.Image(
+            image_bytes=_load_image_bytes(anchor_path),
+            mime_type=_mime(anchor_path),
+        ),
+        config=types.GenerateVideosConfig(
+            duration_seconds=duration_seconds,
+            aspect_ratio=aspect_ratio,
+            negative_prompt=negative_prompt,
+        ),
+    )
+    operation = await _poll_operation(client, operation)
+
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    saved, uris = _collect_video_results(operation, out, ts)
+    results.append(_format_video_result(saved, uris))
+
+    return "\n\n".join(results)
+
+
+# ── Entry Point ───────────────────────────────────────────────────────────────
+
+
+def main() -> None:
+    """Entry point for uvx / python -m google_flow_mcp."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

google_flow_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,252 @@
+"""Unit tests for google_flow_mcp.server — all API calls are mocked."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+# Set env vars before importing the server module
+os.environ.setdefault("GOOGLE_API_KEY", "test-api-key-000")
+os.environ["FLOW_OUTPUT_DIR"] = tempfile.mkdtemp()
+
+import google_flow_mcp.server as server_module  # noqa: E402
+from google_flow_mcp.server import (  # noqa: E402
+    MODEL_IMAGE_FLASH,
+    MODEL_IMAGE_PRO,
+    MODEL_VIDEO,
+    flow_edit_image,
+    flow_extend_video,
+    flow_generate_image,
+    flow_generate_image_with_references,
+    flow_generate_video,
+    flow_image_to_video,
+)
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+
+@pytest.fixture(autouse=True)
+def reset_singleton():
+    """Reset the lazy client singleton between tests."""
+    server_module._client = None
+    yield
+    server_module._client = None
+
+
+@pytest.fixture
+def mock_client(mocker) -> MagicMock:
+    """Patch _get_client to return a fully mocked async client."""
+    client = MagicMock()
+    client.aio = MagicMock()
+    client.aio.models = MagicMock()
+    client.aio.models.generate_images = AsyncMock()
+    client.aio.models.edit_image = AsyncMock()
+    client.aio.models.generate_videos = AsyncMock()
+    client.aio.operations = MagicMock()
+    client.aio.operations.get = AsyncMock()
+    mocker.patch.object(server_module, "_get_client", return_value=client)
+    return client
+
+
+def _fake_gen_image(tmp_path: Path, name: str = "out.png") -> MagicMock:
+    """Build a mock GeneratedImage whose .image.save() actually creates a file."""
+    path_ref: list[Path] = []
+    target = tmp_path / name
+
+    gen = MagicMock()
+    gen.image.image_bytes = None
+
+    def save_side(path_str: str) -> None:
+        p = Path(path_str)
+        path_ref.append(p)
+        p.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 32)
+
+    gen.image.save.side_effect = save_side
+    gen.image._save_target = target
+    return gen
+
+
+def _fake_video_operation(uri: str = "gs://bucket/out.mp4", done: bool = True) -> MagicMock:
+    """Build a mock Veo operation that is immediately done."""
+    op = MagicMock()
+    op.done = done
+    op.error = MagicMock()
+    op.error.message = None
+    vid = MagicMock()
+    vid.video.video_bytes = None
+    vid.video.uri = uri
+    op.response.generated_videos = [vid]
+    return op
+
+
+def _write_tmp_png(tmp_path: Path, name: str = "input.png") -> str:
+    """Write a minimal PNG file and return its path as string."""
+    p = tmp_path / name
+    p.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 32)
+    return str(p)
+
+
+def _write_tmp_mp4(tmp_path: Path, name: str = "input.mp4") -> str:
+    p = tmp_path / name
+    p.write_bytes(b"\x00\x00\x00\x18ftypmp42" + b"\x00" * 32)
+    return str(p)
+
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_01_generate_image_default_model(mock_client, tmp_path):
+    """flow_generate_image uses MODEL_IMAGE_PRO by default."""
+    gen = _fake_gen_image(tmp_path)
+    mock_client.aio.models.generate_images.return_value.generated_images = [gen]
+
+    result = await flow_generate_image(prompt="a red apple", output_dir=str(tmp_path))
+
+    call_kwargs = mock_client.aio.models.generate_images.call_args.kwargs
+    assert call_kwargs["model"] == MODEL_IMAGE_PRO
+    assert call_kwargs["prompt"] == "a red apple"
+    assert "flow_image_" in result
+
+
+@pytest.mark.asyncio
+async def test_02_generate_image_flash_model(mock_client, tmp_path):
+    """Passing model='flash' selects MODEL_IMAGE_FLASH."""
+    gen = _fake_gen_image(tmp_path)
+    mock_client.aio.models.generate_images.return_value.generated_images = [gen]
+
+    await flow_generate_image(prompt="quick sketch", model="flash", output_dir=str(tmp_path))
+
+    call_kwargs = mock_client.aio.models.generate_images.call_args.kwargs
+    assert call_kwargs["model"] == MODEL_IMAGE_FLASH
+
+
+@pytest.mark.asyncio
+async def test_03_generate_image_count_clamped_to_4(mock_client, tmp_path):
+    """number_of_images is clamped to max 4 before being sent to the API."""
+    gens = [_fake_gen_image(tmp_path, f"img{i}.png") for i in range(4)]
+    mock_client.aio.models.generate_images.return_value.generated_images = gens
+
+    result = await flow_generate_image(
+        prompt="many apples", number_of_images=99, output_dir=str(tmp_path)
+    )
+
+    config_arg = mock_client.aio.models.generate_images.call_args.kwargs["config"]
+    assert config_arg.number_of_images == 4
+    assert "4 image(s)" in result
+
+
+@pytest.mark.asyncio
+async def test_04_generate_image_multiple_files_saved(mock_client, tmp_path):
+    """Result lists all saved paths when multiple images are returned."""
+    gens = [_fake_gen_image(tmp_path, f"r{i}.png") for i in range(3)]
+    mock_client.aio.models.generate_images.return_value.generated_images = gens
+
+    result = await flow_generate_image(
+        prompt="trio", number_of_images=3, output_dir=str(tmp_path)
+    )
+
+    assert "3 image(s)" in result
+    assert result.count("flow_image_") == 3
+
+
+@pytest.mark.asyncio
+async def test_05_edit_image_passes_reference(mock_client, tmp_path):
+    """flow_edit_image passes a RawReferenceImage to generate_images."""
+    src = _write_tmp_png(tmp_path, "src.png")
+    gen = _fake_gen_image(tmp_path, "edited.png")
+    mock_client.aio.models.edit_image.return_value.generated_images = [gen]
+
+    result = await flow_edit_image(
+        image_path=src, prompt="make it blue", output_dir=str(tmp_path)
+    )
+
+    call_kwargs = mock_client.aio.models.edit_image.call_args.kwargs
+    ref_images = call_kwargs["reference_images"]
+    assert len(ref_images) == 2  # RawReferenceImage + MaskReferenceImage
+    assert "flow_edit_" in result
+
+
+@pytest.mark.asyncio
+async def test_06_generate_with_references_passes_all_refs(mock_client, tmp_path):
+    """flow_generate_image_with_references passes one RawReferenceImage per path."""
+    paths = [_write_tmp_png(tmp_path, f"ref{i}.png") for i in range(3)]
+    gen = _fake_gen_image(tmp_path, "out.png")
+    mock_client.aio.models.generate_images.return_value.generated_images = [gen]
+
+    result = await flow_generate_image_with_references(
+        prompt="inspired by these", reference_image_paths=paths, output_dir=str(tmp_path)
+    )
+
+    call_kwargs = mock_client.aio.models.generate_images.call_args.kwargs
+    assert len(call_kwargs["reference_images"]) == 3
+    assert "3 reference(s)" in result
+
+
+@pytest.mark.asyncio
+async def test_07_generate_with_references_too_many_raises(mock_client, tmp_path):
+    """More than 14 reference images raises ValueError."""
+    paths = [_write_tmp_png(tmp_path, f"r{i}.png") for i in range(15)]
+
+    with pytest.raises(ValueError, match="14"):
+        await flow_generate_image_with_references(
+            prompt="too many", reference_image_paths=paths, output_dir=str(tmp_path)
+        )
+
+
+@pytest.mark.asyncio
+async def test_08_generate_video_success(mock_client, tmp_path):
+    """flow_generate_video calls generate_videos with MODEL_VIDEO and returns URI."""
+    op = _fake_video_operation(uri="gs://bucket/vid.mp4")
+    mock_client.aio.models.generate_videos.return_value = op
+
+    result = await flow_generate_video(prompt="drone over mountains", output_dir=str(tmp_path))
+
+    call_kwargs = mock_client.aio.models.generate_videos.call_args.kwargs
+    assert call_kwargs["model"] == MODEL_VIDEO
+    assert "SynthID" in result
+
+
+@pytest.mark.asyncio
+async def test_09_generate_video_polls_until_done(mock_client, tmp_path):
+    """flow_generate_video polls the operation when initially not done."""
+    op_pending = _fake_video_operation(done=False)
+    op_done = _fake_video_operation(done=True, uri="gs://bucket/final.mp4")
+    mock_client.aio.models.generate_videos.return_value = op_pending
+    mock_client.aio.operations.get.return_value = op_done
+
+    # Patch sleep to avoid actual delay
+    import asyncio
+    from unittest.mock import patch
+
+    with patch.object(asyncio, "sleep", new_callable=AsyncMock):
+        result = await flow_generate_video(prompt="slow sunrise", output_dir=str(tmp_path))
+
+    mock_client.aio.operations.get.assert_called_once_with(op_pending)
+    assert "SynthID" in result
+
+
+@pytest.mark.asyncio
+async def test_10_image_to_video_generates_anchor_then_video(mock_client, tmp_path):
+    """flow_image_to_video calls generate_images first, then generate_videos."""
+    gen = _fake_gen_image(tmp_path, "anchor.png")
+    mock_client.aio.models.generate_images.return_value.generated_images = [gen]
+
+    op = _fake_video_operation(uri="gs://bucket/final.mp4")
+    mock_client.aio.models.generate_videos.return_value = op
+
+    result = await flow_image_to_video(
+        video_prompt="the scene comes alive",
+        image_prompt="a tranquil mountain lake at dawn",
+        output_dir=str(tmp_path),
+    )
+
+    mock_client.aio.models.generate_images.assert_called_once()
+    mock_client.aio.models.generate_videos.assert_called_once()
+    assert "Anchor image" in result
+    assert "SynthID" in result