# mnhlt/websearch-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/mnhlt/websearch-mcp
- Repository: https://github.com/mnhlt/websearch-mcp

## Overview

##### Project Type and Purpose
- Type: A backend server that implements the Model Context Protocol (MCP) to provide real-time web search capabilities.
- Purpose: It acts as a bridge between AI assistants (like Claude) and a dedicated web crawler service that performs web searches. This MCP server receives requests over stdio (or via subprocess integration) and calls out to an external WebSearch Crawler API to retrieve search results.

##### Analyzing the File Structure
- Top-level files like Dockerfile, docker-compose.yml, package.json, and smithery.yaml indicate that the project is containerized and integrates with external services.
- The src directory, containing index.ts and a test-client.ts, indicates that the server logic and testing logic are distinctly maintained.
- Presence of swagger.json suggests that the Crawler API has a defined interface, and tsconfig.json confirms the usage of TypeScript.
- The inclusion of configuration files (.gitignore, .npmignore) and deployment scripts (Dockerfile, docker-compose.yml) further points toward a production-ready service.

##### Key Components
a. WebSearch-MCP Server:
- Core component handling MCP requests. Indicate its two primary entry points:
- The primary startup (src/index.ts) which wires up the MCP server.
- The test-client (src/test-client.ts) that facilitates local testing of the server.
- Use a label like “MCP WebSearch Server (TypeScript)” and annotate its use of stdio transport for integration with clients.

b. External Crawler Service:
- WebSearch Crawler API that the MCP server interacts with.
- That this service runs separately, and is managed via docker-compose (as seen in the docker-compose.yml).
- Configuration note to show that the API is reached via the environment variable API_URL (defaulting to “http://localhost:3001”).

c. FlareSolverr Service:
- As part of the docker-compose file for the crawler, include a “FlareSolverr” component that bypasses Cloudflare protection.

d. MCP Client Integration:
- That these clients use the MCP protocol to send “web_search” commands and receive search results.

##### Relationships and Data Flow
- MCP WebSearch Server to the External Crawler Service:
- Communication between MCP clients and the WebSearch-MCP server:
- Optionally, include error or health-check flows (e.g., health endpoint calls defined in the docker-compose and README).

##### Architectural Patterns & Design Principles
- Separation of Concerns: Clearly delineate the MCP server logic from the external crawler service.
- Containerization: Emphasize that the crawler service and its dependent FlareSolverr run in isolated containers (via Docker/Docker Compose).
- Modularity: The project’s design is modular—using environment variables for configuration, which fosters easy integration and deployment management.
- Standardized Communication: Using the Model Context Protocol (MCP) ensures standardized message formats between AI assistants and the server.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "MCP Clients"
        Client["MCP Client (e.g., Claude Desktop/Cursor IDE)"]:::client
    end

    subgraph "MCP Server Layer"
        Server["MCP WebSearch Server (TypeScript)"]:::server
        TestClient["MCP WebSearch Server Test Client"]:::server
    end

    subgraph "External Services"
        Crawler["External Crawler API (Containerized Service)"]:::external
        FlareSolverr["FlareSolverr (Cloudflare Bypass Component)"]:::external
    end

    Client -->|"Request(web_search)"| Server
    Server -->|"Response_with_SearchResults"| Client
    Server -->|"HTTP_Requests/API_Calls"| Crawler
    Crawler -->|"Search_Response"| Server
    Crawler -->|"for_Cloudflare_Bypass"| FlareSolverr

    click Server "https://github.com/mnhlt/websearch-mcp/blob/main/src/index.ts"
    click TestClient "https://github.com/mnhlt/websearch-mcp/blob/main/src/test-client.ts"
    click Crawler "https://github.com/mnhlt/websearch-mcp/blob/main/docker-compose.yml"
    click FlareSolverr "https://github.com/mnhlt/websearch-mcp/blob/main/docker-compose.yml"

    classDef client fill:#a2d2ff,stroke:#000,stroke-width:1px
    classDef server fill:#caffbf,stroke:#000,stroke-width:1px
    classDef external fill:#ffadad,stroke:#000,stroke-width:1px
```
