@tasopen/mcp-alphabanana 1.2.1 → 1.3.3

package/README.ja.md

@@ -1,19 +1,20 @@
 # mcp-alphabanana
 
-English | [日本語](README.ja.md)
+[English](README.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) で構築され、シンプルなコードベースと柔軟な出力オプションを提供します。
+[FastMCP 3](https://www.npmjs.com/package/fastmcp) で構築されており、シンプルなコードベースと柔軟な出力オプションを提供します。
 
-## 機能
+## 主な機能
 
-- **Google Gemini AI による汎用画像生成**
-- **カラーキー後処理による透過 PNG 出力**
-- **複数の出力形式**: ファイル、base64、または両方
-- **スタイル参照のための参照画像サポート**
-- **柔軟なリサイズモード**: crop、stretch、letterbox、contain
-- **複数のモデルティア**: flash (Gemini 2.5 Flash) または pro (Gemini 3 Pro)
+- **超高速画像生成**（Gemini 3.1 Flash、0.5K/1K/2K/4K）
+- **高度なマルチ画像推論**（参照画像を最大 14 枚）
+- **Thinking / Grounding 対応**（Flash3.1 のみ）
+- **透過 PNG / WebP 出力**（カラーキー後処理 + デスピル）
+- **複数の出力形式**: file / base64 / combine
+- **柔軟なリサイズモード**: crop / stretch / letterbox / contain
+- **複数モデルティア**: Flash3.1 / Flash2.5 / Pro3 / 互換エイリアス
 
 ## インストール
 
@@ -21,11 +22,11 @@ Google Gemini AI を使って画像アセットを生成する Model Context Pro
 
 ## 設定
 
-`GEMINI_API_KEY` を MCP 設定（例: `mcp.json`）で設定します。一部のエージェント環境では OS 環境変数にアクセスできないため、`mcp.json` で OS 環境変数を参照するか、直接キーを記載できます。
+`GEMINI_API_KEY` を MCP 設定（例: `mcp.json`）で指定します。
 
 例:
 
-- `mcp.json` で OS 環境変数を参照:
+- `mcp.json` で OS 環境変数を参照する場合
 
 ```json
 {
@@ -35,7 +36,7 @@ Google Gemini AI を使って画像アセットを生成する Model Context Pro
 }
 ```
 
-- `mcp.json` に直接キーを記載（エージェントが OS 環境変数を参照できない場合に有用）:
+- `mcp.json` に直接キーを記載する場合
 
 ```json
 {
@@ -45,11 +46,9 @@ Google Gemini AI を使って画像アセットを生成する Model Context Pro
 }
 ```
 
-運用に合わせて選択してください（可能であれば環境参照を推奨）。
+## VS Code 連携
 
-## VS Code 統合
-
-VS Code 設定（`.vscode/settings.json` またはユーザー設定）に追加し、サーバー `env` を `mcp.json` または VS Code MCP 設定で設定します。OS 環境変数参照または直接キー記載の両方に対応:
+VS Code 設定（`.vscode/settings.json` またはユーザー設定）に追加してください。`env` は `mcp.json` もしくは VS Code MCP 設定経由で指定できます。
 
 ```json
 {
@@ -57,9 +56,9 @@ VS Code 設定（`.vscode/settings.json` またはユーザー設定）に追加
     "servers": {
       "mcp-alphabanana": {
         "command": "npx",
-        "args":["-y", "@tasopen/mcp-alphabanana"],
+        "args": ["-y", "@tasopen/mcp-alphabanana"],
         "env": {
-          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"  // or "your_api_key_here"
+          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
         }
       }
     }
@@ -67,115 +66,43 @@ VS Code 設定（`.vscode/settings.json` またはユーザー設定）に追加
 }
 ```
 
-**オプション:** 書き込み失敗時のカスタムフォールバックディレクトリを指定する場合は `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"
-      }
-    }
-  }
-}
-```
-
-注: このリポジトリでは `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"
-      }
-    }
-  }
-}
-```
-
-テスト済み: 上記エントリを Claude Desktop に追加しサーバーを起動すると、MCP サーバーが起動し画像生成が動作しました。
-
-### 環境変数
+**任意:** 書き込み失敗時の保存先を変更したい場合は、`env` に `MCP_FALLBACK_OUTPUT` を追加してください。
 
-| 変数 | 必須 | 説明 |
-|----------|----------|-------------|
-| `GEMINI_API_KEY` | Yes | Google AI Studio APIキー。`mcp.json` で OS 環境変数参照（`${env:GEMINI_API_KEY}`）または直接キー記載（エージェントが OS 環境変数にアクセス不可な場合） |
-| `MCP_FALLBACK_OUTPUT` | No | 書き込み失敗時のフォールバックディレクトリ（デフォルト: `<install-dir>/fallback-output`） |
+## モデル選択とパラメータ
 
-### 出力パスのベストプラクティス
+| 入力モデルID | 内部モデルID | 説明 |
+| --- | --- | --- |
+| `Flash3.1` | `gemini-3.1-flash-image-preview` | 超高速。Thinking / Grounding 対応。 |
+| `Flash2.5` | `gemini-2.5-flash-image` | 旧 Flash 系。安定性高め。低コスト。 |
+| `Pro3` | `gemini-3.0-pro-image-preview` | 高品質な Pro モデル。 |
+| `flash` | `gemini-3.1-flash-image-preview` | 後方互換エイリアス。 |
+| `pro` | `gemini-3.0-pro-image-preview` | 後方互換エイリアス。 |
 
-**常に `outputPath` には絶対パスを使ってください:**
+### パラメータ（v2.0）
 
-✅ 良い例: "C:/Users/you/project/assets", "/home/user/images"  
-❌ 悪い例: `"./"`, `"output/"`, `"../images"`
-
-相対パスは MCP サーバーの作業ディレクトリから解決されるため、サービス実行時に予期しない場所にファイルが作成される可能性があります。
-
-**フォールバック動作:**
-- 指定した `outputPath` が書き込み可能 → 通常通り画像を保存
-- 書き込み不可（パーミッション拒否など） → フォールバックディレクトリに保存しレスポンスに `warning` を含める
-- フォールバックも失敗した場合 → エラーを返す
-
-## 開発
-
-```bash
-# 開発モード（MCP CLI）
-npm run dev
-
-# MCP Inspector (Web UI)
-npm run inspect
-
-# 本番用ビルド
-npm run build
-```
-
-## ツール: generate_image
+| パラメータ | 型 | 既定値 | 説明 |
+|-----------|------|---------|-------------|
+| `prompt` | string | 必須 | 生成したい画像の説明 |
+| `model` | enum | `Flash3.1` | `Flash3.1` / `Flash2.5` / `Pro3` / `flash` / `pro` |
+| `output_resolution` | enum | `1K` | `0.5K` / `1K` / `2K` / `4K`（0.5K/2K/4K は Flash3.1 のみ） |
+| `output_format` | enum | `png` | `png` / `jpg` / `webp`（WebP はアルファ対応） |
+| `transparent` | boolean | `false` | 背景透過（PNG / WebP のみ） |
+| `grounding_type` | enum | `none` | `none` / `text` / `image` / `both`（Flash3.1 のみ） |
+| `thinking_mode` | enum | `minimal` | `minimal` / `high`（Flash3.1 のみ） |
+| `include_thoughts` | boolean | `false` | モデルの思考データを返却（Flash3.1 のみ） |
+| `include_metadata` | boolean | `false` | JSON 出力に grounding / reasoning メタデータを含める |
+| `reference_images` | array | `[]` | 最大 14 枚（Flash3.1/Pro3）、Flash2.5 は 3 枚 |
 
-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",
+  "prompt": "金の縁取りがある木製のピクセルアート宝箱",
+  "model": "Flash3.1",
   "outputFileName": "chest",
   "outputWidth": 64,
   "outputHeight": 64,
@@ -183,110 +110,82 @@ Gemini AI で画像アセットを生成（オプションで透過・参照画
 }
 ```
 
-#### 透過スプライト
+#### 応用例（WebP + Thinking + Grounding）
 
 ```json
 {
-  "prompt": "レトロゲーム風の宇宙戦闘機スプライト、青みがかった銀色、輪郭がはっきり、背景なし、文字・数字・ロゴを含めない",
-  "modelTier": "flash",
-  "outputFileName": "space_fighter",
-  "outputWidth": 64,
-  "outputHeight": 64,
-  "transparent": true
+  "prompt": "ヨーロッパの田園風景の上を飛ぶ翼のある少女、フォトリアル",
+  "model": "Flash3.1",
+  "outputFileName": "girl_wings",
+  "outputWidth": 632,
+  "outputHeight": 424,
+  "output_format": "webp",
+  "thinking_mode": "high",
+  "grounding_type": "both",
+  "include_thoughts": true
 }
 ```
 
-#### 透過 + フリンジ制御
+#### Grounding サンプル（検索連携）
 
 ```json
 {
-  "prompt": "アニメ調 自転車に乗った少女",
-  "modelTier": "flash",
-  "outputFileName": "bicycle_girl",
+  "prompt": "クアラルンプールの今日の天気と主要スカイラインを盛り込んだモダンな旅行ポスター",
+  "model": "Flash3.1",
+  "outputFileName": "kl_travel_poster",
   "outputWidth": 1024,
-  "outputHeight": 576,
-  "transparent": true,
-  "colorTolerance": 30,
-  "fringeMode": "crisp"
+  "outputHeight": 1024,
+  "grounding_type": "text",
+  "thinking_mode": "high",
+  "include_metadata": true,
+  "include_thoughts": true
 }
 ```
 
-#### 高解像度背景
+このサンプルでは Google Search Grounding を有効化し、JSON に grounding / reasoning メタデータを返します。
 
-```json
-{
-  "prompt": "夕暮れのファンタジーの森、光る茸",
-  "outputFileName": "forest_bg",
-  "modelTier": "pro",
-  "sourceResolution": "4K",
-  "outputWidth": 3840,
-  "outputHeight": 2160,
-  "outputFormat": "jpg",
-  "outputPath": "C:/Users/you/project/assets/backgrounds"
-}
-```
-
-#### 参照画像を使用
+#### 参照画像つき生成
 
 ```json
 {
-  "prompt": "同じピクセルアートスタイルで、開いた状態の宝箱",
-  "modelTier": "flash",
+  "prompt": "参照画像と同じピクセルアート調で、開いた状態の宝箱",
+  "model": "Pro3",
   "outputFileName": "chest_open",
   "outputWidth": 64,
   "outputHeight": 64,
   "transparent": true,
-  "referenceImages": [
+  "reference_images": [
     {
-      "description": "スタイル参照用の閉じた宝箱",
-      "filePath": "C:/Users/you/project/assets/references/chest_closed.png"
+      "description": "Closed chest for style reference",
+      "data": "...base64..."
     }
   ]
 }
 ```
 
-## 出力タイプ
-
-| タイプ | ファイル保存 | Base64返却 | MCP画像コンテンツ |
-|------|-----------|----------------|-------------------|
-| `file` | ✓ | ✗ | ✗ |
-| `base64` | ✗ | ✓ | ✓ |
-| `combine` | ✓ | ✓ | ✓ |
+---
 
-## 透過処理
+## 透過と出力形式
 
-サーバーはヒストグラム分析と色相近接により背景色を推定し、RGB距離でキー抜きを行いデスピルします。候補がなければ最も近い色相のコーナーカラーを使用します。
+- **PNG**: 完全アルファ対応、カラーキー + デスピル
+- **WebP**: 完全アルファ対応、より高い圧縮効率
+- **JPEG**: 透過非対応（不透明背景にフォールバック）
 
-### モデルメモ
+---
 
-- 透過 PNG 出力は通常 flash で十分です。
-- `colorTolerance` は 30 前後が最も安定しました。高すぎると誤検出が増えます。
-
-### 推奨背景色
+## 開発
 
-| 色 | 16進数 | 最適な用途 |
-|-------|-----|----------|
-| マゼンタ | `#FF00FF` | ほとんどのスプライト（デフォルト、両モデルで動作） |
-| 緑 | `#00FF00` | 紫/ピンクのオブジェクト |
-| シアン | `#00FFFF` | 赤/オレンジのオブジェクト |
-| 青 | `#0000FF` | 黄/緑のオブジェクト |
+```bash
+# 開発モード（MCP CLI）
+npm run dev
 
-### 例
+# MCP Inspector（Web UI）
+npm run inspect
 
-```json
-{
-  "transparent": true,
-  "transparentColor": "#00FF00",
-  "colorTolerance": 30
-}
+# 本番ビルド
+npm run build
 ```
 
-### Fringe Mode ガイド
-
-- 細い線が消えやすい場合（ドット絵、スポーク、ワイヤーメッシュ等）は `crisp`
-- 高解像度画像でフリンジが目立つ場合は `hd`
-- `auto` はサイズで自動切替（128px 以下は `crisp`、それ以外は `hd`）
-
 ## ライセンス
 
 MIT