create_variation

Instructions

Implementation Reference

• src/tools/index.ts:238-279 (handler)

  MCP tool handler for 'create_variation': resolves image path, invokes DalleService.createVariation, formats success/error response with saved variation paths.

  handler: async (args: VariationArgs): Promise<ToolResponse> => {
    // Resolve relative path to absolute path
    const imagePath = path.isAbsolute(args.imagePath) 
      ? args.imagePath 
      : path.resolve(process.cwd(), args.imagePath);
  
    const result = await dalleService.createVariation(imagePath, {
      model: args.model,
      size: args.size,
      n: args.n,
      saveDir: args.saveDir,
      fileName: args.fileName
    });
  
    if (!result.success) {
      return {
        content: [{
          type: "text",
          text: `Error creating image variations: ${result.error}`
        }]
      };
    }
  
    const imagePaths = result.imagePaths || [];
    const imageCount = imagePaths.length;
    const model = result.model || 'dall-e-2';
  
    let responseText = `Successfully created ${imageCount} variation${imageCount !== 1 ? 's' : ''} using ${model}.\n\n`;
    responseText += `Original image: ${imagePath}\n\n`;
    responseText += `Variation${imageCount !== 1 ? 's' : ''} saved to:\n`;
    
    imagePaths.forEach(imagePath => {
      responseText += `- ${imagePath}\n`;
    });
  
    return {
      content: [{
        type: "text",
        text: responseText
      }]
    };
  }

• src/services/dalle-service.ts:247-341 (helper)

  Core implementation in DalleService: calls OpenAI API /images/variations, saves generated variation images to disk, returns ImageGenerationResult.

  async createVariation(
    imagePath: string,
    options: {
      model?: string;
      size?: string;
      n?: number;
      saveDir?: string;
      fileName?: string;
    } = {}
  ): Promise<ImageGenerationResult> {
    try {
      // Set default options
      const model = options.model || 'dall-e-2'; // DALL-E 3 doesn't support variations yet
      const size = options.size || '1024x1024';
      const n = options.n || 1;
      const saveDir = options.saveDir || this.config.defaultSaveDir || process.cwd();
      const fileName = options.fileName || `dalle-variation-${Date.now()}`;
  
      // Ensure save directory exists
      await fs.ensureDir(saveDir);
  
      // Check if image exists
      if (!await fs.pathExists(imagePath)) {
        return {
          success: false,
          error: `Image file not found: ${imagePath}`
        };
      }
  
      // Create form data
      const formData = new FormData();
      formData.append('n', n.toString());
      formData.append('size', size);
      formData.append('response_format', 'b64_json');
  
      // Read image file and append to form
      const imageBuffer = await fs.readFile(imagePath);
      formData.append('image', imageBuffer, {
        filename: path.basename(imagePath),
        contentType: 'image/png'
      });
  
      // Make request to OpenAI API
      const response = await axios.post(
        `${this.baseUrl}/images/variations`,
        formData,
        {
          headers: {
            'Content-Type': 'multipart/form-data',
            'Authorization': `Bearer ${this.config.apiKey}`
          }
        }
      );
  
      // Process response
      const data = response.data;
      const imagePaths: string[] = [];
  
      // Save each image
      for (let i = 0; i < data.data.length; i++) {
        const item = data.data[i];
        const resultBuffer = Buffer.from(item.b64_json, 'base64');
        let resultPath = path.join(saveDir, `${fileName}${n > 1 ? `-${i + 1}` : ''}.png`);
        
        // Ensure the path is absolute
        if (!path.isAbsolute(resultPath)) {
          resultPath = path.resolve(process.cwd(), resultPath);
        }
        
        await fs.writeFile(resultPath, resultBuffer);
        imagePaths.push(resultPath);
      }
  
      return {
        success: true,
        imagePaths,
        model
      };
    } catch (error) {
      console.log("DALL-E API Error:", error);
      
      let errorMessage = 'Failed to create image variation';
      
      if (axios.isAxiosError(error) && error.response?.data?.error) {
        errorMessage = `DALL-E API Error: ${error.response.data.error.message}`;
      } else if (error instanceof Error) {
        errorMessage = error.message;
      }
      
      return {
        success: false,
        error: errorMessage
      };
    }
  }

• src/tools/index.ts:204-237 (schema)

  Input schema for 'create_variation' tool defining parameters, types, enums, and required fields.

  inputSchema: {
    type: "object",
    properties: {
      imagePath: {
        type: "string",
        description: "Path to the image to create variations of"
      },
      model: {
        type: "string",
        description: "DALL-E model to use (currently only dall-e-2 supports variations)",
        enum: ["dall-e-2"]
      },
      size: {
        type: "string",
        description: "Size of the generated image",
        enum: ["256x256", "512x512", "1024x1024"]
      },
      n: {
        type: "number",
        description: "Number of variations to generate (1-10)",
        minimum: 1,
        maximum: 10
      },
      saveDir: {
        type: "string",
        description: "Directory to save the variation images"
      },
      fileName: {
        type: "string",
        description: "Base filename for the variation images (without extension)"
      }
    },
    required: ["imagePath"]
  },

• src/index.ts:25-32 (registration)

  MCP server capabilities registration declaring 'create_variation' tool availability.

      tools: {
        generate_image: true,
        edit_image: true,
        create_variation: true,
        validate_key: true
      },
    },
  }

• src/index.ts:88-90 (registration)

  Dispatcher in main tool call handler that routes 'create_variation' calls to the specific tool handler.

  case 'create_variation':
    response = await (tool as Tool<VariationArgs>).handler(args as unknown as VariationArgs);
    break;