search

Instructions

Implementation Reference

• src/index.ts:79-160 (handler)

  The core handler logic for the 'search' tool. Processes input arguments, builds and sends a request to the Google Custom Search API (site-restricted or standard), handles errors, and returns search results as formatted JSON.

  if (request.params.name === "search") {
      const args = request.params.arguments as any;
      const {
          q,
          page = 1,
          size = 10,
          lr,
          safe = false,
          sort
      } = args;
  
      if (!q) {
          throw new Error("Missing required argument: q");
      }
      if (!API_KEY) {
          throw new Error("API_KEY is not configured");
      }
      if (!CX) {
          throw new Error("CX is not configured");
      }
  
      // Build query params
      const params = new URLSearchParams();
      params.append("key", API_KEY);
      params.append("cx", CX);
      params.append("q", q);
      params.append("fields", "items(title,htmlTitle,link,snippet,htmlSnippet)");
  
      // Language restriction
      if (lr !== undefined) {
          params.append("lr", String(lr));
      }
  
      // SafeSearch mapping (boolean only)
      if (safe !== undefined) {
          if (typeof safe !== "boolean") {
              throw new Error("SafeSearch (safe) must be a boolean");
          }
          params.append("safe", safe ? "active" : "off");
      }
  
      // Sort validation
      if (sort !== undefined) {
          if (sort === "date") {
              params.append("sort", "date");
          } else {
              throw new Error("Only 'date' is supported for sort");
          }
      }
  
      // Pagination
      params.append("num", String(size));
  
      if (page > 0 && size > 0) {
          const start = ((page - 1) * size) + 1;
          params.append("start", String(start));
      } else {
          params.append("start", "1");
      }
  
      const siteRestricted = args.siteRestricted !== undefined ? args.siteRestricted : SITE_RESTRICTED_DEFAULT;
      const endpoint = siteRestricted ? "/v1/siterestrict" : "/v1";
      const url = `${API_HOST}${endpoint}?${params.toString()}`;
      const response = await fetch(url, {
          method: "GET"
      });
  
      if (!response.ok) {
          throw new Error(`Search API request failed: ${response.status} ${response.statusText}`);
      }
  
      const result = await response.json();
  
      // Return the items array (list of articles)
      const items = result?.items ?? [];
      return {
          content: [{
              type: "text",
              text: JSON.stringify(items, null, 2)
          }]
      };
  }

• src/index.ts:43-68 (schema)

  Tool schema definition including name, description, and detailed inputSchema with properties, types, descriptions, and required fields for the 'search' tool.

  {
      name: "search",
      description: "Search the Web using Google Custom Search API",
      inputSchema: {
          type: "object",
          properties: {
              q: { type: "string", description: "Search query" },
              page: { type: "integer", description: "Page number" },
              size: { type: "integer", description: "Number of search results to return per page. Valid values are integers between 1 and 10, inclusive." },
              sort: {
                  type: "string",
                  description: "Sort expression (e.g., 'date'). Only 'date' is supported by the API."
              },
              safe: {
                  type: "boolean",
                  description: "Enable safe search filtering. Default: false."
              },
              lr: { type: "string", description: "Restricts the search to documents written in a particular language (e.g., lang_en, lang_ja)" },
              siteRestricted: {
                  type: "boolean",
                  description: "If true, use the Site Restricted API endpoint (/v1/siterestrict). If false, use the standard API endpoint (/v1). Default: true."
              },
          },
          required: ["q"]
      }
  }

• src/index.ts:40-71 (registration)

  Registers the 'search' tool with the MCP server by handling ListToolsRequestSchema and returning the tool specification in the tools array.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
          tools: [
              {
                  name: "search",
                  description: "Search the Web using Google Custom Search API",
                  inputSchema: {
                      type: "object",
                      properties: {
                          q: { type: "string", description: "Search query" },
                          page: { type: "integer", description: "Page number" },
                          size: { type: "integer", description: "Number of search results to return per page. Valid values are integers between 1 and 10, inclusive." },
                          sort: {
                              type: "string",
                              description: "Sort expression (e.g., 'date'). Only 'date' is supported by the API."
                          },
                          safe: {
                              type: "boolean",
                              description: "Enable safe search filtering. Default: false."
                          },
                          lr: { type: "string", description: "Restricts the search to documents written in a particular language (e.g., lang_en, lang_ja)" },
                          siteRestricted: {
                              type: "boolean",
                              description: "If true, use the Site Restricted API endpoint (/v1/siterestrict). If false, use the standard API endpoint (/v1). Default: true."
                          },
                      },
                      required: ["q"]
                  }
              }
          ]
      };
  });