mcp-searxng 0.10.5 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # SearXNG MCP Server
 
-An [MCP server](https://modelcontextprotocol.io/introduction) implementation that integrates the [SearXNG](https://docs.searxng.org) API, providing web search capabilities.
+An [MCP server](https://modelcontextprotocol.io/introduction) that integrates the [SearXNG](https://docs.searxng.org) API, giving AI assistants web search capabilities.
 
 [![https://nodei.co/npm/mcp-searxng.png?downloads=true&downloadRank=true&stars=true](https://nodei.co/npm/mcp-searxng.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/mcp-searxng)
 
@@ -8,21 +8,25 @@ An [MCP server](https://modelcontextprotocol.io/introduction) implementation tha
 
 <a href="https://glama.ai/mcp/servers/0j7jjyt7m9"><img width="380" height="200" src="https://glama.ai/mcp/servers/0j7jjyt7m9/badge" alt="SearXNG Server MCP server" /></a>
 
-## How It Works
-
-`mcp-searxng` is an **MCP (Model Context Protocol) server** — it is a separate process that AI assistants (such as Claude) connect to in order to perform web searches. It communicates with a SearXNG instance over SearXNG's HTTP JSON API.
+## Quick Start
 
-> **Not a SearXNG plugin:** This project cannot be installed as a native SearXNG plugin (i.e., a Python module loaded inside the SearXNG process). It is a standalone MCP server that runs alongside your SearXNG instance and queries it via its API. You point it at any existing SearXNG instance by setting the `SEARXNG_URL` environment variable.
+Add to your MCP client configuration (e.g. `claude_desktop_config.json`):
 
+```json
+{
+  "mcpServers": {
+    "searxng": {
+      "command": "npx",
+      "args": ["-y", "mcp-searxng"],
+      "env": {
+        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
+      }
+    }
+  }
+}
 ```
-AI Assistant (e.g. Claude)
-        │  MCP protocol
-        ▼
-  mcp-searxng  (this project — Node.js process)
-        │  HTTP JSON API  (SEARXNG_URL)
-        ▼
-  SearXNG instance
-```
+
+Replace `YOUR_SEARXNG_INSTANCE_URL` with the URL of your SearXNG instance (e.g. `https://search.example.com`).
 
 ## Features
 
@@ -34,6 +38,22 @@ AI Assistant (e.g. Claude)
 - **Language Selection**: Filter results by preferred language.
 - **Safe Search**: Control content filtering level for search results.
 
+## 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.
+
+> **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`.
+
+```
+AI Assistant (e.g. Claude)
+        │  MCP protocol
+        ▼
+  mcp-searxng  (this project — Node.js process)
+        │  HTTP JSON API  (SEARXNG_URL)
+        ▼
+  SearXNG instance
+```
+
 ## Tools
 
 - **searxng_web_search**
@@ -55,88 +75,10 @@ AI Assistant (e.g. Claude)
     - `paragraphRange` (string, optional): Return specific paragraph ranges (e.g., '1-5', '3', '10-')
     - `readHeadings` (boolean, optional): Return only a list of headings instead of full content
 
-## Configuration
-
-### Environment Variables
-
-#### Required
-- **`SEARXNG_URL`**: SearXNG instance URL (default: `http://localhost:8080`)
-  - Format: `<protocol>://<hostname>[:<port>]`
-  - Example: `https://search.example.com`
-
-#### Optional
-- **`AUTH_USERNAME`** / **`AUTH_PASSWORD`**: HTTP Basic Auth credentials for `searxng_web_search` (password-protected SearXNG instances)
-- **`USER_AGENT`**: Global default User-Agent header used by both `searxng_web_search` and `web_url_read` (e.g., `MyBot/1.0`)
-- **`URL_READER_USER_AGENT`**: Custom User-Agent specifically for the `web_url_read` tool (overrides `USER_AGENT` for URL reading requests)
-- **`HTTP_PROXY`** / **`HTTPS_PROXY`**: Global proxy URLs for routing traffic (fallback for both interfaces)
-  - Format: `http://[username:password@]proxy.host:port`
-- **`NO_PROXY`**: Comma-separated bypass list (e.g., `localhost,.internal,example.com`)
-
-##### Interface-Specific Proxies (Optional)
-- **`SEARCH_HTTP_PROXY`** / **`SEARCH_HTTPS_PROXY`**: Proxy for `searxng_web_search` tool only
-- **`URL_READER_HTTP_PROXY`** / **`URL_READER_HTTPS_PROXY`**: Proxy for `web_url_read` tool only
-  - These take priority over `HTTP_PROXY`/`HTTPS_PROXY` for their respective interfaces
-
-#### Advanced Configuration
-
-```bash
-# Separate proxies for search and URL reading
-SEARCH_HTTP_PROXY=http://search-proxy:8080
-URL_READER_HTTP_PROXY=http://reader-proxy:8080
-
-# Custom user_agent for URL reader
-URL_READER_USER_AGENT="Mozilla/5.0 (compatible; Bot/1.0)"
-```
-
-## Installation & Configuration
-
-### [NPX](https://www.npmjs.com/package/mcp-searxng)
-
-```json
-{
-  "mcpServers": {
-    "searxng": {
-      "command": "npx",
-      "args": ["-y", "mcp-searxng"],
-      "env": {
-        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
-      }
-    }
-  }
-}
-```
+## Installation
 
 <details>
-<summary>Full Configuration Example (All Options)</summary>
-
-```json
-{
-  "mcpServers": {
-    "searxng": {
-      "command": "npx",
-      "args": ["-y", "mcp-searxng"],
-      "env": {
-        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
-        "AUTH_USERNAME": "your_username",
-        "AUTH_PASSWORD": "your_password",
-        "USER_AGENT": "MyBot/1.0",
-        "URL_READER_USER_AGENT": "Mozilla/5.0 (compatible; MyBot/1.0)",
-        "SEARCH_HTTP_PROXY": "http://search-proxy.company.com:8080",
-        "URL_READER_HTTP_PROXY": "http://reader-proxy.company.com:8080",
-        "HTTP_PROXY": "http://global-proxy.company.com:8080",
-        "HTTPS_PROXY": "http://global-proxy.company.com:8080",
-        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
-      }
-    }
-  }
-}
-```
-
-**Note:** Mix and match environment variables as needed. All optional variables can be used independently or together.
-
-</details>
-
-### [NPM](https://www.npmjs.com/package/mcp-searxng)
+<summary>NPM (global install)</summary>
 
 ```bash
 npm install -g mcp-searxng
@@ -155,35 +97,12 @@ npm install -g mcp-searxng
 }
 ```
 
-<details>
-<summary>Full Configuration Example (All Options)</summary>
-
-```json
-{
-  "mcpServers": {
-    "searxng": {
-      "command": "mcp-searxng",
-      "env": {
-        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
-        "AUTH_USERNAME": "your_username",
-        "AUTH_PASSWORD": "your_password",
-        "USER_AGENT": "MyBot/1.0",
-        "URL_READER_USER_AGENT": "Mozilla/5.0 (compatible; MyBot/1.0)",
-        "SEARCH_HTTP_PROXY": "http://search-proxy.company.com:8080",
-        "URL_READER_HTTP_PROXY": "http://reader-proxy.company.com:8080",
-        "HTTP_PROXY": "http://global-proxy.company.com:8080",
-        "HTTPS_PROXY": "http://global-proxy.company.com:8080",
-        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
-      }
-    }
-  }
-}
-```
 </details>
 
-### Docker
+<details>
+<summary>Docker</summary>
 
-#### Using [Pre-built Image from Docker Hub](https://hub.docker.com/r/isokoliuk/mcp-searxng)
+**Pre-built image:**
 
 ```bash
 docker pull isokoliuk/mcp-searxng:latest
@@ -207,62 +126,22 @@ docker pull isokoliuk/mcp-searxng:latest
 }
 ```
 
-<details>
-<summary>Full Configuration Example (All Options)</summary>
+To pass additional env vars, add `-e VAR_NAME` to `args` and the variable to `env`.
 
-```json
-{
-  "mcpServers": {
-    "searxng": {
-      "command": "docker",
-      "args": [
-        "run", "-i", "--rm",
-        "-e", "SEARXNG_URL",
-        "-e", "AUTH_USERNAME",
-        "-e", "AUTH_PASSWORD",
-        "-e", "USER_AGENT",
-        "-e", "URL_READER_USER_AGENT",
-        "-e", "SEARCH_HTTP_PROXY",
-        "-e", "SEARCH_HTTPS_PROXY",
-        "-e", "URL_READER_HTTP_PROXY",
-        "-e", "URL_READER_HTTPS_PROXY",
-        "-e", "HTTP_PROXY",
-        "-e", "HTTPS_PROXY",
-        "-e", "NO_PROXY",
-        "isokoliuk/mcp-searxng:latest"
-      ],
-      "env": {
-        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
-        "AUTH_USERNAME": "your_username",
-        "AUTH_PASSWORD": "your_password",
-        "USER_AGENT": "MyBot/1.0",
-        "URL_READER_USER_AGENT": "Mozilla/5.0 (compatible; MyBot/1.0)",
-        "SEARCH_HTTP_PROXY": "http://search-proxy.company.com:8080",
-        "URL_READER_HTTP_PROXY": "http://reader-proxy.company.com:8080",
-        "HTTP_PROXY": "http://global-proxy.company.com:8080",
-        "HTTPS_PROXY": "http://global-proxy.company.com:8080",
-        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
-      }
-    }
-  }
-}
-```
-
-**Note:** Add only the `-e` flags and env variables you need.
-
-</details>
-
-#### Build Locally
+**Build locally:**
 
 ```bash
 docker build -t mcp-searxng:latest -f Dockerfile .
 ```
 
-Use the same configuration as above, replacing `isokoliuk/mcp-searxng:latest` with `mcp-searxng:latest`.
+Use the same config above, replacing `isokoliuk/mcp-searxng:latest` with `mcp-searxng:latest`.
 
-#### Docker Compose
+</details>
 
-Create a `docker-compose.yml` file:
+<details>
+<summary>Docker Compose</summary>
+
+`docker-compose.yml`:
 
 ```yaml
 services:
@@ -271,19 +150,10 @@ services:
     stdin_open: true
     environment:
       - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL
-      # Add any optional variables as needed:
-      # - AUTH_USERNAME=your_username
-      # - AUTH_PASSWORD=your_password
-      # - USER_AGENT=MyBot/1.0
-      # - URL_READER_USER_AGENT=Mozilla/5.0 (compatible; MyBot/1.0)
-      # - SEARCH_HTTP_PROXY=http://search-proxy.company.com:8080
-      # - URL_READER_HTTP_PROXY=http://reader-proxy.company.com:8080
-      # - HTTP_PROXY=http://global-proxy.company.com:8080
-      # - HTTPS_PROXY=http://proxy.company.com:8080
-      # - NO_PROXY=localhost,127.0.0.1,.local,.internal
+      # Add optional variables as needed — see CONFIGURATION.md
 ```
 
-Then configure your MCP client:
+MCP client config:
 
 ```json
 {
@@ -296,9 +166,12 @@ Then configure your MCP client:
 }
 ```
 
-### HTTP Transport (Optional)
+</details>
 
-The server supports both STDIO (default) and HTTP transports. Set `MCP_HTTP_PORT` to enable HTTP mode.
+<details>
+<summary>HTTP Transport</summary>
+
+By default the server uses STDIO. Set `MCP_HTTP_PORT` to enable HTTP mode:
 
 ```json
 {
@@ -314,23 +187,28 @@ The server supports both STDIO (default) and HTTP transports. Set `MCP_HTTP_PORT
 }
 ```
 
-**HTTP Endpoints:**
-- **MCP Protocol**: `POST/GET/DELETE /mcp` 
-- **Health Check**: `GET /health`
+**Endpoints:** `POST/GET/DELETE /mcp` (MCP protocol), `GET /health` (health check)
+
+**Test it:**
 
-**Testing:**
 ```bash
 MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng
 curl http://localhost:3000/health
 ```
 
-## Troubleshooting
+</details>
+
+## Configuration
 
-### 403 Forbidden Error from SearXNG
+Set `SEARXNG_URL` to your SearXNG instance URL. All other variables are optional.
 
-If you receive a `403 Forbidden` error when using `mcp-searxng`, it is likely because your SearXNG instance does not have JSON format enabled. This server requests results in JSON format (`format=json`), which must be explicitly allowed in SearXNG's configuration.
+Full environment variable reference: [CONFIGURATION.md](CONFIGURATION.md)
+
+## Troubleshooting
 
-**To fix this**, edit your SearXNG `settings.yml` (commonly located at `/etc/searxng/settings.yml`) and add `json` to the list of allowed formats:
+### 403 Forbidden from SearXNG
+
+Your SearXNG instance likely has JSON format disabled. Edit `settings.yml` (usually `/etc/searxng/settings.yml`):
 
 ```yaml
 search:
@@ -339,88 +217,20 @@ search:
     - json
 ```
 
-After saving the file, restart your SearXNG instance. For example, if running with Docker:
-
-```bash
-docker restart searxng
-```
-
-You can verify JSON format is working by running:
+Restart SearXNG (`docker restart searxng`) then verify:
 
 ```bash
 curl 'http://localhost:8080/search?q=test&format=json'
 ```
 
-You should receive a JSON response. If you still get a 403 error, double-check that:
-- The `settings.yml` file is correctly mounted into your Docker container
-- The YAML indentation is correct
-- The SearXNG instance was fully restarted after the configuration change
-
-For more details, see the [SearXNG settings documentation](https://docs.searxng.org/admin/settings/settings.html) and [this discussion](https://github.com/searxng/searxng/discussions/1789).
-
-## Running evals
-
-```bash
-SEARXNG_URL=YOUR_URL OPENAI_API_KEY=your-key npx mcp-eval evals.ts src/index.ts
-```
+You should receive a JSON response. If not, confirm the file is correctly mounted and YAML indentation is valid.
 
-## For Developers
-
-### Contributing
-
-We welcome contributions! Follow these guidelines:
-
-**Coding Standards:**
-- Use TypeScript with strict type safety
-- Follow existing error handling patterns
-- Write concise, informative error messages
-- Include unit tests for new functionality
-- Maintain 90%+ test coverage
-- Test with MCP inspector before submitting
-- Run evals to verify functionality
-
-**Workflow:**
-
-1. **Fork and clone:**
-   ```bash
-   git clone https://github.com/YOUR_USERNAME/mcp-searxng.git
-   cd mcp-searxng
-   git remote add upstream https://github.com/ihor-sokoliuk/mcp-searxng.git
-   ```
-
-2. **Setup:**
-   ```bash
-   npm install
-   npm run watch  # Development mode with file watching
-   ```
-
-3. **Development:**
-   ```bash
-   git checkout -b feature/your-feature-name
-   # Make changes in src/
-   npm run build
-   npm test
-   npm run test:coverage
-   npm run inspector
-   ```
-
-4. **Submit:**
-   ```bash
-   git commit -m "feat: description"
-   git push origin feature/your-feature-name
-   # Create PR on GitHub
-   ```
-
-### Testing
+See also: [SearXNG settings docs](https://docs.searxng.org/admin/settings/settings.html) · [discussion](https://github.com/searxng/searxng/discussions/1789)
 
-```bash
-npm test                    # Run all tests
-npm run test:coverage      # Generate coverage report
-npm run test:watch         # Watch mode
-```
+## Contributing
 
-**Coverage:** 100% success rate with comprehensive unit tests covering error handling, types, proxy configs, resources, and logging.
+See [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## License
 
-This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
+MIT — see [LICENSE](LICENSE) for details.

package/dist/cache.d.ts

@@ -7,7 +7,7 @@ declare class SimpleCache {
     private cache;
     private readonly ttlMs;
     private cleanupInterval;
-    constructor(ttlMs?: number);
+    constructor(ttlMs?: number, cleanupIntervalMs?: number);
     private startCleanup;
     private cleanupExpired;
     get(url: string): CacheEntry | null;

package/dist/cache.js

@@ -2,15 +2,15 @@ class SimpleCache {
     cache = new Map();
     ttlMs;
     cleanupInterval = null;
-    constructor(ttlMs = 60000) {
+    constructor(ttlMs = 60000, cleanupIntervalMs = 30000) {
         this.ttlMs = ttlMs;
-        this.startCleanup();
+        this.startCleanup(cleanupIntervalMs);
     }
-    startCleanup() {
-        // Clean up expired entries every 30 seconds
+    startCleanup(cleanupIntervalMs) {
+        // Clean up expired entries every cleanupIntervalMs milliseconds (default 30s)
         this.cleanupInterval = setInterval(() => {
             this.cleanupExpired();
-        }, 30000);
+        }, cleanupIntervalMs);
     }
     cleanupExpired() {
         const now = Date.now();

package/dist/error-handler.d.ts

@@ -20,6 +20,7 @@ export declare function createJSONError(responseText: string, context: ErrorCont
 export declare function createDataError(data: any, context: ErrorContext): 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 createTimeoutError(timeout: number, url: string): MCPSearXNGError;

package/dist/error-handler.js

@@ -11,6 +11,33 @@ export class MCPSearXNGError extends Error {
 export function createConfigurationError(message) {
     return new MCPSearXNGError(`🔧 Configuration Error: ${message}`);
 }
+const TLS_ERROR_CODES = new Set([
+    'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'CERT_UNTRUSTED', 'CERT_HAS_EXPIRED', 'DEPTH_ZERO_SELF_SIGNED_CERT',
+    'SELF_SIGNED_CERT_IN_CHAIN', 'UNABLE_TO_GET_ISSUER_CERT',
+    'CERT_CHAIN_TOO_LONG', 'INVALID_CA',
+]);
+function isTLSError(error) {
+    if (TLS_ERROR_CODES.has(error?.code))
+        return true;
+    if (TLS_ERROR_CODES.has(error?.cause?.code))
+        return true;
+    if (error?.message?.includes('certificate'))
+        return true;
+    if (error?.cause?.message?.includes('certificate'))
+        return true;
+    return false;
+}
+function getTLSRemediationMessage() {
+    const { platform } = process;
+    if (platform === 'win32') {
+        return 'Set NODE_EXTRA_CA_CERTS=C:\\path\\to\\ca-bundle.pem before starting the server.';
+    }
+    if (platform === 'darwin') {
+        return 'Run: sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/ca.crt';
+    }
+    return 'Run: sudo cp /path/to/ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates';
+}
 export function createNetworkError(error, context) {
     const target = context.searxngUrl ? 'SearXNG server' : 'website';
     if (error.code === 'ECONNREFUSED') {
@@ -23,8 +50,10 @@ export function createNetworkError(error, context) {
     if (error.code === 'ETIMEDOUT') {
         return new MCPSearXNGError(`🌐 Timeout Error: ${target} is too slow to respond`);
     }
-    if (error.message?.includes('certificate')) {
-        return new MCPSearXNGError(`🌐 SSL Error: Certificate problem with ${target}`);
+    if (isTLSError(error)) {
+        const causeCode = error?.cause?.code || error?.code || 'CERT_ERROR';
+        return new MCPSearXNGError(`🔒 SSL/TLS Error: Certificate verification failed for ${target} (${causeCode}). ` +
+            getTLSRemediationMessage());
     }
     // For generic fetch failures, provide root cause guidance
     const errorMsg = error.message || error.code || 'Connection failed';
@@ -67,6 +96,10 @@ export function createNoResultsMessage(query) {
 export function createURLFormatError(url) {
     return new MCPSearXNGError(`🔧 URL Format Error: Invalid URL "${url}"`);
 }
+export function createURLSecurityPolicyError(url) {
+    return new MCPSearXNGError(`🔒 URL blocked by security policy: ${url}. ` +
+        "Enable MCP_HTTP_ALLOW_PRIVATE_URLS=true only if internal URL reads are intentional.");
+}
 export function createContentError(message, url) {
     return new MCPSearXNGError(`📄 Content Error: ${message} (${url})`);
 }

package/dist/http-security.d.ts

@@ -0,0 +1,15 @@
+export interface HttpSecurityConfig {
+    harden: boolean;
+    requireAuth: boolean;
+    authToken?: string;
+    restrictOrigins: boolean;
+    allowedOrigins: string[];
+    enableDnsRebindingProtection: boolean;
+    allowedHosts: string[];
+    exposeFullConfig: boolean;
+    allowPrivateUrls: boolean;
+}
+export declare function getHttpSecurityConfig(): HttpSecurityConfig;
+export declare function validateHttpSecurityConfig(config: HttpSecurityConfig): void;
+export declare function isRequestAuthorized(headerValue: string | undefined, config: HttpSecurityConfig): boolean;
+export declare function isOriginAllowed(origin: string | undefined, config: HttpSecurityConfig): boolean;

package/dist/http-security.js

@@ -0,0 +1,52 @@
+function isEnabled(value) {
+    return value === "true";
+}
+function parseCsv(value) {
+    return (value || "")
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+export function getHttpSecurityConfig() {
+    const harden = isEnabled(process.env.MCP_HTTP_HARDEN);
+    const authToken = process.env.MCP_HTTP_AUTH_TOKEN;
+    const allowedOrigins = parseCsv(process.env.MCP_HTTP_ALLOWED_ORIGINS);
+    const allowedHosts = parseCsv(process.env.MCP_HTTP_ALLOWED_HOSTS);
+    return {
+        harden,
+        requireAuth: harden,
+        authToken,
+        restrictOrigins: harden,
+        allowedOrigins,
+        enableDnsRebindingProtection: harden,
+        allowedHosts: allowedHosts.length > 0 ? allowedHosts : ["127.0.0.1", "localhost"],
+        exposeFullConfig: isEnabled(process.env.MCP_HTTP_EXPOSE_FULL_CONFIG),
+        allowPrivateUrls: isEnabled(process.env.MCP_HTTP_ALLOW_PRIVATE_URLS),
+    };
+}
+export function validateHttpSecurityConfig(config) {
+    if (!config.harden) {
+        return;
+    }
+    if (!config.authToken) {
+        throw new Error("MCP_HTTP_HARDEN=true requires MCP_HTTP_AUTH_TOKEN to be set.");
+    }
+    if (config.allowedOrigins.length === 0) {
+        throw new Error("MCP_HTTP_HARDEN=true requires MCP_HTTP_ALLOWED_ORIGINS to be set.");
+    }
+}
+export function isRequestAuthorized(headerValue, config) {
+    if (!config.requireAuth) {
+        return true;
+    }
+    return headerValue === `Bearer ${config.authToken}` || headerValue === config.authToken;
+}
+export function isOriginAllowed(origin, config) {
+    if (!config.restrictOrigins) {
+        return true;
+    }
+    if (!origin) {
+        return true;
+    }
+    return config.allowedOrigins.includes(origin);
+}

package/dist/http-server.js

@@ -5,19 +5,42 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { logMessage } from "./logging.js";
 import { packageVersion } from "./index.js";
+import { getHttpSecurityConfig, isOriginAllowed, isRequestAuthorized, validateHttpSecurityConfig, } from "./http-security.js";
 export async function createHttpServer(mcpServer) {
     const app = express();
+    const security = getHttpSecurityConfig();
+    validateHttpSecurityConfig(security);
     app.use(express.json());
     // Add CORS support for web clients
     app.use(cors({
-        origin: '*', // Configure appropriately for production
-        exposedHeaders: ['Mcp-Session-Id'],
-        allowedHeaders: ['Content-Type', 'mcp-session-id'],
+        origin: (origin, callback) => {
+            if (isOriginAllowed(origin || undefined, security)) {
+                callback(null, true);
+                return;
+            }
+            callback(null, false);
+        },
+        exposedHeaders: ["Mcp-Session-Id"],
+        allowedHeaders: ["Content-Type", "mcp-session-id", "authorization"],
     }));
+    function rejectUnauthorized(res) {
+        res.status(401).json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32001,
+                message: "Unauthorized: missing or invalid HTTP auth token",
+            },
+            id: null,
+        });
+    }
     // Map to store transports by session ID  
     const transports = {};
     // Handle POST requests for client-to-server communication
     app.post('/mcp', async (req, res) => {
+        if (!isRequestAuthorized(req.headers.authorization, security)) {
+            rejectUnauthorized(res);
+            return;
+        }
         const sessionId = req.headers['mcp-session-id'];
         let transport;
         if (sessionId && transports[sessionId]) {
@@ -34,10 +57,9 @@ export async function createHttpServer(mcpServer) {
                     transports[sessionId] = transport;
                     logMessage(mcpServer, "debug", `Session initialized: ${sessionId}`);
                 },
-                // DNS rebinding protection disabled by default for backwards compatibility
-                // For production, consider enabling:
-                // enableDnsRebindingProtection: true,
-                // allowedHosts: ['127.0.0.1', 'localhost'],
+                enableDnsRebindingProtection: security.enableDnsRebindingProtection,
+                allowedHosts: security.allowedHosts,
+                allowedOrigins: security.allowedOrigins,
             });
             // Clean up transport when closed
             transport.onclose = () => {
@@ -89,6 +111,10 @@ export async function createHttpServer(mcpServer) {
     });
     // Handle GET requests for server-to-client notifications via SSE
     app.get('/mcp', async (req, res) => {
+        if (!isRequestAuthorized(req.headers.authorization, security)) {
+            rejectUnauthorized(res);
+            return;
+        }
         const sessionId = req.headers['mcp-session-id'];
         if (!sessionId || !transports[sessionId]) {
             console.warn(`⚠️  GET request rejected - missing or invalid session ID:`, {
@@ -114,6 +140,10 @@ export async function createHttpServer(mcpServer) {
     });
     // Handle DELETE requests for session termination
     app.delete('/mcp', async (req, res) => {
+        if (!isRequestAuthorized(req.headers.authorization, security)) {
+            rejectUnauthorized(res);
+            return;
+        }
         const sessionId = req.headers['mcp-session-id'];
         if (!sessionId || !transports[sessionId]) {
             console.warn(`⚠️  DELETE request rejected - missing or invalid session ID:`, {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-declare const packageVersion = "0.10.5";
+declare const packageVersion = "1.0.2";
 export { packageVersion };
 export declare function isWebUrlReadArgs(args: unknown): args is {
     url: string;

package/dist/index.js

@@ -9,9 +9,8 @@ import { performWebSearch } from "./search.js";
 import { fetchAndConvertToMarkdown } from "./url-reader.js";
 import { createConfigResource, createHelpResource } from "./resources.js";
 import { createHttpServer } from "./http-server.js";
-import { validateEnvironment as validateEnv } from "./error-handler.js";
 // Use a static version string that will be updated by the version script
-const packageVersion = "0.10.5";
+const packageVersion = "1.0.2";
 // Export the version for use in other modules
 export { packageVersion };
 // Global state for logging level
@@ -150,6 +149,7 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
     };
 });
 // List resource templates handler
+// Returns empty list — required by MCP spec even when no templates exist
 server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
     logMessage(mcpServer, "debug", "Handling list_resource_templates request");
     return { resourceTemplates: [] };
@@ -185,12 +185,6 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 });
 // Main function
 async function main() {
-    // Environment validation
-    const validationError = validateEnv();
-    if (validationError) {
-        console.error(`❌ ${validationError}`);
-        process.exit(1);
-    }
     // Check for HTTP transport mode
     const httpPort = process.env.MCP_HTTP_PORT;
     if (httpPort) {
@@ -222,8 +216,12 @@ async function main() {
         // Show helpful message when running in terminal
         if (process.stdin.isTTY) {
             console.error(`🔍 MCP SearXNG Server v${packageVersion} - Ready`);
-            console.error("✅ Configuration valid");
-            console.error(`🌐 SearXNG URL: ${process.env.SEARXNG_URL}`);
+            if (process.env.SEARXNG_URL) {
+                console.error(`🌐 SearXNG URL: ${process.env.SEARXNG_URL}`);
+            }
+            else {
+                console.error("⚠️  SEARXNG_URL not set — configure it before using search tools");
+            }
             console.error("📡 Waiting for MCP client connection via STDIO...\n");
         }
         const transport = new StdioServerTransport();

package/dist/logging.js

@@ -1,29 +1,25 @@
 // Logging state
 let currentLogLevel = "info";
+// Shared handler for sendLoggingMessage errors
+function handleSendError(error) {
+    if (error instanceof Error && error.message !== "Not connected") {
+        console.error("Logging error:", error);
+    }
+}
 // Logging helper function
 export function logMessage(mcpServer, level, message, data) {
     if (shouldLog(level)) {
         try {
-            // Merge message and data together for the notification body
             const notificationData = data !== undefined
                 ? (typeof data === 'object' && data !== null ? { message, ...data } : { message, data })
                 : { message };
             mcpServer.sendLoggingMessage({
                 level,
                 data: notificationData
-            }).catch((error) => {
-                // Silently ignore "Not connected" errors during server startup
-                // This can happen when logging occurs before the transport is fully connected
-                if (error instanceof Error && error.message !== "Not connected") {
-                    console.error("Logging error:", error);
-                }
-            });
+            }).catch(handleSendError);
         }
         catch (error) {
-            // Handle synchronous errors as well
-            if (error instanceof Error && error.message !== "Not connected") {
-                console.error("Logging error:", error);
-            }
+            handleSendError(error);
         }
     }
 }

package/dist/proxy.d.ts

@@ -1,4 +1,4 @@
-import { ProxyAgent } from "undici";
+import { Agent, ProxyAgent } from "undici";
 /**
  * Proxy configuration type for separating search and URL reader proxies.
  */
@@ -37,3 +37,4 @@ export type ProxyType = typeof ProxyType[keyof typeof ProxyType];
  * @returns ProxyAgent dispatcher for fetch, or undefined if no proxy configured or bypassed
  */
 export declare function createProxyAgent(targetUrl?: string, type?: ProxyType): ProxyAgent | undefined;
+export declare function createDefaultAgent(): Agent | undefined;

package/dist/proxy.js

@@ -1,4 +1,5 @@
-import { ProxyAgent } from "undici";
+import { Agent, ProxyAgent } from "undici";
+import { getConnectOptions } from "./tls-config.js";
 /**
  * Checks if a target URL should bypass the proxy based on NO_PROXY environment variable.
  *
@@ -187,5 +188,28 @@ export function createProxyAgent(targetUrl, type) {
         '';
     const normalizedProxyUrl = `${parsedProxyUrl.protocol}//${auth}${parsedProxyUrl.host}`;
     // Create and return Undici ProxyAgent compatible with fetch's dispatcher option
-    return new ProxyAgent(normalizedProxyUrl);
+    return new ProxyAgent({ uri: normalizedProxyUrl, connect: getConnectOptions() });
+}
+/**
+ * Returns a singleton undici Agent with system CA certificates in the connect
+ * options. Used as a dispatcher when no proxy is configured, to ensure
+ * undici's fetch uses system CAs instead of only Node's compiled-in bundle.
+ *
+ * The agent (and the CA bundle disk read) is created once and reused across
+ * requests to avoid repeated synchronous I/O and connection pool proliferation.
+ *
+ * Returns undefined if no system CA bundle is found — callers should treat
+ * undefined as "use Node's default behavior".
+ */
+let _defaultAgentInitialized = false;
+let _defaultAgent;
+export function createDefaultAgent() {
+    if (!_defaultAgentInitialized) {
+        _defaultAgentInitialized = true;
+        const connectOpts = getConnectOptions();
+        if (Object.keys(connectOpts).length > 0) {
+            _defaultAgent = new Agent({ connect: connectOpts });
+        }
+    }
+    return _defaultAgent;
 }

package/dist/resources.js

@@ -1,6 +1,9 @@
 import { getCurrentLogLevel } from "./logging.js";
 import { packageVersion } from "./index.js";
+import { getHttpSecurityConfig } from "./http-security.js";
 export function createConfigResource() {
+    const security = getHttpSecurityConfig();
+    const showFullConfig = !security.harden || security.exposeFullConfig;
     const config = {
         serverInfo: {
             name: "ihor-sokoliuk/mcp-searxng",
@@ -8,7 +11,9 @@ export function createConfigResource() {
             description: "MCP server for SearXNG integration"
         },
         environment: {
-            searxngUrl: process.env.SEARXNG_URL || "(not configured)",
+            ...(showFullConfig
+                ? { searxngUrl: process.env.SEARXNG_URL || "(not configured)" }
+                : { searxngUrlConfigured: !!process.env.SEARXNG_URL }),
             hasAuth: !!(process.env.AUTH_USERNAME && process.env.AUTH_PASSWORD),
             hasProxy: !!(process.env.HTTP_PROXY || process.env.HTTPS_PROXY || process.env.http_proxy || process.env.https_proxy),
             hasNoProxy: !!(process.env.NO_PROXY || process.env.no_proxy),
@@ -67,6 +72,13 @@ Standard input/output transport for desktop clients like Claude Desktop.
 ### HTTP (Optional)
 RESTful HTTP transport for web applications. Set \`MCP_HTTP_PORT\` to enable.
 
+### Hardened HTTP Mode (Optional)
+Default behavior remains compatible for existing deployments.
+For network-exposed HTTP transport, enable:
+- \`MCP_HTTP_HARDEN\`
+- \`MCP_HTTP_AUTH_TOKEN\`
+- \`MCP_HTTP_ALLOWED_ORIGINS\`
+
 ## Usage Examples
 
 ### Search for recent news

package/dist/search.js

@@ -1,6 +1,6 @@
-import { createProxyAgent, ProxyType } from "./proxy.js";
+import { createProxyAgent, createDefaultAgent, ProxyType } from "./proxy.js";
 import { logMessage } from "./logging.js";
-import { createConfigurationError, createNetworkError, createServerError, createJSONError, createDataError, createNoResultsMessage } from "./error-handler.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) {
     const startTime = Date.now();
     // Build detailed log message with all parameters
@@ -11,19 +11,13 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
         safesearch ? `safesearch: ${safesearch}` : null
     ].filter(Boolean).join(", ");
     logMessage(mcpServer, "info", `Starting web search: "${query}" (${searchParams})`);
-    const searxngUrl = process.env.SEARXNG_URL;
-    if (!searxngUrl) {
-        logMessage(mcpServer, "error", "SEARXNG_URL not configured");
-        throw createConfigurationError("SEARXNG_URL not set. Set it to your SearXNG instance (e.g., http://localhost:8080 or https://search.example.com)");
-    }
-    // Validate that searxngUrl is a valid URL
-    let parsedUrl;
-    try {
-        parsedUrl = new URL(searxngUrl.endsWith('/') ? searxngUrl : searxngUrl + '/');
-    }
-    catch (error) {
-        throw createConfigurationError(`Invalid SEARXNG_URL format: ${searxngUrl}. Use format: http://localhost:8080`);
+    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);
     url.searchParams.set("q", query);
     url.searchParams.set("format", "json");
@@ -42,11 +36,11 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
     const requestOptions = {
         method: "GET"
     };
-    // Add proxy dispatcher if proxy is configured
-    // Node.js fetch uses 'dispatcher' option for proxy, not 'agent'
+    // Add proxy or default dispatcher (includes system CA certs for TLS)
     const proxyAgent = createProxyAgent(url.toString(), ProxyType.SEARCH);
-    if (proxyAgent) {
-        requestOptions.dispatcher = proxyAgent;
+    const dispatcher = proxyAgent ?? createDefaultAgent();
+    if (dispatcher) {
+        requestOptions.dispatcher = dispatcher;
     }
     // Add basic authentication if credentials are provided
     const username = process.env.AUTH_USERNAME;
@@ -77,7 +71,7 @@ export async function performWebSearch(mcpServer, query, pageno = 1, time_range,
         const context = {
             url: url.toString(),
             searxngUrl,
-            proxyAgent: !!proxyAgent,
+            proxyAgent: !!dispatcher,
             username
         };
         throw createNetworkError(error, context);

package/dist/tls-config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reads system CA certificates from well-known bundle paths.
+ * Returns null on Windows (no universal file path) or if no bundle is found.
+ *
+ * On Windows, users should set NODE_EXTRA_CA_CERTS pointing to a PEM file.
+ */
+export declare function getSystemCACerts(): string | null;
+/**
+ * Returns undici `connect` options with system CA certs, or an empty object
+ * if no system CA bundle is found (undici uses Node's compiled-in Mozilla
+ * bundle in that case).
+ *
+ * Usage:
+ *   new Agent({ connect: getConnectOptions() })
+ *   new ProxyAgent({ uri: proxyUrl, connect: getConnectOptions() })
+ */
+export declare function getConnectOptions(): {
+    ca: string;
+} | Record<string, never>;

package/dist/tls-config.js

@@ -0,0 +1,49 @@
+import { existsSync, readFileSync } from "node:fs";
+import { platform } from "node:process";
+/**
+ * Ordered list of well-known system CA bundle paths.
+ * Checked in order; first path that exists and is readable wins.
+ */
+const CA_BUNDLE_PATHS = [
+    "/etc/ssl/certs/ca-certificates.crt", // Debian/Ubuntu/WSL2
+    "/etc/pki/tls/certs/ca-bundle.crt", // RHEL/CentOS/Fedora
+    "/etc/ssl/ca-bundle.pem", // OpenSUSE
+    "/etc/ssl/cert.pem", // Alpine, macOS
+];
+/**
+ * Reads system CA certificates from well-known bundle paths.
+ * Returns null on Windows (no universal file path) or if no bundle is found.
+ *
+ * On Windows, users should set NODE_EXTRA_CA_CERTS pointing to a PEM file.
+ */
+export function getSystemCACerts() {
+    // Windows has no universal CA bundle path; skip auto-detection
+    if (platform === "win32") {
+        return null;
+    }
+    for (const caPath of CA_BUNDLE_PATHS) {
+        if (existsSync(caPath)) {
+            try {
+                return readFileSync(caPath, "utf8");
+            }
+            catch {
+                // File exists but is unreadable (permissions); try next
+                continue;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Returns undici `connect` options with system CA certs, or an empty object
+ * if no system CA bundle is found (undici uses Node's compiled-in Mozilla
+ * bundle in that case).
+ *
+ * Usage:
+ *   new Agent({ connect: getConnectOptions() })
+ *   new ProxyAgent({ uri: proxyUrl, connect: getConnectOptions() })
+ */
+export function getConnectOptions() {
+    const ca = getSystemCACerts();
+    return ca !== null ? { ca } : {};
+}

package/dist/url-reader.js

@@ -1,8 +1,54 @@
+import { isIP } from "node:net";
 import { NodeHtmlMarkdown } from "node-html-markdown";
-import { createProxyAgent, ProxyType } from "./proxy.js";
+import { createProxyAgent, createDefaultAgent, ProxyType } from "./proxy.js";
 import { logMessage } from "./logging.js";
 import { urlCache } from "./cache.js";
-import { createURLFormatError, createNetworkError, createServerError, createContentError, createConversionError, createTimeoutError, createEmptyContentWarning, createUnexpectedError } from "./error-handler.js";
+import { getHttpSecurityConfig } from "./http-security.js";
+import { createURLFormatError, createURLSecurityPolicyError, createNetworkError, createServerError, createContentError, createConversionError, createTimeoutError, createEmptyContentWarning, createUnexpectedError } from "./error-handler.js";
+function isPrivateHostname(hostname) {
+    const lower = hostname.toLowerCase().replace(/\.+$/, "");
+    return lower === "localhost" || lower.endsWith(".localhost");
+}
+function isPrivateIpv4(hostname) {
+    if (isIP(hostname) !== 4) {
+        return false;
+    }
+    return (hostname.startsWith("10.") ||
+        hostname.startsWith("127.") ||
+        hostname.startsWith("192.168.") ||
+        /^172\.(1[6-9]|2\d|3[0-1])\./.test(hostname) ||
+        hostname.startsWith("169.254."));
+}
+function isPrivateIPv6(hostname) {
+    // url.hostname wraps IPv6 in brackets (e.g. "[::1]") — strip them first
+    const addr = (hostname.startsWith("[") && hostname.endsWith("]")
+        ? hostname.slice(1, -1)
+        : hostname).toLowerCase();
+    if (isIP(addr) !== 6)
+        return false;
+    if (addr === "::1")
+        return true; // loopback
+    if (addr === "::")
+        return true; // unspecified
+    if (/^f[cd]/i.test(addr))
+        return true; // ULA fc00::/7
+    if (/^fe[89ab][0-9a-f]:/i.test(addr))
+        return true; // link-local fe80::/10
+    // IPv4-mapped ::ffff:<ipv4> — delegate to the IPv4 check
+    const mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (mapped)
+        return isPrivateIpv4(mapped[1]);
+    return false;
+}
+function assertUrlAllowed(url) {
+    const security = getHttpSecurityConfig();
+    if (!security.harden || security.allowPrivateUrls) {
+        return;
+    }
+    if (isPrivateHostname(url.hostname) || isPrivateIpv4(url.hostname) || isPrivateIPv6(url.hostname)) {
+        throw createURLSecurityPolicyError(url.toString());
+    }
+}
 function applyCharacterPagination(content, startChar = 0, maxLength) {
     if (startChar >= content.length) {
         return "";
@@ -121,6 +167,7 @@ export async function fetchAndConvertToMarkdown(mcpServer, url, timeoutMs = 1000
         logMessage(mcpServer, "error", `Invalid URL format: ${url}`);
         throw createURLFormatError(url);
     }
+    assertUrlAllowed(parsedUrl);
     // Create an AbortController instance
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
@@ -129,11 +176,11 @@ export async function fetchAndConvertToMarkdown(mcpServer, url, timeoutMs = 1000
         const requestOptions = {
             signal: controller.signal,
         };
-        // Add proxy dispatcher if proxy is configured
-        // Node.js fetch uses 'dispatcher' option for proxy, not 'agent'
+        // Add proxy or default dispatcher (includes system CA certs for TLS)
         const proxyAgent = createProxyAgent(url, ProxyType.URL_READER);
-        if (proxyAgent) {
-            requestOptions.dispatcher = proxyAgent;
+        const dispatcher = proxyAgent ?? createDefaultAgent();
+        if (dispatcher) {
+            requestOptions.dispatcher = dispatcher;
         }
         // Add User-Agent header if configured (URL_READER_USER_AGENT takes priority over USER_AGENT)
         const userAgent = process.env.URL_READER_USER_AGENT || process.env.USER_AGENT;
@@ -151,7 +198,7 @@ export async function fetchAndConvertToMarkdown(mcpServer, url, timeoutMs = 1000
         catch (error) {
             const context = {
                 url,
-                proxyAgent: !!proxyAgent,
+                proxyAgent: !!dispatcher,
                 timeout: timeoutMs
             };
             throw createNetworkError(error, context);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mcp-searxng",
-    "version": "0.10.5",
+    "version": "1.0.2",
     "mcpName": "io.github.ihor-sokoliuk/mcp-searxng",
     "description": "MCP server for SearXNG integration",
     "license": "MIT",
@@ -51,7 +51,7 @@
         "cors": "^2.8.6",
         "express": "^5.2.1",
         "node-html-markdown": "^2.0.0",
-        "undici": "^7.0.0"
+        "undici": "^7.24.0"
     },
     "devDependencies": {
         "@types/node": "^22.17.2",