mcp-banana-image 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shinsuke Kagawa
+
+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.md

@@ -0,0 +1,343 @@
+<p align="center">
+  <img src="assets/mcp-banana-image.webp" alt="MCP Banana Image" width="400"/>
+</p>
+
+<h1 align="center">MCP Banana Image</h1>
+
+<p align="center">
+  <strong>AI-Powered Image Generation MCP Server using Google Gemini</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/mcp-banana-image">
+    <img src="https://img.shields.io/npm/v/mcp-banana-image?style=flat-square&color=yellow" alt="npm version"/>
+  </a>
+  <a href="https://www.npmjs.com/package/mcp-banana-image">
+    <img src="https://img.shields.io/npm/dm/mcp-banana-image?style=flat-square&color=green" alt="npm downloads"/>
+  </a>
+  <a href="https://github.com/trigidigital/mcp-banana-image/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license"/>
+  </a>
+  <a href="https://nodejs.org/">
+    <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="node version"/>
+  </a>
+  <a href="#">
+    <img src="https://img.shields.io/badge/TypeScript-5.0-blue?style=flat-square&logo=typescript" alt="TypeScript"/>
+  </a>
+  <a href="#">
+    <img src="https://img.shields.io/badge/MCP-1.0-purple?style=flat-square" alt="MCP SDK"/>
+  </a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#api-reference">API</a> •
+  <a href="#docker-deployment">Docker</a> •
+  <a href="#troubleshooting">Troubleshooting</a>
+</p>
+
+---
+
+## Overview
+
+**MCP Banana Image** is a Model Context Protocol (MCP) server that brings AI-powered image generation capabilities to your favorite AI coding assistants. Built with Google's Gemini AI, it offers intelligent prompt enhancement, image editing, format conversion, and smart compression - all through a simple natural language interface.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **AI Image Generation** | Create stunning images from text prompts using Gemini 3 Pro Image Preview |
+| **Intelligent Prompt Enhancement** | Automatically optimizes your prompts using Gemini 2.0 Flash for better results |
+| **Image Editing** | Transform existing images with natural language instructions |
+| **Format Conversion** | Convert output to PNG, JPEG, WebP, or AVIF |
+| **Smart Compression** | Reduce file size with configurable quality presets |
+| **High Resolution** | Support for 2K and 4K image generation |
+| **Flexible Aspect Ratios** | 1:1, 16:9, 9:16, 21:9, and more |
+| **Character Consistency** | Maintain character appearance across generated images |
+| **Image Blending** | Seamlessly blend multiple visual elements |
+| **World Knowledge** | Use real-world knowledge for accurate context |
+| **Google Search Grounding** | Access real-time data for factually accurate generation |
+| **Dual Transport** | STDIO (default) and HTTP (Streamable HTTP Transport) |
+| **Docker Support** | Deploy as HTTP server with Docker |
+
+## Requirements
+
+- **Node.js** 20+
+- **Gemini API Key** from [Google AI Studio](https://aistudio.google.com/apikey)
+
+## Installation
+
+### Claude Code
+
+```bash
+claude mcp add mcp-banana-image \
+  --env GEMINI_API_KEY=your_api_key \
+  --env GEMINI_BASE_URL=https://generativelanguage.googleapis.com \
+  --env IMAGE_OUTPUT_DIR=/path/to/output \
+  --env SKIP_PROMPT_ENHANCEMENT=false \
+  -- npx -y mcp-banana-image
+```
+
+Add `--scope user` for global installation.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-banana-image": {
+      "command": "npx",
+      "args": ["-y", "mcp-banana-image"],
+      "env": {
+        "GEMINI_API_KEY": "your_api_key",
+        "GEMINI_BASE_URL": "https://generativelanguage.googleapis.com",
+        "IMAGE_OUTPUT_DIR": "/path/to/output",
+        "SKIP_PROMPT_ENHANCEMENT": "false"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.mcp-banana-image]
+command = "npx"
+args = ["-y", "mcp-banana-image"]
+
+[mcp_servers.mcp-banana-image.env]
+GEMINI_API_KEY = "your_api_key"
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com"
+IMAGE_OUTPUT_DIR = "/path/to/output"
+SKIP_PROMPT_ENHANCEMENT = "false"
+```
+
+## Usage
+
+### Basic Generation
+
+```
+"Generate a mountain landscape at sunset"
+```
+
+### Image Editing
+
+```
+"Make the sky more dramatic"
+(with inputImagePath: "/path/to/image.jpg")
+```
+
+### Format Conversion
+
+```
+"Generate a product photo"
+(with outputFormat: "webp", compressionPreset: "balanced")
+```
+
+### High Resolution
+
+```
+"Generate a detailed cityscape"
+(with imageSize: "4K", aspectRatio: "21:9")
+```
+
+### Character Consistency
+
+```
+"A warrior with a red cape and scar on the left cheek"
+(with maintainCharacterConsistency: true)
+```
+
+## API Reference
+
+### Tool: `generate_image`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | string | Yes | Text description for image generation |
+| `fileName` | string | No | Custom output filename |
+| `inputImagePath` | string | No | Source image path for editing |
+| `aspectRatio` | string | No | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
+| `imageSize` | string | No | `2K` or `4K` for high resolution |
+| `outputFormat` | string | No | `png`, `jpeg`, `webp`, `avif` |
+| `compressionPreset` | string | No | `lossless`, `high`, `balanced`, `maximum` |
+| `quality` | number | No | 1-100, overrides compressionPreset |
+| `stripMetadata` | boolean | No | Remove EXIF data (default: true) |
+| `blendImages` | boolean | No | Enable multi-image blending |
+| `maintainCharacterConsistency` | boolean | No | Keep character appearance consistent |
+| `useWorldKnowledge` | boolean | No | Use real-world knowledge for accuracy |
+| `useGoogleSearch` | boolean | No | Enable Google Search for current data |
+| `purpose` | string | No | Intended use (e.g., "social media post") |
+
+### Compression Presets
+
+| Preset | Description | Use Case |
+|--------|-------------|----------|
+| `lossless` | No quality loss | Archival, source files |
+| `high` | Minimal loss | Professional work |
+| `balanced` | Good quality/size ratio | General use |
+| `maximum` | Smallest file size | Web optimization |
+
+### Output Formats
+
+| Format | Description |
+|--------|-------------|
+| `png` | Lossless, supports transparency |
+| `jpeg` | Lossy, best for photos |
+| `webp` | Modern format, good compression |
+| `avif` | Best compression, limited support |
+
+## Environment Variables
+
+### Core Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GEMINI_API_KEY` | Yes | - | Google AI API key |
+| `GEMINI_BASE_URL` | No | - | Custom Gemini API endpoint URL |
+| `IMAGE_OUTPUT_DIR` | No | `./output` | Output directory for generated images |
+| `SKIP_PROMPT_ENHANCEMENT` | No | `false` | Disable automatic prompt optimization |
+
+### HTTP Transport Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
+| `MCP_API_KEY` | Yes (http) | - | API key for HTTP authentication |
+| `MCP_HTTP_PORT` | No | `3000` | HTTP server port |
+| `MCP_HTTP_HOST` | No | `0.0.0.0` | HTTP server bind address |
+| `MCP_CORS_ORIGIN` | No | `*` | CORS allowed origins |
+| `MCP_HTTP_TIMEOUT` | No | `300000` | HTTP request timeout in ms |
+
+## Docker Deployment
+
+### Build and Run
+
+```bash
+docker build -t mcp-banana-image .
+docker-compose up
+```
+
+### docker-compose.yml
+
+```yaml
+services:
+  mcp-banana-image:
+    build: .
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./output:/app/output
+    environment:
+      - GEMINI_API_KEY=${GEMINI_API_KEY}
+      - MCP_API_KEY=${MCP_API_KEY}
+      - MCP_TRANSPORT=http
+```
+
+### Health Check
+
+```bash
+curl http://localhost:3000/health
+```
+
+**Response:**
+
+```json
+{
+  "status": "ok",
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "sessions": 0
+}
+```
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph Client
+        A[AI Assistant]
+    end
+
+    subgraph MCP Server
+        B[Transport Layer]
+        C[MCP Handler]
+        D[Prompt Generator]
+        E[Gemini Client]
+        F[Image Processor]
+        G[File Manager]
+    end
+
+    subgraph External
+        H[Gemini 2.0 Flash]
+        I[Gemini 3 Pro Image]
+    end
+
+    A -->|STDIO/HTTP| B
+    B --> C
+    C --> D
+    D -->|Enhance Prompt| H
+    C --> E
+    E -->|Generate Image| I
+    I --> F
+    F -->|Convert & Compress| G
+    G -->|Save| J[(Output)]
+```
+
+## Troubleshooting
+
+### API key not found
+
+- Verify `GEMINI_API_KEY` is set correctly
+- Check key permissions at [Google AI Studio](https://aistudio.google.com/apikey)
+
+### Image not saved
+
+- Ensure `IMAGE_OUTPUT_DIR` is an absolute path
+- Check directory write permissions
+
+### Generation timeout
+
+- High resolution images take longer
+- Check network connectivity
+- Consider increasing `MCP_HTTP_TIMEOUT` for HTTP mode
+
+### Prompt blocked by safety filters
+
+- Rephrase your prompt to avoid potentially sensitive content
+- The AI may reject prompts that could generate inappropriate imagery
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Lint and format
+npm run check:all
+```
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  Made with ❤️ by <a href="https://bitbucket.org/trigidigital">Trigi Digital</a>
+</p>

package/dist/api/geminiClient.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Gemini API client for image generation
+ * Integrates with Google's Gemini AI API using the official SDK
+ * Supports automatic URL Context processing and feature parameters
+ */
+import type { Result } from '../types/result';
+import type { Config } from '../utils/config';
+import { GeminiAPIError, NetworkError } from '../utils/errors';
+/**
+ * Metadata for generated images
+ */
+export interface GeminiGenerationMetadata {
+    model: string;
+    prompt: string;
+    mimeType: string;
+    timestamp: Date;
+    inputImageProvided: boolean;
+    modelVersion?: string;
+    responseId?: string;
+}
+/**
+ * Parameters for Gemini API image generation
+ */
+export interface GeminiApiParams {
+    prompt: string;
+    inputImage?: string;
+    aspectRatio?: string;
+    imageSize?: string;
+    useGoogleSearch?: boolean;
+}
+/**
+ * Result of image generation
+ */
+export interface GeneratedImageResult {
+    imageData: Buffer;
+    metadata: GeminiGenerationMetadata;
+}
+/**
+ * Gemini API client interface
+ */
+export interface GeminiClient {
+    generateImage(params: GeminiApiParams): Promise<Result<GeneratedImageResult, GeminiAPIError | NetworkError>>;
+}
+/**
+ * Creates a new Gemini API client
+ * @param config Configuration containing API key and other settings
+ * @returns Result containing the client or an error
+ */
+export declare function createGeminiClient(config: Config): Result<GeminiClient, GeminiAPIError>;
+//# sourceMappingURL=geminiClient.d.ts.map

package/dist/api/geminiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geminiClient.d.ts","sourceRoot":"","sources":["../../src/api/geminiClient.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAE7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAkH9D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,IAAI,CAAA;IACf,kBAAkB,EAAE,OAAO,CAAA;IAE3B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,wBAAwB,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,aAAa,CACX,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC,CAAA;CACxE;AA2UD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,YAAY,EAAE,cAAc,CAAC,CAsBvF"}