@tasopen/mcp-alphabanana 1.2.1 → 1.3.1

package/README.ja.md

@@ -2,18 +2,19 @@
 
 English | [日本語](README.ja.md)
 
-Google Gemini AI を使って画像アセットを生成する Model Context Protocol (MCP) サーバー。
+Google Gemini AI（Gemini 3.1 Flash/Nano Banana 2対応）で画像アセットを生成する Model Context Protocol (MCP) サーバー。
 
 [FastMCP 3](https://www.npmjs.com/package/fastmcp) で構築され、シンプルなコードベースと柔軟な出力オプションを提供します。
 
 ## 機能
 
-- **Google Gemini AI による汎用画像生成**
-- **カラーキー後処理による透過 PNG 出力**
+- **超高速画像生成**（Gemini 3.1 Flash、0.5K/1K/2K/4K）
+- **高度なマルチ画像推論**（最大14枚の参照画像）
+- **Thinking/Grounding対応**（Flash3.1のみ）
+- **透過PNG/WebP出力**（カラーキー+デスピル）
 - **複数の出力形式**: ファイル、base64、または両方
-- **スタイル参照のための参照画像サポート**
 - **柔軟なリサイズモード**: crop、stretch、letterbox、contain
-- **複数のモデルティア**: flash (Gemini 2.5 Flash) または pro (Gemini 3 Pro)
+- **複数のモデルティア**: Flash3.1、Flash2.5、Pro3、レガシーエイリアス
 
 ## インストール
 
@@ -21,7 +22,7 @@ Google Gemini AI を使って画像アセットを生成する Model Context Pro
 
 ## 設定
 
-`GEMINI_API_KEY` を MCP 設定（例: `mcp.json`）で設定します。一部のエージェント環境では OS 環境変数にアクセスできないため、`mcp.json` で OS 環境変数を参照するか、直接キーを記載できます。
+`GEMINI_API_KEY` を MCP 設定（例: `mcp.json`）で設定します。
 
 例:
 
@@ -35,169 +36,50 @@ Google Gemini AI を使って画像アセットを生成する Model Context Pro
 }
 ```
 
-- `mcp.json` に直接キーを記載（エージェントが OS 環境変数を参照できない場合に有用）:
-
-```json
-{
-  "env": {
-    "GEMINI_API_KEY": "your_api_key_here"
-  }
-}
-```
-
-運用に合わせて選択してください（可能であれば環境参照を推奨）。
-
-## VS Code 統合
-
-VS Code 設定（`.vscode/settings.json` またはユーザー設定）に追加し、サーバー `env` を `mcp.json` または VS Code MCP 設定で設定します。OS 環境変数参照または直接キー記載の両方に対応:
+```bash
+# 開発モード（MCP CLI）
+npm run dev
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "mcp-alphabanana": {
-        "command": "npx",
-        "args":["-y", "@tasopen/mcp-alphabanana"],
-        "env": {
-          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"  // or "your_api_key_here"
-        }
-      }
+# MCP Inspector (Web UI)
     }
-  }
-}
-```
-
-**オプション:** 書き込み失敗時のカスタムフォールバックディレクトリを指定する場合は `MCP_FALLBACK_OUTPUT` を `env` に追加してください。
-
-## Antigravity (mcp_config.json)
 
-Antigravity ではグローバルな `mcp_config.json` で MCP サーバーを登録します。例:
-
-```json
-{
-  "mcpServers": {
-    "mcp-alphabanana": {
-      "command": "npx",
-      "args": ["-y", "@tasopen/mcp-alphabanana"],
-      "env": {
-        "GEMINI_API_KEY": "your_api_key_here"
-      }
-    }
-  }
-}
+# 本番用ビルド
+npm run build
 ```
 
-注: このリポジトリでは `mcp_config.json` に `mcp-alphabanana` エントリ（Antigravity）を追加し、サーバー起動と画像生成の動作を確認しています。
-
-## Claude Desktop
-
-Claude Desktop で MCP サーバーを動かす場合は `claude_desktop_config.json` にエントリを追加:
+## ライセンス
 
-```json
-{
-  "mcpServers": {
-    "mcp-alphabanana": {
-      "command": "npx",
-      "args": ["-y", "@tasopen/mcp-alphabanana"],
-      "env": {
-        "GEMINI_API_KEY": "your_api_key_here"
-      }
-    }
-  }
+MIT
+  ]
 }
 ```
 
-テスト済み: 上記エントリを Claude Desktop に追加しサーバーを起動すると、MCP サーバーが起動し画像生成が動作しました。
-
-### 環境変数
-
-| 変数 | 必須 | 説明 |
-|----------|----------|-------------|
-| `GEMINI_API_KEY` | Yes | Google AI Studio APIキー。`mcp.json` で OS 環境変数参照（`${env:GEMINI_API_KEY}`）または直接キー記載（エージェントが OS 環境変数にアクセス不可な場合） |
-| `MCP_FALLBACK_OUTPUT` | No | 書き込み失敗時のフォールバックディレクトリ（デフォルト: `<install-dir>/fallback-output`） |
-
-### 出力パスのベストプラクティス
+---
 
-**常に `outputPath` には絶対パスを使ってください:**
+## 透過・出力形式
 
-✅ 良い例: "C:/Users/you/project/assets", "/home/user/images"  
-❌ 悪い例: `"./"`, `"output/"`, `"../images"`
+- **PNG**: 完全アルファ、カラーキー+デスピル
+- **WebP**: 完全アルファ、高圧縮（Flash3.1+）
+- **JPEG**: 透過なし（不透明背景にフォールバック）
 
-相対パスは MCP サーバーの作業ディレクトリから解決されるため、サービス実行時に予期しない場所にファイルが作成される可能性があります。
-
-**フォールバック動作:**
-- 指定した `outputPath` が書き込み可能 → 通常通り画像を保存
-- 書き込み不可（パーミッション拒否など） → フォールバックディレクトリに保存しレスポンスに `warning` を含める
-- フォールバックも失敗した場合 → エラーを返す
+---
 
 ## 開発
 
 ```bash
 # 開発モード（MCP CLI）
-npm run dev
+#### 透過 + フリンジ制御
 
 # MCP Inspector (Web UI)
-npm run inspect
+
 
 # 本番用ビルド
 npm run build
 ```
 
-## ツール: generate_image
-
-Gemini AI で画像アセットを生成（オプションで透過・参照画像対応）。
-
-### パラメータ
-
-| パラメータ | 型 | デフォルト | 説明 |
-|-----------|------|---------|-------------|
-| `prompt` | string | *必須* | 生成する画像の説明 |
-| `outputFileName` | string | *必須* | 出力ファイル名（拡張子がない場合は自動追加） |
-| `outputType` | enum | `combine` | 出力形式: `file`、`base64`、または`combine` |
-| `modelTier` | enum | *必須* | モデル: `flash` (Gemini 2.5 Flash, 最大3参照) または `pro` (Gemini 3 Pro, 最大14参照) |
-| `sourceResolution` | enum | `1K` | Gemini生成解像度: `1K`、`2K`、または`4K` (2K/4Kはproのみ) |
-| `outputWidth` | number | `1024` | 出力幅（ピクセル、8-4096） |
-| `outputHeight` | number | `1024` | 出力高さ（ピクセル、8-4096） |
-| `outputFormat` | enum | `png` | 出力形式: `png`または`jpg` |
-| `outputPath` | string | *任意* | 絶対パスの出力ディレクトリ（ファイル保存時は必須） |
-| `transparent` | boolean | `false` | 透過背景をリクエスト（PNGのみ） |
-| `transparentColor` | string | `null` | 透過にする色（例: `#FF00FF`、未指定時は #FF00FF） |
-| `colorTolerance` | number | `30` | 透過色マッチングの許容範囲（0-255） |
-| `fringeMode` | enum | `auto` | フリンジ処理: `auto`、`crisp`、`hd`（autoは128px以下で`crisp`、それ以外は`hd`） |
-| `resizeMode` | enum | `crop` | リサイズモード: `crop`、`stretch`、`letterbox`、または`contain` |
-| `referenceImages` | array | `[]` | スタイルガイダンス用の参照画像（ファイルパス） |
-| `debug` | boolean | `false` | デバッグモード: 中間画像を出力 |
-
-### 使用例
-
-#### 基本的な生成
-
-```json
-{
-  "prompt": "ピクセルアートの宝箱、金の装飾、木の質感",
-  "modelTier": "flash",
-  "outputFileName": "chest",
-  "outputWidth": 64,
-  "outputHeight": 64,
-  "transparent": true
-}
-```
-
-#### 透過スプライト
-
-```json
-{
-  "prompt": "レトロゲーム風の宇宙戦闘機スプライト、青みがかった銀色、輪郭がはっきり、背景なし、文字・数字・ロゴを含めない",
-  "modelTier": "flash",
-  "outputFileName": "space_fighter",
-  "outputWidth": 64,
-  "outputHeight": 64,
-  "transparent": true
-}
-```
-
-#### 透過 + フリンジ制御
+## ライセンス
 
+MIT
 ```json
 {
   "prompt": "アニメ調 自転車に乗った少女",

package/README.md

@@ -2,26 +2,27 @@
 
 English | [日本語](README.ja.md)
 
-A Model Context Protocol (MCP) server for generating image assets using Google Gemini AI.
+A Model Context Protocol (MCP) server for generating image assets using Google Gemini AI (Gemini 3.1 Flash/Nano Banana 2 supported).
 
 Built with [FastMCP 3](https://www.npmjs.com/package/fastmcp) for a simplified codebase and flexible output options.
 
 ## Features
 
-- **General-purpose image generation** using Google Gemini AI
-- **Transparent PNG output** via color-key post-processing
+- **Ultra-fast image generation** (Gemini 3.1 Flash, 0.5K/1K/2K/4K)
+- **Advanced multi-image reasoning** (up to 14 reference images)
+- **Thinking/Grounding support** (Flash3.1 only)
+- **Transparent PNG/WebP output** (color-key post-processing, despill)
 - **Multiple output formats**: file, base64, or both
-- **Reference image support** for style guidance
 - **Flexible resize modes**: crop, stretch, letterbox, contain
-- **Multiple model tiers**: flash (Gemini 2.5 Flash) or pro (Gemini 3 Pro)
+- **Multiple model tiers**: Flash3.1, Flash2.5, Pro3, legacy aliases
 
 ## Installation
 
-add `@tasopen/mcp-alphabanana` to your MCP Servers configuration.
+Add `@tasopen/mcp-alphabanana` to your MCP Servers configuration.
 
 ## Configuration
 
-Configure the `GEMINI_API_KEY` in your MCP configuration (e.g. `mcp.json`). Some agent environments cannot access OS environment variables, so you can either reference an OS environment variable from `mcp.json` or provide the key directly in `mcp.json`.
+Configure the `GEMINI_API_KEY` in your MCP configuration (e.g. `mcp.json`).
 
 Examples:
 
@@ -35,7 +36,7 @@ Examples:
 }
 ```
 
-- Provide the key directly in `mcp.json` (useful when the agent cannot access OS env vars):
+- Provide the key directly in `mcp.json`:
 
 ```json
 {
@@ -45,11 +46,9 @@ Examples:
 }
 ```
 
-Use whichever method suits your deployment — prefer environment references when possible, but include the key directly when agent constraints require it.
-
 ## VS Code Integration
 
-Add to your VS Code settings (`.vscode/settings.json` or user settings), configuring the server `env` in `mcp.json` or via the VS Code MCP settings. You can reference an OS environment variable or put the key directly:
+Add to your VS Code settings (`.vscode/settings.json` or user settings), configuring the server `env` in `mcp.json` or via the VS Code MCP settings.
 
 ```json
 {
@@ -69,114 +68,40 @@ Add to your VS Code settings (`.vscode/settings.json` or user settings), configu
 
 **Optional:** Set a custom fallback directory for write failures by adding `MCP_FALLBACK_OUTPUT` to the `env` object.
 
-## Antigravity (mcp_config.json)
-
-Antigravity uses a global `mcp_config.json` to register MCP servers. Example `mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "mcp-alphabanana": {
-      "command": "npx",
-      "args": ["-y", "@tasopen/mcp-alphabanana"],
-      "env": {
-        "GEMINI_API_KEY": "your_api_key_here"
-      }
-    }
-  }
-}
-```
-
-Note: In this repository we used an `mcp_config.json` with the `mcp-alphabanana` entry (Antigravity) and confirmed the server started and generated images successfully.
-
-## Claude Desktop
-
-If you run MCP servers via Claude Desktop, add an entry in `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "mcp-alphabanana": {
-      "command": "npx",
-      "args": ["-y", "@tasopen/mcp-alphabanana"],
-      "env": {
-        "GEMINI_API_KEY": "your_api_key_here"
-      }
-    }
-  }
-}
-```
-
-Tested: Adding the above entry in Claude Desktop and starting the server launched the MCP server and image generation worked.
-
-### Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `GEMINI_API_KEY` | Yes | Google AI Studio API Key. Configure in `mcp.json` either by referencing an OS environment variable (`${env:GEMINI_API_KEY}`) or by including the key directly (some agents cannot access OS env vars). |
-| `MCP_FALLBACK_OUTPUT` | No | Fallback directory for write failures (default: `<install-dir>/fallback-output`) |
-
-### Output Path Best Practices
-
-**Always use absolute paths for `outputPath`:**
-
-✅ **Good:** "C:/Users/you/project/assets", "/home/user/images"  
-❌ **Bad:** `"./"`, `"output/"`, `"../images"`
-
-Relative paths are resolved from the MCP server's working directory (unpredictable when running as a service), leading to unexpected file locations.
-
-**Fallback behavior:**
-- If the requested `outputPath` is writable → image saved there as usual
-- If not writable (permission denied, etc.) → saves to fallback directory with `warning` in response
-- Fallback directory: `MCP_FALLBACK_OUTPUT` env var, or `<install-dir>/fallback-output` by default
-- If fallback also fails → returns error
-
-## Development
-
-```bash
-# Development mode with MCP CLI
-npm run dev
-
-# MCP Inspector (Web UI)
-npm run inspect
-
-# Build for production
-npm run build
-```
-
-## Tool: generate_image
+## Model Selection & Parameters
 
-Generate image assets using Gemini AI with optional transparency and reference images.
+| Input Model ID | Internal Model ID | Description |
+| --- | --- | --- |
+| `Flash3.1` | `gemini-3.1-flash-image-preview` | Ultra-fast, supports Thinking/Grounding. |
+| `Flash2.5` | `gemini-2.5-flash-image` | Legacy Flash. High stability. Low cost. |
+| `Pro3` | `gemini-3.0-pro-image-preview` | High-fidelity Pro model. |
+| `flash` | `gemini-3.1-flash-image-preview` | Alias for backward compatibility. |
+| `pro` | `gemini-3.0-pro-image-preview` | Alias for backward compatibility. |
 
-### Parameters
+### Parameters (v2.0)
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `prompt` | string | *required* | Description of the image to generate |
-| `outputFileName` | string | *required* | Output filename (extension auto-added if missing) |
-| `outputType` | enum | `combine` | Output format: `file`, `base64`, or `combine` |
-| `modelTier` | enum | *required* | Model: `flash` (Gemini 2.5 Flash, max 3 refs) or `pro` (Gemini 3 Pro, max 14 refs) |
-| `sourceResolution` | enum | `1K` | Gemini source resolution: `1K`, `2K`, or `4K` (2K/4K pro-only) |
-| `outputWidth` | number | `1024` | Output width in pixels (8-4096) |
-| `outputHeight` | number | `1024` | Output height in pixels (8-4096) |
-| `outputFormat` | enum | `png` | Output format: `png` or `jpg` |
-| `outputPath` | string | *optional* | Absolute output directory path (required when saving files) |
-| `transparent` | boolean | `false` | Request transparent background (PNG only) |
-| `transparentColor` | string | `null` | Color to make transparent (e.g., `#FF00FF`), defaults to `#FF00FF` when null |
-| `colorTolerance` | number | `30` | Tolerance for transparent color matching (0-255) |
-| `fringeMode` | enum | `auto` | Fringe reduction mode: `auto`, `crisp`, `hd` (auto uses `crisp` <= 128px, otherwise `hd`) |
-| `resizeMode` | enum | `crop` | Resize mode: `crop`, `stretch`, `letterbox`, or `contain` |
-| `referenceImages` | array | `[]` | Reference images for style guidance (file paths) |
-| `debug` | boolean | `false` | Debug mode: output intermediate images |
-
-### Usage Examples
+| `model` | enum | `Flash3.1` | Model: `Flash3.1`, `Flash2.5`, `Pro3`, `flash`, `pro` |
+| `output_resolution` | enum | `1K` | `0.5K`, `1K`, `2K`, `4K` (0.5K/2K/4K: Flash3.1 only) |
+| `output_format` | enum | `png` | `png`, `jpg`, `webp` (WebP: alpha supported) |
+| `transparent` | boolean | `false` | Transparent background (PNG/WebP only) |
+| `grounding_type` | enum | `none` | `none`, `text`, `image`, `both` (Flash3.1 only) |
+| `thinking_mode` | enum | `minimal` | `minimal`, `high` (Flash3.1 only) |
+| `include_thoughts` | boolean | `false` | Return model's "thoughts" (Flash3.1 only) |
+| `reference_images` | array | `[]` | Up to 14 (Flash3.1/Pro3), 3 (Flash2.5) |
+
+---
+
+## Usage Examples
 
 #### Basic Generation
 
 ```json
 {
   "prompt": "A pixel art treasure chest, golden trim, wooden texture",
-  "modelTier": "flash",
+  "model": "Flash3.1",
   "outputFileName": "chest",
   "outputWidth": 64,
   "outputHeight": 64,
@@ -184,113 +109,66 @@ Generate image assets using Gemini AI with optional transparency and reference i
 }
 ```
 
-
-#### Transparent Sprite
-
-```json
-{
-  "prompt": "Retro game-style space fighter sprite, blue-tinted silver, clean silhouette, no background, no text, no letters, no numbers, no logos",
-  "modelTier": "flash",
-  "outputFileName": "space_fighter",
-  "outputWidth": 64,
-  "outputHeight": 64,
-  "transparent": true
-}
-```
-
-
-#### Transparency + Fringe Control
-
-```json
-{
-  "prompt": "Anime-style girl riding a bicycle",
-  "modelTier": "flash",
-  "outputFileName": "bicycle_girl",
-  "outputWidth": 1024,
-  "outputHeight": 576,
-  "transparent": true,
-  "colorTolerance": 30,
-  "fringeMode": "crisp"
-}
-```
-
-
-#### High-Resolution Background
+#### Advanced (WebP, thinking, grounding)
 
 ```json
 {
-  "prompt": "Fantasy forest at twilight with glowing mushrooms",
-  "outputFileName": "forest_bg",
-  "modelTier": "pro",
-  "sourceResolution": "4K",
-  "outputWidth": 3840,
-  "outputHeight": 2160,
-  "outputFormat": "jpg",
-  "outputPath": "C:/Users/you/project/assets/backgrounds"
+  "prompt": "A photorealistic girl with wings flying over a European countryside",
+  "model": "Flash3.1",
+  "outputFileName": "girl_wings",
+  "outputWidth": 632,
+  "outputHeight": 424,
+  "output_format": "webp",
+  "thinking_mode": "high",
+  "grounding_type": "both",
+  "include_thoughts": true
 }
 ```
 
-#### With Reference Image
+#### With Reference Images
 
 ```json
 {
-  "prompt": "A matching treasure chest, open state, same pixel art style",
-  "modelTier": "flash",
+  "prompt": "A matching treasure chest, open state, same pixel art style as references",
+  "model": "Pro3",
   "outputFileName": "chest_open",
   "outputWidth": 64,
   "outputHeight": 64,
   "transparent": true,
-  "referenceImages": [
+  "reference_images": [
     {
       "description": "Closed chest for style reference",
-      "filePath": "C:/Users/you/project/assets/references/chest_closed.png"
+      "data": "...base64..."
     }
   ]
 }
 ```
 
-## Output Types
-
-| Type | Saves File | Returns Base64 | MCP Image Content |
-|------|-----------|----------------|-------------------|
-| `file` | ✓ | ✗ | ✗ |
-| `base64` | ✗ | ✓ | ✓ |
-| `combine` | ✓ | ✓ | ✓ |
+---
 
-## Transparency Processing
+## Transparency & Output Formats
 
-The server selects the background color by histogram analysis and hue proximity to the requested key color, then applies RGB-distance keying and despill. If no histogram candidate qualifies, it falls back to the closest-hue corner color.
+- **PNG**: Full alpha, color-key + despill
+- **WebP**: Full alpha, better compression (Flash3.1+)
+- **JPEG**: No transparency (falls back to solid background)
 
-### Model Notes
+---
 
-- Flash is sufficient for transparent PNG output in typical use.
-- `colorTolerance` around 30 performed best in tests; higher values can increase false positives.
+## Development
 
-### Recommended Background Colors
+```bash
+# Development mode with MCP CLI
+npm run dev
 
-| Color | Hex | Best For |
-|-------|-----|----------|
-| Magenta | `#FF00FF` | Most sprites (default, works with both models) |
-| Green | `#00FF00` | Purple/pink objects |
-| Cyan | `#00FFFF` | Red/orange objects |
-| Blue | `#0000FF` | Yellow/green objects |
 
-### Examples
+# MCP Inspector (Web UI)
+npm run inspect
 
-```json
-{
-  "transparent": true,
-  "transparentColor": "#00FF00",
-  "colorTolerance": 30
-}
+# Build for production
+npm run build
 ```
 
-### Fringe Mode Guidance
-
-- Use `crisp` when thin lines risk being removed (pixel art, bicycle spokes, wire meshes).
-- Use `hd` for general high-resolution images where fringe is noticeable.
-- Use `auto` for a size-based default (`crisp` for <= 128px, `hd` otherwise).
-
 ## License
 
 MIT
+