mcp-searxng 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 IS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# SearXNG MCP Server
+
+An [MCP server](https://modelcontextprotocol.io/introduction) implementation that integrates the SearxNG API, providing web search capabilities.
+
+<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>
+
+[![smithery badge](https://smithery.ai/badge/@ihor-sokoliuk/server-searxng)](https://smithery.ai/server/@ihor-sokoliuk/server-searxng)
+
+## Features
+
+- **Web Search**: General queries, news, articles, with pagination.
+- **Pagination**: Control return size and result counts options.
+
+## Tools
+
+- **searxng_web_search**
+  - Execute web searches with pagination
+  - Inputs:
+    - `query` (string): Search terms
+    - `count` (number, optional): Results per page (default 20)
+    - `offset` (number, optional): Pagination offset (default 0)
+
+## Configuration
+
+### Setting the SEARXNG_URL
+
+1. Choose a SearxNG instance from the [list of public instances](https://searx.space/) or use your local environment.
+2. Set the `SEARXNG_URL` environment variable to the instance URL.
+3. The default `SEARXNG_URL` value is `http://localhost:8080`.
+
+### Usage with Claude Desktop
+
+### Installing via Smithery
+
+To install SearxNG Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@ihor-sokoliuk/server-searxng):
+
+```bash
+npx -y @smithery/cli install @ihor-sokoliuk/server-searxng --client claude
+```
+
+### Installing via npm
+
+```bash
+npm install -g @ihor-sokoliuk/server-searxng
+```
+
+And then in your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "searxng": {
+      "command": "mcp-server-searxng",
+      "env": {
+        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
+      }
+    }
+  }
+}
+```
+
+### NPX
+
+```json
+{
+  "mcpServers": {
+    "searxng": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@ihor-sokoliuk/server-searxng"
+      ],
+      "env": {
+        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
+      }
+    }
+  }
+}
+```
+
+### Docker
+
+#### Build
+
+```bash
+docker build -t mcp-server-searxng:latest -f Dockerfile .
+```
+
+#### Use
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "searxng": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "SEARXNG_URL",
+        "mcp-server-searxng:latest"
+      ],
+      "env": {
+        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
+      }
+    }
+  }
+}
+```
+
+## Publishing to npm
+
+To make your library publicly available on npm:
+
+### 1. Create an npm Account
+
+If you don't have an npm account, create one at [npmjs.com](https://www.npmjs.com/signup).
+
+### 2. Log in to npm
+
+```bash
+npm login
+```
+
+### 3. Prepare your package
+
+Make sure your package.json is correctly set up with:
+- A unique name (`@ihor-sokoliuk/server-searxng`)
+- Version number
+- Description
+- Entry point
+- Dependencies
+
+### 4. Build your package
+
+```bash
+npm run build
+```
+
+### 5. Publish to npm
+
+```bash
+npm publish --access=public
+```
+
+For subsequent updates:
+1. Update the version in package.json: `npm version patch|minor|major`
+2. Run `npm publish`
+
+### 6. Verify your package
+
+Check that your package is available at `https://www.npmjs.com/package/@ihor-sokoliuk/server-searxng`
+
+## 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.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { NodeHtmlMarkdown } from "node-html-markdown";
+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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "Search query",
+            },
+            count: {
+                type: "number",
+                description: "Number of results",
+                default: 20,
+            },
+            offset: {
+                type: "number",
+                description: "Pagination offset",
+                default: 0,
+            },
+        },
+        required: ["query"],
+    },
+};
+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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            url: {
+                type: "string",
+                description: "URL",
+            },
+        },
+        required: ["url"],
+    },
+};
+// Server implementation
+const server = new Server({
+    name: "example-servers/searxng-search",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        resources: {},
+        tools: {},
+    },
+});
+function isSearXNGWebSearchArgs(args) {
+    return (typeof args === "object" &&
+        args !== null &&
+        "query" in args &&
+        typeof args.query === "string");
+}
+async function performWebSearch(query, count = 10, offset = 0) {
+    const searxngUrl = process.env.SEARXNG_URL || "http://localhost:8080";
+    const url = new URL(`${searxngUrl}/search`);
+    url.searchParams.set("q", query);
+    url.searchParams.set("format", "json");
+    url.searchParams.set("start", offset.toString());
+    url.searchParams.set("count", count.toString());
+    const response = await fetch(url.toString(), {
+        method: "GET",
+    });
+    if (!response.ok) {
+        throw new Error(`SearXNG API error: ${response.status} ${response.statusText}\n${await response.text()}`);
+    }
+    const data = (await response.json());
+    const results = (data.results || []).map((result) => ({
+        title: result.title || "",
+        content: result.content || "",
+        url: result.url || "",
+    }));
+    return results
+        .map((r) => `Title: ${r.title}\nDescription: ${r.content}\nURL: ${r.url}`)
+        .join("\n\n");
+}
+async function fetchAndConvertToMarkdown(url, timeoutMs = 10000) {
+    // Create an AbortController instance
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        // Fetch the URL with the abort signal
+        const response = await fetch(url, {
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch the URL: ${response.statusText}`);
+        }
+        // Retrieve HTML content
+        const htmlContent = await response.text();
+        // Convert HTML to Markdown
+        const markdownContent = NodeHtmlMarkdown.translate(htmlContent);
+        return markdownContent;
+    }
+    catch (error) {
+        if (error.name === "AbortError") {
+            throw new Error(`Request timed out after ${timeoutMs}ms`);
+        }
+        console.error("Error:", error.message);
+        throw error;
+    }
+    finally {
+        // Clean up the timeout to prevent memory leaks
+        clearTimeout(timeoutId);
+    }
+}
+// Tool handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [WEB_SEARCH_TOOL, READ_URL_TOOL],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        const { name, arguments: args } = request.params;
+        if (!args) {
+            throw new Error("No arguments provided");
+        }
+        if (name === "searxng_web_search") {
+            if (!isSearXNGWebSearchArgs(args)) {
+                throw new Error("Invalid arguments for searxng_web_search");
+            }
+            const { query, count = 10 } = args;
+            const results = await performWebSearch(query, count);
+            return {
+                content: [{ type: "text", text: results }],
+                isError: false,
+            };
+        }
+        if (name === "web_url_read") {
+            const { url } = args;
+            const result = await fetchAndConvertToMarkdown(url);
+            return {
+                content: [{ type: "text", text: result }],
+                isError: false,
+            };
+        }
+        return {
+            content: [{ type: "text", text: `Unknown tool: ${name}` }],
+            isError: true,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function runServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+runServer().catch((error) => {
+    console.error("Fatal error running server:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "mcp-searxng",
+    "version": "0.2.0",
+    "description": "MCP server for SearXNG integration",
+    "license": "MIT",
+    "author": "Ihor Sokoliuk (https://github.com/ihor-sokoliuk)",
+    "homepage": "https://github.com/ihor-sokoliuk/mcp-searxng",
+    "bugs": "https://github.com/ihor-sokoliuk/mcp-searxng/issues",
+    "type": "module",
+    "bin": {
+        "mcp-searxng": "dist/index.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc && shx chmod +x dist/*.js",
+        "prepare": "npm run build",
+        "watch": "tsc --watch"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "1.9.0",
+        "node-html-markdown": "^1.3.0"
+    },
+    "devDependencies": {
+        "@types/node": "^22.14.1",
+        "shx": "^0.3.4",
+        "typescript": "^5.7.2"
+    }
+}