mcp-searxng 1.7.2 → 1.9.0

package/README.md

@@ -38,11 +38,12 @@ Add to your MCP client configuration (e.g. `claude_desktop_config.json`):
 }
 ```
 
-Replace `YOUR_SEARXNG_INSTANCE_URL` with the URL of your SearXNG instance (e.g. `https://searxng.example.com`).
+Replace `YOUR_SEARXNG_INSTANCE_URL` with the URL of your SearXNG instance (e.g. `https://searxng.example.com`). You can also provide interchangeable replicas as a semicolon-separated list, e.g. `https://one.example.com;https://two.example.com`.
 
 ## Features
 
 - **Web Search**: General queries, news, articles, with pagination.
+- **Instance Failover**: Configure multiple interchangeable SearXNG replicas in `SEARXNG_URL`; searches fail over by default and can optionally fan out in parallel.
 - **Structured Search Output**: Choose formatted text or raw SearXNG-shaped JSON with `response_format`.
 - **Direct Answers & Metadata**: Text results surface SearXNG answers, corrections, suggestions, and infoboxes before result lists.
 - **Search Suggestions**: Query autocomplete via SearXNG's `/autocompleter` endpoint.
@@ -68,9 +69,9 @@ Replace `YOUR_SEARXNG_INSTANCE_URL` with the URL of your SearXNG instance (e.g.
 
 ## How It Works
 
-`mcp-searxng` is a standalone MCP server — a separate Node.js process that your AI assistant connects to for web search. It queries any SearXNG instance via its HTTP JSON API.
+`mcp-searxng` is a standalone MCP server — a separate Node.js process that your AI assistant connects to for web search. It queries one SearXNG instance, or a semicolon-separated list of interchangeable SearXNG replicas, via the HTTP JSON API.
 
-> **Not a SearXNG plugin:** This project cannot be installed as a native SearXNG plugin. Point it at any existing SearXNG instance by setting `SEARXNG_URL`.
+> **Not a SearXNG plugin:** This project cannot be installed as a native SearXNG plugin. Point it at any existing SearXNG instance, or interchangeable replica list, by setting `SEARXNG_URL`.
 
 ```
 AI Assistant (e.g. Claude)
@@ -79,7 +80,7 @@ AI Assistant (e.g. Claude)
   mcp-searxng  (this project — Node.js process)
         │  HTTP JSON API  (SEARXNG_URL)
         ▼
-  SearXNG instance
+  SearXNG instance(s)
 ```
 
 ## Tools
@@ -91,11 +92,11 @@ AI Assistant (e.g. Claude)
     - `pageno` (number, optional): Search page number, starts at 1 (default 1)
     - `time_range` (string, optional): Filter results by time range - one of: "day", "week", "month", "year" (default: none)
     - `language` (string, optional): Language code for results (e.g., "en", "fr", "de") or "all" (default: "all")
-    - `safesearch` (number, optional): Safe search filter level (0: None, 1: Moderate, 2: Strict) (default: instance setting)
+    - `safesearch` (string enum, optional): Safe search filter level, one of `"0"` (None), `"1"` (Moderate), or `"2"` (Strict). Legacy numeric values `0`, `1`, and `2` are still accepted for backward compatibility. (default: instance setting)
     - `min_score` (number, optional): Minimum relevance score from 0.0 to 1.0. Results below this score are filtered out.
     - `num_results` (number, optional): Maximum number of results to return, from 1 to 20. `SEARXNG_MAX_RESULTS` applies as an operator ceiling.
-    - `categories` (string, optional): Comma-separated SearXNG categories (e.g. `"news"`, `"it,science"`). When live `/config` is available, values are trimmed and normalized case-insensitively to the instance's canonical category names; unknown values are rejected with available categories listed. If `/config` is unavailable, values are forwarded as-is with a warning. Default: SearXNG instance default.
-    - `engines` (string, optional): Comma-separated SearXNG engine names (e.g. `"google,bing,ddg"`, `"semantic scholar"`). When live `/config` is available, values are trimmed and normalized case-insensitively to canonical engine names, including engines disabled by default; unknown values are rejected with available engines listed. If `/config` is unavailable, values are forwarded as-is with a warning.
+    - `categories` (string, optional): Comma-separated SearXNG categories (e.g. `"news"`, `"it,science"`). Live `/config` capabilities are aggregated across reachable instances; prefer `searxng_instance_info` `categories.common` for consistent multi-instance results. Known values are trimmed and normalized case-insensitively; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If `/config` is unavailable, values are forwarded as-is with a warning. If omitted, each instance uses its server-side default.
+    - `engines` (string, optional): Comma-separated SearXNG engine names (e.g. `"google,bing,ddg"`, `"semantic scholar"`). Live `/config` capabilities are aggregated across reachable instances; prefer `searxng_instance_info` `engines.common.enabled` for consistent multi-instance results. Known values are trimmed and normalized case-insensitively, including engines disabled by default; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If `/config` is unavailable, values are forwarded as-is with a warning. If omitted, each instance uses its server-side default.
     - `response_format` (string, optional): Response format, either `"text"` for formatted agent-readable output or `"json"` for raw SearXNG JSON with filtered/sliced `results`. (default: `"text"`)
 
 - **searxng_search_suggestions**
@@ -105,7 +106,7 @@ AI Assistant (e.g. Claude)
     - `language` (string, optional): Language code for suggestions (e.g., "en", "fr", "de") or "all" (default: "all")
 
 - **searxng_instance_info**
-  - Discover categories, engines, defaults, locales, and plugins exposed by the configured SearXNG instance
+  - Discover categories, engines, defaults, locales, and plugins exposed by all reachable configured SearXNG instances. The response reports `common` values present on every reachable instance and `available` values present on at least one reachable instance.
   - Inputs:
     - `includeEngines` (boolean, optional): Include enabled engine names in the response. (default: false)
     - `includeDisabled` (boolean, optional): Include disabled engine names when `includeEngines` is true. (default: false)
@@ -238,6 +239,8 @@ By default the server uses STDIO. Set `MCP_HTTP_PORT` to enable HTTP mode:
 
 **Endpoints:** `POST/GET/DELETE /mcp` (MCP protocol), `GET /health` (health check)
 
+For reverse-proxy deployments, see [CONFIGURATION.md](CONFIGURATION.md) for `MCP_HTTP_TRUST_PROXY` so rate limiting and logs use the correct client IP.
+
 **Test it:**
 
 ```bash
@@ -249,7 +252,7 @@ curl http://localhost:3000/health
 
 ## Configuration
 
-Set `SEARXNG_URL` to your SearXNG instance URL. All other variables are optional.
+Set `SEARXNG_URL` to your SearXNG instance URL. For failover, set it to semicolon-separated interchangeable replica URLs. Set `SEARXNG_FANOUT=true` to query all healthy replicas in parallel and merge results. All other variables are optional.
 
 Full environment variable reference: [CONFIGURATION.md](CONFIGURATION.md)
 

package/dist/cli.js

@@ -1,13 +1,8 @@
 #!/usr/bin/env node
 import { main } from "./index.js";
-process.on('uncaughtException', (error) => {
-    console.error('Uncaught Exception:', error);
-    process.exit(1);
-});
-process.on('unhandledRejection', (reason, promise) => {
-    console.error('Unhandled Rejection at:', promise, 'reason:', reason);
-    process.exit(1);
-});
+import { handleUncaughtException, handleUnhandledRejection } from "./error-handler.js";
+process.on('uncaughtException', handleUncaughtException);
+process.on('unhandledRejection', handleUnhandledRejection);
 main().catch((error) => {
     console.error("Failed to start server:", error);
     process.exit(1);

package/dist/error-handler.d.ts

@@ -16,14 +16,23 @@ export declare class MCPSearXNGError extends Error {
 export declare function createConfigurationError(message: string): MCPSearXNGError;
 export declare function createNetworkError(error: any, context: ErrorContext): MCPSearXNGError;
 export declare function createServerError(status: number, statusText: string, responseBody: string, context: ErrorContext): MCPSearXNGError;
-export declare function createJSONError(responseText: string, context: ErrorContext): MCPSearXNGError;
-export declare function createDataError(data: any, context: ErrorContext): MCPSearXNGError;
+export declare function createJSONError(responseText: string): MCPSearXNGError;
+export declare function createDataError(): MCPSearXNGError;
 export declare function createNoResultsMessage(query: string): string;
 export declare function createURLFormatError(url: string): MCPSearXNGError;
 export declare function createURLSecurityPolicyError(url: string): MCPSearXNGError;
 export declare function createContentError(message: string, url: string): MCPSearXNGError;
-export declare function createConversionError(error: any, url: string, htmlContent: string): MCPSearXNGError;
+export declare function createConversionError(url: string): MCPSearXNGError;
 export declare function createTimeoutError(timeout: number, url: string): MCPSearXNGError;
-export declare function createEmptyContentWarning(url: string, htmlLength: number, htmlPreview: string): string;
+export declare function createEmptyContentWarning(url: string): string;
 export declare function createUnexpectedError(error: any, context: ErrorContext): MCPSearXNGError;
+/**
+ * Process-level crash handlers, registered by the CLI entrypoint (cli.ts).
+ *
+ * Extracted here so the logic is unit-testable: cli.ts calls main() at import
+ * time (it must always start the server — see issue #91), so it cannot be
+ * imported to test these in place.
+ */
+export declare function handleUncaughtException(error: unknown): void;
+export declare function handleUnhandledRejection(reason: unknown, promise: Promise<unknown>): void;
 export declare function validateEnvironment(): string | null;

package/dist/error-handler.js

@@ -2,6 +2,7 @@
  * Concise error handling for MCP SearXNG server
  * Provides clear, focused error messages that identify the root cause
  */
+import { parseSearxngUrls, validateSearxngInstanceUrl } from "./searxng-instances.js";
 export class MCPSearXNGError extends Error {
     constructor(message) {
         super(message);
@@ -83,11 +84,11 @@ export function createServerError(status, statusText, responseBody, context) {
     }
     return new MCPSearXNGError(`🚫 ${target} Error (${status}): ${statusText}`);
 }
-export function createJSONError(responseText, context) {
+export function createJSONError(responseText) {
     const preview = responseText.substring(0, 100).replace(/\n/g, ' ');
     return new MCPSearXNGError(`🔍 SearXNG Response Error: Invalid JSON format. Response: "${preview}..."`);
 }
-export function createDataError(data, context) {
+export function createDataError() {
     return new MCPSearXNGError(`🔍 SearXNG Data Error: Missing results array in response`);
 }
 export function createNoResultsMessage(query) {
@@ -103,35 +104,47 @@ export function createURLSecurityPolicyError(url) {
 export function createContentError(message, url) {
     return new MCPSearXNGError(`📄 Content Error: ${message} (${url})`);
 }
-export function createConversionError(error, url, htmlContent) {
+export function createConversionError(url) {
     return new MCPSearXNGError(`🔄 Conversion Error: Cannot convert HTML to Markdown (${url})`);
 }
 export function createTimeoutError(timeout, url) {
     const hostname = new URL(url).hostname;
     return new MCPSearXNGError(`⏱️ Timeout Error: ${hostname} took longer than ${timeout}ms to respond`);
 }
-export function createEmptyContentWarning(url, htmlLength, htmlPreview) {
+export function createEmptyContentWarning(url) {
     return `📄 Content Warning: Page fetched but appears empty after conversion (${url}). May contain only media or require JavaScript.`;
 }
 export function createUnexpectedError(error, context) {
     return new MCPSearXNGError(`❓ Unexpected Error: ${error.message || String(error)}`);
 }
+/**
+ * Process-level crash handlers, registered by the CLI entrypoint (cli.ts).
+ *
+ * Extracted here so the logic is unit-testable: cli.ts calls main() at import
+ * time (it must always start the server — see issue #91), so it cannot be
+ * imported to test these in place.
+ */
+export function handleUncaughtException(error) {
+    console.error('Uncaught Exception:', error);
+    process.exit(1);
+}
+export function handleUnhandledRejection(reason, promise) {
+    console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+    process.exit(1);
+}
 export function validateEnvironment() {
     const issues = [];
-    const searxngUrl = process.env.SEARXNG_URL;
-    if (!searxngUrl) {
+    const searxngUrls = parseSearxngUrls();
+    if (searxngUrls.length === 0) {
         issues.push("SEARXNG_URL not set");
     }
     else {
-        try {
-            const url = new URL(searxngUrl);
-            if (!['http:', 'https:'].includes(url.protocol)) {
-                issues.push(`SEARXNG_URL invalid protocol: ${url.protocol}`);
+        for (const searxngUrl of searxngUrls) {
+            const validationError = validateSearxngInstanceUrl(searxngUrl);
+            if (validationError) {
+                issues.push(validationError);
             }
         }
-        catch (error) {
-            issues.push(`SEARXNG_URL invalid format: ${searxngUrl}`);
-        }
     }
     const authUsername = process.env.AUTH_USERNAME;
     const authPassword = process.env.AUTH_PASSWORD;

package/dist/http-security.d.ts

@@ -6,6 +6,7 @@ export interface HttpSecurityConfig {
     allowedOrigins: string[];
     enableDnsRebindingProtection: boolean;
     allowedHosts: string[];
+    trustProxy: boolean | number | string;
     exposeFullConfig: boolean;
     allowPrivateUrls: boolean;
 }

package/dist/http-security.js

@@ -7,6 +7,21 @@ function parseCsv(value) {
         .map((item) => item.trim())
         .filter(Boolean);
 }
+function parseTrustProxy(value) {
+    const trimmed = value?.trim();
+    // Treat "0" as disabled (false): operators use 0 to turn numeric knobs off,
+    // and Express would otherwise mis-parse the string "0" as a bogus trust subnet.
+    if (!trimmed || trimmed === "false" || trimmed === "0") {
+        return false;
+    }
+    if (trimmed === "true") {
+        return true;
+    }
+    if (/^[1-9]\d*$/.test(trimmed)) {
+        return Number(trimmed);
+    }
+    return trimmed;
+}
 export function getHttpSecurityConfig() {
     const harden = isEnabled(process.env.MCP_HTTP_HARDEN);
     const authToken = process.env.MCP_HTTP_AUTH_TOKEN;
@@ -20,6 +35,7 @@ export function getHttpSecurityConfig() {
         allowedOrigins,
         enableDnsRebindingProtection: harden,
         allowedHosts: allowedHosts.length > 0 ? allowedHosts : ["127.0.0.1", "localhost"],
+        trustProxy: parseTrustProxy(process.env.MCP_HTTP_TRUST_PROXY),
         exposeFullConfig: isEnabled(process.env.MCP_HTTP_EXPOSE_FULL_CONFIG),
         allowPrivateUrls: isEnabled(process.env.MCP_HTTP_ALLOW_PRIVATE_URLS),
     };

package/dist/http-server.js

@@ -55,6 +55,9 @@ export async function createHttpServer(createMcpServer) {
     const app = express();
     const security = getHttpSecurityConfig();
     validateHttpSecurityConfig(security);
+    if (security.trustProxy !== false) {
+        app.set('trust proxy', security.trustProxy);
+    }
     app.use(express.json());
     // Add CORS support for web clients
     app.use(cors({
@@ -97,7 +100,7 @@ export async function createHttpServer(createMcpServer) {
             mcpServer = session.mcpServer;
             logMessage(mcpServer, "debug", `Reusing session: ${sessionId}`);
         }
-        else if (!sessionId && isInitializeRequest(req.body)) {
+        else if (isInitializeRequest(req.body)) {
             // New initialization request — create fresh McpServer and transport
             mcpServer = createMcpServer();
             transport = new StreamableHTTPServerTransport({
@@ -129,11 +132,12 @@ export async function createHttpServer(createMcpServer) {
                 contentType: req.headers['content-type'],
                 accept: req.headers['accept']
             });
-            res.status(400).json({
+            const sessionNotFound = Boolean(sessionId);
+            res.status(sessionNotFound ? 404 : 400).json({
                 jsonrpc: '2.0',
                 error: {
-                    code: -32000,
-                    message: 'Bad Request: No valid session ID provided',
+                    code: sessionNotFound ? -32001 : -32000,
+                    message: sessionNotFound ? 'Session not found' : 'Bad Request: No valid session ID provided',
                 },
                 id: null,
             });

package/dist/index.js

@@ -10,6 +10,7 @@ import { fetchInstanceInfo } from "./instance-info.js";
 import { fetchAndConvertToMarkdown } from "./url-reader.js";
 import { createConfigResource, createHelpResource } from "./resources.js";
 import { createHttpServer, resolveBindHost } from "./http-server.js";
+import { getSearxngInstances } from "./searxng-instances.js";
 import { packageVersion } from "./version.js";
 // Type guard for URL reading args
 export function isWebUrlReadArgs(args) {
@@ -104,7 +105,7 @@ export function createMcpServer() {
                 if (!isSearXNGWebSearchArgs(args)) {
                     throw new Error("Invalid arguments for web search");
                 }
-                const result = await performWebSearch(mcpServer, args.query, args.pageno, args.time_range, args.language, args.safesearch, args.min_score, args.num_results, args.categories, args.engines, args.response_format);
+                const result = await performWebSearch(mcpServer, args.query, args.pageno, args.time_range, args.language, args.safesearch === undefined ? undefined : Number(args.safesearch), args.min_score, args.num_results, args.categories, args.engines, args.response_format);
                 return {
                     content: [
                         {
@@ -277,8 +278,9 @@ export async function main() {
         // Show helpful message when running in terminal
         if (process.stdin.isTTY) {
             console.error(`🔍 MCP SearXNG Server v${packageVersion} - Ready`);
-            if (process.env.SEARXNG_URL) {
-                console.error(`🌐 SearXNG URL: ${process.env.SEARXNG_URL}`);
+            const searxngInstances = getSearxngInstances();
+            if (searxngInstances.length > 0) {
+                console.error(`🌐 SearXNG URLs: ${searxngInstances.join("; ")}`);
             }
             else {
                 console.error("⚠️  SEARXNG_URL not set — configure it before using search tools");
@@ -291,6 +293,7 @@ export async function main() {
         logMessage(mcpServer, "info", `MCP SearXNG Server v${packageVersion} connected via STDIO`);
         logMessage(mcpServer, "info", `Log level: ${getCurrentLogLevel()}`);
         logMessage(mcpServer, "info", `Environment: ${process.env.NODE_ENV || 'development'}`);
-        logMessage(mcpServer, "info", `SearXNG URL: ${process.env.SEARXNG_URL || 'not configured'}`);
+        const searxngInstances = getSearxngInstances();
+        logMessage(mcpServer, "info", `SearXNG URLs: ${searxngInstances.length > 0 ? searxngInstances.join("; ") : 'not configured'}`);
     }
 }