# jae-jae/g-search-mcp architecture

> Architecture diagram of the GitHub repository jae-jae/g-search-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jae-jae/g-search-mcp
- Repository: https://github.com/jae-jae/g-search-mcp

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Client["Claude Desktop"]:::externalSys

    %% Internal Code Modules
    CLI["CLI Entrypoint\n(index.ts)"]:::internal
    Server["MCP Server\n(server.ts)"]:::internal
    Service["Service Layer\n(googleSearch.ts)"]:::internal
    ToolsEntry["Tools Module\n(index.ts)"]:::internal

    subgraph "Parallel Execution"
        ToolsA["Tool Layer\n(searchGoogle.ts)"]:::internal
        ToolsB["Tool Layer\n(searchGoogle.ts)"]:::internal
    end

    %% External Libraries and Systems
    Playwright["Playwright\n(browser)"]:::externalLib
    Google["Google Search"]:::externalSys

    %% Utilities
    Logger["Logger Utility\n(logger.ts)"]:::utility
    Types["Type Definitions\n(types/index.ts)"]:::utility
    Config1["package.json"]:::utility
    Config2["tsconfig.json"]:::utility

    %% Data Flows
    Client -->|"invoke command/MCP call"| CLI
    CLI -->|"SearchRequest"| Server
    Server -->|"SearchRequest"| Service
    Service -->|"for each query"| ToolsEntry
    ToolsEntry -->|"invoke tool"| ToolsA
    ToolsEntry -->|"invoke tool"| ToolsB
    ToolsA -->|"Playwright API calls"| Playwright
    ToolsB -->|"Playwright API calls"| Playwright
    Playwright -->|"HTTP requests"| Google
    Google -->|"RawHTML"| Playwright
    Playwright -->|"RawData"| ToolsA
    Playwright -->|"RawData"| ToolsB
    ToolsA -->|"RawData"| Service
    ToolsB -->|"RawData"| Service
    Service -->|"StructuredResults"| Server
    Server -->|"JSON Response"| CLI
    CLI -->|"stdout/IPC"| Client

    %% Utility Dependencies
    Logger -.-> CLI
    Logger -.-> Server
    Logger -.-> Service
    Logger -.-> ToolsEntry
    Logger -.-> ToolsA
    Logger -.-> ToolsB

    Types -.-> CLI
    Types -.-> Server
    Types -.-> Service
    Types -.-> ToolsEntry
    Types -.-> ToolsA
    Types -.-> ToolsB

    Config1 -.-> CLI
    Config1 -.-> Server
    Config2 -.-> CLI
    Config2 -.-> Server

    %% Click Events
    click CLI "https://github.com/jae-jae/g-search-mcp/blob/main/src/index.ts"
    click Server "https://github.com/jae-jae/g-search-mcp/blob/main/src/server.ts"
    click Service "https://github.com/jae-jae/g-search-mcp/blob/main/src/services/googleSearch.ts"
    click ToolsEntry "https://github.com/jae-jae/g-search-mcp/blob/main/src/tools/index.ts"
    click ToolsA "https://github.com/jae-jae/g-search-mcp/blob/main/src/tools/searchGoogle.ts"
    click ToolsB "https://github.com/jae-jae/g-search-mcp/blob/main/src/tools/searchGoogle.ts"
    click Logger "https://github.com/jae-jae/g-search-mcp/blob/main/src/utils/logger.ts"
    click Types "https://github.com/jae-jae/g-search-mcp/blob/main/src/types/index.ts"
    click Config1 "https://github.com/jae-jae/g-search-mcp/blob/main/package.json"
    click Config2 "https://github.com/jae-jae/g-search-mcp/blob/main/tsconfig.json"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef externalLib fill:#90EE90,stroke:#000,stroke-width:1px
    classDef externalSys fill:#FFA500,stroke:#000,stroke-width:1px
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:1px
```
