replicate-flux-mcp

Instructions

Implementation Reference

• src/tools/generateImageVariants.ts:20-149 (handler)

  The handler function that executes the generate_image_variants tool logic, generating multiple image variants using Replicate, handling prompt variations and seeds, and building MCP response content with text and image parts.
  export const registerGenerateImageVariantsTool = async ( input: ImageVariantsGenerationParams ): Promise<CallToolResult> => { const { prompt, num_variants, seed, support_image_mcp_response_type, prompt_variations, variation_mode, ...commonParams } = input; try { let effectiveVariants = num_variants; let usingPromptVariations = false; // Decide if we're using prompt variations if (prompt_variations && prompt_variations.length > 0) { usingPromptVariations = true; // If using prompt variations, number of variants is limited by available variations effectiveVariants = Math.min(num_variants, prompt_variations.length); } // Process all variants in parallel const generationPromises = Array.from( { length: effectiveVariants }, (_, index) => { // If seed is provided, create deterministic variants by adding the index const variantSeed = seed !== undefined ? seed + index : undefined; // Determine which prompt to use for this variant let variantPrompt = prompt; if (usingPromptVariations) { const variation = prompt_variations![index]; if (variation_mode === "append") { variantPrompt = `${prompt} ${variation}`; } else { // 'replace' mode variantPrompt = variation; } } return replicate .run(CONFIG.imageModelId, { input: { prompt: variantPrompt, seed: variantSeed, ...commonParams, }, }) .then((outputs) => { const [output] = outputs as [FileOutput]; const imageUrl = output.url() as unknown as string; if (support_image_mcp_response_type) { return outputToBase64(output).then((imageBase64) => ({ variantIndex: index + 1, imageUrl, imageBase64, usedPrompt: variantPrompt, })); } return { variantIndex: index + 1, imageUrl, usedPrompt: variantPrompt, }; }); } ); // Wait for all variant generation to complete const results = (await Promise.all( generationPromises )) as ImageVariantResult[]; // Build response content const responseContent: (TextContent | ImageContent)[] = []; // Add intro text - different based on whether we're using prompt variations if (usingPromptVariations) { responseContent.push({ type: "text", text: `Generated ${results.length} variants of "${prompt}" using custom prompt variations (${variation_mode} mode)`, } as TextContent); } else { responseContent.push({ type: "text", text: `Generated ${results.length} variants of: "${prompt}" using seed variations`, } as TextContent); } // Add each variant with its index and prompt info for (const result of results) { // Build an appropriate description based on variant type let variantDescription = `Variant #${result.variantIndex}`; if (usingPromptVariations) { variantDescription += `\nPrompt: "${result.usedPrompt}"`; } else if (seed !== undefined) { variantDescription += ` (seed: ${seed + (result.variantIndex - 1)})`; } variantDescription += `\nImage URL: ${result.imageUrl}`; responseContent.push({ type: "text", text: `\n\n${variantDescription}`, } as TextContent); if (support_image_mcp_response_type && result.imageBase64) { responseContent.push({ type: "image", data: result.imageBase64, mimeType: `image/${ input.output_format === "jpg" ? "jpeg" : input.output_format }`, } as ImageContent); } } return { content: responseContent, }; } catch (error) { handleError(error); } };
• src/tools/index.ts:33-38 (registration)

  Registers the generate_image_variants tool with the MCP server using server.tool, providing name, description, schema, and handler.
  server.tool( "generate_image_variants", "Generate multiple variants of the same image from a single prompt", imageVariantsGenerationSchema, registerGenerateImageVariantsTool );
• src/types/index.ts:210-297 (schema)

  Zod schema defining the input parameters for the generate_image_variants tool, including prompt, num_variants, prompt_variations, etc.
  export const imageVariantsGenerationSchema = { prompt: z .string() .min(1) .describe("Text description for the image to generate variants of"), num_variants: z .number() .int() .min(2) .max(10) .default(4) .describe("Number of image variants to generate (2-10)"), prompt_variations: z .array(z.string()) .optional() .describe( "Optional list of prompt modifiers to apply to variants (e.g., ['in watercolor style', 'in oil painting style']). If provided, these will be used instead of random seeds." ), variation_mode: z .enum(["append", "replace"]) .default("append") .describe( "How to apply prompt variations: 'append' adds to the base prompt, 'replace' uses variations as standalone prompts" ), seed: z .number() .int() .optional() .describe( "Base random seed. Each variant will use seed+variant_index for reproducibility" ), go_fast: z .boolean() .default(true) .describe( "Run faster predictions with model optimized for speed (currently fp8 quantized); disable to run in original bf16" ), megapixels: z .enum(["1", "0.25"]) .default("1") .describe("Approximate number of megapixels for generated image"), aspect_ratio: z .enum([ "1:1", "16:9", "21:9", "3:2", "2:3", "4:5", "5:4", "3:4", "4:3", "9:16", "9:21", ]) .default("1:1") .describe("Aspect ratio for the generated image"), output_format: z .enum(["webp", "jpg", "png"]) .default("webp") .describe("Format of the output images"), output_quality: z .number() .int() .min(0) .max(100) .default(80) .describe( "Quality when saving the output images, from 0 to 100. 100 is best quality, 0 is lowest quality. Not relevant for .png outputs" ), num_inference_steps: z .number() .int() .min(1) .max(4) .default(4) .describe( "Number of denoising steps. 4 is recommended, and lower number of steps produce lower quality outputs, faster." ), disable_safety_checker: z .boolean() .default(false) .describe("Disable safety checker for generated images."), support_image_mcp_response_type: z .boolean() .default(true) .describe("Support image MCP response type on client side"), };