generate_image

Instructions

Implementation Reference

• src/index.ts:135-148 (handler)

  The inline handler function that processes the tool arguments, invokes the Gemini API via callGeminiGenerate, optionally saves the image, and returns a structured content response with text description, image data, and data URL.

  async (args) => {
    const { prompt, saveToFilePath } = args;
    const results = await callGeminiGenerate({ prompt, saveToFilePath });
    const first = results[0];
    const savedPath = await maybeSaveImage(first.imageBase64, first.mimeType, saveToFilePath);
    const dataUrl = `data:${first.mimeType};base64,${first.imageBase64}`;
    return {
      content: [
        { type: 'text', text: `Generated image${savedPath ? ` saved to ${savedPath}` : ''}` },
        { type: 'image', mimeType: first.mimeType, data: first.imageBase64 },
        { type: 'text', text: dataUrl },
      ],
    };
  }

• src/index.ts:131-134 (schema)

  Zod schema defining the input parameters for the generate_image tool: a required 'prompt' string and an optional 'saveToFilePath' string.

  {
    prompt: z.string().describe('Detailed scene description. Use photographic terms for photorealism.'),
    saveToFilePath: z.string().optional().describe('Optional path to save the image (png/jpeg by extension)'),
  },

• src/index.ts:128-149 (registration)

  Registration of the generate_image tool with the MCP server using mcp.tool(), specifying name, description, input schema, and handler function.

  mcp.tool(
    'generate_image',
    'Generate an image from a text prompt using Gemini 2.5 Flash Image',
    {
      prompt: z.string().describe('Detailed scene description. Use photographic terms for photorealism.'),
      saveToFilePath: z.string().optional().describe('Optional path to save the image (png/jpeg by extension)'),
    },
    async (args) => {
      const { prompt, saveToFilePath } = args;
      const results = await callGeminiGenerate({ prompt, saveToFilePath });
      const first = results[0];
      const savedPath = await maybeSaveImage(first.imageBase64, first.mimeType, saveToFilePath);
      const dataUrl = `data:${first.mimeType};base64,${first.imageBase64}`;
      return {
        content: [
          { type: 'text', text: `Generated image${savedPath ? ` saved to ${savedPath}` : ''}` },
          { type: 'image', mimeType: first.mimeType, data: first.imageBase64 },
          { type: 'text', text: dataUrl },
        ],
      };
    }
  );

• src/index.ts:73-112 (helper)

  Key helper function that performs the HTTP POST request to the Gemini API to generate images based on the prompt and optional input images, parsing the response to extract base64 image data.

  async function callGeminiGenerate(request: GenerateRequest): Promise<{ imageBase64: string; mimeType: string }[]> {
    const textPart = { text: request.prompt };
    const imageParts = await toInlineDataParts(request.images);
    const parts = [textPart as any, ...imageParts];
  
    const fetchResponse = await fetch(`${GEMINI_ENDPOINT}?key=${encodeURIComponent(GEMINI_API_KEY)}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        contents: [
          {
            parts,
          },
        ],
      }),
    });
  
    if (!fetchResponse.ok) {
      const text = await fetchResponse.text();
      throw new Error(`Gemini API error ${fetchResponse.status}: ${text}`);
    }
  
    const json = (await fetchResponse.json()) as GeminiGenerateResponse;
    const images: { imageBase64: string; mimeType: string }[] = [];
    const first = json.candidates?.[0]?.content?.parts ?? [];
    for (const part of first) {
      if (part.inlineData?.data) {
        images.push({ imageBase64: part.inlineData.data, mimeType: part.inlineData.mimeType ?? 'image/png' });
      }
    }
  
    if (images.length === 0) {
      // Fallback: if API returns interleaved text etc.
      throw new Error('No image data returned by Gemini API');
    }
  
    return images;
  }

• src/index.ts:114-123 (helper)

  Helper function to optionally save the generated base64 image to a file path, determining extension from mimeType if needed.

  async function maybeSaveImage(base64: string, mimeType: string, targetPath?: string): Promise<string | undefined> {
    if (!targetPath) return undefined;
    const { writeFile } = await import('node:fs/promises');
    const { extname } = await import('node:path');
    const extension = extname(targetPath) || (mimeType === 'image/jpeg' ? '.jpg' : '.png');
    const resolved = resolve(targetPath.endsWith(extension) ? targetPath : `${targetPath}${extension}`);
    const buffer = Buffer.from(base64, 'base64');
    await writeFile(resolved, buffer);
    return resolved;
  }