brave_local_search

Instructions

Implementation Reference

• index.ts:220-255 (handler)

  Core handler function that executes the brave_local_search tool logic: performs API calls to Brave for local locations, retrieves POI and description data, formats results with fallback to web search.

  async function performLocalSearch(query: string, count: number = 5) {
    checkRateLimit();
    // Initial search to get location IDs
    const webUrl = new URL('https://api.search.brave.com/res/v1/web/search');
    webUrl.searchParams.set('q', query);
    webUrl.searchParams.set('search_lang', 'en');
    webUrl.searchParams.set('result_filter', 'locations');
    webUrl.searchParams.set('count', Math.min(count, 20).toString());
  
    const webResponse = await fetch(webUrl, {
      headers: {
        'Accept': 'application/json',
        'Accept-Encoding': 'gzip',
        'X-Subscription-Token': BRAVE_API_KEY
      }
    });
  
    if (!webResponse.ok) {
      throw new Error(`Brave API error: ${webResponse.status} ${webResponse.statusText}\n${await webResponse.text()}`);
    }
  
    const webData = await webResponse.json() as BraveWeb;
    const locationIds = webData.locations?.results?.filter((r): r is {id: string; title?: string} => r.id != null).map(r => r.id) || [];
  
    if (locationIds.length === 0) {
      return performWebSearch(query, count); // Fallback to web search
    }
  
    // Get POI details and descriptions in parallel
    const [poisData, descriptionsData] = await Promise.all([
      getPoisData(locationIds),
      getDescriptionsData(locationIds)
    ]);
  
    return formatLocalResults(poisData, descriptionsData);
  }

• index.ts:47-73 (registration)

  Tool registration definition including name, description, and input schema for brave_local_search.

  const LOCAL_SEARCH_TOOL: Tool = {
    name: "brave_local_search",
    description:
      "Searches for local businesses and places using Brave's Local Search API. " +
      "Best for queries related to physical locations, businesses, restaurants, services, etc. " +
      "Returns detailed information including:\n" +
      "- Business names and addresses\n" +
      "- Ratings and review counts\n" +
      "- Phone numbers and opening hours\n" +
      "Use this when the query implies 'near me' or mentions specific locations. " +
      "Automatically falls back to web search if no local results are found.",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Local search query (e.g. 'pizza near Central Park')"
        },
        count: {
          type: "number",
          description: "Number of results (1-20, default 5)",
          default: 5
        },
      },
      required: ["query"]
    }
  };

• index.ts:178-185 (schema)

  Schema validation type guard for brave_local_search arguments.

  function isBraveLocalSearchArgs(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:343-353 (handler)

  Dispatch handler case in CallToolRequestHandler for executing brave_local_search.

  case "brave_local_search": {
    if (!isBraveLocalSearchArgs(args)) {
      throw new Error("Invalid arguments for brave_local_search");
    }
    const { query, count = 5 } = args;
    const results = await performLocalSearch(query, count);
    return {
      content: [{ type: "text", text: results }],
      isError: false,
    };
  }

• index.ts:318-320 (registration)

  Registers LOCAL_SEARCH_TOOL (brave_local_search) in the list of available tools.

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