brave_web_search
Perform web searches to gather information from diverse online sources including news, articles, and general content. Supports pagination and content filtering for comprehensive research.
Instructions
Performs a web search using the Brave Search API, ideal for general queries, news, articles, and online content. Use this for broad information gathering, recent events, or when you need diverse web sources. Supports pagination, content filtering, and freshness controls. Maximum 20 results per request, with offset for pagination.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (max 400 chars, 50 words) | |
| count | No | Number of results (1-20, default 10) | |
| offset | No | Pagination offset (max 9, default 0) |
Input Schema (JSON Schema)
{
"properties": {
"count": {
"default": 10,
"description": "Number of results (1-20, default 10)",
"type": "number"
},
"offset": {
"default": 0,
"description": "Pagination offset (max 9, default 0)",
"type": "number"
},
"query": {
"description": "Search query (max 400 chars, 50 words)",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
}
Implementation Reference
- src/brave-search/index.ts:180-211 (handler)Core implementation of the brave_web_search tool: performs API call to Brave Search, handles rate limiting, fetches web results, formats them into text output.async function performWebSearch(query: string, count: number = 10, offset: number = 0) { checkRateLimit(); const url = new URL('https://api.search.brave.com/res/v1/web/search'); url.searchParams.set('q', query); url.searchParams.set('count', Math.min(count, 20).toString()); // API limit url.searchParams.set('offset', offset.toString()); const response = await fetch(url, { headers: { 'Accept': 'application/json', 'Accept-Encoding': 'gzip', 'X-Subscription-Token': BRAVE_API_KEY } }); if (!response.ok) { throw new Error(`Brave API error: ${response.status} ${response.statusText}\n${await response.text()}`); } const data = await response.json() as BraveWeb; // Extract just web results const results = (data.web?.results || []).map(result => ({ title: result.title || '', description: result.description || '', url: result.url || '' })); return results.map(r => `Title: ${r.title}\nDescription: ${r.description}\nURL: ${r.url}` ).join('\n\n'); }
- src/brave-search/index.ts:18-37 (schema)Input schema definition for the brave_web_search tool, specifying parameters like query, count, offset.inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query (max 400 chars, 50 words)" }, count: { type: "number", description: "Number of results (1-20, default 10)", default: 10 }, offset: { type: "number", description: "Pagination offset (max 9, default 0)", default: 0 }, }, required: ["query"], },
- src/brave-search/index.ts:311-313 (registration)Registers the brave_web_search tool (as WEB_SEARCH_TOOL) in the MCP server's list of available tools.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [WEB_SEARCH_TOOL, LOCAL_SEARCH_TOOL], }));
- src/brave-search/index.ts:324-334 (handler)Tool dispatch handler: validates arguments and calls the performWebSearch function for brave_web_search.case "brave_web_search": { if (!isBraveWebSearchArgs(args)) { throw new Error("Invalid arguments for brave_web_search"); } const { query, count = 10 } = args; const results = await performWebSearch(query, count); return { content: [{ type: "text", text: results }], isError: false, }; }
- src/brave-search/index.ts:162-169 (helper)Type guard helper for validating brave_web_search input arguments.function isBraveWebSearchArgs(args: unknown): args is { query: string; count?: number } { return ( typeof args === "object" && args !== null && "query" in args && typeof (args as { query: string }).query === "string" ); }