Edit Image (Multi-Reference)

Instructions

Implementation Reference

• src/tools/edit-image.ts:67-129 (handler)

  The complete implementation of edit_image_multi tool including registration, schema definition, and handler logic. This function registers the tool with the MCP server and handles multi-reference image editing by processing a prompt and up to 14 base64-encoded images through the gemini-3-pro-image-preview model.

  export function registerMulti(server: McpServer, ai: GoogleGenAI): void {
    server.registerTool(
      'edit_image_multi',
      {
        title: 'Edit Image (Multi-Reference)',
        description: 'Edit or compose images using multiple reference images (up to 14). Uses gemini-3-pro-image-preview (Nano Banana Pro).',
        inputSchema: {
          prompt: z.string().min(1).describe('Description of the desired output'),
          images: z.array(z.object({
            data: z.string().min(1).describe('Base64-encoded image'),
            mimeType: z.enum(['image/png', 'image/jpeg', 'image/webp']).default('image/png'),
          })).min(1).max(14).describe('Array of reference images (1-14)'),
          aspectRatio: AspectRatio.default('1:1').describe('Aspect ratio of the output image'),
          imageSize: ImageSize.default('1K').describe('Output image resolution'),
        },
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          openWorldHint: true,
        },
      },
      async ({ prompt, images, aspectRatio, imageSize }) => {
        try {
          const parts = [
            { text: prompt },
            ...images.map((img: { mimeType: string; data: string }) => ({
              inlineData: { mimeType: img.mimeType, data: img.data },
            })),
          ];
  
          const response = await ai.models.generateContent({
            model: 'gemini-3-pro-image-preview',
            contents: parts,
            config: {
              responseModalities: ['TEXT', 'IMAGE'],
              imageConfig: { aspectRatio, imageSize },
            },
          });
  
          const result = extractImageFromResponse(response);
          if (!result) {
            return {
              content: [{ type: 'text' as const, text: 'No image was produced. Try a different prompt.' }],
              isError: true,
            };
          }
  
          if (!validateImageSize(result.data)) {
            return {
              content: [{ type: 'text' as const, text: 'Output image exceeds size limit. Try a smaller imageSize.' }],
              isError: true,
            };
          }
  
          return {
            content: [{ type: 'image' as const, data: result.data, mimeType: result.mimeType }],
          };
        } catch (error) {
          return formatToolError(error);
        }
      },
    );
  }

• src/index.ts:9-31 (registration)

  Tool registration in the main server file. Imports registerMulti as registerEditImageMulti and registers it with the MCP server instance.

  import { register as registerEditImage, registerMulti as registerEditImageMulti } from './tools/edit-image.js';
  
  const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
  if (!GEMINI_API_KEY) {
    console.error('GEMINI_API_KEY environment variable is required');
    process.exit(1);
  }
  
  const ai = createClient(GEMINI_API_KEY);
  
  const server = new McpServer(
    { name: 'gemini', version: '2.0.0' },
    { capabilities: { logging: {} } },
  );
  
  // Register all 7 tools
  registerGenerateText(server, ai);
  registerChat(server, ai);
  registerGenerateWithSearch(server, ai);
  registerCodeExecution(server, ai);
  registerGenerateImage(server, ai);
  registerEditImage(server, ai);
  registerEditImageMulti(server, ai);

• src/types.ts:18-24 (schema)

  Type definitions for schema validation used by edit_image_multi tool, defining allowed aspect ratios and image sizes.

  export const AspectRatio = z.enum([
    '1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9',
  ]);
  export type AspectRatio = z.infer<typeof AspectRatio>;
  
  export const ImageSize = z.enum(['1K', '2K', '4K']);
  export type ImageSize = z.infer<typeof ImageSize>;

• src/utils/image.ts:1-20 (helper)

  Helper utilities used by edit_image_multi handler: validateImageSize checks if base64 image size is within 2MB limit, extractImageFromResponse parses the Gemini API response to extract the generated image data.

  const MAX_IMAGE_SIZE = 2 * 1024 * 1024; // 2MB — conservative limit for MCP stdio transport
  
  export function validateImageSize(base64: string): boolean {
    const sizeInBytes = Math.ceil(base64.length * 3 / 4);
    return sizeInBytes <= MAX_IMAGE_SIZE;
  }
  
  export function extractImageFromResponse(response: any): { data: string; mimeType: string } | null {
    const parts = response?.candidates?.[0]?.content?.parts;
    if (!parts) return null;
    for (const part of parts) {
      if (part.inlineData) {
        return {
          data: part.inlineData.data,
          mimeType: part.inlineData.mimeType,
        };
      }
    }
    return null;
  }

• src/utils/errors.ts:1-7 (helper)

  Error formatting utility used by edit_image_multi handler to format errors into the expected MCP tool response structure.

  export function formatToolError(error: unknown) {
    const text = error instanceof Error ? error.message : String(error);
    return {
      content: [{ type: 'text' as const, text }],
      isError: true,
    };
  }