@tasopen/mcp-alphabanana 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) TasogarePenguin 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,292 @@
+# mcp-alphabanana
+
+English | [日本語](README.ja.md)
+
+Google Gemini AI を使って画像アセットを生成する Model Context Protocol (MCP) サーバー。
+
+[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)
+
+## インストール
+
+`@tasopen/mcp-alphabanana` を MCP サーバー設定に追加してください。
+
+## 設定
+
+`GEMINI_API_KEY` を MCP 設定（例: `mcp.json`）で設定します。一部のエージェント環境では OS 環境変数にアクセスできないため、`mcp.json` で OS 環境変数を参照するか、直接キーを記載できます。
+
+例:
+
+- `mcp.json` で OS 環境変数を参照:
+
+```json
+{
+  "env": {
+    "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
+  }
+}
+```
+
+- `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 環境変数参照または直接キー記載の両方に対応:
+
+```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_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 サーバーが起動し画像生成が動作しました。
+
+### 環境変数
+
+| 変数 | 必須 | 説明 |
+|----------|----------|-------------|
+| `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"`
+
+相対パスは 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
+}
+```
+
+#### 透過 + フリンジ制御
+
+```json
+{
+  "prompt": "アニメ調 自転車に乗った少女",
+  "modelTier": "flash",
+  "outputFileName": "bicycle_girl",
+  "outputWidth": 1024,
+  "outputHeight": 576,
+  "transparent": true,
+  "colorTolerance": 30,
+  "fringeMode": "crisp"
+}
+```
+
+#### 高解像度背景
+
+```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",
+  "outputFileName": "chest_open",
+  "outputWidth": 64,
+  "outputHeight": 64,
+  "transparent": true,
+  "referenceImages": [
+    {
+      "description": "スタイル参照用の閉じた宝箱",
+      "filePath": "C:/Users/you/project/assets/references/chest_closed.png"
+    }
+  ]
+}
+```
+
+## 出力タイプ
+
+| タイプ | ファイル保存 | Base64返却 | MCP画像コンテンツ |
+|------|-----------|----------------|-------------------|
+| `file` | ✓ | ✗ | ✗ |
+| `base64` | ✗ | ✓ | ✓ |
+| `combine` | ✓ | ✓ | ✓ |
+
+## 透過処理
+
+サーバーはヒストグラム分析と色相近接により背景色を推定し、RGB距離でキー抜きを行いデスピルします。候補がなければ最も近い色相のコーナーカラーを使用します。
+
+### モデルメモ
+
+- 透過 PNG 出力は通常 flash で十分です。
+- `colorTolerance` は 30 前後が最も安定しました。高すぎると誤検出が増えます。
+
+### 推奨背景色
+
+| 色 | 16進数 | 最適な用途 |
+|-------|-----|----------|
+| マゼンタ | `#FF00FF` | ほとんどのスプライト（デフォルト、両モデルで動作） |
+| 緑 | `#00FF00` | 紫/ピンクのオブジェクト |
+| シアン | `#00FFFF` | 赤/オレンジのオブジェクト |
+| 青 | `#0000FF` | 黄/緑のオブジェクト |
+
+### 例
+
+```json
+{
+  "transparent": true,
+  "transparentColor": "#00FF00",
+  "colorTolerance": 30
+}
+```
+
+### Fringe Mode ガイド
+
+- 細い線が消えやすい場合（ドット絵、スポーク、ワイヤーメッシュ等）は `crisp`
+- 高解像度画像でフリンジが目立つ場合は `hd`
+- `auto` はサイズで自動切替（128px 以下は `crisp`、それ以外は `hd`）
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,296 @@
+# mcp-alphabanana
+
+English | [日本語](README.ja.md)
+
+A Model Context Protocol (MCP) server for generating image assets using Google Gemini AI.
+
+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
+- **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)
+
+## Installation
+
+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`.
+
+Examples:
+
+- Reference an OS environment variable from `mcp.json`:
+
+```json
+{
+  "env": {
+    "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
+  }
+}
+```
+
+- Provide the key directly in `mcp.json` (useful when the agent cannot access OS env vars):
+
+```json
+{
+  "env": {
+    "GEMINI_API_KEY": "your_api_key_here"
+  }
+}
+```
+
+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:
+
+```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"
+        }
+      }
+    }
+  }
+}
+```
+
+**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
+
+Generate image assets using Gemini AI with optional transparency and reference images.
+
+### Parameters
+
+| 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
+
+#### Basic Generation
+
+```json
+{
+  "prompt": "A pixel art treasure chest, golden trim, wooden texture",
+  "modelTier": "flash",
+  "outputFileName": "chest",
+  "outputWidth": 64,
+  "outputHeight": 64,
+  "transparent": true
+}
+```
+
+
+#### 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
+
+```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"
+}
+```
+
+#### With Reference Image
+
+```json
+{
+  "prompt": "A matching treasure chest, open state, same pixel art style",
+  "modelTier": "flash",
+  "outputFileName": "chest_open",
+  "outputWidth": 64,
+  "outputHeight": 64,
+  "transparent": true,
+  "referenceImages": [
+    {
+      "description": "Closed chest for style reference",
+      "filePath": "C:/Users/you/project/assets/references/chest_closed.png"
+    }
+  ]
+}
+```
+
+## Output Types
+
+| Type | Saves File | Returns Base64 | MCP Image Content |
+|------|-----------|----------------|-------------------|
+| `file` | ✓ | ✗ | ✗ |
+| `base64` | ✗ | ✓ | ✓ |
+| `combine` | ✓ | ✓ | ✓ |
+
+## Transparency Processing
+
+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.
+
+### 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.
+
+### Recommended Background Colors
+
+| 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
+
+```json
+{
+  "transparent": true,
+  "transparentColor": "#00FF00",
+  "colorTolerance": 30
+}
+```
+
+### 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

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * mcp-alphabanana - FastMCP server for image generation using Google Gemini AI.
+ * Supports transparent PNG output, multiple resolutions, and style references.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}