NanoBanana MCP

Instructions

Implementation Reference

• src/index.ts:735-895 (handler)

  The handler for the gemini_edit_image tool, which processes the input arguments, validates the image paths (including history), prepares the parts for the Gemini API, and calls the API to generate the edited image.

        case "gemini_edit_image": {
          const {
            image_path,
            edit_prompt,
            aspect_ratio,
            output_path,
            conversation_id = "default",
            reference_images = [],
          } = args as any;
  
          try {
            // 대화 컨텍스트 가져오기/생성
            const context = getOrCreateContext(conversation_id);
  
            // Validate directly passed aspect_ratio
            if (aspect_ratio && !VALID_ASPECT_RATIOS.includes(aspect_ratio as AspectRatio)) {
              return {
                content: [{
                  type: "text",
                  text: `Invalid aspect ratio: ${aspect_ratio}. Valid: ${VALID_ASPECT_RATIOS.join(", ")}`,
                }],
                isError: true,
              };
            }
  
            // Priority: direct param > session setting
            const effectiveAspectRatio = aspect_ratio ?? context.aspectRatio;
  
            // aspectRatio 필수 체크 (둘 다 없으면 에러)
            if (effectiveAspectRatio === null) {
              return {
                content: [{
                  type: "text",
                  text: `Error: Aspect ratio not specified. Either pass aspect_ratio parameter or call set_aspect_ratio first.\nValid ratios: ${VALID_ASPECT_RATIOS.join(", ")}`,
                }],
                isError: true,
              };
            }
  
            // 히스토리 참조 확인 ("last", "history:N")
            let resolvedImagePath = image_path;
            let imageBase64: string;
  
            const historyImage = getImageFromHistory(context, image_path);
            if (historyImage) {
              // 히스토리에서 이미지 가져오기
              resolvedImagePath = historyImage.filePath;
              imageBase64 = historyImage.base64Data;
            } else {
              // 파일 경로로 처리
              if (!path.isAbsolute(resolvedImagePath)) {
                resolvedImagePath = path.join(process.cwd(), resolvedImagePath);
              }
  
              // Check if file exists
              try {
                await fs.access(resolvedImagePath);
              } catch {
                // If file doesn't exist in CWD, try in Documents/nanobanana_generated
                const homeDir = os.homedir();
                const altPath = path.join(homeDir, 'Documents', 'nanobanana_generated', path.basename(image_path));
                try {
                  await fs.access(altPath);
                  resolvedImagePath = altPath;
                } catch {
                  throw new Error(`Image file not found: ${image_path}. Use 'last' or 'history:N' to reference session images.`);
                }
              }
  
              // Read the original image
              imageBase64 = await imageToBase64(resolvedImagePath);
            }
  
            // contents 구성: 참조 이미지들 + 프롬프트 + 원본 이미지
            const parts: GeminiImageRequestPart[] = [];
            const failedReferenceImages: Array<{ path: string; reason: string }> = [];
  
            // 1. 추가 참조 이미지 (스타일 일관성용, 최대 10개)
            const refImages = (reference_images as string[] || []).slice(0, 10);
            for (const imgRef of refImages) {
              try {
                // Check for history reference
                const refHistoryImage = getImageFromHistory(context, imgRef);
                if (refHistoryImage) {
                  parts.push({
                    inlineData: {
                      mimeType: refHistoryImage.mimeType,
                      data: refHistoryImage.base64Data,
                    },
                  });
                } else {
                  // File path
                  let refPath = imgRef;
                  if (!path.isAbsolute(refPath)) {
                    refPath = path.join(process.cwd(), refPath);
                  }
                  // Try alternative path if not found
                  try {
                    await fs.access(refPath);
                  } catch {
                    const homeDir = os.homedir();
                    const altPath = path.join(homeDir, 'Documents', 'nanobanana_generated', path.basename(imgRef));
                    await fs.access(altPath);
                    refPath = altPath;
                  }
                  const refBase64 = await imageToBase64(refPath);
                  parts.push({
                    inlineData: {
                      mimeType: "image/png",
                      data: refBase64,
                    },
                  });
                }
              } catch (error) {
                failedReferenceImages.push({
                  path: imgRef,
                  reason: error instanceof Error ? error.message : String(error),
                });
              }
            }
  
            // 2. 편집 프롬프트
            const editingPrompt = `Based on this image, generate a new edited version with the following modifications: ${edit_prompt}
  
  IMPORTANT: Create a completely new image that incorporates the requested changes while maintaining the style and overall composition of the original.`;
            parts.push({ text: editingPrompt });
  
            // 3. 원본 이미지
            parts.push({
              inlineData: {
                mimeType: "image/png",
                data: imageBase64,
              },
            });
  
            // REST API 직접 호출 (세션 모델 우선, 없으면 환경 변수 기본값)
            const effectiveModel = context.selectedModel ?? IMAGE_MODEL;
            const apiResponse = await callGeminiImageAPI(parts, effectiveAspectRatio, effectiveModel);
  
            if (apiResponse.error) {
              return {
                content: [{
                  type: "text",
                  text: `Image editing failed: ${apiResponse.error}\n${apiResponse.textResponse}`,
                }],
                isError: true,
              };
            }
  
            if (!apiResponse.imageData) {
              return {
                content: [{
                  type: "text",
                  text: `Image editing failed.\nOriginal: ${image_path}\nEdit request: "${edit_prompt}"\n` +
                        (apiResponse.textResponse ? `Model response: ${apiResponse.textResponse}` : 'No image returned from model'),
                }],
                isError: true,
              };
            }
  
            // Determine output path - ensure PNG extension for edited images

• src/index.ts:353-374 (schema)

  The definition of the gemini_edit_image tool, including its input schema and description.

  name: "gemini_edit_image",
  description: "Edit or modify existing images based on prompts. Supports session history references ('last' or 'history:N') and image consistency features.",
  inputSchema: {
    type: "object",
    properties: {
      image_path: {
        type: "string",
        description: "Path to the original image. Use 'last' for most recent generated image, or 'history:N' (e.g., 'history:0') to reference by index",
      },
      edit_prompt: {
        type: "string",
        description: "Instructions for how to edit the image",
      },
      aspect_ratio: {
        type: "string",
        enum: [...VALID_ASPECT_RATIOS],
        description: "Aspect ratio for the edited image. Overrides session setting if provided.",
      },
      output_path: {
        type: "string",
        description: "Optional output path. If not provided, saves to ~/Documents/nanobanana_generated/",
      },