MCP fal.ai Image Server

Instructions

Implementation Reference

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

  Core implementation of the generate-image tool: validates parameters, calls fal.ai API with dynamic model support, downloads images locally, and returns enhanced results with file 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)

  Input schema for the 'generate-image' tool, defining parameters like prompt, model, image size, and 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:298-352 (registration)

  Registration of the 'generate-image' tool in the ListToolsRequestSchema handler, specifying name, description, and input schema.

    {
      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-410 (handler)

  MCP CallToolRequestSchema handler branch that invokes generateImageFromText for 'generate-image' tool calls and handles responses/errors.

  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}`,
          },
        ],
      };
    }

• src/index.ts:71-102 (helper)

  Helper utility to download generated images from fal.ai URLs to a local directory, appending local paths to results.

  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;
    }
  }