@missionsquad/mcp-searxng-puppeteer

Instructions

Implementation Reference

• index.ts:125-178 (handler)

  The core handler function that performs the web search. It constructs the SearXNG API URL with provided parameters, fetches JSON results, processes them, and returns formatted text output with titles, descriptions, and URLs.

  async function performWebSearch(
    query: string,
    pageno: number = 1,
    count: number = 10,
    time_range?: string,
    language: string = "all",
    safesearch?: string
  ) {
    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("pageno", pageno.toString());
    url.searchParams.set("count", count.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);
    }
  
    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()) as SearXNGWeb;
  
    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");
  }

• index.ts:17-59 (schema)

  Defines the complete Tool object for 'web_search', including name, description, and detailed inputSchema with properties, defaults, enums, and required fields.

  const WEB_SEARCH_TOOL: Tool = {
    name: "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:
            "The search query. This is the main input for the web search",
        },
        pageno: {
          type: "number",
          description: "Search page number (starts at 1)",
          default: 1,
        },
        count: {
          type: "number",
          description: "Number of results per page (default: 10)",
          default: 10,
        },
        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.",
        },
        safesearch: {
          type: "string",
          description:
            "Safe search filter level (0: None, 1: Moderate, 2: Strict) (default: 0)",
          enum: ["0", "1", "2"],
        },
      },
      required: ["query"],
    },
  };

• index.ts:88-91 (registration)

  Registers the web_search tool in the MCP server capabilities section, referencing the tool's description and input schema.

  web_search: {
    description: WEB_SEARCH_TOOL.description,
    schema: WEB_SEARCH_TOOL.inputSchema,
  },

• index.ts:246-248 (registration)

  Registers the web_search tool (via WEB_SEARCH_TOOL constant) in the response handler for listing available tools.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [WEB_SEARCH_TOOL, READ_URL_TOOL],
  }));

• index.ts:109-123 (helper)

  Type guard helper function to validate and type-check the input arguments for the web_search tool.

  function isSearXNGWebSearchArgs(args: unknown): args is {
    query: string;
    pageno?: number;
    count?: number;
    time_range?: string;
    language?: string;
    safesearch?: string;
  } {
    return (
      typeof args === "object" &&
      args !== null &&
      "query" in args &&
      typeof (args as { query: string }).query === "string"
    );
  }