search
Perform web searches via Google Custom Search API, enabling precise querying, result filtering, and pagination for relevant, tailored information retrieval.
Instructions
Search the Web using Google Custom Search API
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lr | No | Restricts the search to documents written in a particular language (e.g., lang_en, lang_ja) | |
| page | No | Page number | |
| q | Yes | Search query | |
| safe | No | Enable safe search filtering. Default: false. | |
| siteRestricted | No | If true, use the Site Restricted API endpoint (/v1/siterestrict). If false, use the standard API endpoint (/v1). Default: true. | |
| size | No | Number of search results to return per page. Valid values are integers between 1 and 10, inclusive. | |
| sort | No | Sort expression (e.g., 'date'). Only 'date' is supported by the API. |
Input Schema (JSON Schema)
{
"properties": {
"lr": {
"description": "Restricts the search to documents written in a particular language (e.g., lang_en, lang_ja)",
"type": "string"
},
"page": {
"description": "Page number",
"type": "integer"
},
"q": {
"description": "Search query",
"type": "string"
},
"safe": {
"description": "Enable safe search filtering. Default: false.",
"type": "boolean"
},
"siteRestricted": {
"description": "If true, use the Site Restricted API endpoint (/v1/siterestrict). If false, use the standard API endpoint (/v1). Default: true.",
"type": "boolean"
},
"size": {
"description": "Number of search results to return per page. Valid values are integers between 1 and 10, inclusive.",
"type": "integer"
},
"sort": {
"description": "Sort expression (e.g., 'date'). Only 'date' is supported by the API.",
"type": "string"
}
},
"required": [
"q"
],
"type": "object"
}
Implementation Reference
- src/index.ts:79-160 (handler)Executes the 'search' tool by querying the Google Custom Search API with user-provided parameters (query, page, size, etc.), handling validation, constructing the API request, fetching results, and returning formatted JSON output.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 (registration)Registers the 'search' tool in the ListToolsRequestSchema handler, providing name, description, and detailed input schema for parameters like query (q), pagination, sorting, safety filters, language, and site restriction.{ 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:46-66 (schema)Input schema definition for the 'search' tool, specifying types, descriptions, and requirements for parameters such as q (required string), page, size, sort, safe, lr, and siteRestricted.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"]