How jae-jae/g-search-mcp works
Project type and purpose
• This is an open-source MCP (Model Control Plugin) server written in Node.js/TypeScript that exposes a CLI entrypoint (npx g-search-mcp).
• Purpose: perform parallel Google searches via a headless or visible Playwright browser, return structured JSON results, and integrate as a “search” tool in Claude Desktop or other MCP-aware clients.
File structure
• Top-level:
• package.json / tsconfig.json / build scripts / Playwright install script
• src/
– index.ts: CLI argument parsing & bootstrap
– server.ts: MCP server setup and request dispatcher
– services/googleSearch.ts: high-level search orchestration (parallel queries, result aggregation)
– tools/searchGoogle.ts: low-level Playwright browser automation (open tabs, navigate, extract DOM)
– utils/logger.ts: logging abstraction
– types/index.ts: request/response type definitions
• Configuration and metadata: .github/, .gitignore, CONTRIBUTING, etc.
README for additional insights
• Confirms a single MCP command “search” with parameters: queries, limit, timeout, locale, debug.
• Describes integration with Claude Desktop via a JSON config file.
• Emphasizes Playwright-based parallel tab search, CAPTCHA handling (visible mode toggle).
Main components & their interactions
a. Components:
• CLI Entrypoint (index.ts)
• MCP Server / Dispatcher (server.ts)
• Service Layer (services/googleSearch.ts)
• Tool Layer (tools/searchGoogle.ts)
• Playwright Browser Instance (external library)
• Google Search Engine (external system)
• Client (Claude Desktop or any MCP-aware caller)
• Logger & Config & Type Definitions (supporting utilities)
b. Relationships / Data Flow:
1. Client invokes npx g-search-mcp --debug or MCP RPC call → CLI Entrypoint
2. CLI parses flags, calls Server initialization
3. Server receives “search” command payload → invokes Service Layer
4. Service Layer breaks payload into parallel tasks → calls Tool Layer for each query
5. Tool Layer uses Playwright API to open browser/page(s), navigate to Google, detect CAPTCHA, extract results → returns raw data
6. Service Layer aggregates & structures results → returns JSON to Server
7. Server serializes & writes to stdout or IPC → Client
c. Architectural patterns / design principles:
– Layered architecture (CLI → Server → Service → Tool → External)
– Single responsibility (search orchestration vs browser automation vs logging)
– Asynchronous / parallel execution model
– Pluggable tool abstraction for future search engines
d. Key technologies / frameworks / libraries:
– Node.js & TypeScript (strong typing, async/await)
– Playwright (browser automation)
– commander or similar (CLI parsing)
– JSON-based MCP protocol (stdin/stdout or IPC)