firecrawl_search

Instructions

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "top AI companies",
    "limit": 5,
    "sources": [
      "web"
    ]
  }
}

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "latest AI research papers 2023",
    "limit": 5,
    "lang": "en",
    "country": "us",
    "sources": [
      "web",
      "images",
      "news"
    ],
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}

Implementation Reference

• src/index.ts:433-446 (handler)

  The execute handler for the firecrawl_search tool, which uses the Firecrawl client to perform the search, cleans options, logs the query, and returns the result as JSON string.

  execute: async (
    args: unknown,
    { session, log }: { session?: SessionData; log: Logger }
  ): Promise<string> => {
    const client = getClient(session);
    const { query, ...opts } = args as Record<string, unknown>;
    const cleaned = removeEmptyTopLevel(opts as Record<string, unknown>);
    log.info('Searching', { query: String(query) });
    const res = await client.search(query as string, {
      ...(cleaned as any),
      origin: ORIGIN,
    });
    return asText(res);
  },

• src/index.ts:422-432 (schema)

  Zod schema defining the input parameters for firecrawl_search, including query, limit, sources, and optional scrapeOptions referencing the shared scrapeParamsSchema.

  parameters: z.object({
    query: z.string().min(1),
    limit: z.number().optional(),
    tbs: z.string().optional(),
    filter: z.string().optional(),
    location: z.string().optional(),
    sources: z
      .array(z.object({ type: z.enum(['web', 'images', 'news']) }))
      .optional(),
    scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional(),
  }),

• src/index.ts:185-260 (schema)

  Shared scrapeParamsSchema used by firecrawl_search via scrapeOptions for configuring scraping behavior on search results.

  const scrapeParamsSchema = z.object({
    url: z.string().url(),
    formats: z
      .array(
        z.union([
          z.enum([
            'markdown',
            'html',
            'rawHtml',
            'screenshot',
            'links',
            'summary',
            'changeTracking',
            'branding',
          ]),
          z.object({
            type: z.literal('json'),
            prompt: z.string().optional(),
            schema: z.record(z.string(), z.any()).optional(),
          }),
          z.object({
            type: z.literal('screenshot'),
            fullPage: z.boolean().optional(),
            quality: z.number().optional(),
            viewport: z
              .object({ width: z.number(), height: z.number() })
              .optional(),
          }),
        ])
      )
      .optional(),
    parsers: z
      .array(
        z.union([
          z.enum(['pdf']),
          z.object({
            type: z.enum(['pdf']),
            maxPages: z.number().int().min(1).max(10000).optional(),
          }),
        ])
      )
      .optional(),
    onlyMainContent: z.boolean().optional(),
    includeTags: z.array(z.string()).optional(),
    excludeTags: z.array(z.string()).optional(),
    waitFor: z.number().optional(),
    ...(SAFE_MODE
      ? {}
      : {
          actions: z
            .array(
              z.object({
                type: z.enum(allowedActionTypes),
                selector: z.string().optional(),
                milliseconds: z.number().optional(),
                text: z.string().optional(),
                key: z.string().optional(),
                direction: z.enum(['up', 'down']).optional(),
                script: z.string().optional(),
                fullPage: z.boolean().optional(),
              })
            )
            .optional(),
        }),
    mobile: z.boolean().optional(),
    skipTlsVerification: z.boolean().optional(),
    removeBase64Images: z.boolean().optional(),
    location: z
      .object({
        country: z.string().optional(),
        languages: z.array(z.string()).optional(),
      })
      .optional(),
    storeInCache: z.boolean().optional(),
    maxAge: z.number().optional(),
  });

• src/index.ts:360-360 (registration)

  Tool registration within server.addTool call specifying the name 'firecrawl_search'.

  name: 'firecrawl_search',

• src/index.ts:142-162 (helper)

  Helper function getClient used in the handler to create and return the FirecrawlApp client instance based on session and env.

  function getClient(session?: SessionData): FirecrawlApp {
    // For cloud service, API key is required
    if (process.env.CLOUD_SERVICE === 'true') {
      if (!session || !session.firecrawlApiKey) {
        throw new Error('Unauthorized');
      }
      return createClient(session.firecrawlApiKey);
    }
  
    // For self-hosted instances, API key is optional if FIRECRAWL_API_URL is provided
    if (
      !process.env.FIRECRAWL_API_URL &&
      (!session || !session.firecrawlApiKey)
    ) {
      throw new Error(
        'Unauthorized: API key is required when not using a self-hosted instance'
      );
    }
  
    return createClient(session?.firecrawlApiKey);
  }