$ show ihor-sokoliuk/mcp-searxng
This repository implements an MCP (Model Context Protocol) server that bridges AI assistants with SearXNG, a privacy-respecting metasearch engine. It exposes four primary tools: `searxng_web_search` for web queries, `searxng_search_suggestions` for autocomplete, `searxng_instance_info` for capability discovery, and `web_url_read` for fetching and converting web pages to markdown. The server runs in two transport modes: STDIO (default) for simple MCP integration, and HTTP for stateful/stateless remote access with optional OAuth and static bearer authentication. The architecture is modular and security-focused. Core modules include a proxy layer with per-type agent selection, SSRF protection via private IP blocking and DNS rebinding detection, a browser solver chain (FlareSolverr/Byparr) for challenge solving, worker-threaded PDF extraction, and multi-instance failover/fanout for SearXNG replicas. All credential-bearing output (logs, errors, MCP resources) is redacted by a centralized sanitizer. Extensive environment-variable configuration (~40+ knobs) controls caching, timeouts, rate limiting, TLS, and result formatting. Highlights include a strict integer parser that rejects unsafe or malformed values, an LFU cache with age tie-breakers and configurable TTL, and a comprehensive URL security module covering both IPv4 and IPv6 private ranges. The test suite achieves over 90% line coverage and includes integration, unit, fuzz, and e2e tests, with documentation tests that verify README and configuration docs match source contracts. The project is actively maintained with frequent releases, pinned dependencies, and a verification gate that enforces zero-vulnerability audits before publishing.
The LLM identified 6 files worth highlighting for reuse:
Implements comprehensive private IP detection for both IPv4 (RFC1918, CGNAT, multicast, etc.) and IPv6 (including embedded IPv4 forms, site-local, multicast). Uses WHATWG URL parsing and falls closed on parse errors. Also provides DNS rebinding protection by resolving hostnames before comparison. This module is self-contained and could be extracted into a standalone SSRF prevention library with minimal modification.
A generic LFU (Least Frequently Used) cache with frequency-based eviction and age tie-breaker. Supports configurable max entries, TTL per entry, periodic cleanup interval, and a global singleton instance. The implementation is self-contained and demonstrates a well-tuned caching strategy suitable for any Node.js application needing bounded in-memory caching.
Provides `parseStrictInteger` and `parseBoundedInteger` functions that reject fractional numbers, decimal suffixes, non-decimal radixes, and unsafe integers (outside Number.MIN_SAFE_INTEGER/MAX_SAFE_INTEGER). This prevents common configuration injection or silent truncation bugs. The module is completely self-contained and reusable across any Node.js project that parses integer environment variables.
Defines `MCPSearXNGError` base class with an `expected` flag to distinguish recoverable errors from unexpected failures. Provides factory functions like `createNetworkError()`, `createServerError()`, etc., that produce consistent error objects with context (url, status, cause). This pattern is extractable and useful for any project requiring structured error handling with user-friendly messages.
Implements per-type proxy selection (search vs url_reader vs global) using environment variables, with wildcard/domain matching for NO_PROXY. Creates undici ProxyAgent instances on demand and provides a custom DNS lookup hook for SSRF protection. The proxy resolution logic is self-contained and can be extracted for any Node.js application that needs flexible, type-aware proxy configuration.
Centralized singleton that redacts credentials (URL userinfo, Basic auth, bearer tokens, AUTH_USERNAME/PASSWORD) from logs, error messages, and MCP resource outputs. Provides a `REDACT()` function that replaces sensitive patterns with placeholders. This module is a drop-in solution for preventing credential leakage in any Node.js application with similar diagnostic output needs.