FAL Image/Video MCP Server

Instructions

Implementation Reference

• src/index.ts:719-798 (handler)

  Core handler function that executes the custom model by subscribing to the FAL endpoint, processing outputs (images or videos), handling downloads, data URLs, and formatting the response.

  private async handleCustomModel(args: any) {
    const { endpoint, input_params, category_hint = 'other' } = args;
  
    try {
      // Configure FAL client lazily with query config override
      configureFalClient(this.currentQueryConfig);
      const result = await fal.subscribe(endpoint, { input: input_params });
  
      // Handle different output types based on category hint
      if (category_hint === 'image' || category_hint === 'other') {
        // Assume image output
        const data = result.data as any;
        if (data.images && Array.isArray(data.images)) {
          const processedImages = await downloadAndProcessImages(data.images, endpoint.replace(/[^a-zA-Z0-9]/g, '_'));
          
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify({
                  endpoint,
                  category_hint,
                  images: processedImages,
                  raw_output: data,
                  input_params,
                  download_path: DOWNLOAD_PATH,
                }, null, 2),
              },
            ],
          };
        }
      } else if (category_hint === 'video' || category_hint === 'image_to_video') {
        // Assume video output
        const data = result.data as any;
        if (data.video) {
          const videoProcessed = await downloadAndProcessVideo(data.video.url, endpoint.replace(/[^a-zA-Z0-9]/g, '_'));
          
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify({
                  endpoint,
                  category_hint,
                  video: {
                    url: data.video.url,
                    dataUrl: videoProcessed.dataUrl,
                    localPath: videoProcessed.localPath,
                    width: data.video.width,
                    height: data.video.height,
                  },
                  raw_output: data,
                  input_params,
                  download_path: DOWNLOAD_PATH,
                }, null, 2),
              },
            ],
          };
        }
      }
  
      // Fallback: return raw output
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              endpoint,
              category_hint,
              raw_output: result.data,
              input_params,
              note: "Raw output - model type not recognized for enhanced processing"
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new Error(`Custom model execution failed for ${endpoint}: ${error}`);
    }
  }

• src/index.ts:428-451 (schema)

  Tool schema definition including input parameters: endpoint, input_params (object), and optional category_hint for output processing.

  tools.push({
    name: 'execute_custom_model',
    description: 'Execute any FAL model by specifying the endpoint directly',
    inputSchema: {
      type: 'object',
      properties: {
        endpoint: {
          type: 'string',
          description: 'FAL model endpoint (e.g., fal-ai/flux/schnell, fal-ai/custom-model)'
        },
        input_params: {
          type: 'object',
          description: 'Input parameters for the model (varies by model)'
        },
        category_hint: {
          type: 'string',
          enum: ['image', 'video', 'image_to_video', 'other'],
          default: 'other',
          description: 'Hint about the expected output type for proper handling'
        }
      },
      required: ['endpoint', 'input_params']
    }
  });

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

  Dispatch registration in the stdio CallToolRequestSchema handler that calls the custom model handler when the tool name matches.

  if (name === 'list_available_models') {
    return await this.handleListModels(args);
  } else if (name === 'execute_custom_model') {
    return await this.handleCustomModel(args);
  }

• src/index.ts:1051-1055 (registration)

  Dispatch registration in the HTTP direct tool call handler (duplicate logic for HTTP transport support).

  if (name === 'list_available_models') {
    toolResult = await this.handleListModels(args);
  } else if (name === 'execute_custom_model') {
    toolResult = await this.handleCustomModel(args);
  } else {

• src/index.ts:1013-1035 (schema)

  Duplicate tool schema definition for the HTTP tools/list endpoint.

    name: 'execute_custom_model',
    description: 'Execute any FAL model by specifying the endpoint directly',
    inputSchema: {
      type: 'object',
      properties: {
        endpoint: {
          type: 'string',
          description: 'FAL model endpoint (e.g., fal-ai/flux/schnell, fal-ai/custom-model)'
        },
        input_params: {
          type: 'object',
          description: 'Input parameters for the model (varies by model)'
        },
        category_hint: {
          type: 'string',
          enum: ['image', 'video', 'image_to_video', 'other'],
          default: 'other',
          description: 'Hint about the expected output type for proper handling'
        }
      },
      required: ['endpoint', 'input_params']
    }
  });