@mindstone-engineering/mcp-server-nano-banana 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Nano Banana authentication module.
+ *
+ * Simple API key management — stored via env var (GEMINI_API_KEY)
+ * or configured at runtime via the configure_nano_banana_api_key tool.
+ *
+ * Auth: Gemini API key as query parameter (?key=...) on all API requests (NOT header).
+ */
+/**
+ * Get the current API key.
+ */
+export declare function getApiKey(): string;
+/**
+ * Set the API key at runtime (from configure tool).
+ */
+export declare function setApiKey(key: string): void;
+/**
+ * Check if an API key is configured.
+ */
+export declare function hasApiKey(): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,29 @@
+/**
+ * Nano Banana authentication module.
+ *
+ * Simple API key management — stored via env var (GEMINI_API_KEY)
+ * or configured at runtime via the configure_nano_banana_api_key tool.
+ *
+ * Auth: Gemini API key as query parameter (?key=...) on all API requests (NOT header).
+ */
+/** Runtime API key — starts from env, can be updated via configure tool. */
+let apiKey = process.env.GEMINI_API_KEY ?? '';
+/**
+ * Get the current API key.
+ */
+export function getApiKey() {
+    return apiKey;
+}
+/**
+ * Set the API key at runtime (from configure tool).
+ */
+export function setApiKey(key) {
+    apiKey = key;
+}
+/**
+ * Check if an API key is configured.
+ */
+export function hasApiKey() {
+    return apiKey.trim().length > 0;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Nano Banana / Gemini API HTTP client.
+ *
+ * Centralises query-param auth injection, error handling, rate-limit
+ * messaging, and timeout handling for all Gemini API calls.
+ *
+ * Auth: ?key={GEMINI_API_KEY} query parameter (NOT header)
+ * Base URL: https://generativelanguage.googleapis.com/v1beta
+ */
+import { type GeminiResponse } from './types.js';
+/**
+ * Make an authenticated request to the Gemini API.
+ * The API key is injected as a query parameter.
+ * Returns the parsed GeminiResponse.
+ */
+export declare function geminiFetch(apiKey: string, modelPath: string, body: Record<string, unknown>, signal?: AbortSignal): Promise<GeminiResponse>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,73 @@
+/**
+ * Nano Banana / Gemini API HTTP client.
+ *
+ * Centralises query-param auth injection, error handling, rate-limit
+ * messaging, and timeout handling for all Gemini API calls.
+ *
+ * Auth: ?key={GEMINI_API_KEY} query parameter (NOT header)
+ * Base URL: https://generativelanguage.googleapis.com/v1beta
+ */
+import { NanoBananaError, REQUEST_TIMEOUT_MS, getErrorResolution, } from './types.js';
+const GEMINI_API_BASE = 'https://generativelanguage.googleapis.com/v1beta';
+/**
+ * Make an authenticated request to the Gemini API.
+ * The API key is injected as a query parameter.
+ * Returns the parsed GeminiResponse.
+ */
+export async function geminiFetch(apiKey, modelPath, body, signal) {
+    if (!apiKey || apiKey.trim().length === 0) {
+        throw new NanoBananaError('Gemini API key not configured', 'AUTH_REQUIRED', 'Configure your Gemini API key. Get one at https://aistudio.google.com/api-keys');
+    }
+    const url = `${GEMINI_API_BASE}/models/${modelPath}:generateContent?key=${apiKey}`;
+    // Log URL without key
+    console.error(`[NanoBanana API] POST ${GEMINI_API_BASE}/models/${modelPath}:generateContent`);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            signal: signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new NanoBananaError('Request to Gemini API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the Gemini API is available.');
+        }
+        throw error;
+    }
+    // Handle rate limiting
+    if (response.status === 429) {
+        throw new NanoBananaError('Rate limited. Please wait a moment before retrying.', 'RATE_LIMITED', getErrorResolution(429));
+    }
+    // Handle auth errors
+    if (response.status === 401 || response.status === 403) {
+        let detail = '';
+        try {
+            const errBody = await response.clone().json();
+            detail = errBody.error?.message || '';
+        }
+        catch { /* not JSON */ }
+        throw new NanoBananaError('Authentication failed', 'AUTH_FAILED', getErrorResolution(response.status, detail));
+    }
+    // Handle other HTTP errors
+    if (!response.ok) {
+        let detail = '';
+        try {
+            const errBody = await response.clone().json();
+            detail = errBody.error?.message || '';
+        }
+        catch { /* not JSON */ }
+        throw new NanoBananaError(`Gemini API error (HTTP ${response.status}): ${detail || response.statusText}`, `HTTP_${response.status}`, getErrorResolution(response.status, detail));
+    }
+    // Parse response
+    try {
+        return (await response.json());
+    }
+    catch {
+        throw new NanoBananaError('Failed to parse Gemini API response', 'PARSE_ERROR', 'The API returned an unparseable response. Try again.');
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Nano Banana MCP Server
+ *
+ * Provides Google Gemini image generation and editing via Model Context Protocol.
+ * Generate images from text, edit existing images with AI.
+ *
+ * Environment variables:
+ * - GEMINI_API_KEY: Gemini API key (required, get from https://aistudio.google.com/api-keys)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Nano Banana MCP Server
+ *
+ * Provides Google Gemini image generation and editing via Model Context Protocol.
+ * Generate images from text, edit existing images with AI.
+ *
+ * Environment variables:
+ * - GEMINI_API_KEY: Gemini API key (required, get from https://aistudio.google.com/api-keys)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('NanoBanana MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,13 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerGenerateTools, registerEditTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'nano-banana-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerGenerateTools(server);
+    registerEditTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { setApiKey } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { NanoBananaError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_nano_banana_api_key', {
+        title: 'Configure NanoBanana API Key',
+        description: 'Save your Gemini API key for NanoBanana image generation. Call this when the user provides their key. ' +
+            'WHERE TO GET A KEY: Go to https://aistudio.google.com/api-keys → Create new API key → Copy the key. ' +
+            'FREE TIER: Generous free usage for Gemini API. Supports image generation and editing.',
+        inputSchema: z.object({
+            api_key: z.string().min(1).describe('Gemini API key from https://aistudio.google.com/api-keys'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const key = args.api_key.trim();
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/nanobanana/configure', { apiKey: key });
+                if (result.success) {
+                    setApiKey(key);
+                    const message = result.warning
+                        ? `Gemini API key configured successfully. Note: ${result.warning}`
+                        : 'Gemini API key configured successfully! You can now use nano_banana_generate and nano_banana_edit to create and edit images.';
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new NanoBananaError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof NanoBananaError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new NanoBananaError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge — store in-memory
+        setApiKey(key);
+        return JSON.stringify({
+            ok: true,
+            message: 'Gemini API key configured successfully! You can now use nano_banana_generate and nano_banana_edit to create and edit images.',
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/edit.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerEditTools(server: McpServer): void;
+//# sourceMappingURL=edit.d.ts.map

package/dist/tools/edit.js

@@ -0,0 +1,197 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { z } from 'zod';
+import { getApiKey, hasApiKey } from '../auth.js';
+import { geminiFetch } from '../client.js';
+import { NanoBananaError, SUPPORTED_MODELS, DEFAULT_MODEL, SUPPORTED_ASPECT_RATIOS, SUPPORTED_IMAGE_EXTENSIONS, } from '../types.js';
+import { resolveSavePath } from './path-safety.js';
+const MODEL_DESCRIPTION = 'Model to use: "gemini-3.1-flash-image-preview" (Nano Banana 2, default — pro-quality at flash speed, 4K), ' +
+    '"gemini-3-pro-image-preview" (Nano Banana Pro — highest quality), or ' +
+    '"gemini-2.5-flash-image" (original Nano Banana — fast, legacy)';
+/**
+ * Expand ~ to home directory.
+ */
+function expandPath(filePath) {
+    return filePath.replace(/^~/, os.homedir());
+}
+/**
+ * Detect MIME type from file extension.
+ * Returns null for unsupported formats.
+ */
+function getMimeTypeFromPath(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return SUPPORTED_IMAGE_EXTENSIONS[ext] || null;
+}
+export function registerEditTools(server) {
+    server.registerTool('nano_banana_edit', {
+        title: 'Edit Image (Nano Banana)',
+        description: `Edit an existing image using Google Gemini's image editing capabilities.\n\n` +
+            `Use this when the user wants to modify, edit, or transform an existing image using AI.\n\n` +
+            `Provide a source image file path and edit instructions. The edited image will appear inline in the conversation.\n\n` +
+            `Examples of edit prompts:\n` +
+            `- "Remove the background and make it transparent"\n` +
+            `- "Change the color of the car to red"\n` +
+            `- "Add a sunset sky in the background"\n` +
+            `- "Make this photo look like a watercolor painting"\n` +
+            `- "Remove the person on the right side"`,
+        inputSchema: z.object({
+            source_image_path: z.string().min(1).describe('Path to the image file to edit (supports ~ for home directory)'),
+            prompt: z.string().min(1).describe('Instructions for how to edit the image'),
+            model: z.enum(SUPPORTED_MODELS).optional().describe(MODEL_DESCRIPTION),
+            aspect_ratio: z.enum(SUPPORTED_ASPECT_RATIOS).optional().describe('Aspect ratio for the edited image'),
+            save_path: z.string().optional().describe('Optional file path to save the edited image. IMPORTANT: Must be inside the workspace directory so the image can be displayed inline.'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async (input) => {
+        if (!hasApiKey()) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            ok: false,
+                            error: 'Gemini API key not configured',
+                            code: 'AUTH_REQUIRED',
+                            resolution: 'Configure your Gemini API key. Get one at https://aistudio.google.com/api-keys',
+                            next_step: {
+                                action: 'Ask the user for their Gemini API key, then call configure_nano_banana_api_key',
+                                tool_to_call: 'configure_nano_banana_api_key',
+                                tool_parameters: { api_key: '<user_provided_key>' },
+                                get_key_from: 'https://aistudio.google.com/api-keys',
+                            },
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const sourcePath = expandPath(input.source_image_path);
+        const model = input.model ?? DEFAULT_MODEL;
+        // Check file format before reading
+        const sourceMimeType = getMimeTypeFromPath(sourcePath);
+        if (!sourceMimeType) {
+            const ext = path.extname(sourcePath).toLowerCase() || '(no extension)';
+            return {
+                content: [{ type: 'text', text: `Unsupported image format: ${ext}. Supported formats: PNG, JPEG, WebP.` }],
+                isError: true,
+            };
+        }
+        // Read and encode source image
+        let imageBuffer;
+        try {
+            if (!fs.existsSync(sourcePath)) {
+                return {
+                    content: [{ type: 'text', text: `File not found: ${sourcePath}` }],
+                    isError: true,
+                };
+            }
+            imageBuffer = fs.readFileSync(sourcePath);
+            console.error(`[NanoBanana] Read source image: ${imageBuffer.length} bytes, type: ${sourceMimeType}`);
+        }
+        catch (readError) {
+            const errMsg = readError instanceof Error ? readError.message : String(readError);
+            return {
+                content: [{ type: 'text', text: `Failed to read image file: ${errMsg}` }],
+                isError: true,
+            };
+        }
+        const sourceBase64 = imageBuffer.toString('base64');
+        const generationConfig = { responseModalities: ['TEXT', 'IMAGE'] };
+        if (input.aspect_ratio) {
+            generationConfig.imageConfig = { aspectRatio: input.aspect_ratio };
+        }
+        const requestBody = {
+            contents: [{
+                    parts: [
+                        { text: `Edit this image: ${input.prompt}` },
+                        { inlineData: { mimeType: sourceMimeType, data: sourceBase64 } },
+                    ],
+                }],
+            generationConfig,
+        };
+        let data;
+        try {
+            data = await geminiFetch(getApiKey(), model, requestBody);
+        }
+        catch (error) {
+            if (error instanceof NanoBananaError) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ ok: false, error: error.message, code: error.code, resolution: error.resolution }) }],
+                    isError: true,
+                };
+            }
+            const errMsg = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: `Network error: ${errMsg}` }) }],
+                isError: true,
+            };
+        }
+        // Check for prompt blocks
+        const candidates = data.candidates;
+        if (!candidates || !candidates.length) {
+            const blockReason = data.promptFeedback?.blockReason;
+            if (blockReason) {
+                return {
+                    content: [{ type: 'text', text: `Prompt was blocked: ${blockReason}. Please try a different prompt.` }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [{ type: 'text', text: 'No edited image generated — API returned no results' }],
+                isError: true,
+            };
+        }
+        // Extract edited image from response
+        const parts = candidates[0]?.content?.parts || [];
+        let imageData = null;
+        let imageMimeType = 'image/png';
+        let textResponse = null;
+        for (const part of parts) {
+            if (part.inlineData?.data) {
+                imageData = part.inlineData.data;
+                imageMimeType = part.inlineData.mimeType || 'image/png';
+            }
+            else if (part.text) {
+                textResponse = part.text;
+            }
+        }
+        if (!imageData) {
+            const responseText = textResponse || 'No edited image was generated. The model may not support this type of edit.';
+            return {
+                content: [{ type: 'text', text: responseText }],
+                isError: true,
+            };
+        }
+        console.error('[NanoBanana] Image edited successfully');
+        // Optionally save to disk with path traversal protection
+        let savedPath = null;
+        if (input.save_path) {
+            const resolveResult = resolveSavePath(input.save_path, imageMimeType);
+            if (!resolveResult.ok) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ ok: false, error: resolveResult.error }) }],
+                    isError: true,
+                };
+            }
+            try {
+                fs.mkdirSync(path.dirname(resolveResult.path), { recursive: true });
+                fs.writeFileSync(resolveResult.path, Buffer.from(imageData, 'base64'));
+                savedPath = resolveResult.path;
+                console.error(`[NanoBanana] Saved edited image to: ${savedPath}`);
+            }
+            catch (saveError) {
+                const errMsg = saveError instanceof Error ? saveError.message : String(saveError);
+                console.error(`[NanoBanana] Failed to save: ${errMsg}`);
+            }
+        }
+        const textMessage = savedPath
+            ? `Image edited and saved to: ${savedPath}`
+            : 'Image edited successfully!';
+        return {
+            content: [
+                { type: 'text', text: textMessage },
+                { type: 'image', data: imageData, mimeType: imageMimeType },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=edit.js.map

package/dist/tools/generate.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGenerateTools(server: McpServer): void;
+//# sourceMappingURL=generate.d.ts.map

package/dist/tools/generate.js

@@ -0,0 +1,144 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { z } from 'zod';
+import { getApiKey, hasApiKey } from '../auth.js';
+import { geminiFetch } from '../client.js';
+import { NanoBananaError, SUPPORTED_MODELS, DEFAULT_MODEL, SUPPORTED_ASPECT_RATIOS, } from '../types.js';
+import { resolveSavePath } from './path-safety.js';
+const MODEL_DESCRIPTION = 'Model to use: "gemini-3.1-flash-image-preview" (Nano Banana 2, default — pro-quality at flash speed, 4K), ' +
+    '"gemini-3-pro-image-preview" (Nano Banana Pro — highest quality), or ' +
+    '"gemini-2.5-flash-image" (original Nano Banana — fast, legacy)';
+export function registerGenerateTools(server) {
+    server.registerTool('nano_banana_generate', {
+        title: 'Generate Image (Nano Banana)',
+        description: `Generate images from text descriptions using Google Gemini's image generation capabilities.\n\n` +
+            `Use this when the user asks you to create, generate, draw, or design an image, illustration, or visual content using Gemini/Google AI.\n\n` +
+            `The generated image will appear inline in the conversation. You can also save it to disk by providing save_path.\n\n` +
+            `Tips for good prompts:\n` +
+            `- Be specific about style, colors, composition, and mood\n` +
+            `- Mention artistic styles if relevant (e.g., "watercolor", "minimalist", "photorealistic")\n` +
+            `- Include details about lighting, perspective, and background`,
+        inputSchema: z.object({
+            prompt: z.string().min(1).describe('Text description of the image to generate'),
+            model: z.enum(SUPPORTED_MODELS).optional().describe(MODEL_DESCRIPTION),
+            aspect_ratio: z.enum(SUPPORTED_ASPECT_RATIOS).optional().describe('Aspect ratio for the generated image (default: 1:1)'),
+            save_path: z.string().optional().describe('Optional file path to save the image. IMPORTANT: Must be inside the workspace directory so the image can be displayed inline.'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async (input) => {
+        if (!hasApiKey()) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            ok: false,
+                            error: 'Gemini API key not configured',
+                            code: 'AUTH_REQUIRED',
+                            resolution: 'Configure your Gemini API key. Get one at https://aistudio.google.com/api-keys',
+                            next_step: {
+                                action: 'Ask the user for their Gemini API key, then call configure_nano_banana_api_key',
+                                tool_to_call: 'configure_nano_banana_api_key',
+                                tool_parameters: { api_key: '<user_provided_key>' },
+                                get_key_from: 'https://aistudio.google.com/api-keys',
+                            },
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const model = input.model ?? DEFAULT_MODEL;
+        const generationConfig = { responseModalities: ['TEXT', 'IMAGE'] };
+        if (input.aspect_ratio) {
+            generationConfig.imageConfig = { aspectRatio: input.aspect_ratio };
+        }
+        const requestBody = {
+            contents: [{ parts: [{ text: input.prompt }] }],
+            generationConfig,
+        };
+        let data;
+        try {
+            data = await geminiFetch(getApiKey(), model, requestBody);
+        }
+        catch (error) {
+            if (error instanceof NanoBananaError) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ ok: false, error: error.message, code: error.code, resolution: error.resolution }) }],
+                    isError: true,
+                };
+            }
+            const errMsg = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: `Network error: ${errMsg}` }) }],
+                isError: true,
+            };
+        }
+        // Check for prompt blocks
+        const candidates = data.candidates;
+        if (!candidates || !candidates.length) {
+            const blockReason = data.promptFeedback?.blockReason;
+            if (blockReason) {
+                return {
+                    content: [{ type: 'text', text: `Prompt was blocked: ${blockReason}. Please try a different prompt.` }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [{ type: 'text', text: 'No image generated — API returned no results' }],
+                isError: true,
+            };
+        }
+        // Extract image and text from response
+        const parts = candidates[0]?.content?.parts || [];
+        let imageData = null;
+        let imageMimeType = 'image/png';
+        let textResponse = null;
+        for (const part of parts) {
+            if (part.inlineData?.data) {
+                imageData = part.inlineData.data;
+                imageMimeType = part.inlineData.mimeType || 'image/png';
+            }
+            else if (part.text) {
+                textResponse = part.text;
+            }
+        }
+        if (!imageData) {
+            const responseText = textResponse || 'No image was generated. The model may not support image generation for this prompt.';
+            return {
+                content: [{ type: 'text', text: responseText }],
+                isError: true,
+            };
+        }
+        console.error('[NanoBanana] Image generated successfully');
+        // Optionally save to disk with path traversal protection
+        let savedPath = null;
+        if (input.save_path) {
+            const resolveResult = resolveSavePath(input.save_path, imageMimeType);
+            if (!resolveResult.ok) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ ok: false, error: resolveResult.error }) }],
+                    isError: true,
+                };
+            }
+            try {
+                fs.mkdirSync(path.dirname(resolveResult.path), { recursive: true });
+                fs.writeFileSync(resolveResult.path, Buffer.from(imageData, 'base64'));
+                savedPath = resolveResult.path;
+                console.error(`[NanoBanana] Saved to: ${savedPath}`);
+            }
+            catch (saveError) {
+                const errMsg = saveError instanceof Error ? saveError.message : String(saveError);
+                console.error(`[NanoBanana] Failed to save: ${errMsg}`);
+            }
+        }
+        const textMessage = savedPath
+            ? `Image generated and saved to: ${savedPath}`
+            : 'Image generated successfully!';
+        return {
+            content: [
+                { type: 'text', text: textMessage },
+                { type: 'image', data: imageData, mimeType: imageMimeType },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=generate.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { registerConfigureTools } from './configure.js';
+export { registerGenerateTools } from './generate.js';
+export { registerEditTools } from './edit.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export { registerConfigureTools } from './configure.js';
+export { registerGenerateTools } from './generate.js';
+export { registerEditTools } from './edit.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/path-safety.d.ts

@@ -0,0 +1,28 @@
+export type ResolveResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Derive the canonical workspace root directory.
+ *
+ * Priority: REBEL_WORKSPACE_PATH env var > process.cwd()
+ * The result is always resolved to an absolute path.
+ */
+export declare function getWorkspaceRoot(): string;
+/**
+ * Safely resolve a user-provided save_path.
+ *
+ * Security rules:
+ * - Rejects paths containing `..` segments (path traversal)
+ * - Rejects absolute paths outside the workspace root
+ * - Relative paths are resolved against the workspace root
+ * - Tilde expansion (~) is NOT allowed — it would escape the workspace boundary
+ * - Final path (after extension append) must still be within workspace root
+ *
+ * Adds appropriate file extension if missing.
+ */
+export declare function resolveSavePath(savePath: string, mimeType: string): ResolveResult;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/tools/path-safety.js

@@ -0,0 +1,78 @@
+import * as path from 'path';
+/**
+ * MIME type to file extension mapping.
+ */
+const MIME_TO_EXT = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/webp': '.webp',
+};
+/**
+ * Derive the canonical workspace root directory.
+ *
+ * Priority: REBEL_WORKSPACE_PATH env var > process.cwd()
+ * The result is always resolved to an absolute path.
+ */
+export function getWorkspaceRoot() {
+    const envRoot = process.env.REBEL_WORKSPACE_PATH;
+    if (envRoot && envRoot.trim()) {
+        return path.resolve(envRoot.trim());
+    }
+    return path.resolve(process.cwd());
+}
+/**
+ * Safely resolve a user-provided save_path.
+ *
+ * Security rules:
+ * - Rejects paths containing `..` segments (path traversal)
+ * - Rejects absolute paths outside the workspace root
+ * - Relative paths are resolved against the workspace root
+ * - Tilde expansion (~) is NOT allowed — it would escape the workspace boundary
+ * - Final path (after extension append) must still be within workspace root
+ *
+ * Adds appropriate file extension if missing.
+ */
+export function resolveSavePath(savePath, mimeType) {
+    const workspaceRoot = getWorkspaceRoot();
+    // Reject explicit path traversal via '..' segments
+    // Normalise path separators so we catch both `/` and `\` on any OS
+    const normalized = savePath.replace(/\\/g, '/');
+    // Check for '..' segments in the raw input
+    const segments = normalized.split('/');
+    if (segments.some((s) => s === '..')) {
+        return {
+            ok: false,
+            error: 'Path traversal is not allowed: save_path must not contain ".." segments.',
+        };
+    }
+    // Reject tilde paths — they resolve to the home directory, which is outside the workspace
+    if (savePath.startsWith('~')) {
+        return {
+            ok: false,
+            error: `Tilde paths are not allowed: save_path must be within the workspace root (${workspaceRoot}). Use a relative path instead.`,
+        };
+    }
+    let expanded;
+    if (path.isAbsolute(savePath)) {
+        expanded = path.resolve(savePath);
+    }
+    else {
+        // Relative — resolve against workspace root
+        expanded = path.resolve(workspaceRoot, savePath);
+    }
+    // Add file extension if missing
+    const defaultExt = MIME_TO_EXT[mimeType] || '.png';
+    const finalPath = expanded.match(/\.(png|jpg|jpeg|webp)$/i)
+        ? expanded
+        : `${expanded}${defaultExt}`;
+    // Validate the FINAL path (after extension append) is within workspace root
+    const canonicalFinal = path.resolve(finalPath);
+    if (!canonicalFinal.startsWith(workspaceRoot + path.sep) && canonicalFinal !== workspaceRoot) {
+        return {
+            ok: false,
+            error: `Path must be within the workspace root (${workspaceRoot}). Got: ${savePath}`,
+        };
+    }
+    return { ok: true, path: canonicalFinal };
+}
+//# sourceMappingURL=path-safety.js.map

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class NanoBananaError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+export declare const SUPPORTED_MODELS: readonly ["gemini-3.1-flash-image-preview", "gemini-3-pro-image-preview", "gemini-2.5-flash-image"];
+export type SupportedModel = (typeof SUPPORTED_MODELS)[number];
+export declare const DEFAULT_MODEL: SupportedModel;
+export declare const SUPPORTED_ASPECT_RATIOS: readonly ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"];
+export type SupportedAspectRatio = (typeof SUPPORTED_ASPECT_RATIOS)[number];
+export interface GeminiApiErrorData {
+    error?: {
+        message?: string;
+    };
+}
+export interface GeminiInlineData {
+    data: string;
+    mimeType?: string;
+}
+export interface GeminiPart {
+    inlineData?: GeminiInlineData;
+    text?: string;
+}
+export interface GeminiCandidate {
+    content?: {
+        parts?: GeminiPart[];
+    };
+}
+export interface GeminiResponse {
+    candidates?: GeminiCandidate[];
+    promptFeedback?: {
+        blockReason?: string;
+    };
+}
+export interface ImageConfig {
+    aspectRatio: string;
+}
+export interface GenerationConfig {
+    responseModalities: string[];
+    imageConfig?: ImageConfig;
+}
+export declare const SUPPORTED_IMAGE_EXTENSIONS: Record<string, string>;
+/**
+ * Resolve an error status code to an actionable resolution string.
+ */
+export declare function getErrorResolution(status: number, detail?: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,46 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export class NanoBananaError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'NanoBananaError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Gemini API types
+// ---------------------------------------------------------------------------
+export const SUPPORTED_MODELS = [
+    'gemini-3.1-flash-image-preview',
+    'gemini-3-pro-image-preview',
+    'gemini-2.5-flash-image',
+];
+export const DEFAULT_MODEL = 'gemini-3.1-flash-image-preview';
+export const SUPPORTED_ASPECT_RATIOS = [
+    '1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9',
+];
+export const SUPPORTED_IMAGE_EXTENSIONS = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+};
+/**
+ * Resolve an error status code to an actionable resolution string.
+ */
+export function getErrorResolution(status, detail) {
+    const msg = (detail || '').toLowerCase();
+    if (status === 401 || status === 403 || msg.includes('invalid') || msg.includes('unauthorized')) {
+        return 'Invalid Gemini API key. Check your key at https://aistudio.google.com/api-keys';
+    }
+    if (status === 429) {
+        return 'Rate limit exceeded. Wait a moment and try again.';
+    }
+    if (msg.includes('safety') || msg.includes('blocked')) {
+        return 'Content was blocked by safety filters. Try a different prompt.';
+    }
+    return 'Please try again. If the issue persists, check your API key at https://aistudio.google.com/api-keys';
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On NanoBananaError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { NanoBananaError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On NanoBananaError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof NanoBananaError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mindstone-engineering/mcp-server-nano-banana",
+  "version": "0.1.0",
+  "description": "Nano Banana MCP server — Google Gemini image generation and editing via Model Context Protocol",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-nano-banana": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/nano-banana"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/nano-banana",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}