fal-search-models

Instructions

Implementation Reference

• src/tools/index.ts:37-53 (handler)

  The tool handler/registration for 'fal-search-models'. Defines the tool with Zod schema (keyword required, limit and category optional) and the async handler that calls client.searchModels() and returns the result as text.

  server.tool(
      'fal-search-models',
      'Search for models by keywords with optional category and limit filtering. The keywords are used to search for models that match the keywords.',
      {
          keyword: z.string(),
          limit: z.number().optional(),
          category: z.string().optional(),
      },
      async ({ keyword, limit, category }) => {
          const result = (await client.searchModels({ keyword, limit, category })) as
              | { models?: FalModel[] }
              | FalModel[]
              | unknown;
          const list = Array.isArray(result) ? result : ((result as any)?.models ?? result);
          return { content: [{ type: 'text', text: toText(list) }] };
      },
  );

• src/tools/index.ts:37-53 (registration)

  The tool registration via server.tool('fal-search-models', ...) on line 38. This is where the tool is registered with the MCP server.

  server.tool(
      'fal-search-models',
      'Search for models by keywords with optional category and limit filtering. The keywords are used to search for models that match the keywords.',
      {
          keyword: z.string(),
          limit: z.number().optional(),
          category: z.string().optional(),
      },
      async ({ keyword, limit, category }) => {
          const result = (await client.searchModels({ keyword, limit, category })) as
              | { models?: FalModel[] }
              | FalModel[]
              | unknown;
          const list = Array.isArray(result) ? result : ((result as any)?.models ?? result);
          return { content: [{ type: 'text', text: toText(list) }] };
      },
  );

• src/services/fal-client.ts:33-43 (helper)

  The searchModels() method on FalClient that performs the HTTP GET request to https://fal.ai/api/models with query parameters (keywords, limit, category) and returns the parsed JSON result as {models: FalModel[]}.

  async searchModels(params: {
      keyword: string;
      limit?: number;
      category?: string;
  }): Promise<{ models: FalModel[] }> {
      const url = new URL(`${this.BASE_URL}/models`);
      url.searchParams.set('keywords', params.keyword);
      if (params.limit != null) url.searchParams.set('limit', String(params.limit));
      if (params.category != null) url.searchParams.set('category', params.category);
      return this._getJson(url.toString()) as Promise<{ models: FalModel[] }>;
  }

• src/types/model.ts:1-35 (schema)

  The FalModelSchema Zod schema and FalModel type used for the search results. Defines the structure of a model object returned by the search.

  import { z } from 'zod';
  
  export const FalModelSchema = z.object({
      id: z.string(),
      modelId: z.string(),
      isFavorited: z.boolean(),
      title: z.string(),
      category: z.string(),
      tags: z.array(z.string()),
      shortDescription: z.string(),
      thumbnailUrl: z.string(),
      modelUrl: z.string(),
      githubUrl: z.string(),
      licenseType: z.string(),
      date: z.string(),
      group: z.object({
          key: z.string(),
          label: z.string(),
      }),
      machineType: z.string().nullable(),
      examples: z.array(z.string()),
      highlighted: z.boolean(),
      authSkippable: z.boolean(),
      unlisted: z.boolean(),
      deprecated: z.boolean(),
      resultComparison: z.boolean(),
      hidePricing: z.boolean(),
      private: z.boolean(),
      removed: z.boolean(),
      adminOnly: z.boolean(),
      kind: z.string(),
      trainingEndpoints: z.array(z.unknown()),
  });
  
  export type FalModel = z.infer<typeof FalModelSchema>;

• src/examples/list-models.ts:42-75 (helper)

  Example usage of fal-search-models tool in a test script, demonstrating how to search for 'image generation' and 'text' models with limit=5.

  console.log('\n🎨 Image generation models:');
  console.log('='.repeat(50));
  const imageModels = await client.callTool({
      name: 'fal-search-models',
      arguments: {
          keyword: 'image generation',
          limit: 5,
      },
  });
  console.log('Image models:', JSON.stringify(imageModels.content, null, 2));
  
  // Example 3: Search for text models
  console.log('\n📝 Text/Language models:');
  console.log('='.repeat(50));
  const textModels = await client.callTool({
      name: 'fal-search-models',
      arguments: {
          keyword: 'text',
          limit: 5,
      },
  });
  
  const textModelsText = ((textModels as any).content?.[0] as any)?.text as string | undefined;
  const textModelsList = textModelsText ? JSON.parse(textModelsText) : [];
  
  if (Array.isArray(textModelsList)) {
      textModelsList.forEach((model: any, index: number) => {
          console.log(`${index + 1}. ${model.title || model.modelId}`);
          console.log(`   ID: ${model.modelId}`);
          console.log(`   Category: ${model.category}`);
          console.log(`   Description: ${model.shortDescription}`);
          console.log('');
      });
  }