mcp-google-custom-search: Instructions file for Claude Code

CLAUDE.md — mcp-google-custom-search

MCP server for the Google Custom Search JSON API (TypeScript, stdio). Read-only end to end: search (web), search_images and the raw_request escape hatch all hit the API's single GET endpoint customsearch/v1 on https://customsearch.googleapis.com. Auth is a static Google Cloud API key sent in the X-Goog-Api-Key header (no OAuth, no scopes, no token refresh) plus a Programmable Search Engine id (cx) — configured as the default engine or passed per call as engine_id. The API has no write endpoint; nothing here can modify data.

Commands

npm run dev        # run from source (tsx watch)
npm test           # unit tests + dist smoke, no network
npm run typecheck  # types for src + tests
npm run build      # emit dist/
npm run smoke      # live READ-ONLY check: one 1-result search (argv/GOOGLE_CUSTOM_SEARCH_SMOKE_QUERY)

Architecture

• src/config.ts — env → config. Credentials: GOOGLE_CUSTOM_SEARCH_API_KEY (the key — required for anything to work) + GOOGLE_CUSTOM_SEARCH_ENGINE_ID (the default cx; addressing, not a credential — tools can override it per call); optional GOOGLE_CUSTOM_SEARCH_API_BASE, GOOGLE_CUSTOM_SEARCH_TIMEOUT_MS, GOOGLE_CUSTOM_SEARCH_MAX_RETRIES. No credentials at all is NOT an error: the fields stay undefined and the server starts degraded. An engine id without a key throws ConfigError incomplete_config (the key cannot come per call, so that install can never work). Also home to CredentialsError / MISSING_CREDENTIALS_MESSAGE (names both variables and the restart), EngineIdError / MISSING_ENGINE_ID_MESSAGE (missing cx: fix per call via engine_id or via the env var + restart) and hasCredentials() (= the key is present).
• src/client.ts — all HTTP and all wire mapping. apiKey() throws CredentialsError before any fetch; resolveEngineId() prefers the per-call override and throws a typed EngineIdError (naming both the env var and the engine_id parameter) when neither exists; request() resolves the path against the base and rejects foreign origins (SSRF guard), sends the key in the X-Goog-Api-Key header (never the URL), fills in the configured cx when the path has none, enforces an AbortController timeout that also covers reading the body, retries 429 and 5xx/network errors with backoff honoring Retry-After in both RFC 9110 forms — delta-seconds and HTTP-date (every request is an idempotent GET — this API has no writes an ambiguous failure could duplicate) and throws GoogleCustomSearchError(status, body). buildSearchQuery() / buildImageSearchQuery() map the normalized vocabulary to the wire parameters (lr=lang_<code>, cr=country<CC>, siteSearchFilter i/e, filter 0/1, uppercase imgSize, searchType=image); normalizeSearchResponse() reduces the envelope to query/totals/cursors/items with title-url-snippet-metadata (pagemap only on request).
• src/tools/search.ts — search, plus the shared searchInputFields() schema factory and the toSearchParams() rename that images.ts reuses. src/tools/images.ts — search_images. src/tools/raw.ts — raw_request (GET only; the API has no other verbs). src/tools/util.ts — ok/fail, the four annotation presets (READ_ONLY/WRITE/UPDATE/DESTRUCTIVE; only READ_ONLY is in use — see conventions) shared zod schema factories (querySchema, numSchema, startSchema, languageCodeSchema, countryCodeSchema, dateRestrictSchema, engineIdSchema) and checkPageWindow (the cross-field start + num - 1 <= 100 guard the flat zod shapes cannot express — called by both search tools before the client, so an impossible window never burns a quota unit on a guaranteed 400).
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded() catches ConfigError, pings startup_failed (fire-and-forget) and degrades the config to "no credentials"; an unconfigured start prepends UNCONFIGURED_PREFIX — plus Configuration problem: <message> when a ConfigError was caught — to the initialize instructions, and oninitialized sends server_start for a configured install or unconfigured_start (with the reason) otherwise.
• src/telemetry.ts — anonymous usage pings (ids/names/versions only, never queries, results or arguments; fire-and-forget, must never block or throw; opt-out ASKADS_TELEMETRY=0). server_start means "a usable install started"; unconfigured_start is a degraded start and startup_failed a malformed config caught at load — both carry a reason from a closed vocabulary (missing_credentials, incomplete_config) — never a variable's name or value.