@kassol/mcp-searxng 1.0.3-custom.0

package/dist/proxy.js

@@ -0,0 +1,215 @@
+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.
+ *
+ * @param targetUrl - The URL to check against NO_PROXY rules
+ * @returns true if the URL should bypass the proxy, false otherwise
+ */
+function shouldBypassProxy(targetUrl) {
+    const noProxy = process.env.NO_PROXY || process.env.no_proxy;
+    if (!noProxy) {
+        return false;
+    }
+    // Wildcard bypass
+    if (noProxy.trim() === '*') {
+        return true;
+    }
+    let hostname;
+    try {
+        const url = new URL(targetUrl);
+        hostname = url.hostname.toLowerCase();
+    }
+    catch (error) {
+        // Invalid URL, don't bypass
+        return false;
+    }
+    // Parse comma-separated list of bypass patterns
+    const bypassPatterns = noProxy.split(',').map(pattern => pattern.trim().toLowerCase());
+    for (const pattern of bypassPatterns) {
+        if (!pattern)
+            continue;
+        // Exact hostname match
+        if (hostname === pattern) {
+            return true;
+        }
+        // Domain suffix match with leading dot (e.g., .example.com matches sub.example.com)
+        if (pattern.startsWith('.') && hostname.endsWith(pattern)) {
+            return true;
+        }
+        // Domain suffix match without leading dot (e.g., example.com matches sub.example.com and example.com)
+        if (!pattern.startsWith('.')) {
+            // Exact match
+            if (hostname === pattern) {
+                return true;
+            }
+            // Subdomain match
+            if (hostname.endsWith(`.${pattern}`)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Proxy configuration type for separating search and URL reader proxies.
+ */
+export const ProxyType = {
+    SEARCH: 'search',
+    URL_READER: 'url_reader',
+};
+/**
+ * Gets proxy URL for the specified proxy type.
+ * Checks type-specific proxy first, then falls back to global proxy.
+ *
+ * @param type - The type of proxy to get ('search' or 'url_reader')
+ * @param targetUrl - Optional target URL whose protocol is used to select between HTTP and HTTPS proxies
+ * @returns The proxy URL or undefined if not configured
+ */
+function getProxyUrl(type, targetUrl) {
+    let isHttps = false;
+    if (targetUrl) {
+        try {
+            const url = new URL(targetUrl);
+            isHttps = url.protocol === 'https:';
+        }
+        catch {
+            isHttps = false;
+        }
+    }
+    if (type === ProxyType.SEARCH) {
+        if (isHttps) {
+            return process.env.SEARCH_HTTPS_PROXY ||
+                process.env.SEARCH_HTTP_PROXY ||
+                process.env.search_https_proxy ||
+                process.env.search_http_proxy ||
+                process.env.HTTPS_PROXY ||
+                process.env.HTTP_PROXY ||
+                process.env.https_proxy ||
+                process.env.http_proxy;
+        }
+        return process.env.SEARCH_HTTP_PROXY ||
+            process.env.SEARCH_HTTPS_PROXY ||
+            process.env.search_http_proxy ||
+            process.env.search_https_proxy ||
+            // Fallback to global proxies
+            process.env.HTTP_PROXY ||
+            process.env.HTTPS_PROXY ||
+            process.env.http_proxy ||
+            process.env.https_proxy;
+    }
+    if (type === ProxyType.URL_READER) {
+        if (isHttps) {
+            return process.env.URL_READER_HTTPS_PROXY ||
+                process.env.URL_READER_HTTP_PROXY ||
+                process.env.url_reader_https_proxy ||
+                process.env.url_reader_http_proxy ||
+                process.env.HTTPS_PROXY ||
+                process.env.HTTP_PROXY ||
+                process.env.https_proxy ||
+                process.env.http_proxy;
+        }
+        return process.env.URL_READER_HTTP_PROXY ||
+            process.env.URL_READER_HTTPS_PROXY ||
+            process.env.url_reader_http_proxy ||
+            process.env.url_reader_https_proxy ||
+            // Fallback to global proxies
+            process.env.HTTP_PROXY ||
+            process.env.HTTPS_PROXY ||
+            process.env.http_proxy ||
+            process.env.https_proxy;
+    }
+    if (isHttps) {
+        return process.env.HTTPS_PROXY ||
+            process.env.HTTP_PROXY ||
+            process.env.https_proxy ||
+            process.env.http_proxy;
+    }
+    return process.env.HTTP_PROXY ||
+        process.env.HTTPS_PROXY ||
+        process.env.http_proxy ||
+        process.env.https_proxy;
+}
+/**
+ * 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 function createProxyAgent(targetUrl, type) {
+    const proxyUrl = getProxyUrl(type, targetUrl);
+    if (!proxyUrl) {
+        return undefined;
+    }
+    // Check if target URL should bypass proxy
+    if (targetUrl && shouldBypassProxy(targetUrl)) {
+        return undefined;
+    }
+    // Validate and normalize proxy URL
+    let parsedProxyUrl;
+    try {
+        parsedProxyUrl = new URL(proxyUrl);
+    }
+    catch (error) {
+        throw new Error(`Invalid proxy URL: ${proxyUrl}. ` +
+            "Please provide a valid URL (e.g., http://proxy:8080 or http://user:pass@proxy:8080)");
+    }
+    // Ensure proxy protocol is supported
+    if (!['http:', 'https:'].includes(parsedProxyUrl.protocol)) {
+        throw new Error(`Unsupported proxy protocol: ${parsedProxyUrl.protocol}. ` +
+            "Only HTTP and HTTPS proxies are supported.");
+    }
+    // Reconstruct base proxy URL preserving credentials
+    const auth = parsedProxyUrl.username ?
+        (parsedProxyUrl.password ? `${parsedProxyUrl.username}:${parsedProxyUrl.password}@` : `${parsedProxyUrl.username}@`) :
+        '';
+    const normalizedProxyUrl = `${parsedProxyUrl.protocol}//${auth}${parsedProxyUrl.host}`;
+    // Create and return Undici ProxyAgent compatible with fetch's dispatcher option
+    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.d.ts

@@ -0,0 +1,2 @@
+export declare function createConfigResource(): string;
+export declare function createHelpResource(): string;

package/dist/resources.js

@@ -0,0 +1,114 @@
+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: "kassol/mcp-searxng",
+            version: packageVersion,
+            description: "MCP server for SearXNG integration"
+        },
+        environment: {
+            ...(showFullConfig
+                ? { searxngUrl: process.env.SEARXNG_URL || "(not configured)" }
+                : { searxngUrlConfigured: !!process.env.SEARXNG_URL }),
+            hasAuth: !!(process.env.AUTH_USERNAME && process.env.AUTH_PASSWORD),
+            hasSearxngHeaders: !!process.env.SEARXNG_HEADERS,
+            hasUrlReaderHeaders: !!process.env.URL_READER_HEADERS,
+            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),
+            nodeVersion: process.version,
+            currentLogLevel: getCurrentLogLevel()
+        },
+        capabilities: {
+            tools: ["searxng_web_search", "web_url_read"],
+            logging: true,
+            resources: true,
+            transports: process.env.MCP_HTTP_PORT ? ["stdio", "http"] : ["stdio"]
+        }
+    };
+    return JSON.stringify(config, null, 2);
+}
+export function createHelpResource() {
+    return `# SearXNG MCP Server Help
+
+## Overview
+This is a Model Context Protocol (MCP) server that provides web search capabilities through SearXNG and URL content reading functionality.
+
+## Available Tools
+
+### 1. searxng_web_search
+Performs web searches using the configured SearXNG instance.
+
+**Parameters:**
+- \`query\` (required): The search query string
+- \`pageno\` (optional): Page number (default: 1)
+- \`time_range\` (optional): Filter by time - "day", "month", or "year"
+- \`language\` (optional): Language code like "en", "fr", "de" (default: "all")
+- \`safesearch\` (optional): Safe search level - 0 (none), 1 (moderate), 2 (strict)
+
+### 2. web_url_read
+Reads and converts web page content to Markdown format.
+
+**Parameters:**
+- \`url\` (required): The URL to fetch and convert
+
+## Configuration
+
+### Required Environment Variables
+- \`SEARXNG_URL\`: URL of your SearXNG instance (e.g., http://localhost:8080)
+
+### Optional Environment Variables
+- \`AUTH_USERNAME\` & \`AUTH_PASSWORD\`: Basic authentication for SearXNG
+- \`USER_AGENT\`: Global User-Agent header for outgoing requests
+- \`URL_READER_USER_AGENT\`: User-Agent for \`web_url_read\`, overrides \`USER_AGENT\`
+- \`SEARXNG_HEADERS\`: Extra JSON headers for SearXNG search requests
+- \`URL_READER_HEADERS\`: Extra JSON headers for URL read requests
+- \`HTTP_PROXY\` / \`HTTPS_PROXY\`: Proxy server configuration
+- \`NO_PROXY\` / \`no_proxy\`: Comma-separated list of hosts to bypass proxy
+- \`MCP_HTTP_PORT\`: Enable HTTP transport on specified port
+
+## Transport Modes
+
+### STDIO (Default)
+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
+\`\`\`
+Tool: searxng_web_search
+Args: {"query": "latest AI developments", "time_range": "day"}
+\`\`\`
+
+### Read a specific article
+\`\`\`
+Tool: web_url_read  
+Args: {"url": "https://example.com/article"}
+\`\`\`
+
+## Troubleshooting
+
+1. **"SEARXNG_URL not set"**: Configure the SEARXNG_URL environment variable
+2. **Network errors**: Check if SearXNG is running and accessible
+3. **Empty results**: Try different search terms or check SearXNG instance
+4. **Timeout errors**: The server has a 10-second timeout for URL fetching
+
+Use logging level "debug" for detailed request information.
+
+## Current Configuration
+See the "Current Configuration" resource for live settings.
+`;
+}

package/dist/search.d.ts

@@ -0,0 +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): Promise<string>;

package/dist/search.js

@@ -0,0 +1,133 @@
+import { createProxyAgent, createDefaultAgent, ProxyType } from "./proxy.js";
+import { logMessage } from "./logging.js";
+import { mergeHeaders, parseHeadersFromEnv } from "./headers.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
+    const searchParams = [
+        `page ${pageno}`,
+        `lang: ${language}`,
+        time_range ? `time: ${time_range}` : null,
+        safesearch ? `safesearch: ${safesearch}` : 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);
+    url.searchParams.set("q", query);
+    url.searchParams.set("format", "json");
+    url.searchParams.set("pageno", pageno.toString());
+    if (time_range !== undefined &&
+        ["day", "month", "year"].includes(time_range)) {
+        url.searchParams.set("time_range", time_range);
+    }
+    if (language && language !== "all") {
+        url.searchParams.set("language", language);
+    }
+    if (safesearch !== undefined && [0, 1, 2].includes(safesearch)) {
+        url.searchParams.set("safesearch", safesearch.toString());
+    }
+    // Prepare request options with headers
+    const requestOptions = {
+        method: "GET"
+    };
+    // Add proxy or default dispatcher (includes system CA certs for TLS)
+    const proxyAgent = createProxyAgent(url.toString(), ProxyType.SEARCH);
+    const dispatcher = proxyAgent ?? createDefaultAgent();
+    if (dispatcher) {
+        requestOptions.dispatcher = dispatcher;
+    }
+    // Add basic authentication if credentials are provided
+    const username = process.env.AUTH_USERNAME;
+    const password = process.env.AUTH_PASSWORD;
+    if (username && password) {
+        const base64Auth = Buffer.from(`${username}:${password}`).toString('base64');
+        requestOptions.headers = {
+            ...requestOptions.headers,
+            'Authorization': `Basic ${base64Auth}`
+        };
+    }
+    // Add User-Agent header if configured
+    const userAgent = process.env.USER_AGENT;
+    if (userAgent) {
+        requestOptions.headers = {
+            ...requestOptions.headers,
+            'User-Agent': userAgent
+        };
+    }
+    const additionalHeaders = parseHeadersFromEnv("SEARXNG_HEADERS");
+    if (Object.keys(additionalHeaders).length > 0) {
+        requestOptions.headers = mergeHeaders(requestOptions.headers, additionalHeaders);
+    }
+    // Fetch with enhanced error handling
+    let response;
+    try {
+        logMessage(mcpServer, "info", `Making request to: ${url.toString()}`);
+        response = await fetch(url.toString(), requestOptions);
+    }
+    catch (error) {
+        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);
+    }
+    if (!response.ok) {
+        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);
+    }
+    // Parse JSON response
+    let data;
+    try {
+        data = (await response.json());
+    }
+    catch (error) {
+        let responseText;
+        try {
+            responseText = await response.text();
+        }
+        catch {
+            responseText = '[Could not read response text]';
+        }
+        const context = { url: url.toString() };
+        throw createJSONError(responseText, context);
+    }
+    if (!data.results) {
+        const context = { url: url.toString(), query };
+        throw createDataError(data, context);
+    }
+    const results = data.results.map((result) => ({
+        title: result.title || "",
+        content: result.content || "",
+        url: result.url || "",
+        score: result.score || 0,
+    }));
+    if (results.length === 0) {
+        logMessage(mcpServer, "info", `No results found for query: "${query}"`);
+        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)}`)
+        .join("\n\n");
+}

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

@@ -0,0 +1,18 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+export interface SearXNGWeb {
+    results: Array<{
+        title: string;
+        content: string;
+        url: string;
+        score: number;
+    }>;
+}
+export declare function isSearXNGWebSearchArgs(args: unknown): args is {
+    query: string;
+    pageno?: number;
+    time_range?: string;
+    language?: string;
+    safesearch?: number;
+};
+export declare const WEB_SEARCH_TOOL: Tool;
+export declare const READ_URL_TOOL: Tool;

package/dist/types.js

@@ -0,0 +1,87 @@
+export function isSearXNGWebSearchArgs(args) {
+    return (typeof args === "object" &&
+        args !== null &&
+        "query" in args &&
+        typeof args.query === "string");
+}
+export const WEB_SEARCH_TOOL = {
+    name: "searxng_web_search",
+    description: "Performs a web search using the SearXNG API, ideal for general queries, news, articles, and online content. " +
+        "Use this for broad information gathering, recent events, or when you need diverse web sources.",
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "The search query. This is the main input for the web search",
+            },
+            pageno: {
+                type: "number",
+                description: "Search page number (starts at 1)",
+                default: 1,
+            },
+            time_range: {
+                type: "string",
+                description: "Time range of search (day, month, year)",
+                enum: ["day", "month", "year"],
+            },
+            language: {
+                type: "string",
+                description: "Language code for search results (e.g., 'en', 'fr', 'de'). Default is instance-dependent.",
+                default: "all",
+            },
+            safesearch: {
+                type: "number",
+                description: "Safe search filter level (0: None, 1: Moderate, 2: Strict)",
+                enum: [0, 1, 2],
+                default: 0,
+            },
+        },
+        required: ["query"],
+    },
+};
+export const READ_URL_TOOL = {
+    name: "web_url_read",
+    description: "Read the content from an URL. " +
+        "Use this for further information retrieving to understand the content of each URL.",
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            url: {
+                type: "string",
+                description: "URL",
+            },
+            startChar: {
+                type: "number",
+                description: "Starting character position for content extraction (default: 0)",
+                minimum: 0,
+            },
+            maxLength: {
+                type: "number",
+                description: "Maximum number of characters to return",
+                minimum: 1,
+            },
+            section: {
+                type: "string",
+                description: "Extract content under a specific heading (searches for heading text)",
+            },
+            paragraphRange: {
+                type: "string",
+                description: "Return specific paragraph ranges (e.g., '1-5', '3', '10-')",
+            },
+            readHeadings: {
+                type: "boolean",
+                description: "Return only a list of headings instead of full content",
+            },
+        },
+        required: ["url"],
+    },
+};

package/dist/url-reader.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+interface PaginationOptions {
+    startChar?: number;
+    maxLength?: number;
+    section?: string;
+    paragraphRange?: string;
+    readHeadings?: boolean;
+}
+export declare function fetchAndConvertToMarkdown(mcpServer: McpServer, url: string, timeoutMs?: number, paginationOptions?: PaginationOptions): Promise<string>;
+export {};