google-search

Executes real Google searches using Playwright browser automation while implementing multiple anti-detection strategies (user-agent rotation, viewport randomization, request throttling, browser state persistence) to bypass Google's anti-scraping mechanisms. The core googleSearch() function in src/search.ts orchestrates browser navigation, DOM waiting, and result extraction without relying on external SERP APIs, enabling unlimited searches without rate limits or API quotas.

Wraps the core googleSearch() function as a Model Context Protocol (MCP) server using the MCP SDK, enabling AI assistants like Claude to invoke Google searches via standardized tool-calling interface. The mcp-server.ts component manages McpServer instance, StdioServerTransport for stdio communication, and a global persistent Playwright browser to serve multiple search requests from a single AI session without browser restart overhead.

Exposes search functionality via CLI using the commander package (src/index.ts) with options for result limit, timeout, headless mode toggle, browser state file path, and HTML extraction modes. Parses command-line arguments and invokes the core googleSearch() function with validated parameters, supporting both structured JSON output and raw HTML retrieval for downstream processing.

Saves and restores Playwright browser state (cookies, localStorage, sessionStorage) to a JSON file (default ./browser-state.json) between search invocations. This stateful approach preserves Google's session context and reduces CAPTCHA triggers by maintaining browser identity across multiple searches, unlike stateless HTTP clients that appear as fresh visitors to Google on each request.

Parses Google search result DOM using Playwright's page.locator() and evaluate() methods to extract structured data (title, link, snippet) from each result element. Returns SearchResponse JSON array with typed fields, enabling downstream processing without regex parsing or HTML string manipulation. Extraction logic handles Google's dynamic DOM structure and adapts to layout variations.

Provides --get-html flag to return raw HTML string of search results page and --save-html flag to capture and save full page screenshot/HTML to disk. Enables custom parsing, archival, or visual debugging workflows where structured extraction is insufficient. Playwright's page.content() and page.screenshot() methods handle full-page capture including dynamic content.

Exposes --timeout <milliseconds> (default 60000) and --no-headless CLI options to control Playwright browser behavior. Timeout parameter sets page navigation and element waiting limits; --no-headless disables headless mode to show visible browser window for debugging. Enables developers to tune performance vs. reliability and visually inspect search execution.

Implements logging via Pino logger (src/logger.ts) with structured JSON output, enabling developers to track search execution flow, anti-bot detection events, and errors. Logs include timestamps, log levels, and contextual data suitable for parsing by log aggregation systems (ELK, Datadog, CloudWatch). Supports configurable log levels for production vs. development environments.

Defines typed interfaces (src/types.ts) for SearchResponse (array of {title, link, snippet} objects) and HtmlResponse (raw HTML string) using TypeScript. Enables type-safe consumption of search results in TypeScript applications and provides IDE autocomplete for result fields. Type definitions document expected output structure and catch type errors at compile time.

Implements anti-bot evasion through user-agent rotation (randomizing User-Agent header), viewport randomization (varying browser window size), and request throttling (adding delays between navigation and interactions). These strategies operate at the Playwright browser level, making searches appear as legitimate user traffic rather than automated bots. Combines multiple evasion techniques to increase success rate against Google's detection heuristics.