@rlabs-inc/gemini-mcp 0.5.0

package/dist/tools/image-edit.js

@@ -0,0 +1,291 @@
+/**
+ * Image Editing Tool - Multi-turn conversational image editing with Nano Banana Pro
+ *
+ * This tool enables iterative image refinement through conversation.
+ * Uses Gemini 3's chat sessions to maintain context and thought signatures.
+ *
+ * Workflow:
+ * 1. Start an edit session with an initial image generation
+ * 2. Continue refining with follow-up prompts ("make it warmer", "add more clouds")
+ * 3. Each response returns the updated image
+ */
+import { z } from 'zod';
+import { GoogleGenAI, Modality } from '@google/genai';
+import { logger } from '../utils/logger.js';
+import * as fs from 'fs';
+import * as path from 'path';
+// Store active image editing sessions
+// The SDK handles thought signatures automatically when using chat sessions
+const activeEditSessions = new Map();
+// Get output directory
+function getOutputDir() {
+    return (process.env.GEMINI_OUTPUT_DIR || path.join(process.cwd(), 'gemini-output'));
+}
+// Save image to disk
+function saveImage(base64, mimeType) {
+    const outputDir = getOutputDir();
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+    const timestamp = Date.now();
+    const extension = mimeType.split('/')[1] || 'png';
+    const filename = `edit-${timestamp}.${extension}`;
+    const filePath = path.join(outputDir, filename);
+    const buffer = Buffer.from(base64, 'base64');
+    fs.writeFileSync(filePath, buffer);
+    return filePath;
+}
+/**
+ * Register image editing tools with the MCP server
+ */
+export function registerImageEditTool(server) {
+    // Start a new image editing session
+    server.tool('gemini-start-image-edit', {
+        prompt: z
+            .string()
+            .describe('Initial prompt to generate the base image to edit'),
+        aspectRatio: z
+            .enum([
+            '1:1',
+            '2:3',
+            '3:2',
+            '3:4',
+            '4:3',
+            '4:5',
+            '5:4',
+            '9:16',
+            '16:9',
+            '21:9',
+        ])
+            .default('1:1')
+            .describe('Aspect ratio for the image'),
+        imageSize: z
+            .enum(['1K', '2K', '4K'])
+            .default('2K')
+            .describe('Resolution: 1K (fast), 2K (balanced), 4K (highest quality)'),
+        useGoogleSearch: z
+            .boolean()
+            .default(false)
+            .describe('Ground the image in real-world info via Google Search'),
+    }, async ({ prompt, aspectRatio, imageSize, useGoogleSearch }) => {
+        logger.info(`Starting image edit session: ${prompt.substring(0, 50)}...`);
+        try {
+            const apiKey = process.env.GEMINI_API_KEY;
+            if (!apiKey) {
+                throw new Error('GEMINI_API_KEY not set');
+            }
+            const genAI = new GoogleGenAI({ apiKey });
+            const imageModel = process.env.GEMINI_IMAGE_MODEL || 'gemini-3-pro-image-preview';
+            // Create a chat session for multi-turn editing
+            // The SDK handles thought signatures automatically in chat mode
+            const chatConfig = {
+                responseModalities: [Modality.TEXT, Modality.IMAGE],
+                imageConfig: {
+                    aspectRatio,
+                    imageSize,
+                },
+            };
+            if (useGoogleSearch) {
+                chatConfig.tools = [{ googleSearch: {} }];
+            }
+            const chat = genAI.chats.create({
+                model: imageModel,
+                config: chatConfig,
+            });
+            // Send the initial prompt
+            const response = await chat.sendMessage({ message: prompt });
+            // Extract image from response
+            const parts = response.candidates?.[0]?.content?.parts;
+            if (!parts) {
+                throw new Error('No parts in response');
+            }
+            let imageData;
+            let mimeType = 'image/png';
+            let description;
+            for (const part of parts) {
+                if (part.inlineData) {
+                    const inlineData = part.inlineData;
+                    imageData = inlineData.data;
+                    mimeType = inlineData.mimeType || 'image/png';
+                }
+                else if (part.text) {
+                    description = part.text;
+                }
+            }
+            if (!imageData) {
+                throw new Error('No image data in response');
+            }
+            // Generate session ID and store the chat
+            const sessionId = `edit-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+            activeEditSessions.set(sessionId, {
+                chat,
+                lastImageBase64: imageData,
+                lastImageMimeType: mimeType,
+            });
+            // Save to disk
+            const filePath = saveImage(imageData, mimeType);
+            logger.info(`Image edit session started: ${sessionId}`);
+            return {
+                content: [
+                    {
+                        type: 'image',
+                        data: imageData,
+                        mimeType,
+                    },
+                    {
+                        type: 'text',
+                        text: `Image edit session started!\n\nSession ID: ${sessionId}\nSettings: ${imageSize}, ${aspectRatio}${useGoogleSearch ? ', with Google Search' : ''}\nSaved to: ${filePath}\n\nUse gemini-continue-image-edit with this session ID to make changes.${description ? `\n\nGemini's description: ${description}` : ''}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`Error starting image edit session: ${errorMessage}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error starting image edit session: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Continue editing in an existing session
+    server.tool('gemini-continue-image-edit', {
+        sessionId: z.string().describe('The session ID from gemini-start-image-edit'),
+        prompt: z
+            .string()
+            .describe('Edit instruction (e.g., "make it warmer", "add mountains in the background", "change to night time")'),
+    }, async ({ sessionId, prompt }) => {
+        logger.info(`Continuing image edit: ${prompt.substring(0, 50)}...`);
+        try {
+            const session = activeEditSessions.get(sessionId);
+            if (!session) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Session not found: ${sessionId}\n\nActive sessions may have expired. Start a new session with gemini-start-image-edit.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Send the edit instruction
+            const chat = session.chat;
+            const response = await chat.sendMessage({ message: prompt });
+            // Extract image from response
+            const parts = response.candidates?.[0]?.content?.parts;
+            if (!parts) {
+                throw new Error('No parts in response');
+            }
+            let imageData;
+            let mimeType = 'image/png';
+            let description;
+            for (const part of parts) {
+                if (part.inlineData) {
+                    imageData = part.inlineData.data;
+                    mimeType = part.inlineData.mimeType || 'image/png';
+                }
+                else if (part.text) {
+                    description = part.text;
+                }
+            }
+            if (!imageData) {
+                // Sometimes the model responds with just text (explanation)
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: description || 'No image generated. Try a different edit instruction.',
+                        },
+                    ],
+                };
+            }
+            // Update session with new image
+            session.lastImageBase64 = imageData;
+            session.lastImageMimeType = mimeType;
+            // Save to disk
+            const filePath = saveImage(imageData, mimeType);
+            logger.info(`Image edit continued successfully`);
+            return {
+                content: [
+                    {
+                        type: 'image',
+                        data: imageData,
+                        mimeType,
+                    },
+                    {
+                        type: 'text',
+                        text: `Image updated!\n\nSession ID: ${sessionId}\nSaved to: ${filePath}\n\nContinue editing with more instructions or start a new session.${description ? `\n\nGemini's description: ${description}` : ''}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`Error continuing image edit: ${errorMessage}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error continuing image edit: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // End/close an editing session
+    server.tool('gemini-end-image-edit', {
+        sessionId: z.string().describe('The session ID to close'),
+    }, async ({ sessionId }) => {
+        const session = activeEditSessions.get(sessionId);
+        if (!session) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Session not found or already closed: ${sessionId}`,
+                    },
+                ],
+            };
+        }
+        // Remove the session
+        activeEditSessions.delete(sessionId);
+        logger.info(`Image edit session closed: ${sessionId}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Session ${sessionId} closed successfully.`,
+                },
+            ],
+        };
+    });
+    // List active editing sessions
+    server.tool('gemini-list-image-sessions', {}, async () => {
+        const sessions = Array.from(activeEditSessions.keys());
+        if (sessions.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No active image editing sessions.\n\nStart one with gemini-start-image-edit.',
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Active image editing sessions:\n\n${sessions.map((id) => `• ${id}`).join('\n')}\n\nUse gemini-continue-image-edit with a session ID to continue editing.`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/image-gen.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Image Generation Tool - Generate images using Gemini's Nano Banana Pro model
+ *
+ * This tool generates actual images from text descriptions and returns them
+ * both as base64 (for Claude to view) and saves them to disk (for user access).
+ *
+ * Nano Banana Pro Features:
+ * - Up to 4K resolution
+ * - 10 aspect ratios
+ * - Google Search grounding for real-world accuracy
+ * - High-fidelity text rendering
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Register image generation tools with the MCP server
+ */
+export declare function registerImageGenTool(server: McpServer): void;

package/dist/tools/image-gen.js

@@ -0,0 +1,148 @@
+/**
+ * Image Generation Tool - Generate images using Gemini's Nano Banana Pro model
+ *
+ * This tool generates actual images from text descriptions and returns them
+ * both as base64 (for Claude to view) and saves them to disk (for user access).
+ *
+ * Nano Banana Pro Features:
+ * - Up to 4K resolution
+ * - 10 aspect ratios
+ * - Google Search grounding for real-world accuracy
+ * - High-fidelity text rendering
+ */
+import { z } from 'zod';
+import { generateImage, getOutputDir, } from '../gemini-client.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Register image generation tools with the MCP server
+ */
+export function registerImageGenTool(server) {
+    // Image generation tool with full Nano Banana Pro capabilities
+    server.tool('gemini-generate-image', {
+        prompt: z.string().describe('Description of the image to generate'),
+        style: z
+            .string()
+            .optional()
+            .describe('Art style (e.g., "photorealistic", "watercolor", "anime", "oil painting", "cyberpunk")'),
+        aspectRatio: z
+            .enum([
+            '1:1',
+            '2:3',
+            '3:2',
+            '3:4',
+            '4:3',
+            '4:5',
+            '5:4',
+            '9:16',
+            '16:9',
+            '21:9',
+        ])
+            .default('1:1')
+            .describe('Aspect ratio: 1:1 (square), 16:9 (widescreen), 9:16 (portrait/mobile), 21:9 (ultrawide), etc.'),
+        imageSize: z
+            .enum(['1K', '2K', '4K'])
+            .default('2K')
+            .describe('Resolution: 1K (fast), 2K (balanced, default), 4K (highest quality)'),
+        useGoogleSearch: z
+            .boolean()
+            .default(false)
+            .describe('Ground the image in real-world info via Google Search (useful for current events, real places, etc.)'),
+    }, async ({ prompt, style, aspectRatio, imageSize, useGoogleSearch }) => {
+        logger.info(`Generating ${imageSize} image: ${prompt.substring(0, 50)}...`);
+        try {
+            const result = await generateImage(prompt, {
+                aspectRatio: aspectRatio,
+                imageSize: imageSize,
+                style,
+                saveToFile: true,
+                useGoogleSearch,
+            });
+            // Return the image in MCP format - Claude will be able to SEE this!
+            const content = [
+                {
+                    type: 'image',
+                    data: result.base64,
+                    mimeType: result.mimeType,
+                },
+                {
+                    type: 'text',
+                    text: `Image generated successfully!\n\nSettings: ${imageSize}, ${aspectRatio}${useGoogleSearch ? ', with Google Search grounding' : ''}\nSaved to: ${result.filePath}\nOutput directory: ${getOutputDir()}${result.description ? `\n\nGemini's description: ${result.description}` : ''}`,
+                },
+            ];
+            return { content };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`Error generating image: ${errorMessage}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error generating image: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Legacy image prompt tool (for compatibility) - generates text prompts for other tools
+    server.tool('gemini-image-prompt', {
+        description: z
+            .string()
+            .describe('Description of the image to generate a prompt for'),
+        style: z.string().optional().describe('The artistic style for the image'),
+        mood: z
+            .string()
+            .optional()
+            .describe('The mood or atmosphere of the image'),
+        details: z
+            .string()
+            .optional()
+            .describe('Additional details to include'),
+    }, async ({ description, style, mood, details }) => {
+        logger.info(`Generating image prompt for: ${description}`);
+        try {
+            // Import the text generation function
+            const { generateWithGeminiPro } = await import('../gemini-client.js');
+            const prompt = `
+You are an expert at creating detailed text-to-image prompts for generative AI art tools.
+Based on the following description, create a highly detailed, structured prompt that would produce the best possible image.
+
+Description: ${description}
+${style ? `Style: ${style}` : ''}
+${mood ? `Mood: ${mood}` : ''}
+${details ? `Additional details: ${details}` : ''}
+
+Format your response as follows:
+1. A refined one-paragraph image prompt that's highly detailed and descriptive
+2. Key elements that should be emphasized
+3. Technical suggestions (like camera angle, lighting, etc.)
+4. Style references that would work well
+
+Use detail-rich, vivid language that generative AI image models would respond well to.
+`;
+            const response = await generateWithGeminiPro(prompt);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: response,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`Error generating image prompt: ${errorMessage}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/query.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Query Tool - Send direct queries to Gemini models
+ *
+ * This tool allows sending prompts directly to Gemini and receiving responses.
+ * Supports Gemini 3's thinking levels for controlling reasoning depth.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Register query tools with the MCP server
+ */
+export declare function registerQueryTool(server: McpServer): void;

package/dist/tools/query.js

@@ -0,0 +1,63 @@
+/**
+ * Query Tool - Send direct queries to Gemini models
+ *
+ * This tool allows sending prompts directly to Gemini and receiving responses.
+ * Supports Gemini 3's thinking levels for controlling reasoning depth.
+ */
+import { z } from 'zod';
+import { generateWithGeminiPro, generateWithGeminiFlash, } from '../gemini-client.js';
+/**
+ * Register query tools with the MCP server
+ */
+export function registerQueryTool(server) {
+    // Standard query tool using Pro model with thinking level support
+    server.tool('gemini-query', {
+        prompt: z.string().describe('The prompt to send to Gemini'),
+        model: z
+            .enum(['pro', 'flash'])
+            .default('pro')
+            .describe('The Gemini model to use (pro or flash)'),
+        thinkingLevel: z
+            .enum(['minimal', 'low', 'medium', 'high'])
+            .optional()
+            .describe('Reasoning depth: minimal/low for fast responses, medium/high for complex tasks. ' +
+            'Pro supports low/high only. Flash supports all levels. Default is high.'),
+    }, async ({ prompt, model, thinkingLevel }) => {
+        console.log(`Querying Gemini ${model} model (thinking: ${thinkingLevel || 'default'}) with prompt: ${prompt.substring(0, 100)}...`);
+        try {
+            const options = thinkingLevel
+                ? { thinkingLevel: thinkingLevel }
+                : {};
+            const response = model === 'pro'
+                ? await generateWithGeminiPro(prompt, options)
+                : await generateWithGeminiFlash(prompt, options);
+            // Check for empty response to avoid potential MCP errors
+            if (!response || response.trim() === "") {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Error: Received empty response from Gemini API"
+                        }],
+                    isError: true
+                };
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: response
+                    }]
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            console.error(`Error querying Gemini: ${errorMessage}`);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error: ${errorMessage}`
+                    }],
+                isError: true
+            };
+        }
+    });
+}

package/dist/tools/search.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Google Search Grounding Tool - Real-time web information with citations
+ *
+ * This tool connects Gemini to Google Search for:
+ * - Accurate answers grounded in real-world information
+ * - Access to recent events and current topics
+ * - Verifiable sources with citations
+ *
+ * Returns responses with inline citations linked to source URLs.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Register Google Search grounding tools with the MCP server
+ */
+export declare function registerSearchTool(server: McpServer): void;

package/dist/tools/search.js

@@ -0,0 +1,128 @@
+/**
+ * Google Search Grounding Tool - Real-time web information with citations
+ *
+ * This tool connects Gemini to Google Search for:
+ * - Accurate answers grounded in real-world information
+ * - Access to recent events and current topics
+ * - Verifiable sources with citations
+ *
+ * Returns responses with inline citations linked to source URLs.
+ */
+import { z } from 'zod';
+import { GoogleGenAI } from '@google/genai';
+import { logger } from '../utils/logger.js';
+/**
+ * Add inline citations to text based on grounding metadata
+ */
+function addCitations(text, supports, chunks) {
+    if (!supports || !chunks || supports.length === 0) {
+        return text;
+    }
+    // Sort supports by endIndex in descending order to avoid shifting issues
+    const sortedSupports = [...supports].sort((a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0));
+    let result = text;
+    for (const support of sortedSupports) {
+        const endIndex = support.segment?.endIndex;
+        if (endIndex === undefined || !support.groundingChunkIndices?.length) {
+            continue;
+        }
+        const citationLinks = support.groundingChunkIndices
+            .map((i) => {
+            const uri = chunks[i]?.web?.uri;
+            const title = chunks[i]?.web?.title;
+            if (uri) {
+                return `[${title || i + 1}](${uri})`;
+            }
+            return null;
+        })
+            .filter(Boolean);
+        if (citationLinks.length > 0) {
+            const citationString = ' ' + citationLinks.join(', ');
+            result = result.slice(0, endIndex) + citationString + result.slice(endIndex);
+        }
+    }
+    return result;
+}
+/**
+ * Register Google Search grounding tools with the MCP server
+ */
+export function registerSearchTool(server) {
+    server.tool('gemini-search', {
+        query: z
+            .string()
+            .describe('The question or topic to search for. Gemini will use Google Search to find current information.'),
+        returnCitations: z
+            .boolean()
+            .default(true)
+            .describe('Include inline citations with source URLs'),
+    }, async ({ query, returnCitations }) => {
+        logger.info(`Google Search query: ${query.substring(0, 50)}...`);
+        try {
+            const apiKey = process.env.GEMINI_API_KEY;
+            if (!apiKey) {
+                throw new Error('GEMINI_API_KEY not set');
+            }
+            const genAI = new GoogleGenAI({ apiKey });
+            const model = process.env.GEMINI_PRO_MODEL || 'gemini-3-pro-preview';
+            // Execute with Google Search tool enabled
+            const response = await genAI.models.generateContent({
+                model,
+                contents: query,
+                config: {
+                    tools: [{ googleSearch: {} }],
+                },
+            });
+            const candidate = response.candidates?.[0];
+            if (!candidate) {
+                throw new Error('No response from search');
+            }
+            let responseText = response.text || '';
+            const groundingMetadata = candidate.groundingMetadata;
+            // Build response with citations if requested
+            if (returnCitations && groundingMetadata) {
+                const supports = groundingMetadata.groundingSupports || [];
+                const chunks = groundingMetadata.groundingChunks || [];
+                if (supports.length > 0 && chunks.length > 0) {
+                    responseText = addCitations(responseText, supports, chunks);
+                }
+                // Add sources section at the end
+                if (chunks.length > 0) {
+                    responseText += '\n\n---\n**Sources:**\n';
+                    const seenUrls = new Set();
+                    for (const chunk of chunks) {
+                        if (chunk.web?.uri && !seenUrls.has(chunk.web.uri)) {
+                            seenUrls.add(chunk.web.uri);
+                            responseText += `- [${chunk.web.title || 'Source'}](${chunk.web.uri})\n`;
+                        }
+                    }
+                }
+                // Add search queries used (for transparency)
+                if (groundingMetadata.webSearchQueries?.length) {
+                    responseText += `\n*Searches performed: ${groundingMetadata.webSearchQueries.join(', ')}*`;
+                }
+            }
+            logger.info('Google Search completed successfully');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: responseText,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`Error in Google Search: ${errorMessage}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error performing search: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}