web_search
Perform real-time web searches to retrieve up-to-date information, news, blogs, or details about companies, products, events, or people. Configure results by language, region, domains, or result type for precise data retrieval.
Instructions
Search the web for information. Use this tool when you need to search the web for information. You can use this tool to search for news, blogs, or all types of information. You can also use this tool to search for information about a specific company or product. You can also use this tool to search for information about a specific person. You can also use this tool to search for information about a specific product. You can also use this tool to search for information about a specific company. You can also use this tool to search for information about a specific event. You can also use this tool to search for information about a specific location. You can also use this tool to search for information about a specific thing. If you request search with 1 result number and failed, retry with bigger results number.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| excludeDomains | No | Domains to exclude from results | |
| excludeTerms | No | Terms to exclude from results | |
| includeDomains | No | Only include these domains in results | |
| language | No | Language code for search results (e.g., 'en') | |
| numResults | No | Number of results to return (default: 5) | |
| query | Yes | The search query to look up | |
| region | No | Region code for search results (e.g., 'us') | |
| resultType | No | Type of results to return |
Implementation Reference
- src/index.ts:98-171 (handler)The handler function that executes the web_search tool logic. It prepares a crawl request, sends it to an external API using axios, formats the results into a JSON string, and returns them as MCP content. Handles errors appropriately.
async (params) => { try { console.error(`Performing web search for: ${params.query}`); // Prepare request payload for crawler API const requestPayload: CrawlRequest = { query: params.query, numResults: params.numResults ?? MAX_SEARCH_RESULT, language: params.language, region: params.region, filters: { excludeDomains: params.excludeDomains, includeDomains: params.includeDomains, excludeTerms: params.excludeTerms, resultType: params.resultType as "all" | "news" | "blogs", }, }; // Call the crawler API console.error(`Sending request to ${API_URL}/crawl`); const response = await axios.post<CrawlResponse>( `${API_URL}/crawl`, requestPayload ); // Format the response for the MCP client const results = response.data.results.map((result) => ({ title: result.title, snippet: result.excerpt, text: result.text, url: result.url, siteName: result.siteName || "", byline: result.byline || "", })); return { content: [ { type: "text", text: JSON.stringify( { query: response.data.query, results: results, }, null, 2 ), }, ], }; } catch (error) { console.error("Error performing web search:", error); if (axios.isAxiosError(error)) { const errorMessage = error.response?.data?.error || error.message; return { content: [{ type: "text", text: `Error: ${errorMessage}` }], isError: true, }; } return { content: [ { type: "text", text: `Error: ${ error instanceof Error ? error.message : "Unknown error" }`, }, ], isError: true, }; } } - src/index.ts:65-97 (schema)Input schema for the web_search tool defined using Zod validators for parameters like query, numResults, language, region, filters, etc.
{ query: z.string().describe("The search query to look up"), numResults: z .number() .optional() .describe( `Number of results to return (default: ${MAX_SEARCH_RESULT})` ), language: z .string() .optional() .describe("Language code for search results (e.g., 'en')"), region: z .string() .optional() .describe("Region code for search results (e.g., 'us')"), excludeDomains: z .array(z.string()) .optional() .describe("Domains to exclude from results"), includeDomains: z .array(z.string()) .optional() .describe("Only include these domains in results"), excludeTerms: z .array(z.string()) .optional() .describe("Terms to exclude from results"), resultType: z .enum(["all", "news", "blogs"]) .optional() .describe("Type of results to return"), }, - src/index.ts:52-172 (registration)Registration of the 'web_search' tool on the MCP server using server.tool(), including description, input schema, and handler function.
server.tool( "web_search", "Search the web for information.\n" + "Use this tool when you need to search the web for information.\n" + "You can use this tool to search for news, blogs, or all types of information.\n" + "You can also use this tool to search for information about a specific company or product.\n" + "You can also use this tool to search for information about a specific person.\n" + "You can also use this tool to search for information about a specific product.\n" + "You can also use this tool to search for information about a specific company.\n" + "You can also use this tool to search for information about a specific event.\n" + "You can also use this tool to search for information about a specific location.\n" + "You can also use this tool to search for information about a specific thing.\n" + "If you request search with 1 result number and failed, retry with bigger results number.", { query: z.string().describe("The search query to look up"), numResults: z .number() .optional() .describe( `Number of results to return (default: ${MAX_SEARCH_RESULT})` ), language: z .string() .optional() .describe("Language code for search results (e.g., 'en')"), region: z .string() .optional() .describe("Region code for search results (e.g., 'us')"), excludeDomains: z .array(z.string()) .optional() .describe("Domains to exclude from results"), includeDomains: z .array(z.string()) .optional() .describe("Only include these domains in results"), excludeTerms: z .array(z.string()) .optional() .describe("Terms to exclude from results"), resultType: z .enum(["all", "news", "blogs"]) .optional() .describe("Type of results to return"), }, async (params) => { try { console.error(`Performing web search for: ${params.query}`); // Prepare request payload for crawler API const requestPayload: CrawlRequest = { query: params.query, numResults: params.numResults ?? MAX_SEARCH_RESULT, language: params.language, region: params.region, filters: { excludeDomains: params.excludeDomains, includeDomains: params.includeDomains, excludeTerms: params.excludeTerms, resultType: params.resultType as "all" | "news" | "blogs", }, }; // Call the crawler API console.error(`Sending request to ${API_URL}/crawl`); const response = await axios.post<CrawlResponse>( `${API_URL}/crawl`, requestPayload ); // Format the response for the MCP client const results = response.data.results.map((result) => ({ title: result.title, snippet: result.excerpt, text: result.text, url: result.url, siteName: result.siteName || "", byline: result.byline || "", })); return { content: [ { type: "text", text: JSON.stringify( { query: response.data.query, results: results, }, null, 2 ), }, ], }; } catch (error) { console.error("Error performing web search:", error); if (axios.isAxiosError(error)) { const errorMessage = error.response?.data?.error || error.message; return { content: [{ type: "text", text: `Error: ${errorMessage}` }], isError: true, }; } return { content: [ { type: "text", text: `Error: ${ error instanceof Error ? error.message : "Unknown error" }`, }, ], isError: true, }; } } ); - src/index.ts:13-42 (schema)TypeScript interfaces defining the structure for crawl requests, results, and responses used internally by the web_search handler.
interface CrawlRequest { query: string; numResults?: number; language?: string; region?: string; filters?: { excludeDomains?: string[]; includeDomains?: string[]; excludeTerms?: string[]; resultType?: "all" | "news" | "blogs"; }; } interface CrawlResult { url: string; title: string; excerpt: string; text?: string; html?: string; siteName?: string; byline?: string; error?: string | null; } interface CrawlResponse { query: string; results: CrawlResult[]; error: string | null; }