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"),
  };