SearXNG

Executes web searches against a SearXNG metasearch engine instance via HTTP requests, supporting pagination, time-based filtering (last day/week/month/year), language selection, and safe search controls. The implementation constructs parameterized queries to the SearXNG API endpoint and parses JSON responses containing ranked search results with titles, URLs, and snippets, enabling AI clients to retrieve current web information without direct search engine API dependencies.

Fetches arbitrary web pages via HTTP, parses HTML structure, extracts semantic content (headings, paragraphs, links), and converts to Markdown format with optional section filtering and paragraph extraction. The implementation uses a headless browser or HTML parsing library to handle dynamic content and malformed HTML, preserving document structure while removing boilerplate (navigation, ads, footers) to produce clean, AI-readable text suitable for context injection into LLM prompts.

Implements an in-memory cache for fetched URL content with configurable time-to-live (TTL) expiration, reducing redundant HTTP requests to the same URLs within a time window. The cache stores Markdown-converted content keyed by URL, automatically evicts expired entries, and provides cache hit/miss metrics for monitoring. This pattern is particularly valuable for multi-turn conversations where the same URLs may be referenced repeatedly or for batch processing workflows.

Implements the Model Context Protocol server with support for two transport mechanisms: STDIO (standard input/output) for desktop clients like Claude Desktop, and optional HTTP server for web-based or remote clients. The server uses @modelcontextprotocol/sdk to handle protocol negotiation, request routing, and response serialization; clients connect via their preferred transport and invoke tools through standard MCP tool-calling conventions. This dual-mode design enables both local desktop integration and distributed deployment scenarios.

Supports configurable HTTP and HTTPS proxies for outbound requests from the MCP server, with optional bypass rules for direct connections to specific hosts or domains. The implementation uses Node.js native proxy agents (http.Agent, https.Agent) or libraries like node-https-proxy-agent to route traffic through corporate proxies, and applies bypass patterns to skip proxy for internal/local addresses. This enables deployment in restricted network environments without modifying application code.

Exposes server configuration and help documentation as MCP resources (read-only endpoints) that clients can query to understand available tools, parameters, and setup instructions. Resources are defined using the MCP resource protocol and return structured or text content describing the server's capabilities, environment variables, and usage examples. This pattern enables self-documenting servers where clients can discover configuration options without external documentation.

Implements a centralized error handling system that catches exceptions from web search and URL reading operations, logs detailed error context (URL, query, HTTP status, stack trace), and returns user-friendly error messages to MCP clients. The logging system uses a configurable logger (likely Winston or Pino) to write structured logs with timestamps, severity levels, and contextual metadata, enabling debugging and monitoring of MCP server health. Error handling distinguishes between recoverable errors (network timeouts, 404s) and fatal errors (configuration issues).

Registers web search and URL reading tools with the MCP server using the @modelcontextprotocol/sdk tool registration API, defining parameter schemas (JSON Schema format) that specify required inputs, types, descriptions, and constraints. The MCP server validates incoming tool calls against these schemas before execution, rejecting malformed requests and providing schema-based hints to clients about available parameters. This pattern enables type-safe tool invocation and self-documenting tool interfaces.

Provides a Docker image (isokoliuk/mcp-searxng on Docker Hub) built with multi-stage compilation to minimize image size, with environment variable configuration for SearXNG endpoint, proxy settings, and logging levels. The Dockerfile uses Node.js base images, installs dependencies, and exposes the MCP server for container orchestration platforms (Kubernetes, Docker Compose). This enables deployment in containerized environments without manual Node.js installation or dependency management.

Distributes the MCP server as an NPM package (mcp-searxng) installable via npm install or npx, with support for global installation via npm install -g for command-line access. The package includes a bin entry point that enables running the server directly from the terminal without explicit Node.js invocation. This pattern enables easy installation and updates through the Node.js package ecosystem.