crawleo-mcp

Instructions

Implementation Reference

• src/index.ts:107-142 (handler)

  The asynchronous handler function that executes the search_web tool. It invokes makeSearchRequest with user arguments, returns JSON-formatted results or an error response.

  async (args) => {
    try {
      const result = await makeSearchRequest<Record<string, unknown>>({
        query: args.query,
        max_pages: args.max_pages,
        setLang: args.setLang,
        cc: args.cc,
        geolocation: args.geolocation,
        device: args.device,
        enhanced_html: args.enhanced_html,
        raw_html: args.raw_html,
        page_text: args.page_text,
        markdown: args.markdown,
      });
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
      return {
        content: [
          {
            type: "text" as const,
            text: `Error performing search: ${errorMessage}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:21-32 (schema)

  Zod input schema for the search_web tool, defining parameters like query, max_pages, language, geolocation, device, and content format options.

  const WebSearchSchema = z.object({
    query: z.string().describe("Search query term. The main keyword or phrase to search for."),
    max_pages: z.number().optional().default(1).describe("Max result pages to crawl. Each page costs 1 credit. Min: 1"),
    setLang: z.string().optional().default("en").describe("Language code for search interface (e.g., 'en', 'es', 'fr', 'ar')"),
    cc: z.string().optional().describe("Country code for search results (e.g., 'US', 'GB', 'DE', 'EG')"),
    geolocation: z.enum(["random", "pl", "gb", "jp", "de", "fr", "es", "us"]).optional().default("random").describe("Geo location for search"),
    device: z.enum(["desktop", "mobile", "tablet"]).optional().default("desktop").describe("Device simulation"),
    enhanced_html: z.boolean().optional().default(true).describe("Return AI-enhanced, cleaned HTML optimized for processing"),
    raw_html: z.boolean().optional().default(false).describe("Return original, unprocessed HTML of the page"),
    page_text: z.boolean().optional().default(false).describe("Return extracted plain text without HTML tags"),
    markdown: z.boolean().optional().default(true).describe("Return content in Markdown format for easy parsing"),
  });

• src/index.ts:103-143 (registration)

  Registration of the search_web tool on the MCP server, specifying name, description, input schema, and handler function.

  server.tool(
    "search_web",
    "Search the web using Crawleo's AI-powered search engine. Returns results with optional AI-enhanced HTML, markdown content, and structured data.",
    WebSearchSchema.shape,
    async (args) => {
      try {
        const result = await makeSearchRequest<Record<string, unknown>>({
          query: args.query,
          max_pages: args.max_pages,
          setLang: args.setLang,
          cc: args.cc,
          geolocation: args.geolocation,
          device: args.device,
          enhanced_html: args.enhanced_html,
          raw_html: args.raw_html,
          page_text: args.page_text,
          markdown: args.markdown,
        });
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
        return {
          content: [
            {
              type: "text" as const,
              text: `Error performing search: ${errorMessage}`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/index.ts:43-71 (helper)

  Helper function to make authenticated GET requests to the Crawleo web search API endpoint, building query parameters and handling errors.

  async function makeSearchRequest<T>(
    params: Record<string, unknown>
  ): Promise<T> {
    const apiKey = getApiKey();
    
    // Build query string from params
    const queryParams = new URLSearchParams();
    for (const [key, value] of Object.entries(params)) {
      if (value !== undefined && value !== null) {
        queryParams.append(key, String(value));
      }
    }
    
    const url = `${API_BASE_URL}/search?${queryParams.toString()}`;
    
    const response = await fetch(url, {
      method: "GET",
      headers: {
        "x-api-key": apiKey,
      },
    });
  
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`API request failed: ${response.status} - ${errorText}`);
    }
  
    return response.json() as Promise<T>;
  }