brave_web_search

Instructions

Implementation Reference

• index.ts:187-218 (handler)

  Core implementation of the brave_web_search tool: performs API call to Brave Search, handles response, extracts and formats web search results.

  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');
  }

• index.ts:331-341 (handler)

  MCP CallTool handler case for brave_web_search: validates arguments and calls performWebSearch.

  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,
    };
  }

• index.ts:18-45 (schema)

  Tool schema definition for brave_web_search, including name, description, and JSON schema for inputs.

  const WEB_SEARCH_TOOL: Tool = {
    name: "brave_web_search",
    description:
      "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. ",
    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"],
    },
  };

• index.ts:169-176 (schema)

  Type guard function for validating brave_web_search 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"
    );
  }

• index.ts:318-320 (registration)

  Registers brave_web_search (via WEB_SEARCH_TOOL) in the MCP listTools handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [WEB_SEARCH_TOOL, LOCAL_SEARCH_TOOL],
  }));