generateImage

Instructions

Implementation Reference

• src/services/bflService.ts:102-221 (handler)

  The core handler function that executes the generateImage tool logic: makes API call to Black Forest Lab FLUX, polls for completion, downloads and saves image locally if requested.

  export async function generateImage(
    prompt: string, 
    options: ImageGenerationOptions = {}
  ): Promise<ImageGenerationResult> {
    const apiKey = process.env.BFL_API_KEY;
    
    if (!apiKey) {
      throw new Error('API key is required. Set BFL_API_KEY environment variable.');
    }
    
    // Build the request payload
    const payload = {
      prompt,
      width: options.width || 1024,
      height: options.height || 1024,
      prompt_upsampling: options.promptUpsampling || false,
      safety_tolerance: options.safetyTolerance || 3,
      ...(options.seed !== undefined && { seed: options.seed })
    };
    
    let pollingUrl;
    try {
      // Make the initial API request
      console.error(`[INFO] Sending request to FLUX API for prompt: "${prompt}"`);
      const response = await axios.post(BFL_API_ENDPOINT, payload, {
        headers: {
          'Content-Type': 'application/json',
          'X-Key': apiKey
        }
      });
      
      // Check if we need to poll for results
      if (response.data.polling_url) {
        pollingUrl = response.data.polling_url;
        console.error(`[INFO] Got polling URL: ${pollingUrl}`);
      } else if (response.data.image_url) {
        // If we got an image URL directly, no need to poll
        console.error(`[INFO] Got image URL directly: ${response.data.image_url}`);
        
        const result: ImageGenerationResult = {
          image_url: response.data.image_url,
          local_path: null
        };
        
        // Save the image locally if requested
        if (options.saveImage) {
          try {
            const filename = options.filename || `flux_${Date.now()}.png`;
            const savePath = await downloadImage(
              result.image_url, 
              filename, 
              options.outputDir || process.env.OUTPUT_DIR || './output',
              options.customPath
            );
            result.local_path = savePath;
          } catch (downloadError: any) {
            console.error(`[ERROR] Error saving image: ${downloadError.message}`);
            // Continue with the operation even if download fails
          }
        }
        
        return result;
      } else {
        throw new Error('Invalid response from Black Forest Lab API: No polling URL or image URL');
      }
    } catch (error: any) {
      const errorMsg = error.response?.data?.message || error.message || 'Unknown error';
      console.error(`[ERROR] Error calling Black Forest Lab API: ${errorMsg}`);
      throw new Error(`Failed to generate image: ${errorMsg}`);
    }
    
    // If we have a polling URL, poll for the result
    try {
      const maxPollingAttempts = options.maxPollingAttempts || 30;
      const pollingInterval = options.pollingInterval || 2000;
      
      const pollResult = await pollForResults(
        pollingUrl, 
        apiKey, 
        maxPollingAttempts, 
        pollingInterval
      );
      
      // Check if we have a direct image_url or need to extract it from result.sample
      if (!pollResult.image_url && pollResult.result && pollResult.result.sample) {
        pollResult.image_url = pollResult.result.sample;
      }
      
      if (!pollResult.image_url) {
        throw new Error('No image URL in completed result');
      }
      
      const result: ImageGenerationResult = {
        image_url: pollResult.image_url,
        local_path: null
      };
      
      // Save the image locally if requested
      if (options.saveImage) {
        try {
          const filename = options.filename || `flux_${Date.now()}.png`;
          const savePath = await downloadImage(
            result.image_url, 
            filename, 
            options.outputDir || process.env.OUTPUT_DIR || './output',
            options.customPath
          );
          result.local_path = savePath;
        } catch (downloadError: any) {
          console.error(`[ERROR] Error saving image: ${downloadError.message}`);
          // Continue with the operation even if download fails
        }
      }
      
      return result;
    } catch (error: any) {
      console.error(`[ERROR] Error in polling process: ${error.message}`);
      throw new Error(`Failed to generate image: ${error.message}`);
    }
  }

• src/schemas.ts:9-50 (schema)

  The schema definition for the generateImage tool, including input schema, description, and parameters.

  export const GENERATE_IMAGE_TOOL: Tool = {
    name: "generateImage",
    description: "Generate an image using Black Forest Lab's FLUX model based on a text prompt",
    inputSchema: {
      type: "object",
      properties: {
        prompt: {
          type: "string",
          description: "Text description of the image to generate"
        },
        width: {
          type: "number",
          description: "Width of the image in pixels",
          default: 1024
        },
        height: {
          type: "number",
          description: "Height of the image in pixels",
          default: 1024
        },
        promptUpsampling: {
          type: "boolean",
          description: "Enhance detail by upsampling the prompt",
          default: false
        },
        seed: {
          type: "number",
          description: "Random seed for reproducible results"
        },
        safetyTolerance: {
          type: "number",
          description: "Content moderation tolerance (1-5)",
          default: 3
        },
        customPath: {
          type: "string",
          description: "Custom path to save the generated image"
        }
      },
      required: ["prompt"]
    }
  };

• src/index.ts:48-54 (registration)

  Registration of the generateImage tool schema in the MCP server's listTools request handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      GENERATE_IMAGE_TOOL,
      QUICK_IMAGE_TOOL,
      BATCH_GENERATE_IMAGES_TOOL
    ],
  }));

• src/index.ts:72-106 (handler)

  The MCP CallToolRequestSchema handler case for generateImage: validates input arguments, prepares options, calls the core generateImage function, and formats the response.

  case "generateImage": {
    // Validate parameters
    if (typeof args.prompt !== 'string') {
      throw new Error("Invalid prompt: must be a string");
    }
  
    // Use the full image generation capabilities
    const options = {
      width: typeof args.width === 'number' ? args.width : 1024,
      height: typeof args.height === 'number' ? args.height : 1024,
      promptUpsampling: typeof args.promptUpsampling === 'boolean' ? args.promptUpsampling : false,
      seed: typeof args.seed === 'number' ? args.seed : undefined,
      safetyTolerance: typeof args.safetyTolerance === 'number' ? args.safetyTolerance : 3,
      saveImage: true,
      filename: `flux_${Date.now()}.png`,
      customPath: typeof args.customPath === 'string' ? args.customPath : undefined
    };
    
    const result = await generateImage(args.prompt, options);
    
    // Return a plain text response with the image URL and save location
    let textContent = `Image generated\nLink: ${result.image_url}`;
    
    // Add information about where the image was saved
    if (result.local_path) {
      textContent += `\nImage saved to: ${result.local_path}`;
    }
    
    return {
      content: [
        { type: "text", text: textContent }
      ],
      isError: false,
    };
  }