OneSearch MCP Server

Instructions

Implementation Reference

• src/index.ts:91-137 (handler)

  Executes the one_search tool: validates input, invokes processSearch, formats search results into MCP content response.

        case 'one_search': {
          // check args.
          if (!checkSearchArgs(args)) {
            throw new Error(`Invalid arguments for tool: [${name}]`);
          }
          try {
            const { results, success } = await processSearch({
              ...args,
              apiKey: SEARCH_API_KEY ?? '',
              apiUrl: SEARCH_API_URL,
            });
            if (!success) {
              throw new Error('Failed to search');
            }
            const resultsText = results.map((result) => (
              `Title: ${result.title}
  URL: ${result.url}
  Description: ${result.snippet}
  ${result.markdown ? `Content: ${result.markdown}` : ''}`
            ));
            return {
              content: [
                {
                  type: 'text',
                  text: resultsText.join('\n\n'),
                },
              ],
              results,
              success,
            };
          } catch (error) {
            server.sendLoggingMessage({
              level: 'error',
              data: `[${new Date().toISOString()}] Error searching: ${error}`,
            });
            const msg = error instanceof Error ? error.message : 'Unknown error';
            return {
              success: false,
              content: [
                {
                  type: 'text',
                  text: msg,
                },
              ],
            };
          }
        }

• src/tools.ts:9-59 (schema)

  Tool schema defining name, description, and input validation for one_search.

  export const SEARCH_TOOL: Tool = {
    name: 'one_search',
    description:
      'Search and retrieve content from web pages. ' +
      'Returns SERP results by default (url, title, description).',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query string',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return (default: 10)',
        },
        language: {
          type: 'string',
          description: 'Language code for search results (default: auto)',
        },
        categories: {
          type: 'string',
          enum: [
            'general',
            'news',
            'images',
            'videos',
            'it',
            'science',
            'map',
            'music',
            'files',
            'social_media',
          ],
          description: 'Categories to search for (default: general)',
        },
        timeRange: {
          type: 'string',
          description: 'Time range for search results (default: all)',
          enum: [
            'all',
            'day',
            'week',
            'month',
            'year',
          ],
        },
      },
      required: ['query'],
    },
  };

• src/index.ts:66-73 (registration)

  Registers the one_search tool (as SEARCH_TOOL) for discovery via listTools.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      SEARCH_TOOL,
      EXTRACT_TOOL,
      SCRAPE_TOOL,
      MAP_TOOL,
    ],
  }));

• src/index.ts:240-294 (helper)

  Dispatches search requests to the configured provider (searxng, tavily, bing, duckduckgo, or local).

  async function processSearch(args: ISearchRequestOptions): Promise<ISearchResponse> {
    switch (SEARCH_PROVIDER) {
      case 'searxng': {
        // merge default config with args
        const params = {
          ...searchDefaultConfig,
          ...args,
          apiKey: SEARCH_API_KEY,
        };
  
        // but categories and language have higher priority (ENV > args).
        const { categories, language } = searchDefaultConfig;
  
        if (categories) {
          params.categories = categories;
        }
        if (language) {
          params.language = language;
        }
        return await searxngSearch(params);
      }
      case 'tavily': {
        return await tavilySearch({
          ...searchDefaultConfig,
          ...args,
          apiKey: SEARCH_API_KEY,
        });
      }
      case 'bing': {
        return await bingSearch({
          ...searchDefaultConfig,
          ...args,
          apiKey: SEARCH_API_KEY,
        });
      }
      case 'duckduckgo': {
        const safeSearch = args.safeSearch ?? 0;
        const safeSearchOptions = [SafeSearchType.STRICT, SafeSearchType.MODERATE, SafeSearchType.OFF];
        return await duckDuckGoSearch({
          ...searchDefaultConfig,
          ...args,
          apiKey: SEARCH_API_KEY,
          safeSearch: safeSearchOptions[safeSearch],
        });
      }
      case 'local': {
        return await localSearch({
          ...searchDefaultConfig,
          ...args,
        });
      }
      default:
        throw new Error(`Unsupported search provider: ${SEARCH_PROVIDER}`);
    }
  }