Earch MCP

Instructions

Implementation Reference

• src/index.ts:115-120 (handler)

  The async handler function for the 'local.descriptions' tool. It constructs a URLSearchParams from the input ids array and fetches AI descriptions from the Brave Local Search API endpoint, returning the JSON response as text content.

  async handler(args) {
    const usp = new URLSearchParams();
    for (const id of args.ids as string[]) usp.append('ids', id);
    const data = await braveGet('https://api.search.brave.com/res/v1/local/descriptions', Object.fromEntries(usp.entries()));
    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
  },

• src/index.ts:29-41 (schema)

  Input schema definition for the 'ids' array parameter, requiring 1-20 string location IDs. Shared with 'local.pois' tool.

  const idsArraySchema = {
    type: 'object',
    properties: {
      ids: {
        type: 'array',
        items: { type: 'string' },
        minItems: 1,
        maxItems: 20,
      },
    },
    required: ['ids'],
    additionalProperties: false,
  } as const;

• src/index.ts:111-121 (registration)

  The tool definition object registered in the toolDefs array, including name, description, inputSchema reference, and inline handler.

  {
    name: 'local.descriptions',
    description: 'Brave Local Search AI descriptions: fetch descriptions for up to 20 location ids',
    inputSchema: idsArraySchema,
    async handler(args) {
      const usp = new URLSearchParams();
      for (const id of args.ids as string[]) usp.append('ids', id);
      const data = await braveGet('https://api.search.brave.com/res/v1/local/descriptions', Object.fromEntries(usp.entries()));
      return { content: [{ type: 'text', text: JSON.stringify(data) }] };
    },
  },

• src/index.ts:51-74 (helper)

  Utility function to make authenticated fetch requests to Brave Search APIs, handling params, API key from env, and error cases. Used by all tool handlers including 'local.descriptions'.

  async function braveGet(url: string, params: Record<string, string | number | boolean | undefined>) {
    const apiKey = process.env.EARCH_MCP_API_KEY || process.env.BRAVE_API_KEY || process.env.BRAVE_SEARCH_API_KEY;
    if (!apiKey) {
      throw new Error('Missing API key. Set EARCH_MCP_API_KEY or BRAVE_API_KEY.');
    }
    const headers: Record<string, string> = {
      Accept: 'application/json',
      'Accept-Encoding': 'gzip',
      'X-Subscription-Token': apiKey,
    };
  
    const usp = new URLSearchParams();
    for (const [k, v] of Object.entries(params)) {
      if (v === undefined) continue;
      usp.set(k, String(v));
    }
    const endpoint = `${url}?${usp.toString()}`;
    const res = await fetch(endpoint, { headers });
    if (!res.ok) {
      const body = await res.text().catch(() => '');
      throw new Error(`Brave API error ${res.status}: ${body}`);
    }
    return res.json();
  }