open-webSearch

Instructions

Implementation Reference

• src/tools/setupTools.ts:203-229 (handler)

  The handler function for the 'search' tool. It takes query, limit, and engines parameters, executes the search using executeSearch, formats results as JSON text content, and handles errors.

  async ({query, limit = 10, engines = ['bing']}) => {
      try {
          console.error(`Searching for "${query}" using engines: ${engines.join(', ')}`);
  
          const results = await executeSearch(query.trim(), engines, limit);
  
          return {
              content: [{
                  type: 'text',
                  text: JSON.stringify({
                      query: query.trim(),
                      engines: engines,
                      totalResults: results.length,
                      results: results
                  }, null, 2)
              }]
          };
      } catch (error) {
          console.error('Search tool execution failed:', error);
          return {
              content: [{
                  type: 'text',
                  text: `Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`
              }],
              isError: true
          };
      }

• src/tools/setupTools.ts:186-202 (schema)

  Zod input schema for the 'search' tool defining parameters: query (required string), limit (number 1-50, default 10), engines (array of allowed engines with transformation for filtering).

      query: z.string().min(1, "Search query must not be empty"),
      limit: z.number().min(1).max(50).default(10),
      engines: z.array(getEnginesEnum()).min(1).default([config.defaultSearchEngine])
          .transform(requestedEngines => {
              // 如果有配置允许的搜索引擎，过滤请求的引擎
              if (config.allowedSearchEngines.length > 0) {
                  const filteredEngines = requestedEngines.filter(engine =>
                      config.allowedSearchEngines.includes(engine));
  
                  // 如果所有请求的引擎都被过滤掉，使用默认引擎
                  return filteredEngines.length > 0 ?
                      filteredEngines :
                      [config.defaultSearchEngine];
              }
              return requestedEngines;
          })
  },

• src/tools/setupTools.ts:182-231 (registration)

  Registers the 'search' tool (name configurable via MCP_TOOL_SEARCH_NAME env var, default 'search') on the MCP server with description, schema, and handler.

  server.tool(
      searchToolName,
      getSearchDescription(),
      {
          query: z.string().min(1, "Search query must not be empty"),
          limit: z.number().min(1).max(50).default(10),
          engines: z.array(getEnginesEnum()).min(1).default([config.defaultSearchEngine])
              .transform(requestedEngines => {
                  // 如果有配置允许的搜索引擎，过滤请求的引擎
                  if (config.allowedSearchEngines.length > 0) {
                      const filteredEngines = requestedEngines.filter(engine =>
                          config.allowedSearchEngines.includes(engine));
  
                      // 如果所有请求的引擎都被过滤掉，使用默认引擎
                      return filteredEngines.length > 0 ?
                          filteredEngines :
                          [config.defaultSearchEngine];
                  }
                  return requestedEngines;
              })
      },
      async ({query, limit = 10, engines = ['bing']}) => {
          try {
              console.error(`Searching for "${query}" using engines: ${engines.join(', ')}`);
  
              const results = await executeSearch(query.trim(), engines, limit);
  
              return {
                  content: [{
                      type: 'text',
                      text: JSON.stringify({
                          query: query.trim(),
                          engines: engines,
                          totalResults: results.length,
                          results: results
                      }, null, 2)
                  }]
              };
          } catch (error) {
              console.error('Search tool execution failed:', error);
              return {
                  content: [{
                      type: 'text',
                      text: `Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`
                  }],
                  isError: true
              };
          }
      }
  );

• src/tools/setupTools.ts:46-81 (helper)

  Helper function that executes parallel searches across multiple engines, distributes the limit evenly, handles individual engine failures gracefully, and aggregates results.

  const executeSearch = async (query: string, engines: string[], limit: number): Promise<SearchResult[]> => {
      // Clean up the query string to ensure it won't cause issues due to spaces or special characters
      const cleanQuery = query.trim();
      console.error(`[DEBUG] Executing search, query: "${cleanQuery}", engines: ${engines.join(', ')}, limit: ${limit}`);
  
      if (!cleanQuery) {
          console.error('Query string is empty');
          throw new Error('Query string cannot be empty');
  
      }
  
      const limits = distributeLimit(limit, engines.length);
  
      const searchTasks = engines.map((engine, index) => {
          const engineLimit = limits[index];
          const searchFn = engineMap[engine as SupportedEngine];
  
          if (!searchFn) {
              console.warn(`Unsupported search engine: ${engine}`);
              return Promise.resolve([]);
          }
  
          return searchFn(query, engineLimit).catch(error => {
              console.error(`Search failed for engine ${engine}:`, error);
              return [];
          });
      });
  
      try {
          const results = await Promise.all(searchTasks);
          return results.flat().slice(0, limit);
      } catch (error) {
          console.error('Search execution failed:', error);
          throw error;
      }
  };

• src/tools/setupTools.ts:24-33 (helper)

  Mapping of supported search engines to their respective search functions imported from engines directories.

  const engineMap: Record<SupportedEngine, (query: string, limit: number) => Promise<SearchResult[]>> = {
      baidu: searchBaidu,
      bing: searchBing,
      linuxdo: searchLinuxDo,
      csdn: searchCsdn,
      duckduckgo: searchDuckDuckGo,
      exa: searchExa,
      brave: searchBrave,
      juejin: searchJuejin,
  };

• src/index.ts:20-21 (registration)

  Calls setupTools on the MCP server instance, which registers all tools including 'search'.

  // Set up server tools
  setupTools(server);