mcp-searxng 1.3.3 → 1.4.0

package/README.md

@@ -10,7 +10,7 @@
 [![Docker Pulls](https://img.shields.io/docker/pulls/isokoliuk/mcp-searxng?style=flat-square&logo=docker)](https://hub.docker.com/r/isokoliuk/mcp-searxng)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ihor-sokoliuk/mcp-searxng/badge)](https://scorecard.dev/viewer/?uri=github.com/ihor-sokoliuk/mcp-searxng)
-[![OpenSSF Baseline](https://www.bestpractices.dev/projects/13143/baseline)](https://www.bestpractices.dev/projects/13143)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13143/badge)](https://www.bestpractices.dev/projects/13143)
 [![mcp-searxng MCP server](https://glama.ai/mcp/servers/ihor-sokoliuk/mcp-searxng/badges/score.svg)](https://glama.ai/mcp/servers/ihor-sokoliuk/mcp-searxng)
 
 An [MCP server](https://modelcontextprotocol.io/introduction) that integrates the [SearXNG](https://docs.searxng.org) API, giving AI assistants web search capabilities.
@@ -86,6 +86,8 @@ AI Assistant (e.g. Claude)
     - `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)
     - `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`).
 
 - **web_url_read**
   - Read and convert the content from a URL to markdown with advanced content extraction options
@@ -130,6 +132,8 @@ npm install -g mcp-searxng
 docker pull isokoliuk/mcp-searxng:latest
 ```
 
+Image signatures can be verified with Cosign — see [SECURITY.md](SECURITY.md) for instructions.
+
 ```json
 {
   "mcpServers": {

package/dist/index.js

@@ -2,7 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, SetLevelRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 // Import modularized functionality
-import { WEB_SEARCH_TOOL, READ_URL_TOOL, isSearXNGWebSearchArgs } from "./types.js";
+import { WEB_SEARCH_TOOL, READ_URL_TOOL, LITE_WEB_SEARCH_TOOL, LITE_READ_URL_TOOL, isSearXNGWebSearchArgs } from "./types.js";
 import { logMessage, setLogLevel, getCurrentLogLevel } from "./logging.js";
 import { performWebSearch } from "./search.js";
 import { fetchAndConvertToMarkdown } from "./url-reader.js";
@@ -41,6 +41,30 @@ export function isWebUrlReadArgs(args) {
     }
     return true;
 }
+function getFetchTimeoutMs(mcpServer) {
+    const rawValue = process.env.FETCH_TIMEOUT_MS;
+    if (rawValue === undefined || rawValue.trim() === "") {
+        return 10000;
+    }
+    const parsed = parseInt(rawValue, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        logMessage(mcpServer, "warning", `Ignoring invalid FETCH_TIMEOUT_MS="${rawValue}". Expected a positive integer. Using default 10000.`);
+        return 10000;
+    }
+    return parsed;
+}
+function getDefaultUrlReadMaxChars(mcpServer) {
+    const rawValue = process.env.URL_READ_MAX_CHARS;
+    if (rawValue === undefined || rawValue.trim() === "") {
+        return undefined;
+    }
+    const parsed = parseInt(rawValue, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        logMessage(mcpServer, "warning", `Ignoring invalid URL_READ_MAX_CHARS="${rawValue}". Expected a positive integer.`);
+        return undefined;
+    }
+    return parsed;
+}
 /**
  * Creates and configures a new McpServer with all handlers registered.
  * Called once per HTTP session, or once for STDIO mode.
@@ -57,11 +81,14 @@ export function createMcpServer() {
         },
     });
     const server = mcpServer.server;
+    const useLiteTools = process.env.SEARXNG_LITE_TOOLS === "true";
+    const searchTool = useLiteTools ? LITE_WEB_SEARCH_TOOL : WEB_SEARCH_TOOL;
+    const readUrlTool = useLiteTools ? LITE_READ_URL_TOOL : READ_URL_TOOL;
     // List tools handler
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         logMessage(mcpServer, "debug", "Handling list_tools request");
         return {
-            tools: [WEB_SEARCH_TOOL, READ_URL_TOOL],
+            tools: [searchTool, readUrlTool],
         };
     });
     // Call tool handler
@@ -73,7 +100,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);
+                const result = await performWebSearch(mcpServer, args.query, args.pageno, args.time_range, args.language, args.safesearch, args.min_score, args.num_results, args.categories);
                 return {
                     content: [
                         {
@@ -87,14 +114,15 @@ export function createMcpServer() {
                 if (!isWebUrlReadArgs(args)) {
                     throw new Error("Invalid arguments for URL reading");
                 }
+                const defaultMaxLength = getDefaultUrlReadMaxChars(mcpServer);
                 const paginationOptions = {
                     startChar: args.startChar,
-                    maxLength: args.maxLength,
+                    maxLength: args.maxLength ?? defaultMaxLength,
                     section: args.section,
                     paragraphRange: args.paragraphRange,
                     readHeadings: args.readHeadings,
                 };
-                const result = await fetchAndConvertToMarkdown(mcpServer, args.url, 10000, paginationOptions);
+                const result = await fetchAndConvertToMarkdown(mcpServer, args.url, getFetchTimeoutMs(mcpServer), paginationOptions);
                 return {
                     content: [
                         {

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): 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): Promise<string>;

package/dist/search.js

@@ -1,14 +1,69 @@
 import { createProxyAgent, createDefaultAgent, ProxyType } from "./proxy.js";
 import { logMessage } from "./logging.js";
 import { MCPSearXNGError, validateEnvironment, createNetworkError, createServerError, createJSONError, createDataError, createNoResultsMessage } from "./error-handler.js";
-export async function performWebSearch(mcpServer, query, pageno = 1, time_range, language = "all", safesearch, min_score) {
+function getOperatorMaxResults(mcpServer) {
+    const rawValue = process.env.SEARXNG_MAX_RESULTS;
+    if (rawValue === undefined || rawValue.trim() === "") {
+        return undefined;
+    }
+    const parsed = parseInt(rawValue, 10);
+    if (Number.isNaN(parsed) || parsed <= 0 || parsed > 20) {
+        logMessage(mcpServer, "warning", `Ignoring invalid SEARXNG_MAX_RESULTS="${rawValue}". Expected an integer from 1 to 20.`);
+        return undefined;
+    }
+    return parsed;
+}
+function getMaxResultChars(mcpServer) {
+    const rawValue = process.env.SEARXNG_MAX_RESULT_CHARS;
+    if (rawValue === undefined || rawValue.trim() === "") {
+        return undefined;
+    }
+    const parsed = parseInt(rawValue, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        logMessage(mcpServer, "warning", `Ignoring invalid SEARXNG_MAX_RESULT_CHARS="${rawValue}". Expected a positive integer.`);
+        return undefined;
+    }
+    return parsed;
+}
+function truncateResultContent(content, maxResultChars) {
+    if (maxResultChars === undefined || content.length <= maxResultChars) {
+        return content;
+    }
+    return `${content.slice(0, maxResultChars)}…`;
+}
+function getDefaultLanguage() {
+    return process.env.SEARXNG_DEFAULT_LANGUAGE ?? "all";
+}
+function getDefaultSafesearch(mcpServer) {
+    const rawValue = process.env.SEARXNG_DEFAULT_SAFESEARCH;
+    if (rawValue === undefined || rawValue.trim() === "") {
+        return undefined;
+    }
+    const parsed = parseInt(rawValue, 10);
+    if (Number.isNaN(parsed) || ![0, 1, 2].includes(parsed)) {
+        logMessage(mcpServer, "warning", `Ignoring invalid SEARXNG_DEFAULT_SAFESEARCH="${rawValue}". Expected 0, 1, or 2.`);
+        return undefined;
+    }
+    return parsed;
+}
+export async function performWebSearch(mcpServer, query, pageno = 1, time_range, language, safesearch, min_score, num_results, categories) {
     const startTime = Date.now();
+    const operatorMax = getOperatorMaxResults(mcpServer);
+    const effectiveMax = operatorMax !== undefined
+        ? (num_results !== undefined ? Math.min(num_results, operatorMax) : operatorMax)
+        : num_results;
+    const maxResultChars = getMaxResultChars(mcpServer);
+    const effectiveLanguage = language ?? getDefaultLanguage();
+    const effectiveSafesearch = safesearch !== undefined ? safesearch : getDefaultSafesearch(mcpServer);
     // Build detailed log message with all parameters
     const searchParams = [
         `page ${pageno}`,
-        `lang: ${language}`,
+        `lang: ${effectiveLanguage}`,
         time_range ? `time: ${time_range}` : null,
-        safesearch ? `safesearch: ${safesearch}` : null
+        effectiveSafesearch !== undefined ? `safesearch: ${effectiveSafesearch}` : null,
+        min_score !== undefined ? `min_score: ${min_score}` : null,
+        effectiveMax !== undefined ? `num_results: ${effectiveMax}` : null,
+        categories ? `categories: ${categories}` : null,
     ].filter(Boolean).join(", ");
     logMessage(mcpServer, "info", `Starting web search: "${query}" (${searchParams})`);
     const validationError = validateEnvironment();
@@ -26,11 +81,14 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
         ["day", "week", "month", "year"].includes(time_range)) {
         url.searchParams.set("time_range", time_range);
     }
-    if (language && language !== "all") {
-        url.searchParams.set("language", language);
+    if (effectiveLanguage && effectiveLanguage !== "all") {
+        url.searchParams.set("language", effectiveLanguage);
+    }
+    if (effectiveSafesearch !== undefined && [0, 1, 2].includes(effectiveSafesearch)) {
+        url.searchParams.set("safesearch", effectiveSafesearch.toString());
     }
-    if (safesearch !== undefined && [0, 1, 2].includes(safesearch)) {
-        url.searchParams.set("safesearch", safesearch.toString());
+    if (categories) {
+        url.searchParams.set("categories", categories);
     }
     // Prepare request options with headers
     const requestOptions = {
@@ -126,14 +184,21 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
         score: result.score || 0,
     }))
         .filter((result) => min_score === undefined || result.score >= min_score);
-    if (results.length === 0) {
-        const filterNote = min_score === undefined ? "" : ` after applying min_score=${min_score}`;
+    const slicedResults = effectiveMax !== undefined
+        ? results.slice(0, effectiveMax)
+        : results;
+    if (slicedResults.length === 0) {
+        const appliedFilters = [
+            min_score === undefined ? null : `min_score=${min_score}`,
+            effectiveMax === undefined ? null : `num_results=${effectiveMax}`,
+        ].filter(Boolean).join(" ");
+        const filterNote = appliedFilters ? ` after applying ${appliedFilters}` : "";
         logMessage(mcpServer, "info", `No results found for query: "${query}"${filterNote}`);
         return createNoResultsMessage(query);
     }
     const duration = Date.now() - startTime;
-    logMessage(mcpServer, "info", `Search completed: "${query}" (${searchParams}) - ${results.length} results in ${duration}ms`);
-    return results
-        .map((r) => `Title: ${r.title}\nDescription: ${r.content}\nURL: ${r.url}\nRelevance Score: ${r.score.toFixed(3)}`)
+    logMessage(mcpServer, "info", `Search completed: "${query}" (${searchParams}) - ${slicedResults.length} results in ${duration}ms`);
+    return slicedResults
+        .map((r) => `Title: ${r.title}\nDescription: ${truncateResultContent(r.content, maxResultChars)}\nURL: ${r.url}\nRelevance Score: ${r.score.toFixed(3)}`)
         .join("\n\n");
 }

package/dist/types.d.ts

@@ -36,6 +36,10 @@ export declare function isSearXNGWebSearchArgs(args: unknown): args is {
     language?: string;
     safesearch?: number;
     min_score?: number;
+    num_results?: number;
+    categories?: string;
 };
 export declare const WEB_SEARCH_TOOL: Tool;
+export declare const LITE_WEB_SEARCH_TOOL: Tool;
+export declare const LITE_READ_URL_TOOL: Tool;
 export declare const READ_URL_TOOL: Tool;

package/dist/types.js

@@ -29,6 +29,17 @@ export function isSearXNGWebSearchArgs(args) {
             searchArgs.min_score > 1)) {
         return false;
     }
+    if (searchArgs.num_results !== undefined &&
+        (typeof searchArgs.num_results !== "number" ||
+            Number.isNaN(searchArgs.num_results) ||
+            !Number.isInteger(searchArgs.num_results) ||
+            searchArgs.num_results < 1 ||
+            searchArgs.num_results > 20)) {
+        return false;
+    }
+    if (searchArgs.categories !== undefined && typeof searchArgs.categories !== "string") {
+        return false;
+    }
     return true;
 }
 export const WEB_SEARCH_TOOL = {
@@ -76,10 +87,38 @@ export const WEB_SEARCH_TOOL = {
                 minimum: 0,
                 maximum: 1,
             },
+            num_results: {
+                type: "number",
+                description: "Maximum number of results to return (1-20). Operator cap SEARXNG_MAX_RESULTS applies as a ceiling.",
+                minimum: 1,
+                maximum: 20,
+            },
+            categories: {
+                type: "string",
+                description: "Comma-separated SearXNG categories. Supported: general, news, images, videos, it, science, files, social media. Default: general (SearXNG instance default).",
+            },
         },
         required: ["query"],
     },
 };
+export const LITE_WEB_SEARCH_TOOL = {
+    name: "searxng_web_search",
+    description: "Web search. Returns titles, URLs, snippets.",
+    inputSchema: {
+        type: "object",
+        properties: { query: { type: "string", description: "Search query." } },
+        required: ["query"],
+    },
+};
+export const LITE_READ_URL_TOOL = {
+    name: "web_url_read",
+    description: "Fetch URL. Returns page text as markdown.",
+    inputSchema: {
+        type: "object",
+        properties: { url: { type: "string", description: "URL to fetch." } },
+        required: ["url"],
+    },
+};
 export const READ_URL_TOOL = {
     name: "web_url_read",
     description: "Fetches a URL and returns its text content converted to markdown. " +

package/dist/url-reader.d.ts

@@ -1,4 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Dispatcher } from "undici";
 interface PaginationOptions {
     startChar?: number;
     maxLength?: number;
@@ -6,5 +7,7 @@ interface PaginationOptions {
     paragraphRange?: string;
     readHeadings?: boolean;
 }
+export declare const DEFAULT_MAX_CONTENT_LENGTH_BYTES: number;
+export declare function checkContentLength(mcpServer: McpServer, url: string, timeoutMs: number, dispatcher?: Dispatcher, baseRequestOptions?: RequestInit): Promise<number | null>;
 export declare function fetchAndConvertToMarkdown(mcpServer: McpServer, url: string, timeoutMs?: number, paginationOptions?: PaginationOptions): Promise<string>;
 export {};

package/dist/url-reader.js

@@ -8,6 +8,8 @@ import { getHttpSecurityConfig } from "./http-security.js";
 import { createURLFormatError, createURLSecurityPolicyError, createNetworkError, createServerError, createContentError, createConversionError, createTimeoutError, createEmptyContentWarning, createUnexpectedError } from "./error-handler.js";
 const REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308]);
 const MAX_REDIRECTS = 5;
+export const DEFAULT_MAX_CONTENT_LENGTH_BYTES = 5 * 1024 * 1024;
+const HEAD_TIMEOUT_CAP_MS = 3000;
 function isPrivateHostname(hostname) {
     const lower = hostname.toLowerCase().replace(/\.+$/, "");
     return lower === "localhost" || lower.endsWith(".localhost");
@@ -162,6 +164,53 @@ function applyPaginationOptions(markdownContent, options) {
     }
     return result;
 }
+export async function checkContentLength(mcpServer, url, timeoutMs, dispatcher, baseRequestOptions = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), Math.min(timeoutMs, HEAD_TIMEOUT_CAP_MS));
+    try {
+        const requestOptions = {
+            ...baseRequestOptions,
+            method: "HEAD",
+            signal: controller.signal,
+            redirect: "manual",
+        };
+        if (dispatcher) {
+            requestOptions.dispatcher = dispatcher;
+        }
+        const response = await undiciFetch(url, requestOptions);
+        const contentLength = response.headers.get("content-length");
+        if (!contentLength) {
+            return null;
+        }
+        const parsed = parseInt(contentLength, 10);
+        return Number.isNaN(parsed) || parsed < 0 ? null : parsed;
+    }
+    catch (error) {
+        logMessage(mcpServer, "warning", `HEAD check failed (proceeding with GET): ${error.message}`);
+        return null;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+function getMaxContentLengthBytes(mcpServer) {
+    const rawValue = process.env.URL_READ_MAX_CONTENT_LENGTH_BYTES;
+    if (rawValue === undefined || rawValue.trim() === "") {
+        return DEFAULT_MAX_CONTENT_LENGTH_BYTES;
+    }
+    const parsed = parseInt(rawValue, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        logMessage(mcpServer, "warning", `Ignoring invalid URL_READ_MAX_CONTENT_LENGTH_BYTES="${rawValue}". Expected a positive integer; using default ${DEFAULT_MAX_CONTENT_LENGTH_BYTES}.`);
+        return DEFAULT_MAX_CONTENT_LENGTH_BYTES;
+    }
+    return parsed;
+}
+function createContentTooLargeMessage(contentLength, maxBytes) {
+    const sizeMB = (contentLength / (1024 * 1024)).toFixed(1);
+    const limitMB = (maxBytes / (1024 * 1024)).toFixed(1);
+    return (`Content too large: server reports Content-Length of ${sizeMB} MB (limit: ${limitMB} MB). ` +
+        `Try using readHeadings or section to fetch only the relevant parts.`);
+}
 export async function fetchAndConvertToMarkdown(mcpServer, url, timeoutMs = 10000, paginationOptions = {}) {
     const startTime = Date.now();
     logMessage(mcpServer, "info", `Fetching URL: ${url}`);
@@ -184,6 +233,7 @@ export async function fetchAndConvertToMarkdown(mcpServer, url, timeoutMs = 1000
         throw createURLFormatError(url);
     }
     assertUrlAllowed(parsedUrl);
+    const maxContentLengthBytes = getMaxContentLengthBytes(mcpServer);
     // Create an AbortController instance
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
@@ -216,6 +266,10 @@ export async function fetchAndConvertToMarkdown(mcpServer, url, timeoutMs = 1000
                 if (dispatcher) {
                     currentRequestOptions.dispatcher = dispatcher;
                 }
+                const contentLength = await checkContentLength(mcpServer, currentUrl.toString(), timeoutMs, dispatcher, currentRequestOptions);
+                if (contentLength !== null && contentLength > maxContentLengthBytes) {
+                    return createContentTooLargeMessage(contentLength, maxContentLengthBytes);
+                }
                 // Fetch the URL with the abort signal.
                 // Use undici's own fetch so it shares the same internal version as the
                 // Agent/ProxyAgent dispatcher — avoids the Node.js bundled-undici vs

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const packageVersion = "1.3.3";
+export declare const packageVersion = "1.4.0";

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "1.3.3";
+export const packageVersion = "1.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mcp-searxng",
-    "version": "1.3.3",
+    "version": "1.4.0",
     "mcpName": "io.github.ihor-sokoliuk/mcp-searxng",
     "description": "MCP server for SearXNG integration",
     "license": "MIT",
@@ -66,6 +66,7 @@
         "cross-env": "^10.1.0",
         "eslint": "10.4.1",
         "eslint-plugin-security": "^4.0.0",
+        "fast-check": "^4.8.0",
         "shx": "^0.4.0",
         "supertest": "^7.2.2",
         "tsx": "4.22.4",