MCP fal.ai Image Server

Instructions

Implementation Reference

• src/index.ts:178-277 (handler)

  Main handler function that executes the 'generate-image' tool logic: validates inputs, calls fal.ai API with selected model, downloads images to local dir, returns result with local paths.
  export async function generateImageFromText( prompt: string, imageSize: ImageSize = 'landscape_4_3', numInferenceSteps = 28, guidanceScale = 3.5, numImages = 1, enableSafetyChecker = true, model: string = SUPPORTED_MODELS[0].id // default to first model ) { // --- Pre-validation and user guidance --- // 1. Prompt required if (!prompt || !prompt.trim()) { throw new Error( 'Prompt is required. Please describe the image you want to generate. Example: generate an image of a red apple' ); } // 2. Image size validation const SUPPORTED_SIZES = [ 'square_hd', 'square', 'portrait_4_3', 'portrait_16_9', 'landscape_4_3', 'landscape_16_9', ]; if (imageSize && !SUPPORTED_SIZES.includes(imageSize)) { throw new Error( `Error: '${imageSize}' is not a supported image size.\nSupported sizes: ${SUPPORTED_SIZES.join( ', ' )}` ); } // 3. Batch size validation const MAX_IMAGES = 5; if (numImages > MAX_IMAGES) { throw new Error( `Error: Maximum number of images per request is ${MAX_IMAGES}. Please request ${MAX_IMAGES} or fewer images.` ); } // 4. Safety checker toggle validation (should be boolean) if (typeof enableSafetyChecker !== 'boolean') { throw new Error( "'safety checker' must be either 'on' (true) or 'off' (false). Example: safety checker on" ); } // 5. Dynamic model selection: allow any model ID, warn if not in SUPPORTED_MODELS const foundModel = SUPPORTED_MODELS.find((m) => m.id === model); if (!foundModel) { console.warn( `Warning: Model '${model}' is not in the recommended list. Attempting generation anyway.\n` + `If you encounter errors, check the model ID at https://fal.ai/models or the fal.ai API docs.\n` + `Recommended models:\n${SUPPORTED_MODELS.map( (m) => `- ${m.name} (${m.id})` ).join('\n')}` ); } try { const result = await fal.subscribe(model, { input: { prompt, image_size: imageSize, num_inference_steps: numInferenceSteps, guidance_scale: guidanceScale, num_images: numImages, enable_safety_checker: enableSafetyChecker, }, logs: true, onQueueUpdate: (update: any) => { if (update.status === 'IN_PROGRESS' && update.logs) { update.logs.map((log: any) => log.message).forEach(console.error); } }, }); console.error('Image generation result:', result.data); // Download images and enhance the result with local paths if (result.data && result.data.images) { const downloadedImages = await Promise.all( result.data.images.map(async (img: any, idx: number) => { try { const localPath = await downloadImage(img.url, prompt, idx); console.error(`Image #${idx + 1} saved to: ${localPath}`); return { ...img, localPath }; } catch (error) { console.error(`Failed to download image #${idx + 1}:`, error); return img; } }) ); // Replace the images with the enhanced versions that include local paths result.data.images = downloadedImages; } return result.data; } catch (err: any) { console.error('FAL text-to-image error:', err?.response?.data || err); throw err; } }
• src/index.ts:302-350 (schema)

  JSON Schema defining the input parameters for the 'generate-image' tool, including prompt (required), model, image_size enum, etc., with defaults.
  inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'Text prompt describing the image to generate', }, model: { type: 'string', description: 'ID of the text-to-image model to use (any valid fal.ai model ID)', default: SUPPORTED_MODELS[0].id, }, image_size: { type: 'string', enum: [ 'square_hd', 'square', 'portrait_4_3', 'portrait_16_9', 'landscape_4_3', 'landscape_16_9', ], default: 'landscape_4_3', description: 'Size of the generated image', }, num_images: { type: 'integer', default: 1, description: 'Number of images to generate', }, num_inference_steps: { type: 'integer', default: 28, description: 'Number of inference steps', }, guidance_scale: { type: 'number', default: 3.5, description: 'Classifier Free Guidance scale', }, enable_safety_checker: { type: 'boolean', default: true, description: 'Enable the safety checker', }, }, required: ['prompt'], },
• src/index.ts:295-354 (registration)

  Registers the 'generate-image' tool in the MCP server's listTools response, providing name, description, and inputSchema.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'generate-image', description: 'Generate an image from a text prompt using a selectable text-to-image model.', inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'Text prompt describing the image to generate', }, model: { type: 'string', description: 'ID of the text-to-image model to use (any valid fal.ai model ID)', default: SUPPORTED_MODELS[0].id, }, image_size: { type: 'string', enum: [ 'square_hd', 'square', 'portrait_4_3', 'portrait_16_9', 'landscape_4_3', 'landscape_16_9', ], default: 'landscape_4_3', description: 'Size of the generated image', }, num_images: { type: 'integer', default: 1, description: 'Number of images to generate', }, num_inference_steps: { type: 'integer', default: 28, description: 'Number of inference steps', }, guidance_scale: { type: 'number', default: 3.5, description: 'Classifier Free Guidance scale', }, enable_safety_checker: { type: 'boolean', default: true, description: 'Enable the safety checker', }, }, required: ['prompt'], }, }, ], }; });
• src/index.ts:363-411 (handler)

  MCP CallTool request handler that invokes generateImageFromText for 'generate-image' tool calls and formats the response.
  if (name === 'generate-image') { try { const result = await generateImageFromText( args.prompt, args.image_size, args.num_inference_steps, args.guidance_scale, args.num_images, args.enable_safety_checker, args.model // new model param ); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } catch (error: any) { // --- Enhanced error handling for guidance --- let errorMsg = error instanceof Error ? error.message : String(error); // If model error, append recommended models and link if (errorMsg.match(/model/i)) { errorMsg += '\n\nRecommended models:\n' + SUPPORTED_MODELS.map((m) => `- ${m.name} (${m.id})`).join('\n') + '\nSee all models: https://fal.ai/models'; } // If image size error, append supported sizes if (errorMsg.match(/image size|supported sizes/i)) { errorMsg += '\nSupported sizes: square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9'; } // If prompt error, add example if (errorMsg.match(/prompt is required/i)) { errorMsg += '\nExample: generate an image of a red apple'; } return { isError: true, content: [ { type: 'text', text: `Error generating image: ${errorMsg}`, }, ], }; } } else {
• src/index.ts:71-102 (helper)

  Helper function to download generated image from fal.ai URL to local filesystem, used by the main handler.
  async function downloadImage( url: string, prompt: string, idx?: number ): Promise<string> { ensureDownloadDir(); // Generate a filename from the prompt and timestamp const timestamp = new Date().toISOString().replace(/[:.]/g, '-'); const sanitizedPrompt = prompt .slice(0, 30) .replace(/[^a-z0-9]/gi, '_') .toLowerCase(); const filename = `${sanitizedPrompt}_${timestamp}${ typeof idx === 'number' ? `_${idx + 1}` : '' }.png`; const filepath = path.join(FAL_IMAGES_DIR, filename); try { const response = await fetch(url); if (!response.ok) throw new Error(`Failed to fetch: ${response.statusText}`); const buffer = await response.arrayBuffer(); fs.writeFileSync(filepath, Buffer.from(buffer)); console.error(`✅ Downloaded image to: ${filepath}`); return filepath; } catch (error) { console.error(`❌ Failed to download image: ${error}`); throw error; } }