Create image variation

Instructions

Implementation Reference

• src/tools/variation.ts:27-79 (handler)

  The registerVariationTool function registers the 'create_variation' tool on the MCP server. The handler reads the source image as an upload, calls OpenAI's images.createVariation API with model 'dall-e-2', saves the resulting images to disk, and returns file paths (and optionally inline image content).

  export function registerVariationTool(server: McpServer): void {
    server.registerTool(
      "create_variation",
      {
        title: "Create image variation",
        description:
          "Generate variations of an existing image using DALL·E 2 (the only model that supports variations). Results are saved to disk and file paths are returned.",
        inputSchema,
      },
      async (args) => {
        try {
          const upload = await readImageAsUpload(args.image);
          const params: ImageCreateVariationParams = {
            model: "dall-e-2",
            image: upload,
            response_format: "b64_json",
          };
          if (args.n !== undefined) params.n = args.n;
          if (args.size) params.size = args.size;
          if (args.user) params.user = args.user;
  
          const client = getOpenAI();
          const response = await client.images.createVariation(params);
          const items = response.data ?? [];
          if (items.length === 0) {
            return errorContent(new Error("OpenAI returned no images."));
          }
  
          const outDir = resolveOutputDir(args.output_dir);
          const seed = `${Date.now()}_variation_${args.image}`;
          const saved = await Promise.all(
            items.map(async (item, i) => {
              const extracted = await extractImage(item, "png");
              return saveImage(extracted, outDir, args.filename_prefix ?? "variation", seed, i);
            }),
          );
  
          const summary = [
            `Generated ${saved.length} variation${saved.length === 1 ? "" : "s"} of ${args.image} with dall-e-2.`,
            `Saved to: ${outDir}`,
            "",
            ...saved.map((s, i) => `  [${i}] ${s.path} (${s.mime}, ${s.bytes} bytes)`),
          ].join("\n");
  
          return {
            content: buildContent(summary, saved, args.return_image_content === true),
          };
        } catch (err) {
          return errorContent(err);
        }
      },
    );
  }

• src/tools/variation.ts:14-25 (schema)

  Zod schema definitions for the 'create_variation' tool inputs: image (required absolute path), n (1-10 optional), size (256x256|512x512|1024x1024 optional), user (optional string), output_dir (optional), filename_prefix (optional), return_image_content (optional boolean).

  const inputSchema = {
    image: z.string().describe("Absolute path to the source image (PNG, square, <4MB)."),
    n: z.number().int().min(1).max(10).optional().describe("Number of variations to generate (default 1)."),
    size: z
      .enum(["256x256", "512x512", "1024x1024"])
      .optional()
      .describe("Output size. Default 1024x1024."),
    user: z.string().optional(),
    output_dir: z.string().optional(),
    filename_prefix: z.string().optional(),
    return_image_content: z.boolean().optional(),
  };

• src/server.ts:22-22 (registration)

  Registration of the 'create_variation' tool by calling registerVariationTool(server) during server creation.

  registerVariationTool(server);

• src/tools/variation.ts:28-30 (registration)

  The tool name 'create_variation' is registered via server.registerTool('create_variation', ...).

  server.registerTool(
    "create_variation",
    {

• src/models.ts:103-103 (helper)

  Model definition for dall-e-2 showing supportsVariation: true, confirming dall-e-2 is the only model that supports the variation feature.

  supportsVariation: true,