# nano-banana-mcp

Servidor **MCP** (Model Context Protocol) en TypeScript que expone **Nano Banana**
—el modelo de imagen **Gemini 2.5 Flash Image** de Google— a Claude. Permite
**generar**, **editar** y **componer** imágenes desde Claude Desktop, Claude Code
o cualquier cliente MCP.

## Capacidades (tools)

| Tool | Descripción | Entradas |
|------|-------------|----------|
| `generate_image` | Texto → imagen | `prompt` |
| `edit_image` | Imagen + texto → imagen (inpainting, estilo, retoques) | `prompt`, `image` |
| `compose_images` | N imágenes + texto → imagen (fusión, composición, transferencia de estilo) | `prompt`, `images[]` |

Las imágenes de entrada (`image` / `images`) aceptan: **ruta a archivo local**,
**data URL** (`data:image/png;base64,...`) o **base64 crudo**.
Las imágenes de salida se devuelven **inline en base64** en la respuesta del tool.

## Requisitos

- Node.js >= 18
- Una API key de **Google AI Studio**: https://aistudio.google.com/apikey

## Instalación

```bash
npm install
npm run build
```

Copia `.env.example` a `.env` y coloca tu key:

```bash
cp .env.example .env
# edita .env -> GEMINI_API_KEY=...
```

> El `.env` es solo para desarrollo local. Al conectarlo a un cliente MCP, la key
> se pasa por la variable de entorno del propio cliente (ver abajo).

## Conectar a Claude

### Claude Code (CLI)

```bash
claude mcp add nano-banana \
  -e GEMINI_API_KEY=tu_api_key \
  -- node /ruta/absoluta/nano-banana-mcp/dist/index.js
```

### Claude Desktop

Edita `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "nano-banana": {
      "command": "node",
      "args": ["/ruta/absoluta/nano-banana-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "tu_api_key"
      }
    }
  }
}
```

Reinicia el cliente y pídele, por ejemplo: *"genera una imagen de un gato astronauta en acuarela"*.

## Desarrollo

```bash
npm run dev        # ejecuta con tsx (sin compilar)
npm run typecheck  # verifica tipos
npm run build      # compila a dist/
```

Prueba rápida del protocolo (sin key, solo lista tools):

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node dist/index.js
```

## Configuración

| Variable | Requerida | Por defecto | Descripción |
|----------|-----------|-------------|-------------|
| `GEMINI_API_KEY` | Sí | — | API key de Google AI Studio |
| `NANO_BANANA_MODEL` | No | `gemini-2.5-flash-image` | Modelo de imagen a usar |

## Ambientes

La configuración por ambiente (local / integración / QA / producción) está
documentada en [`docs/environments/`](docs/environments/). Las decisiones de
arquitectura en [`docs/architecture/`](docs/architecture/).

## Notas

- En un servidor **stdio**, `stdout` está reservado para el protocolo MCP; los
  logs de diagnóstico van a `stderr`.
- Nunca comitees tu `.env` ni la API key (ya está en `.gitignore`).