mcp-searxng 1.5.0 → 1.7.0

package/README.md

@@ -91,7 +91,8 @@ AI Assistant (e.g. Claude)
     - `safesearch` (number, optional): Safe search filter level (0: None, 1: Moderate, 2: Strict) (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"`). Supported values: `general`, `news`, `images`, `videos`, `it`, `science`, `files`, `social media`. Default: SearXNG instance default (usually `general`).
+    - `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.
     - `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**
@@ -272,6 +273,21 @@ You should receive a JSON response. If not, confirm the file is correctly mounte
 
 See also: [SearXNG settings docs](https://docs.searxng.org/admin/settings/settings.html) · [discussion](https://github.com/searxng/searxng/discussions/1789)
 
+### Can't enable JSON? (HTML fallback)
+
+If you must use a public instance you don't control and it rejects `format=json` (the 403 above), set the opt-in flag instead of editing the server:
+
+```json
+"SEARXNG_HTML_FALLBACK": "true"
+```
+
+A search that gets a `403`/`404` or a non-JSON response is then retried automatically **without** `format=json` and parsed from the regular HTML results page.
+
+- **On success:** you get normal results (title, URL, snippet). They are marked `sourceFormat: "html"` in JSON mode, and text mode adds the line *"Note: Results parsed from SearXNG HTML fallback; metadata is limited."* Relevance scores and engine names are not available from HTML.
+- **On failure:** parsing is best-effort and varies by the instance's theme/version, so some results may be missed or sparse. If the HTML page itself also fails — still blocked, rate-limited (`429`), auth (`401`), or `5xx` — the **original error is surfaced unchanged**. The fallback only triggers on `403`/`404`/non-JSON, never on auth or network errors.
+
+Enabling JSON on an instance you control (above) remains the recommended setup — the fallback is a compatibility aid, not a replacement.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)

package/dist/cache.d.ts

@@ -2,14 +2,17 @@ interface CacheEntry {
     htmlContent: string;
     markdownContent: string;
     timestamp: number;
+    hitCount: number;
 }
 declare class SimpleCache {
     private cache;
     private readonly ttlMs;
+    private readonly maxEntries;
     private cleanupInterval;
-    constructor(ttlMs?: number, cleanupIntervalMs?: number);
+    constructor(ttlMs?: number, maxEntries?: number, cleanupIntervalMs?: number);
     private startCleanup;
     private cleanupExpired;
+    private evictIfNeeded;
     get(url: string): CacheEntry | null;
     set(url: string, htmlContent: string, markdownContent: string): void;
     clear(): void;
@@ -19,6 +22,7 @@ declare class SimpleCache {
         entries: Array<{
             url: string;
             age: number;
+            hitCount: number;
         }>;
     };
 }

package/dist/cache.js

@@ -1,13 +1,28 @@
+const DEFAULT_CACHE_TTL_MS = 86400000;
+const DEFAULT_CACHE_MAX_ENTRIES = 500;
+const DEFAULT_CLEANUP_INTERVAL_MS = 60000;
+function parsePositiveInteger(value, fallback) {
+    if (value === undefined || value.trim() === "") {
+        return fallback;
+    }
+    const parsed = parseInt(value, 10);
+    return Number.isNaN(parsed) || parsed <= 0 ? fallback : parsed;
+}
+function normalizePositiveInteger(value, fallback) {
+    return !Number.isFinite(value) || !Number.isInteger(value) || value <= 0 ? fallback : value;
+}
 class SimpleCache {
     cache = new Map();
     ttlMs;
+    maxEntries;
     cleanupInterval = null;
-    constructor(ttlMs = 60000, cleanupIntervalMs = 30000) {
-        this.ttlMs = ttlMs;
-        this.startCleanup(cleanupIntervalMs);
+    constructor(ttlMs = parsePositiveInteger(process.env.CACHE_TTL_MS, DEFAULT_CACHE_TTL_MS), maxEntries = parsePositiveInteger(process.env.CACHE_MAX_ENTRIES, DEFAULT_CACHE_MAX_ENTRIES), cleanupIntervalMs = DEFAULT_CLEANUP_INTERVAL_MS) {
+        this.ttlMs = normalizePositiveInteger(ttlMs, DEFAULT_CACHE_TTL_MS);
+        this.maxEntries = normalizePositiveInteger(maxEntries, DEFAULT_CACHE_MAX_ENTRIES);
+        this.startCleanup(normalizePositiveInteger(cleanupIntervalMs, DEFAULT_CLEANUP_INTERVAL_MS));
     }
     startCleanup(cleanupIntervalMs) {
-        // Clean up expired entries every cleanupIntervalMs milliseconds (default 30s)
+        // Clean up expired entries every cleanupIntervalMs milliseconds (default 60s)
         this.cleanupInterval = setInterval(() => {
             this.cleanupExpired();
         }, cleanupIntervalMs);
@@ -21,6 +36,25 @@ class SimpleCache {
             }
         }
     }
+    evictIfNeeded() {
+        this.cleanupExpired();
+        while (this.cache.size > this.maxEntries) {
+            let evictionKey = null;
+            let evictionEntry = null;
+            for (const [key, entry] of this.cache.entries()) {
+                if (evictionEntry === null ||
+                    entry.hitCount < evictionEntry.hitCount ||
+                    (entry.hitCount === evictionEntry.hitCount && entry.timestamp < evictionEntry.timestamp)) {
+                    evictionKey = key;
+                    evictionEntry = entry;
+                }
+            }
+            if (evictionKey === null) {
+                return;
+            }
+            this.cache.delete(evictionKey);
+        }
+    }
     get(url) {
         const entry = this.cache.get(url);
         if (!entry) {
@@ -31,14 +65,17 @@ class SimpleCache {
             this.cache.delete(url);
             return null;
         }
+        entry.hitCount++;
         return entry;
     }
     set(url, htmlContent, markdownContent) {
         this.cache.set(url, {
             htmlContent,
             markdownContent,
-            timestamp: Date.now()
+            timestamp: Date.now(),
+            hitCount: 0
         });
+        this.evictIfNeeded();
     }
     clear() {
         this.cache.clear();
@@ -55,7 +92,8 @@ class SimpleCache {
         const now = Date.now();
         const entries = Array.from(this.cache.entries()).map(([url, entry]) => ({
             url,
-            age: now - entry.timestamp
+            age: now - entry.timestamp,
+            hitCount: entry.hitCount
         }));
         return {
             size: this.cache.size,

package/dist/index.js

@@ -104,7 +104,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.response_format);
+                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);
                 return {
                     content: [
                         {

package/dist/instance-info.d.ts

@@ -1,3 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function clearInstanceInfoCacheForTests(): void;
+export declare function getKnownEngines(mcpServer: McpServer, refresh?: boolean): Promise<Set<string> | null>;
+export declare function getKnownCategories(mcpServer: McpServer, refresh?: boolean): Promise<Set<string> | null>;
 export declare function fetchInstanceInfo(mcpServer: McpServer, includeEngines?: boolean, includeDisabled?: boolean, category?: string, refresh?: boolean): Promise<string>;

package/dist/instance-info.js

@@ -9,11 +9,39 @@ function unavailable(message, status) {
         ...(status !== undefined ? { status } : {}),
     }, null, 2);
 }
+function categoryNamesFromEngines(config) {
+    const names = new Set();
+    if (Array.isArray(config.engines)) {
+        for (const engine of config.engines) {
+            for (const category of engineCategories(engine)) {
+                if (typeof category === "string" && category.trim() !== "") {
+                    names.add(category);
+                }
+            }
+        }
+    }
+    return [...names];
+}
 function namesFromCategories(config) {
-    if (!config.categories || typeof config.categories !== "object") {
-        return [];
+    const names = new Set();
+    if (Array.isArray(config.categories)) {
+        for (const category of config.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 Object.keys(config.categories).sort();
+    for (const category of categoryNamesFromEngines(config)) {
+        names.add(category);
+    }
+    return [...names].sort();
 }
 function engineCategories(engine) {
     if (Array.isArray(engine.categories)) {
@@ -51,6 +79,17 @@ function collectEngines(config, includeDisabled, category) {
         ...(includeDisabled ? { disabled: [...disabled].sort() } : {}),
     };
 }
+function allEngineNames(config) {
+    const names = new Set();
+    if (Array.isArray(config.engines)) {
+        for (const engine of config.engines) {
+            if (engine && typeof engine.name === "string") {
+                names.add(engine.name);
+            }
+        }
+    }
+    return names;
+}
 function formatInstanceInfo(config, includeEngines, includeDisabled, category) {
     const categories = category
         ? namesFromCategories(config).filter((name) => name === category)
@@ -76,16 +115,19 @@ export function clearInstanceInfoCacheForTests() {
     cachedConfig = null;
     cachedBaseUrl = null;
 }
-export async function fetchInstanceInfo(mcpServer, includeEngines = false, includeDisabled = false, category, refresh = false) {
+async function fetchConfig(mcpServer, refresh = false) {
     const base = process.env.SEARXNG_URL;
     if (!base) {
-        return unavailable("SEARXNG_URL is not configured; cannot fetch SearXNG /config.");
+        return {
+            available: false,
+            message: "SEARXNG_URL is not configured; cannot fetch SearXNG /config.",
+        };
     }
     if (refresh) {
         cachedConfig = null;
     }
     if (cachedConfig && cachedBaseUrl === base) {
-        return formatInstanceInfo(cachedConfig, includeEngines, includeDisabled, category);
+        return { available: true, config: cachedConfig };
     }
     const parsedBase = new URL(base.endsWith("/") ? base : `${base}/`);
     const url = new URL("config", parsedBase);
@@ -100,14 +142,42 @@ export async function fetchInstanceInfo(mcpServer, includeEngines = false, inclu
         }
         const response = await fetch(url.toString(), requestOptions);
         if (!response.ok) {
-            return unavailable(`SearXNG /config is unavailable: HTTP ${response.status} ${response.statusText}`, response.status);
+            return {
+                available: false,
+                message: `SearXNG /config is unavailable: HTTP ${response.status} ${response.statusText}`,
+                status: response.status,
+            };
         }
         cachedConfig = await response.json();
         cachedBaseUrl = base;
-        return formatInstanceInfo(cachedConfig, includeEngines, includeDisabled, category);
+        return { available: true, config: cachedConfig };
     }
     catch (error) {
         logMessage(mcpServer, "warning", `SearXNG /config fetch failed: ${error instanceof Error ? error.message : String(error)}`);
-        return unavailable("SearXNG /config is unavailable; instance capability discovery could not complete.");
+        return {
+            available: false,
+            message: "SearXNG /config is unavailable; instance capability discovery could not complete.",
+        };
+    }
+}
+export async function getKnownEngines(mcpServer, refresh = false) {
+    const result = await fetchConfig(mcpServer, refresh);
+    if (!result.available) {
+        return null;
+    }
+    return allEngineNames(result.config);
+}
+export async function getKnownCategories(mcpServer, refresh = false) {
+    const result = await fetchConfig(mcpServer, refresh);
+    if (!result.available) {
+        return null;
+    }
+    return new Set(namesFromCategories(result.config));
+}
+export async function fetchInstanceInfo(mcpServer, includeEngines = false, includeDisabled = false, category, refresh = false) {
+    const result = await fetchConfig(mcpServer, refresh);
+    if (!result.available) {
+        return unavailable(result.message, result.status);
     }
+    return formatInstanceInfo(result.config, includeEngines, includeDisabled, category);
 }

package/dist/resources.js

@@ -53,10 +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"
-- \`response_format\` (optional): "text" for formatted output or "json" for raw SearXNG-shaped JSON
+- \`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
+- \`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\`.
+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.
 
 ### 2. searxng_search_suggestions
 Returns autocomplete suggestions from the configured SearXNG instance.

package/dist/search.d.ts

@@ -1,2 +1,2 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function performWebSearch(mcpServer: McpServer, query: string, pageno?: number, time_range?: string, language?: string, safesearch?: number, min_score?: number, num_results?: number, categories?: string, response_format?: "text" | "json"): Promise<string>;
+export declare function performWebSearch(mcpServer: McpServer, query: string, pageno?: number, time_range?: string, language?: string, safesearch?: number, min_score?: number, num_results?: number, categories?: string, engines?: string, response_format?: "text" | "json"): Promise<string>;

package/dist/search.js

@@ -1,3 +1,5 @@
+import { parse } from "node-html-parser";
+import { getKnownCategories, getKnownEngines } from "./instance-info.js";
 import { createProxyAgent, createDefaultAgent, ProxyType } from "./proxy.js";
 import { logMessage } from "./logging.js";
 import { MCPSearXNGError, validateEnvironment, createNetworkError, createServerError, createJSONError, createDataError, createNoResultsMessage } from "./error-handler.js";
@@ -31,9 +33,226 @@ function truncateResultContent(content, maxResultChars) {
     }
     return `${content.slice(0, maxResultChars)}…`;
 }
+function normalizeHtmlText(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function isHtmlFallbackEnabled() {
+    return process.env.SEARXNG_HTML_FALLBACK === "true";
+}
+function shouldFallbackForStatus(status) {
+    return status === 403 || status === 404;
+}
+function buildHtmlFallbackUrl(jsonUrl) {
+    const htmlUrl = new URL(jsonUrl.toString());
+    htmlUrl.searchParams.delete("format");
+    return htmlUrl;
+}
+function parseHtmlSearchResults(html, query) {
+    const root = parse(html);
+    const articles = root.querySelectorAll("article.result");
+    const candidates = articles.length > 0 ? articles : root.querySelectorAll(".result");
+    const results = candidates
+        .map((entry) => {
+        const link = entry.querySelector("h3 > a") ?? entry.querySelector("h3 a") ?? entry.querySelector("a[href]");
+        if (!link) {
+            return undefined;
+        }
+        const href = link?.getAttribute("href")?.trim();
+        if (!href) {
+            return undefined;
+        }
+        try {
+            new URL(href);
+        }
+        catch {
+            return undefined;
+        }
+        const title = normalizeHtmlText(link.text);
+        const snippetNode = entry.querySelector("p.content") ?? entry.querySelector(".content");
+        const content = snippetNode ? normalizeHtmlText(snippetNode.text) : "";
+        return {
+            title,
+            url: href,
+            content,
+        };
+    })
+        .filter((result) => result !== undefined);
+    return {
+        query,
+        number_of_results: results.length,
+        results,
+        sourceFormat: "html",
+    };
+}
+async function fetchWithSearchTimeout(mcpServer, url, requestOptions, timeoutMs, query, searxngUrl) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        logMessage(mcpServer, "info", `Making request to: ${url.toString()}`);
+        return await fetch(url.toString(), {
+            ...requestOptions,
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        logMessage(mcpServer, "error", `Network error during search request: ${error.message}`, { query, url: url.toString() });
+        const context = {
+            url: url.toString(),
+            searxngUrl,
+            proxyAgent: !!requestOptions.dispatcher,
+            username: process.env.AUTH_USERNAME,
+        };
+        throw createNetworkError(error, context);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+async function fetchHtmlFallbackSearch(mcpServer, jsonUrl, requestOptions, timeoutMs, query, searxngUrl) {
+    const htmlUrl = buildHtmlFallbackUrl(jsonUrl);
+    logMessage(mcpServer, "info", `Retrying search with HTML fallback: ${htmlUrl.toString()}`);
+    const response = await fetchWithSearchTimeout(mcpServer, htmlUrl, requestOptions, timeoutMs, query, searxngUrl);
+    if (!response.ok) {
+        let responseBody;
+        try {
+            responseBody = await response.text();
+        }
+        catch {
+            responseBody = '[Could not read response body]';
+        }
+        const context = {
+            url: htmlUrl.toString(),
+            searxngUrl,
+        };
+        throw createServerError(response.status, response.statusText, responseBody, context);
+    }
+    const html = await response.text();
+    return parseHtmlSearchResults(html, query);
+}
 function hasItems(items) {
     return Array.isArray(items) && items.length > 0;
 }
+function splitCommaSeparated(value) {
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry !== "");
+}
+function buildCanonicalLookup(knownValues) {
+    const lookup = new Map();
+    for (const value of knownValues) {
+        lookup.set(value.trim().toLowerCase(), value);
+    }
+    return lookup;
+}
+function normalizeCommaSeparated(value, knownValues) {
+    const lookup = buildCanonicalLookup(knownValues);
+    const normalized = [];
+    const invalid = [];
+    for (const requested of splitCommaSeparated(value)) {
+        const canonical = lookup.get(requested.toLowerCase());
+        if (canonical === undefined) {
+            invalid.push(requested);
+        }
+        else {
+            normalized.push(canonical);
+        }
+    }
+    return {
+        normalized: normalized.join(","),
+        invalid,
+    };
+}
+function formatAvailableValues(label, values) {
+    const available = [...values].sort().join(", ");
+    return available === "" ? "" : ` Available ${label}: ${available}.`;
+}
+function createValidationError(kind, invalid, available) {
+    const label = kind === "category" ? "categories" : "engines";
+    return new MCPSearXNGError(`🔍 Invalid SearXNG ${kind} name(s): ${invalid.join(", ")}.` +
+        formatAvailableValues(label, available) +
+        ` Use the searxng_instance_info tool to discover available ${label}.`);
+}
+async function normalizeSearchFilters(mcpServer, categories, engines) {
+    const effectiveCategories = categories !== undefined && categories.trim() !== "" ? categories : undefined;
+    const effectiveEngines = engines !== undefined && engines.trim() !== "" ? engines : undefined;
+    if (!effectiveCategories && !effectiveEngines) {
+        return {};
+    }
+    const unavailableFilterLabel = effectiveCategories && effectiveEngines
+        ? "categories and engines"
+        : effectiveCategories
+            ? "categories"
+            : "engines";
+    const unavailableWarning = `${unavailableFilterLabel[0].toUpperCase()}${unavailableFilterLabel.slice(1)} were not validated or normalized because SearXNG /config is unavailable.`;
+    const unavailableNote = `Note: ${unavailableFilterLabel} were not validated or normalized (SearXNG /config unavailable).`;
+    let knownCategories;
+    let knownEngines;
+    if (effectiveCategories) {
+        knownCategories = await getKnownCategories(mcpServer);
+        if (knownCategories === null) {
+            return {
+                categories: effectiveCategories,
+                engines: effectiveEngines,
+                validationWarning: unavailableWarning,
+                validationNote: unavailableNote,
+            };
+        }
+    }
+    if (effectiveEngines) {
+        knownEngines = await getKnownEngines(mcpServer);
+        if (knownEngines === null) {
+            return {
+                categories: effectiveCategories,
+                engines: effectiveEngines,
+                validationWarning: unavailableWarning,
+                validationNote: unavailableNote,
+            };
+        }
+    }
+    let normalizedCategories = effectiveCategories && knownCategories
+        ? normalizeCommaSeparated(effectiveCategories, knownCategories)
+        : undefined;
+    let normalizedEngines = effectiveEngines && knownEngines
+        ? normalizeCommaSeparated(effectiveEngines, knownEngines)
+        : undefined;
+    if ((normalizedCategories && normalizedCategories.invalid.length > 0) ||
+        (normalizedEngines && normalizedEngines.invalid.length > 0)) {
+        if (effectiveCategories) {
+            knownCategories = await getKnownCategories(mcpServer, true);
+            knownEngines = effectiveEngines && knownCategories !== null
+                ? await getKnownEngines(mcpServer)
+                : knownEngines;
+        }
+        else if (effectiveEngines) {
+            knownEngines = await getKnownEngines(mcpServer, true);
+        }
+        if (knownCategories === null || knownEngines === null) {
+            return {
+                categories: effectiveCategories,
+                engines: effectiveEngines,
+                validationWarning: unavailableWarning,
+                validationNote: unavailableNote,
+            };
+        }
+        normalizedCategories = effectiveCategories && knownCategories
+            ? normalizeCommaSeparated(effectiveCategories, knownCategories)
+            : undefined;
+        normalizedEngines = effectiveEngines && knownEngines
+            ? normalizeCommaSeparated(effectiveEngines, knownEngines)
+            : undefined;
+    }
+    if (normalizedCategories && normalizedCategories.invalid.length > 0 && knownCategories) {
+        throw createValidationError("category", normalizedCategories.invalid, knownCategories);
+    }
+    if (normalizedEngines && normalizedEngines.invalid.length > 0 && knownEngines) {
+        throw createValidationError("engine", normalizedEngines.invalid, knownEngines);
+    }
+    return {
+        categories: normalizedCategories ? normalizedCategories.normalized : undefined,
+        engines: normalizedEngines ? normalizedEngines.normalized : undefined,
+    };
+}
 function formatSearchMetadata(data) {
     const sections = [];
     if (hasItems(data.answers)) {
@@ -77,7 +296,7 @@ function getDefaultSafesearch(mcpServer) {
     }
     return parsed;
 }
-export async function performWebSearch(mcpServer, query, pageno = 1, time_range, language, safesearch, min_score, num_results, categories, response_format = "text") {
+export async function performWebSearch(mcpServer, query, pageno = 1, time_range, language, safesearch, min_score, num_results, categories, engines, response_format = "text") {
     const startTime = Date.now();
     const operatorMax = getOperatorMaxResults(mcpServer);
     const effectiveMax = operatorMax !== undefined
@@ -86,6 +305,12 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
     const maxResultChars = getMaxResultChars(mcpServer);
     const effectiveLanguage = language ?? getDefaultLanguage();
     const effectiveSafesearch = safesearch !== undefined ? safesearch : getDefaultSafesearch(mcpServer);
+    const validationError = validateEnvironment();
+    if (validationError) {
+        logMessage(mcpServer, "error", "Configuration invalid");
+        throw new MCPSearXNGError(validationError);
+    }
+    const filters = await normalizeSearchFilters(mcpServer, categories, engines);
     // Build detailed log message with all parameters
     const searchParams = [
         `page ${pageno}`,
@@ -94,14 +319,10 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
         effectiveSafesearch !== undefined ? `safesearch: ${effectiveSafesearch}` : null,
         min_score !== undefined ? `min_score: ${min_score}` : null,
         effectiveMax !== undefined ? `num_results: ${effectiveMax}` : null,
-        categories ? `categories: ${categories}` : null,
+        filters.categories ? `categories: ${filters.categories}` : null,
+        filters.engines ? `engines: ${filters.engines}` : null,
     ].filter(Boolean).join(", ");
     logMessage(mcpServer, "info", `Starting web search: "${query}" (${searchParams})`);
-    const validationError = validateEnvironment();
-    if (validationError) {
-        logMessage(mcpServer, "error", "Configuration invalid");
-        throw new MCPSearXNGError(validationError);
-    }
     const searxngUrl = process.env.SEARXNG_URL;
     const parsedUrl = new URL(searxngUrl.endsWith('/') ? searxngUrl : searxngUrl + '/');
     const url = new URL('search', parsedUrl);
@@ -118,8 +339,11 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
     if (effectiveSafesearch !== undefined && [0, 1, 2].includes(effectiveSafesearch)) {
         url.searchParams.set("safesearch", effectiveSafesearch.toString());
     }
-    if (categories) {
-        url.searchParams.set("categories", categories);
+    if (filters.categories) {
+        url.searchParams.set("categories", filters.categories);
+    }
+    if (filters.engines) {
+        url.searchParams.set("engines", filters.engines);
     }
     // Prepare request options with headers
     const requestOptions = {
@@ -151,57 +375,49 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
     }
     // Fetch with AbortController timeout and enhanced error handling
     const SEARCH_TIMEOUT_MS = parseInt(process.env.SEARXNG_TIMEOUT_MS ?? "10000", 10);
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), SEARCH_TIMEOUT_MS);
     let response;
-    try {
-        logMessage(mcpServer, "info", `Making request to: ${url.toString()}`);
-        response = await fetch(url.toString(), {
-            ...requestOptions,
-            signal: controller.signal,
-        });
-    }
-    catch (error) {
-        clearTimeout(timeoutId);
-        logMessage(mcpServer, "error", `Network error during search request: ${error.message}`, { query, url: url.toString() });
-        const context = {
-            url: url.toString(),
-            searxngUrl,
-            proxyAgent: !!dispatcher,
-            username
-        };
-        throw createNetworkError(error, context);
-    }
-    clearTimeout(timeoutId);
+    response = await fetchWithSearchTimeout(mcpServer, url, requestOptions, SEARCH_TIMEOUT_MS, query, searxngUrl);
+    let data;
     if (!response.ok) {
-        let responseBody;
-        try {
-            responseBody = await response.text();
+        if (isHtmlFallbackEnabled() && shouldFallbackForStatus(response.status)) {
+            data = await fetchHtmlFallbackSearch(mcpServer, url, requestOptions, SEARCH_TIMEOUT_MS, query, searxngUrl);
         }
-        catch {
-            responseBody = '[Could not read response body]';
+        else {
+            let responseBody;
+            try {
+                responseBody = await response.text();
+            }
+            catch {
+                responseBody = '[Could not read response body]';
+            }
+            const context = {
+                url: url.toString(),
+                searxngUrl
+            };
+            throw createServerError(response.status, response.statusText, responseBody, context);
         }
-        const context = {
-            url: url.toString(),
-            searxngUrl
-        };
-        throw createServerError(response.status, response.statusText, responseBody, context);
-    }
-    // Parse JSON response
-    let data;
-    try {
-        data = (await response.json());
     }
-    catch (error) {
-        let responseText;
+    else {
+        // Parse JSON response
         try {
-            responseText = await response.text();
+            data = (await response.json());
         }
-        catch {
-            responseText = '[Could not read response text]';
+        catch (error) {
+            if (isHtmlFallbackEnabled()) {
+                data = await fetchHtmlFallbackSearch(mcpServer, url, requestOptions, SEARCH_TIMEOUT_MS, query, searxngUrl);
+            }
+            else {
+                let responseText;
+                try {
+                    responseText = await response.text();
+                }
+                catch {
+                    responseText = '[Could not read response text]';
+                }
+                const context = { url: url.toString() };
+                throw createJSONError(responseText, context);
+            }
         }
-        const context = { url: url.toString() };
-        throw createJSONError(responseText, context);
     }
     if (!data.results) {
         const context = { url: url.toString(), query };
@@ -213,9 +429,18 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
         ? results.slice(0, effectiveMax)
         : results;
     if (response_format === "json") {
-        return JSON.stringify({ ...data, results: slicedResults }, null, 2);
+        return JSON.stringify({
+            ...data,
+            results: slicedResults,
+            ...(filters.validationWarning ? { warnings: [filters.validationWarning] } : {}),
+        }, null, 2);
     }
     const metadata = formatSearchMetadata(data);
+    const leadingSections = [
+        filters.validationNote ?? null,
+        data.sourceFormat === "html" ? "Note: Results parsed from SearXNG HTML fallback; metadata is limited." : null,
+        metadata || null,
+    ].filter(Boolean).join("\n\n");
     if (slicedResults.length === 0) {
         const appliedFilters = [
             min_score === undefined ? null : `min_score=${min_score}`,
@@ -224,15 +449,22 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
         const filterNote = appliedFilters ? ` after applying ${appliedFilters}` : "";
         logMessage(mcpServer, "info", `No results found for query: "${query}"${filterNote}`);
         const noResultsMessage = createNoResultsMessage(query);
-        return metadata ? `${metadata}\n\n---\n\n${noResultsMessage}` : noResultsMessage;
+        return leadingSections ? `${leadingSections}\n\n---\n\n${noResultsMessage}` : noResultsMessage;
     }
     const duration = Date.now() - startTime;
     logMessage(mcpServer, "info", `Search completed: "${query}" (${searchParams}) - ${slicedResults.length} results in ${duration}ms`);
     const formattedResults = slicedResults
         .map((r) => {
-        const score = r.score || 0;
-        return `Title: ${r.title || ""}\nDescription: ${truncateResultContent(r.content || "", maxResultChars)}\nURL: ${r.url || ""}\nRelevance Score: ${score.toFixed(3)}`;
+        const lines = [
+            `Title: ${r.title || ""}`,
+            `Description: ${truncateResultContent(r.content || "", maxResultChars)}`,
+            `URL: ${r.url || ""}`,
+        ];
+        if (r.score !== undefined) {
+            lines.push(`Relevance Score: ${r.score.toFixed(3)}`);
+        }
+        return lines.join("\n");
     })
         .join("\n\n");
-    return metadata ? `${metadata}\n\n---\n\n${formattedResults}` : formattedResults;
+    return leadingSections ? `${leadingSections}\n\n---\n\n${formattedResults}` : formattedResults;
 }

package/dist/types.d.ts

@@ -3,7 +3,7 @@ export interface SearXNGWebResult {
     title: string;
     content: string;
     url: string;
-    score: number;
+    score?: number;
     engine?: string;
     engines?: string[];
     category?: string;
@@ -23,6 +23,7 @@ export interface SearXNGWeb {
     query: string;
     number_of_results: number;
     results: SearXNGWebResult[];
+    sourceFormat?: "json" | "html";
     suggestions?: string[];
     corrections?: string[];
     answers?: string[];
@@ -38,6 +39,7 @@ export declare function isSearXNGWebSearchArgs(args: unknown): args is {
     min_score?: number;
     num_results?: number;
     categories?: string;
+    engines?: string;
     response_format?: "text" | "json";
 };
 export declare function isSearXNGSearchSuggestionsArgs(args: unknown): args is {

package/dist/types.js

@@ -41,6 +41,9 @@ export function isSearXNGWebSearchArgs(args) {
     if (searchArgs.categories !== undefined && typeof searchArgs.categories !== "string") {
         return false;
     }
+    if (searchArgs.engines !== undefined && typeof searchArgs.engines !== "string") {
+        return false;
+    }
     if (searchArgs.response_format !== undefined &&
         (typeof searchArgs.response_format !== "string" || !VALID_RESPONSE_FORMATS.includes(searchArgs.response_format))) {
         return false;
@@ -132,7 +135,11 @@ export const WEB_SEARCH_TOOL = {
             },
             categories: {
                 type: "string",
-                description: "Comma-separated SearXNG categories. Supported: general, news, images, videos, it, science, files, social media. Default: general (SearXNG instance default).",
+                description: "Comma-separated SearXNG categories. Values are normalized case-insensitively to canonical names from live /config; unknown values are rejected with available categories listed. If /config is unavailable, values are forwarded as-is with a warning.",
+            },
+            engines: {
+                type: "string",
+                description: "Comma-separated SearXNG engine names to query (e.g. 'google,bing,ddg'). Values are normalized case-insensitively to canonical names from live /config; unknown values are rejected with available engines listed. If /config is unavailable, values are forwarded as-is with a warning.",
             },
             response_format: {
                 type: "string",

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const packageVersion = "1.5.0";
+export declare const packageVersion = "1.7.0";

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "1.5.0";
+export const packageVersion = "1.7.0";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mcp-searxng",
-    "version": "1.5.0",
+    "version": "1.7.0",
     "mcpName": "io.github.ihor-sokoliuk/mcp-searxng",
     "description": "MCP server for SearXNG integration",
     "license": "MIT",
@@ -55,21 +55,25 @@
         "express": "^5.2.1",
         "express-rate-limit": "^8.5.2",
         "node-html-markdown": "^2.0.0",
-        "undici": "7.27.2"
+        "node-html-parser": "^6.1.13",
+        "undici": "7.28.0"
     },
     "devDependencies": {
-        "@types/node": "22.19.20",
+        "@types/node": "22.19.21",
         "@types/supertest": "^7.2.0",
-        "@typescript-eslint/eslint-plugin": "8.61.0",
-        "@typescript-eslint/parser": "8.61.0",
+        "@typescript-eslint/eslint-plugin": "8.61.1",
+        "@typescript-eslint/parser": "8.61.1",
         "c8": "^11.0.0",
         "cross-env": "^10.1.0",
-        "eslint": "10.4.1",
+        "eslint": "10.5.0",
         "eslint-plugin-security": "^4.0.0",
         "fast-check": "^4.8.0",
         "shx": "^0.4.0",
         "supertest": "^7.2.2",
         "tsx": "4.22.4",
         "typescript": "^5.8.3"
+    },
+    "overrides": {
+        "hono": ">=4.12.25"
     }
 }