google_web_search

Instructions

Implementation Reference

• src/index.ts:204-244 (handler)

  Core handler function that performs the Google Custom Search web search, handles parameters like site restriction, rate limiting, API call, error handling, and formats results into a readable text response.

  async function performWebSearch(query: string, count: number = 5, start: number = 1, site: string = "") {
    checkRateLimit();
    
    let searchQuery = query;
    // If site is provided, append it to the query
    if (site && !query.includes("site:")) {
      searchQuery = `${query} site:${site}`;
    }
    
    const url = new URL('https://www.googleapis.com/customsearch/v1');
    url.searchParams.set('key', GOOGLE_API_KEY);
    url.searchParams.set('cx', GOOGLE_CSE_ID);
    url.searchParams.set('q', searchQuery);
    url.searchParams.set('num', Math.min(count, 10).toString()); // API limit is 10
    url.searchParams.set('start', start.toString());
  
    const response = await fetch(url, {
      headers: {
        'Accept': 'application/json',
      }
    });
  
    if (!response.ok) {
      throw new Error(`Google API error: ${response.status} ${response.statusText}\n${await response.text()}`);
    }
  
    const data = await response.json() as GoogleSearchResult;
    
    if (data.error) {
      throw new Error(`Google API error: ${data.error.code} ${data.error.message}`);
    }
  
    if (!data.items || data.items.length === 0) {
      return "No results found for your query.";
    }
  
    // Format the results
    return data.items.map((item, index) => 
      `[${index + 1}] Title: ${item.title}\nDescription: ${item.snippet}\nURL: ${item.link}`
    ).join('\n\n');
  }

• src/index.ts:186-193 (schema)

  Type guard function for validating input arguments to the google_web_search tool.

  function isGoogleWebSearchArgs(args: unknown): args is { query: string; count?: number; start?: number; site?: string } {
    return (
      typeof args === "object" &&
      args !== null &&
      "query" in args &&
      typeof (args as { query: string }).query === "string"
    );
  }

• src/index.ts:11-43 (registration)

  Tool registration object defining the name, description, and input schema for google_web_search, used in listTools response.

  const WEB_SEARCH_TOOL: Tool = {
    name: "google_web_search",
    description:
      "Performs a web search using the Google Custom 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 and filtering by site or type. " +
      "Maximum 10 results per request, with start index for pagination. ",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search query"
        },
        count: {
          type: "number",
          description: "Number of results (1-10, default 5)",
          default: 5
        },
        start: {
          type: "number",
          description: "Pagination start index (default 1)",
          default: 1
        },
        site: {
          type: "string",
          description: "Optional: Limit search to specific site (e.g., 'site:example.com')",
          default: ""
        },
      },
      required: ["query"],
    },
  };

• src/index.ts:297-307 (handler)

  Dispatch handler case within CallToolRequestSchema that validates arguments and invokes the performWebSearch function for google_web_search.

  case "google_web_search": {
    if (!isGoogleWebSearchArgs(args)) {
      throw new Error("Invalid arguments for google_web_search");
    }
    const { query, count = 5, start = 1, site = "" } = args;
    const results = await performWebSearch(query, count, start, site);
    return {
      content: [{ type: "text", text: results }],
      isError: false,
    };
  }

• src/index.ts:285-286 (registration)

  Server request handler for ListToolsRequestSchema that registers and exposes the google_web_search tool.

    tools: [WEB_SEARCH_TOOL, IMAGE_SEARCH_TOOL],
  }));