firecrawl_map

Instructions

{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com"
  }
}

Implementation Reference

• src/index.ts:954-966 (registration)

  Registration of MAP_TOOL (firecrawl_map) in the ListToolsRequestSchema handler, making it available for calls.

  // Tool handlers
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      SCRAPE_TOOL,
      MAP_TOOL,
      CRAWL_TOOL,
      CHECK_CRAWL_STATUS_TOOL,
      SEARCH_TOOL,
      EXTRACT_TOOL,
      DEEP_RESEARCH_TOOL,
      GENERATE_LLMSTXT_TOOL,
    ],
  }));

• src/index.ts:196-246 (schema)

  MAP_TOOL definition with inputSchema for firecrawl_map tool. Defines parameters: url (required), search, ignoreSitemap, sitemapOnly, includeSubdomains, limit.

  const MAP_TOOL: Tool = {
    name: 'firecrawl_map',
    description: `
  Map a website to discover all indexed URLs on the site.
  
  **Best for:** Discovering URLs on a website before deciding what to scrape; finding specific sections of a website.
  **Not recommended for:** When you already know which specific URL you need (use scrape or batch_scrape); when you need the content of the pages (use scrape after mapping).
  **Common mistakes:** Using crawl to discover URLs instead of map.
  **Prompt Example:** "List all URLs on example.com."
  **Usage Example:**
  \`\`\`json
  {
    "name": "firecrawl_map",
    "arguments": {
      "url": "https://example.com"
    }
  }
  \`\`\`
  **Returns:** Array of URLs found on the site.
  `,
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'Starting URL for URL discovery',
        },
        search: {
          type: 'string',
          description: 'Optional search term to filter URLs',
        },
        ignoreSitemap: {
          type: 'boolean',
          description: 'Skip sitemap.xml discovery and only use HTML links',
        },
        sitemapOnly: {
          type: 'boolean',
          description: 'Only use sitemap.xml for discovery, ignore HTML links',
        },
        includeSubdomains: {
          type: 'boolean',
          description: 'Include URLs from subdomains in results',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of URLs to return',
        },
      },
      required: ['url'],
    },
  };

• src/index.ts:1076-1098 (handler)

  Handler logic for 'firecrawl_map' case in CallToolRequestSchema. Validates args via isMapOptions, calls client.mapUrl(), and returns links joined by newlines.

  case 'firecrawl_map': {
    if (!isMapOptions(args)) {
      throw new Error('Invalid arguments for firecrawl_map');
    }
    const { url, ...options } = args;
    const response = await client.mapUrl(url, {
      ...options,
      // @ts-expect-error Extended API options including origin
      origin: 'mcp-server',
    });
    if ('error' in response) {
      throw new Error(response.error);
    }
    if (!response.links) {
      throw new Error('No links received from Firecrawl API');
    }
    return {
      content: [
        { type: 'text', text: trimResponseText(response.links.join('\n')) },
      ],
      isError: false,
    };
  }

• src/index.ts:787-794 (helper)

  isMapOptions type guard: validates that args is an object with a string 'url' property (MapParams & { url: string }).

  function isMapOptions(args: unknown): args is MapParams & { url: string } {
    return (
      typeof args === 'object' &&
      args !== null &&
      'url' in args &&
      typeof (args as { url: unknown }).url === 'string'
    );
  }

• src/index.ts:1463-1465 (helper)

  trimResponseText utility used in the map handler to trim whitespace from response text.

  function trimResponseText(text: string): string {
    return text.trim();
  }