How mnhlt/websearch-mcp works
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.