@kassol/mcp-searxng 1.0.3-custom.0

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.d.ts

@@ -0,0 +1,3 @@
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createHttpServer(createMcpServer: () => McpServer): Promise<express.Application>;

package/dist/http-server.js

@@ -0,0 +1,185 @@
+import express from "express";
+import cors from "cors";
+import { randomUUID } from "crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+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(createMcpServer) {
+    const app = express();
+    const security = getHttpSecurityConfig();
+    validateHttpSecurityConfig(security);
+    app.use(express.json());
+    // Add CORS support for web clients
+    app.use(cors({
+        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 sessions by session ID
+    const sessions = new Map();
+    // 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;
+        let mcpServer;
+        if (sessionId && sessions.has(sessionId)) {
+            // Reuse existing session
+            const session = sessions.get(sessionId);
+            transport = session.transport;
+            mcpServer = session.mcpServer;
+            logMessage(mcpServer, "debug", `Reusing session: ${sessionId}`);
+        }
+        else if (!sessionId && isInitializeRequest(req.body)) {
+            // New initialization request — create fresh McpServer and transport
+            mcpServer = createMcpServer();
+            transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sessionId) => {
+                    sessions.set(sessionId, { transport, mcpServer });
+                    logMessage(mcpServer, "debug", `Session initialized: ${sessionId}`);
+                },
+                enableDnsRebindingProtection: security.enableDnsRebindingProtection,
+                allowedHosts: security.allowedHosts,
+                allowedOrigins: security.allowedOrigins,
+            });
+            // Clean up session when transport closes
+            transport.onclose = () => {
+                if (transport.sessionId) {
+                    sessions.delete(transport.sessionId);
+                }
+            };
+            // Connect this session's McpServer to its transport
+            await mcpServer.connect(transport);
+        }
+        else {
+            // Invalid request
+            console.warn(`⚠️  POST request rejected - invalid request:`, {
+                clientIP: req.ip || req.socket.remoteAddress,
+                sessionId: sessionId || 'undefined',
+                hasInitializeRequest: isInitializeRequest(req.body),
+                userAgent: req.headers['user-agent'],
+                contentType: req.headers['content-type'],
+                accept: req.headers['accept']
+            });
+            res.status(400).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32000,
+                    message: 'Bad Request: No valid session ID provided',
+                },
+                id: null,
+            });
+            return;
+        }
+        // Handle the request
+        try {
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            // Log header-related rejections for debugging
+            if (error instanceof Error && error.message.includes('accept')) {
+                console.warn(`⚠️  Connection rejected due to missing headers:`, {
+                    clientIP: req.ip || req.socket.remoteAddress,
+                    userAgent: req.headers['user-agent'],
+                    contentType: req.headers['content-type'],
+                    accept: req.headers['accept'],
+                    error: error.message
+                });
+            }
+            throw error;
+        }
+    });
+    // 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 || !sessions.has(sessionId)) {
+            console.warn(`⚠️  GET request rejected - missing or invalid session ID:`, {
+                clientIP: req.ip || req.socket.remoteAddress,
+                sessionId: sessionId || 'undefined',
+                userAgent: req.headers['user-agent']
+            });
+            res.status(400).send('Invalid or missing session ID');
+            return;
+        }
+        const session = sessions.get(sessionId);
+        try {
+            await session.transport.handleRequest(req, res);
+        }
+        catch (error) {
+            console.warn(`⚠️  GET request failed:`, {
+                clientIP: req.ip || req.socket.remoteAddress,
+                sessionId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+        }
+    });
+    // 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 || !sessions.has(sessionId)) {
+            console.warn(`⚠️  DELETE request rejected - missing or invalid session ID:`, {
+                clientIP: req.ip || req.socket.remoteAddress,
+                sessionId: sessionId || 'undefined',
+                userAgent: req.headers['user-agent']
+            });
+            res.status(400).send('Invalid or missing session ID');
+            return;
+        }
+        const session = sessions.get(sessionId);
+        try {
+            await session.transport.handleRequest(req, res);
+        }
+        catch (error) {
+            console.warn(`⚠️  DELETE request failed:`, {
+                clientIP: req.ip || req.socket.remoteAddress,
+                sessionId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+        }
+        finally {
+            sessions.delete(sessionId);
+        }
+    });
+    // Health check endpoint
+    app.get('/health', (_req, res) => {
+        res.json({
+            status: 'healthy',
+            server: 'kassol/mcp-searxng',
+            version: packageVersion,
+            transport: 'http'
+        });
+    });
+    return app;
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+declare const packageVersion = "1.0.3-custom.0";
+export { packageVersion };
+export declare function isWebUrlReadArgs(args: unknown): args is {
+    url: string;
+    startChar?: number;
+    maxLength?: number;
+    section?: string;
+    paragraphRange?: string;
+    readHeadings?: boolean;
+};
+/**
+ * Creates and configures a new McpServer with all handlers registered.
+ * Called once per HTTP session, or once for STDIO mode.
+ */
+export declare function createMcpServer(): McpServer;

package/dist/index.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+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 { logMessage, setLogLevel, getCurrentLogLevel } from "./logging.js";
+import { performWebSearch } from "./search.js";
+import { fetchAndConvertToMarkdown } from "./url-reader.js";
+import { createConfigResource, createHelpResource } from "./resources.js";
+import { createHttpServer } from "./http-server.js";
+// Use a static version string that will be updated by the version script
+const packageVersion = "1.0.3-custom.0";
+// Export the version for use in other modules
+export { packageVersion };
+// Type guard for URL reading args
+export function isWebUrlReadArgs(args) {
+    if (typeof args !== "object" ||
+        args === null ||
+        !("url" in args) ||
+        typeof args.url !== "string") {
+        return false;
+    }
+    const urlArgs = args;
+    // Convert empty strings to undefined for optional string parameters
+    if (urlArgs.section === "")
+        urlArgs.section = undefined;
+    if (urlArgs.paragraphRange === "")
+        urlArgs.paragraphRange = undefined;
+    // Validate optional parameters
+    if (urlArgs.startChar !== undefined && (typeof urlArgs.startChar !== "number" || urlArgs.startChar < 0)) {
+        return false;
+    }
+    if (urlArgs.maxLength !== undefined && (typeof urlArgs.maxLength !== "number" || urlArgs.maxLength < 1)) {
+        return false;
+    }
+    if (urlArgs.section !== undefined && typeof urlArgs.section !== "string") {
+        return false;
+    }
+    if (urlArgs.paragraphRange !== undefined && typeof urlArgs.paragraphRange !== "string") {
+        return false;
+    }
+    if (urlArgs.readHeadings !== undefined && typeof urlArgs.readHeadings !== "boolean") {
+        return false;
+    }
+    return true;
+}
+/**
+ * Creates and configures a new McpServer with all handlers registered.
+ * Called once per HTTP session, or once for STDIO mode.
+ */
+export function createMcpServer() {
+    const mcpServer = new McpServer({
+        name: "kassol/mcp-searxng",
+        version: packageVersion,
+    }, {
+        capabilities: {
+            logging: {},
+            resources: {},
+            tools: {},
+        },
+    });
+    const server = mcpServer.server;
+    // List tools handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        logMessage(mcpServer, "debug", "Handling list_tools request");
+        return {
+            tools: [WEB_SEARCH_TOOL, READ_URL_TOOL],
+        };
+    });
+    // Call tool handler
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        logMessage(mcpServer, "debug", `Handling call_tool request: ${name}`);
+        try {
+            if (name === "searxng_web_search") {
+                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);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: result,
+                        },
+                    ],
+                };
+            }
+            else if (name === "web_url_read") {
+                if (!isWebUrlReadArgs(args)) {
+                    throw new Error("Invalid arguments for URL reading");
+                }
+                const paginationOptions = {
+                    startChar: args.startChar,
+                    maxLength: args.maxLength,
+                    section: args.section,
+                    paragraphRange: args.paragraphRange,
+                    readHeadings: args.readHeadings,
+                };
+                const result = await fetchAndConvertToMarkdown(mcpServer, args.url, 10000, paginationOptions);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: result,
+                        },
+                    ],
+                };
+            }
+            else {
+                throw new Error(`Unknown tool: ${name}`);
+            }
+        }
+        catch (error) {
+            logMessage(mcpServer, "error", `Tool execution error: ${error instanceof Error ? error.message : String(error)}`, {
+                tool: name,
+                args: args,
+                error: error instanceof Error ? error.stack : String(error)
+            });
+            throw error;
+        }
+    });
+    // Logging level handler
+    server.setRequestHandler(SetLevelRequestSchema, async (request) => {
+        const { level } = request.params;
+        logMessage(mcpServer, "info", `Setting log level to: ${level}`);
+        setLogLevel(level);
+        return {};
+    });
+    // List resources handler
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        logMessage(mcpServer, "debug", "Handling list_resources request");
+        return {
+            resources: [
+                {
+                    uri: "config://server-config",
+                    mimeType: "application/json",
+                    name: "Server Configuration",
+                    description: "Current server configuration and environment variables"
+                },
+                {
+                    uri: "help://usage-guide",
+                    mimeType: "text/markdown",
+                    name: "Usage Guide",
+                    description: "How to use the MCP SearXNG server effectively"
+                }
+            ]
+        };
+    });
+    // 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: [] };
+    });
+    // Read resource handler
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        logMessage(mcpServer, "debug", `Handling read_resource request for: ${uri}`);
+        switch (uri) {
+            case "config://server-config":
+                return {
+                    contents: [
+                        {
+                            uri: uri,
+                            mimeType: "application/json",
+                            text: createConfigResource()
+                        }
+                    ]
+                };
+            case "help://usage-guide":
+                return {
+                    contents: [
+                        {
+                            uri: uri,
+                            mimeType: "text/markdown",
+                            text: createHelpResource()
+                        }
+                    ]
+                };
+            default:
+                throw new Error(`Unknown resource: ${uri}`);
+        }
+    });
+    return mcpServer;
+}
+// Main function
+async function main() {
+    // Check for HTTP transport mode
+    const httpPort = process.env.MCP_HTTP_PORT;
+    if (httpPort) {
+        const port = parseInt(httpPort, 10);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            console.error(`Invalid HTTP port: ${httpPort}. Must be between 1-65535.`);
+            process.exit(1);
+        }
+        console.log(`Starting HTTP transport on port ${port}`);
+        const app = await createHttpServer(createMcpServer);
+        const httpServer = app.listen(port, () => {
+            console.log(`HTTP server listening on port ${port}`);
+            console.log(`Health check: http://localhost:${port}/health`);
+            console.log(`MCP endpoint: http://localhost:${port}/mcp`);
+        });
+        // Handle graceful shutdown
+        const shutdown = (signal) => {
+            console.log(`Received ${signal}. Shutting down HTTP server...`);
+            httpServer.close(() => {
+                console.log("HTTP server closed");
+                process.exit(0);
+            });
+        };
+        process.on('SIGINT', () => shutdown('SIGINT'));
+        process.on('SIGTERM', () => shutdown('SIGTERM'));
+    }
+    else {
+        // Default STDIO transport — single session, single server
+        const mcpServer = createMcpServer();
+        // Show helpful message when running in terminal
+        if (process.stdin.isTTY) {
+            console.error(`🔍 MCP SearXNG Server v${packageVersion} - Ready`);
+            if (process.env.SEARXNG_URL) {
+                console.error(`🌐 SearXNG URL: ${process.env.SEARXNG_URL}`);
+            }
+            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();
+        await mcpServer.connect(transport);
+        // Log after connection is established
+        logMessage(mcpServer, "info", `MCP SearXNG Server v${packageVersion} connected via STDIO`);
+        logMessage(mcpServer, "info", `Log level: ${getCurrentLogLevel()}`);
+        logMessage(mcpServer, "info", `Environment: ${process.env.NODE_ENV || 'development'}`);
+        logMessage(mcpServer, "info", `SearXNG URL: ${process.env.SEARXNG_URL || 'not configured'}`);
+    }
+}
+// Handle uncaught errors
+process.on('uncaughtException', (error) => {
+    console.error('Uncaught Exception:', error);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason, promise) => {
+    console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+    process.exit(1);
+});
+// Start the server (CLI entrypoint)
+main().catch((error) => {
+    console.error("Failed to start server:", error);
+    process.exit(1);
+});

package/dist/logging.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { LoggingLevel } from "@modelcontextprotocol/sdk/types.js";
+export declare function logMessage(mcpServer: McpServer, level: LoggingLevel, message: string, data?: unknown): void;
+export declare function shouldLog(level: LoggingLevel): boolean;
+export declare function setLogLevel(level: LoggingLevel): void;
+export declare function getCurrentLogLevel(): LoggingLevel;

package/dist/logging.js

@@ -0,0 +1,35 @@
+// 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 {
+            const notificationData = data !== undefined
+                ? (typeof data === 'object' && data !== null ? { message, ...data } : { message, data })
+                : { message };
+            mcpServer.sendLoggingMessage({
+                level,
+                data: notificationData
+            }).catch(handleSendError);
+        }
+        catch (error) {
+            handleSendError(error);
+        }
+    }
+}
+export function shouldLog(level) {
+    const levels = ["debug", "info", "warning", "error"];
+    return levels.indexOf(level) >= levels.indexOf(currentLogLevel);
+}
+export function setLogLevel(level) {
+    currentLogLevel = level;
+}
+export function getCurrentLogLevel() {
+    return currentLogLevel;
+}

package/dist/proxy.d.ts

@@ -0,0 +1,40 @@
+import { Agent, ProxyAgent } from "undici";
+/**
+ * Proxy configuration type for separating search and URL reader proxies.
+ */
+export declare const ProxyType: {
+    readonly SEARCH: "search";
+    readonly URL_READER: "url_reader";
+};
+export type ProxyType = typeof ProxyType[keyof typeof ProxyType];
+/**
+ * Creates a proxy agent dispatcher for Node.js fetch API.
+ *
+ * Node.js fetch uses Undici under the hood, which requires a 'dispatcher' option
+ * instead of 'agent'. This function creates a ProxyAgent compatible with fetch.
+ *
+ * Environment variables checked (in order, depending on URL protocol):
+ * - For type 'search' and HTTPS URLs:
+ *   SEARCH_HTTPS_PROXY, SEARCH_HTTP_PROXY, search_https_proxy, search_http_proxy,
+ *   then HTTPS_PROXY, HTTP_PROXY, https_proxy, http_proxy
+ * - For type 'search' and HTTP/unknown URLs:
+ *   SEARCH_HTTP_PROXY, SEARCH_HTTPS_PROXY, search_http_proxy, search_https_proxy,
+ *   then HTTP_PROXY, HTTPS_PROXY, http_proxy, https_proxy
+ * - For type 'url_reader' and HTTPS URLs:
+ *   URL_READER_HTTPS_PROXY, URL_READER_HTTP_PROXY, url_reader_https_proxy, url_reader_http_proxy,
+ *   then HTTPS_PROXY, HTTP_PROXY, https_proxy, http_proxy
+ * - For type 'url_reader' and HTTP/unknown URLs:
+ *   URL_READER_HTTP_PROXY, URL_READER_HTTPS_PROXY, url_reader_http_proxy, url_reader_https_proxy,
+ *   then HTTP_PROXY, HTTPS_PROXY, http_proxy, https_proxy
+ * - For no specific type and HTTPS URLs:
+ *   HTTPS_PROXY, HTTP_PROXY, https_proxy, http_proxy
+ * - For no specific type and HTTP/unknown URLs:
+ *   HTTP_PROXY, HTTPS_PROXY, http_proxy, https_proxy
+ * - NO_PROXY / no_proxy: Comma-separated list of hosts to bypass proxy
+ *
+ * @param targetUrl - Optional target URL to check against NO_PROXY rules
+ * @param type - Optional proxy type ('search' or 'url_reader') for separate proxy configs
+ * @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;