firecrawl_deep_research

Instructions

{
  "name": "firecrawl_deep_research",
  "arguments": {
    "query": "What are the environmental impacts of electric vehicles compared to gasoline vehicles?",
    "maxDepth": 3,
    "timeLimit": 120,
    "maxUrls": 50
  }
}

Implementation Reference

• src/index.ts:1296-1364 (handler)

  The main handler function for the firecrawl_deep_research tool. Validates input arguments, initializes the Firecrawl client, calls the deepResearch method with query and optional parameters (maxDepth, timeLimit, maxUrls), handles activity and source logging callbacks, processes the response, and returns the final analysis as text content.

  case 'firecrawl_deep_research': {
    if (!args || typeof args !== 'object' || !('query' in args)) {
      throw new Error('Invalid arguments for firecrawl_deep_research');
    }
  
    try {
      const researchStartTime = Date.now();
      safeLog('info', `Starting deep research for query: ${args.query}`);
  
      const response = await client.deepResearch(
        args.query as string,
        {
          maxDepth: args.maxDepth as number,
          timeLimit: args.timeLimit as number,
          maxUrls: args.maxUrls as number,
          // @ts-expect-error Extended API options including origin
          origin: 'mcp-server',
        },
        // Activity callback
        (activity) => {
          safeLog(
            'info',
            `Research activity: ${activity.message} (Depth: ${activity.depth})`
          );
        },
        // Source callback
        (source) => {
          safeLog(
            'info',
            `Research source found: ${source.url}${source.title ? ` - ${source.title}` : ''}`
          );
        }
      );
  
      // Log performance metrics
      safeLog(
        'info',
        `Deep research completed in ${Date.now() - researchStartTime}ms`
      );
  
      if (!response.success) {
        throw new Error(response.error || 'Deep research failed');
      }
  
      // Format the results
      const formattedResponse = {
        finalAnalysis: response.data.finalAnalysis,
        activities: response.data.activities,
        sources: response.data.sources,
      };
  
      return {
        content: [
          {
            type: 'text',
            text: trimResponseText(formattedResponse.finalAnalysis),
          },
        ],
        isError: false,
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      return {
        content: [{ type: 'text', text: trimResponseText(errorMessage) }],
        isError: true,
      };
    }
  }

• src/index.ts:589-638 (schema)

  Defines the Tool object for firecrawl_deep_research, including name, detailed description, and inputSchema for validating parameters like query (required), maxDepth, timeLimit, and maxUrls.

  const DEEP_RESEARCH_TOOL: Tool = {
    name: 'firecrawl_deep_research',
    description: `
  Conduct deep web research on a query using intelligent crawling, search, and LLM analysis.
  
  **Best for:** Complex research questions requiring multiple sources, in-depth analysis.
  **Not recommended for:** Simple questions that can be answered with a single search; when you need very specific information from a known page (use scrape); when you need results quickly (deep research can take time).
  **Arguments:**
  - query (string, required): The research question or topic to explore.
  - maxDepth (number, optional): Maximum recursive depth for crawling/search (default: 3).
  - timeLimit (number, optional): Time limit in seconds for the research session (default: 120).
  - maxUrls (number, optional): Maximum number of URLs to analyze (default: 50).
  **Prompt Example:** "Research the environmental impact of electric vehicles versus gasoline vehicles."
  **Usage Example:**
  \`\`\`json
  {
    "name": "firecrawl_deep_research",
    "arguments": {
      "query": "What are the environmental impacts of electric vehicles compared to gasoline vehicles?",
      "maxDepth": 3,
      "timeLimit": 120,
      "maxUrls": 50
    }
  }
  \`\`\`
  **Returns:** Final analysis generated by an LLM based on research. (data.finalAnalysis); may also include structured activities and sources used in the research process.
  `,
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'The query to research',
        },
        maxDepth: {
          type: 'number',
          description: 'Maximum depth of research iterations (1-10)',
        },
        timeLimit: {
          type: 'number',
          description: 'Time limit in seconds (30-300)',
        },
        maxUrls: {
          type: 'number',
          description: 'Maximum number of URLs to analyze (1-1000)',
        },
      },
      required: ['query'],
    },
  };

• src/index.ts:963-973 (registration)

  Registers the firecrawl_deep_research tool (as DEEP_RESEARCH_TOOL) in the list of available tools returned by the ListToolsRequestSchema handler.

    tools: [
      SCRAPE_TOOL,
      MAP_TOOL,
      CRAWL_TOOL,
      CHECK_CRAWL_STATUS_TOOL,
      SEARCH_TOOL,
      EXTRACT_TOOL,
      DEEP_RESEARCH_TOOL,
      GENERATE_LLMSTXT_TOOL,
    ],
  }));