FAL Image/Video MCP Server

Instructions

Implementation Reference

• src/index.ts:677-717 (handler)

  The main handler function for the 'list_available_models' tool. It filters models from the MODEL_REGISTRY based on the provided category and returns a formatted list with details.

  private async handleListModels(args: any) {
    const { category = 'all' } = args;
  
    let modelsToList: any[] = [];
    
    if (category === 'all') {
      modelsToList = getAllModels();
    } else if (category === 'imageGeneration') {
      modelsToList = MODEL_REGISTRY.imageGeneration;
    } else if (category === 'imageGeneration') {
      modelsToList = MODEL_REGISTRY.imageGeneration;
    } else if (category === 'textToVideo') {
      modelsToList = MODEL_REGISTRY.textToVideo;
    } else if (category === 'imageToVideo') {
      modelsToList = MODEL_REGISTRY.imageToVideo;
    }
  
    const modelList = modelsToList.map(model => ({
      id: model.id,
      name: model.name,
      description: model.description,
      endpoint: model.endpoint,
      category: MODEL_REGISTRY.imageGeneration.includes(model as any) ? 'imageGeneration' :
                MODEL_REGISTRY.textToVideo.includes(model as any) ? 'textToVideo' :
                MODEL_REGISTRY.imageToVideo.includes(model as any) ? 'imageToVideo' : 'unknown'
    }));
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            total_models: modelList.length,
            category_filter: category,
            models: modelList,
            note: "Use 'execute_custom_model' to run any FAL endpoint not in this registry"
          }, null, 2),
        },
      ],
    };
  }

• src/index.ts:411-426 (schema)

  Defines the input schema for the 'list_available_models' tool, specifying an optional 'category' parameter to filter models.

  tools.push({
    name: 'list_available_models',
    description: 'List all available models in the current registry with their capabilities',
    inputSchema: {
      type: 'object',
      properties: {
        category: {
          type: 'string',
          enum: ['all', 'imageGeneration', 'textToVideo', 'imageToVideo'],
          default: 'all',
          description: 'Filter models by category'
        }
      },
      required: []
    }
  });

• src/index.ts:460-465 (registration)

  Tool dispatch/registration in the main CallToolRequestSchema handler, routing 'list_available_models' calls to the handleListModels function.

  // Handle special tools first
  if (name === 'list_available_models') {
    return await this.handleListModels(args);
  } else if (name === 'execute_custom_model') {
    return await this.handleCustomModel(args);
  }

• src/index.ts:131-137 (helper)

  Helper function that aggregates all models from the categorized MODEL_REGISTRY for easy access.

  function getAllModels() {
    return [
      ...MODEL_REGISTRY.imageGeneration,
      ...MODEL_REGISTRY.textToVideo,
      ...MODEL_REGISTRY.imageToVideo
    ];
  }

• src/index.ts:99-128 (helper)

  The MODEL_REGISTRY object containing all available models, categorized into imageGeneration, textToVideo, and imageToVideo. This is the data source for the tool.

  const MODEL_REGISTRY = {
    imageGeneration: [
      { id: 'imagen4', endpoint: 'fal-ai/imagen4/preview', name: 'Imagen 4', description: 'Google\'s latest text-to-image model' },
      { id: 'flux_kontext', endpoint: 'fal-ai/flux-pro/kontext/text-to-image', name: 'FLUX Kontext Pro', description: 'State-of-the-art prompt adherence and typography' },
      { id: 'ideogram_v3', endpoint: 'fal-ai/ideogram/v3', name: 'Ideogram V3', description: 'Advanced typography and realistic outputs' },
      { id: 'recraft_v3', endpoint: 'fal-ai/recraft/v3/text-to-image', name: 'Recraft V3', description: 'Professional design and illustration' },
      { id: 'stable_diffusion_35', endpoint: 'fal-ai/stable-diffusion-v35-large', name: 'Stable Diffusion 3.5 Large', description: 'Improved image quality and performance' },
      { id: 'flux_dev', endpoint: 'fal-ai/flux/dev', name: 'FLUX Dev', description: 'High-quality 12B parameter model' },
      { id: 'hidream', endpoint: 'fal-ai/hidream-i1-full', name: 'HiDream I1', description: 'High-resolution image generation' },
      { id: 'janus', endpoint: 'fal-ai/janus', name: 'Janus', description: 'Multimodal understanding and generation' }
    ],
    textToVideo: [
      { id: 'veo3', endpoint: 'fal-ai/veo3', name: 'Veo 3', description: 'Google DeepMind\'s latest with speech and audio' },
      { id: 'kling_master_text', endpoint: 'fal-ai/kling-video/v2.1/master/text-to-video', name: 'Kling 2.1 Master', description: 'Premium text-to-video with motion fluidity' },
      { id: 'pixverse_text', endpoint: 'fal-ai/pixverse/v4.5/text-to-video', name: 'Pixverse V4.5', description: 'Advanced text-to-video generation' },
      { id: 'magi', endpoint: 'fal-ai/magi', name: 'Magi', description: 'Creative video generation' },
      { id: 'luma_ray2', endpoint: 'fal-ai/luma-dream-machine/ray-2', name: 'Luma Ray 2', description: 'Latest Luma Dream Machine' },
      { id: 'wan_pro_text', endpoint: 'fal-ai/wan-pro/text-to-video', name: 'Wan Pro', description: 'Professional video effects' },
      { id: 'vidu_text', endpoint: 'fal-ai/vidu/q1/text-to-video', name: 'Vidu Q1', description: 'High-quality text-to-video' }
    ],
    imageToVideo: [
      { id: 'ltx_video', endpoint: 'fal-ai/ltx-video-13b-distilled/image-to-video', name: 'LTX Video', description: 'Fast and high-quality image-to-video conversion' },
      { id: 'kling_master_image', endpoint: 'fal-ai/kling-video/v2.1/master/image-to-video', name: 'Kling 2.1 Master I2V', description: 'Premium image-to-video conversion' },
      { id: 'pixverse_image', endpoint: 'fal-ai/pixverse/v4.5/image-to-video', name: 'Pixverse V4.5 I2V', description: 'Advanced image-to-video' },
      { id: 'wan_pro_image', endpoint: 'fal-ai/wan-pro/image-to-video', name: 'Wan Pro I2V', description: 'Professional image animation' },
      { id: 'hunyuan_image', endpoint: 'fal-ai/hunyuan-video-image-to-video', name: 'Hunyuan I2V', description: 'Open-source image-to-video' },
      { id: 'vidu_image', endpoint: 'fal-ai/vidu/image-to-video', name: 'Vidu I2V', description: 'High-quality image animation' },
      { id: 'luma_ray2_image', endpoint: 'fal-ai/luma-dream-machine/ray-2/image-to-video', name: 'Luma Ray 2 I2V', description: 'Latest Luma image-to-video' }
    ]
  };