mcp-searxng 1.7.2 → 1.8.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)
@@ -249,7 +250,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

@@ -26,4 +26,13 @@ export declare function createConversionError(error: any, url: string, htmlConte
 export declare function createTimeoutError(timeout: number, url: string): MCPSearXNGError;
 export declare function createEmptyContentWarning(url: string, htmlLength: number, htmlPreview: 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);
@@ -116,22 +117,34 @@ export function createEmptyContentWarning(url, htmlLength, htmlPreview) {
 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/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'}`);
     }
 }

package/dist/instance-info.js

@@ -1,12 +1,35 @@
 import { logMessage } from "./logging.js";
 import { createDefaultAgent, createProxyAgent, ProxyType } from "./proxy.js";
-let cachedConfig = null;
-let cachedBaseUrl = null;
-function unavailable(message, status) {
+import { getSearxngInstances } from "./searxng-instances.js";
+const CONFIG_FAILURE_CACHE_TTL_MS = 60_000;
+const cachedConfigs = new Map();
+const cachedConfigFailures = new Map();
+function redactInstanceUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (!url.username && !url.password) {
+            return raw;
+        }
+        url.username = "";
+        url.password = "";
+        return url.toString();
+    }
+    catch {
+        return raw;
+    }
+}
+function redactFailures(failures) {
+    return failures.map(({ sourceUrl, message, status }) => ({
+        sourceUrl: redactInstanceUrl(sourceUrl),
+        message,
+        ...(status !== undefined ? { status } : {}),
+    }));
+}
+function unavailable(message, failures = []) {
     return JSON.stringify({
         available: false,
         message,
-        ...(status !== undefined ? { status } : {}),
+        ...(failures.length > 0 ? { instancesUnreachable: redactFailures(failures) } : {}),
     }, null, 2);
 }
 function categoryNamesFromEngines(config) {
@@ -22,22 +45,35 @@ function categoryNamesFromEngines(config) {
     }
     return [...names];
 }
-function namesFromCategories(config) {
+function categoryNamesFromArray(categories) {
     const names = new Set();
-    if (Array.isArray(config.categories)) {
-        for (const category of config.categories) {
-            if (typeof category === "string" && category.trim() !== "") {
-                names.add(category);
-            }
+    for (const category of categories) {
+        if (typeof category === "string" && category.trim() !== "") {
+            names.add(category);
         }
     }
-    else if (config.categories && typeof config.categories === "object") {
-        for (const category of Object.keys(config.categories)) {
-            if (category.trim() !== "") {
-                names.add(category);
-            }
+    return [...names];
+}
+function categoryNamesFromObject(categories) {
+    const names = new Set();
+    for (const category of Object.keys(categories)) {
+        if (category.trim() !== "") {
+            names.add(category);
         }
     }
+    return [...names];
+}
+function configuredCategoryNames(config) {
+    if (Array.isArray(config.categories)) {
+        return categoryNamesFromArray(config.categories);
+    }
+    if (config.categories && typeof config.categories === "object") {
+        return categoryNamesFromObject(config.categories);
+    }
+    return [];
+}
+function namesFromCategories(config) {
+    const names = new Set(configuredCategoryNames(config));
     for (const category of categoryNamesFromEngines(config)) {
         names.add(category);
     }
@@ -52,7 +88,7 @@ function engineCategories(engine) {
     }
     return [];
 }
-function collectEngines(config, includeDisabled, category) {
+function engineSets(config, category) {
     const enabled = new Set();
     const disabled = new Set();
     if (Array.isArray(config.engines)) {
@@ -65,19 +101,14 @@ function collectEngines(config, includeDisabled, category) {
                 continue;
             }
             if (engine.disabled) {
-                if (includeDisabled) {
-                    disabled.add(engine.name);
-                }
+                disabled.add(engine.name);
             }
             else {
                 enabled.add(engine.name);
             }
         }
     }
-    return {
-        enabled: [...enabled].sort(),
-        ...(includeDisabled ? { disabled: [...disabled].sort() } : {}),
-    };
+    return { enabled, disabled };
 }
 function allEngineNames(config) {
     const names = new Set();
@@ -90,48 +121,114 @@ function allEngineNames(config) {
     }
     return names;
 }
-function formatInstanceInfo(config, includeEngines, includeDisabled, category) {
-    const categories = category
+function sorted(values) {
+    return [...values].sort();
+}
+function union(sets) {
+    const result = new Set();
+    for (const set of sets) {
+        for (const value of set) {
+            result.add(value);
+        }
+    }
+    return result;
+}
+function intersection(sets) {
+    if (sets.length === 0) {
+        return new Set();
+    }
+    const result = new Set(sets[0]);
+    for (const set of sets.slice(1)) {
+        for (const value of [...result]) {
+            if (!set.has(value)) {
+                result.delete(value);
+            }
+        }
+    }
+    return result;
+}
+function categoriesForConfig(config, category) {
+    const names = category
         ? namesFromCategories(config).filter((name) => name === category)
         : namesFromCategories(config);
+    return new Set(names);
+}
+function aggregateCategories(configs, category) {
+    const sets = configs.map(({ config }) => categoriesForConfig(config, category));
+    return {
+        common: sorted(intersection(sets)),
+        available: sorted(union(sets)),
+    };
+}
+function aggregateEngines(configs, includeDisabled, category) {
+    const perInstance = configs.map(({ config }) => engineSets(config, category));
+    const payload = {
+        common: {
+            enabled: sorted(intersection(perInstance.map(({ enabled }) => enabled))),
+        },
+        available: {
+            enabled: sorted(union(perInstance.map(({ enabled }) => enabled))),
+        },
+    };
+    if (includeDisabled) {
+        payload.common.disabled = sorted(intersection(perInstance.map(({ disabled }) => disabled)));
+        payload.available.disabled = sorted(union(perInstance.map(({ disabled }) => disabled)));
+    }
+    return payload;
+}
+function formatInstanceInfo(configs, failures, includeEngines, includeDisabled, category) {
+    const primary = configs[0].config;
     const payload = {
         available: true,
-        categories,
+        instancesReachable: configs.map(({ sourceUrl }) => redactInstanceUrl(sourceUrl)),
+        ...(failures.length > 0 ? { instancesUnreachable: redactFailures(failures) } : {}),
+        categories: aggregateCategories(configs, category),
         defaults: {
-            safesearch: config.search?.safe_search ?? config.default_safe_search,
-            locale: config.default_locale,
-            language: config.default_language,
-            theme: config.default_theme,
+            safesearch: primary.search?.safe_search ?? primary.default_safe_search,
+            locale: primary.default_locale,
+            language: primary.default_language,
+            theme: primary.default_theme,
         },
-        locales: config.locales,
-        plugins: config.plugins ?? [],
+        defaultsNote: "Defaults, locales, and plugins are reported from the primary reachable instance and may vary across configured instances.",
+        locales: primary.locales,
+        plugins: primary.plugins ?? [],
     };
     if (includeEngines) {
-        payload.engines = collectEngines(config, includeDisabled, category);
+        payload.engines = aggregateEngines(configs, includeDisabled, category);
     }
     return JSON.stringify(payload, null, 2);
 }
 export function clearInstanceInfoCacheForTests() {
-    cachedConfig = null;
-    cachedBaseUrl = null;
+    cachedConfigs.clear();
+    cachedConfigFailures.clear();
 }
-async function fetchConfig(mcpServer, refresh = false) {
-    const base = process.env.SEARXNG_URL;
-    if (!base) {
-        return {
-            available: false,
-            message: "SEARXNG_URL is not configured; cannot fetch SearXNG /config.",
-        };
-    }
-    if (refresh) {
-        cachedConfig = null;
+function getCachedFailure(base, now = Date.now()) {
+    const cached = cachedConfigFailures.get(base);
+    if (!cached) {
+        return null;
     }
-    if (cachedConfig && cachedBaseUrl === base) {
-        return { available: true, config: cachedConfig };
+    if (cached.until <= now) {
+        cachedConfigFailures.delete(base);
+        return null;
     }
-    const parsedBase = new URL(base.endsWith("/") ? base : `${base}/`);
-    const url = new URL("config", parsedBase);
+    return {
+        available: false,
+        sourceUrl: base,
+        message: cached.message,
+        ...(cached.status !== undefined ? { status: cached.status } : {}),
+    };
+}
+function cacheFailure(base, message, status) {
+    cachedConfigFailures.set(base, {
+        until: Date.now() + CONFIG_FAILURE_CACHE_TTL_MS,
+        message,
+        ...(status !== undefined ? { status } : {}),
+    });
+}
+async function requestInstanceConfig(mcpServer, base) {
     try {
+        const parsedBase = new URL(base.endsWith("/") ? base : `${base}/`);
+        const url = new URL("config", parsedBase);
         const requestOptions = {
             signal: AbortSignal.timeout(5000),
         };
@@ -142,42 +239,96 @@ async function fetchConfig(mcpServer, refresh = false) {
         }
         const response = await fetch(url.toString(), requestOptions);
         if (!response.ok) {
+            const message = `SearXNG /config is unavailable: HTTP ${response.status} ${response.statusText}`;
             return {
                 available: false,
-                message: `SearXNG /config is unavailable: HTTP ${response.status} ${response.statusText}`,
+                message,
                 status: response.status,
+                sourceUrl: base,
             };
         }
-        cachedConfig = await response.json();
-        cachedBaseUrl = base;
-        return { available: true, config: cachedConfig };
+        const config = await response.json();
+        return { available: true, config, sourceUrl: base };
     }
     catch (error) {
-        logMessage(mcpServer, "warning", `SearXNG /config fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+        logMessage(mcpServer, "warning", `SearXNG /config fetch failed for ${redactInstanceUrl(base)}: ${error instanceof Error ? error.message : String(error)}`);
+        const message = "SearXNG /config is unavailable; instance capability discovery could not complete.";
         return {
             available: false,
-            message: "SearXNG /config is unavailable; instance capability discovery could not complete.",
+            message,
+            sourceUrl: base,
         };
     }
 }
-export async function getKnownEngines(mcpServer, refresh = false) {
-    const result = await fetchConfig(mcpServer, refresh);
-    if (!result.available) {
-        return null;
+async function fetchConfigFromInstance(mcpServer, base) {
+    const cached = cachedConfigs.get(base);
+    if (cached) {
+        return { available: true, config: cached, sourceUrl: base };
+    }
+    const cachedFailure = getCachedFailure(base);
+    if (cachedFailure) {
+        return cachedFailure;
     }
-    return allEngineNames(result.config);
+    const result = await requestInstanceConfig(mcpServer, base);
+    if (result.available) {
+        cachedConfigs.set(base, result.config);
+        cachedConfigFailures.delete(base);
+    }
+    else {
+        cacheFailure(base, result.message, result.status);
+    }
+    return result;
 }
-export async function getKnownCategories(mcpServer, refresh = false) {
-    const result = await fetchConfig(mcpServer, refresh);
+async function fetchConfigs(mcpServer, refresh = false) {
+    const instances = getSearxngInstances();
+    if (instances.length === 0) {
+        return {
+            available: false,
+            message: "SEARXNG_URL is not configured; cannot fetch SearXNG /config.",
+            failures: [],
+        };
+    }
+    if (refresh) {
+        cachedConfigs.clear();
+        cachedConfigFailures.clear();
+    }
+    const results = await Promise.all(instances.map((instance) => fetchConfigFromInstance(mcpServer, instance)));
+    const configs = results
+        .filter((result) => result.available)
+        .map(({ config, sourceUrl }) => ({ config, sourceUrl }));
+    const failures = results
+        .filter((result) => !result.available)
+        .map(({ sourceUrl, message, status }) => ({
+        sourceUrl,
+        message,
+        ...(status !== undefined ? { status } : {}),
+    }));
+    if (configs.length === 0) {
+        return {
+            available: false,
+            message: "SearXNG /config is unavailable; no configured instances answered capability discovery.",
+            failures,
+        };
+    }
+    return { available: true, configs, failures };
+}
+async function getAggregatedCapability(mcpServer, refresh, extractor) {
+    const result = await fetchConfigs(mcpServer, refresh);
     if (!result.available) {
         return null;
     }
-    return new Set(namesFromCategories(result.config));
+    return union(result.configs.map(({ config }) => extractor(config)));
+}
+export async function getKnownEngines(mcpServer, refresh = false) {
+    return getAggregatedCapability(mcpServer, refresh, allEngineNames);
+}
+export async function getKnownCategories(mcpServer, refresh = false) {
+    return getAggregatedCapability(mcpServer, refresh, (config) => new Set(namesFromCategories(config)));
 }
 export async function fetchInstanceInfo(mcpServer, includeEngines = false, includeDisabled = false, category, refresh = false) {
-    const result = await fetchConfig(mcpServer, refresh);
+    const result = await fetchConfigs(mcpServer, refresh);
     if (!result.available) {
-        return unavailable(result.message, result.status);
+        return unavailable(result.message, result.failures);
     }
-    return formatInstanceInfo(result.config, includeEngines, includeDisabled, category);
+    return formatInstanceInfo(result.configs, result.failures, includeEngines, includeDisabled, category);
 }

package/dist/resources.js

@@ -43,7 +43,7 @@ This is a Model Context Protocol (MCP) server that provides web search, autocomp
 ## Available Tools
 
 ### 1. searxng_web_search
-Performs web searches using the configured SearXNG instance.
+Performs web searches using the configured SearXNG instance or replica list, with failover/fanout when multiple instances are configured.
 
 **Parameters:**
 - \`query\` (required): The search query string
@@ -53,11 +53,11 @@ Performs web searches using the configured SearXNG instance.
 - \`safesearch\` (optional): Safe search level - 0 (none), 1 (moderate), 2 (strict)
 - \`min_score\` (optional): Minimum relevance score from 0.0 to 1.0
 - \`num_results\` (optional): Maximum result count from 1 to 20
-- \`categories\` (optional): Comma-separated SearXNG categories such as "news" or "it,science"; live \`/config\` values are normalized case-insensitively when available
-- \`engines\` (optional): Comma-separated SearXNG engine names such as "google,bing,ddg" or "semantic scholar"; live \`/config\` values are normalized case-insensitively when available
+- \`categories\` (optional): Comma-separated SearXNG categories such as "news" or "it,science"; live \`/config\` values are aggregated across reachable instances and normalized case-insensitively when available
+- \`engines\` (optional): Comma-separated SearXNG engine names such as "google,bing,ddg" or "semantic scholar"; live \`/config\` values are aggregated across reachable instances and normalized case-insensitively when available
 - \`response_format\` (optional): "text" for formatted output or "json" for raw SearXNG-shaped JSON (may include a \`warnings\` array for non-fatal issues)
 
-Text output can include metadata sections for direct answers, spelling corrections, suggestions, and infoboxes before the result list. JSON output preserves the SearXNG response shape with filtered and sliced \`results\`, and may include a \`warnings\` array for non-fatal issues. Unknown categories or engines are rejected when live \`/config\` validation is available; if \`/config\` is unavailable, the search proceeds with the supplied values and emits a warning.
+Text output can include metadata sections for direct answers, spelling corrections, suggestions, and infoboxes before the result list. JSON output preserves the SearXNG response shape with filtered and sliced \`results\`, and may include a \`warnings\` array for non-fatal issues. Use \`searxng_instance_info\` and prefer \`common\` categories/engines for consistent multi-instance results; \`available\`-only filters are best-effort. Unknown categories or engines are forwarded trimmed so SearXNG can ignore or honor them; if \`/config\` is unavailable, the search proceeds with the supplied values and emits a warning.
 
 ### 2. searxng_search_suggestions
 Returns autocomplete suggestions from the configured SearXNG instance.
@@ -67,7 +67,7 @@ Returns autocomplete suggestions from the configured SearXNG instance.
 - \`language\` (optional): Language code like "en", "fr", "de" or "all" (default: "all")
 
 ### 3. searxng_instance_info
-Discovers categories, engines, defaults, locales, and plugins exposed by the configured SearXNG instance.
+Discovers 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.
 
 **Parameters:**
 - \`includeEngines\` (optional): Include enabled engine names