内容
# 纳米香蕉克劳德
*由 `generate_image` 生成（纳米香蕉闪电版，16:9）。*
一个小型 [MCP](https://modelcontextprotocol.io) 服务器，为克劳德代码（或任何MCP客户端）提供图像生成功能，使用谷歌的 **纳米香蕉** Gemini图像模型 — 以及模型本身无法可靠执行的一些确定性后处理：**真实的alpha透明度**、**AI超分辨率**、调整大小和格式转换。
其理念是：将生成留在模型中，但将需要真正代码的功能（真正的alpha通道、精确尺寸、超分辨率）放在工具后面，使它们更可靠，而不是仅凭提示和希望。
## 工具
| 工具 | 功能 |
|------|--------------|
| `generate_image` | 文本 → 图片。`model` (`flash`/`pro`)，`aspect_ratio`，`format`，`output_path`。 |
| `generate_transparent_image` | 生成图片，然后使用rembg（U2-Net）移除背景 → 真实的 **RGBA PNG**。纳米香蕉无法独自生成可靠的alpha透明度。 |
| `edit_image` | 一个或多个输入图片 + 一个提示 → 编辑/合成结果。 |
| `process_image` | 本地Pillow操作，无需API调用：调整大小/适应/裁剪，转换（png/webp/jpeg + 质量），可选背景移除。 |
| `upscale_image` | 使用Real-ESRGAN（`realesr-general-x4v3`）进行AI超分辨率。针对大图片进行分块处理，保留alpha透明度。 |
**模型：** `flash` → `gemini-2.5-flash-image`（纳米香蕉，默认，快速/廉价），`pro` → `gemini-3-pro-image-preview`（纳米香蕉Pro，更高质量）。
## 需求
- Python 3.10+
- 一个Gemini API密钥（免费层可用）来自 <https://aistudio.google.com/apikey>
- 约500 MB磁盘空间用于依赖项；不需要GPU（CPU即可）
## 安装
```bash
git clone https://github.com/tougenrip/nano-banana-claude.git
cd nano-banana-claude
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```
两个ML模型在首次使用时自动下载（不包含在仓库中）：
- rembg U2-Net（~176 MB）→ `~/.u2net/` — 首次调用透明图片
- Real-ESRGAN x4（~4.6 MB）→ `~/.cache/nano-banana/` — 首次调用超分辨率
## 在克劳德代码中注册
从克隆的目录中：
```bash
claude mcp add nano-banana --scope user \
--env GEMINI_API_KEY=your-key-here \
-- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"
```
`--scope user`使其在每个项目中都可用；如果仅限于当前项目，请删除它。重新连接后，五个`nano-banana`工具就会出现。API密钥在运行时从环境中读取，绝不会写入代码。
## 用法
注册后，只需用自然语言提问 — 克劳德会选择合适的工具：
- *"生成一个16:9的夜间霓虹城市图片。"* → `generate_image`
- *"生成一个红色运动鞋的透明PNG图片。"* → `generate_transparent_image`
- *"将logo.png中的标志放在mug.jpg的马克杯上。"* → `edit_image`
- *"将hero.png调整为1200px宽的webp格式。"* → `process_image`
- *"将icon.png放大4倍。"* → `upscale_image`
工具可以链式调用：生成一个透明剪切图，然后放大它 — alpha透明度得以保留。
输出文件将写入当前工作目录（或`output_path`）旁边，并返回绝对路径。设置`NANO_BANANA_OUTPUT_DIR`可更改默认位置。
## 透明度工作原理
图像模型会绘制像素；询问“透明背景”通常会产生纯色或绘制的棋盘格，而不是真正的alpha通道。因此，`generate_transparent_image`会在纯色背景上生成主体，然后运行rembg（U2-Net）计算实际的alpha遮罩，生成真正的RGBA PNG。`process_image(remove_background=true)`会对任何现有图片执行相同的操作。
<img src="examples/transparent-banana.png" alt="透明剪切图示例" width="320">
`*generate_transparent_image`的输出 — 真实的RGBA PNG（约90%的像素完全透明），而非绘制的棋盘格。*
## 布局
```
server.py FastMCP服务器 + 工具定义；通过标准库urllib进行Gemini REST调用
upscale.py Real-ESRGAN推理（onnxruntime），延迟加载，支持分块处理
requirements.txt mcp、Pillow、rembg、onnxruntime
```
## 许可证
MIT — 见 [LICENSE](LICENSE)。
