Serpex MCP

Instructions

Implementation Reference

• src/index.ts:149-197 (handler)

  The primary handler function that executes the serpex_search tool logic. It constructs the API request to Serpex, fetches search results, formats them into JSON, and returns as MCP tool content. Handles errors gracefully.

  private async handleSearch(params: SearchParams) {
    try {
      if (!params.q || params.q.trim().length === 0) {
        throw new Error('Query is required');
      }
  
      const response = await this.axiosInstance.get<SerpexResponse>('/api/search', {
        params: {
          q: params.q,
          engine: params.engine || 'auto',
          category: 'web',
          time_range: params.time_range || 'all',
          format: 'json',
        },
      });
  
      const data = response.data;
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              query: data.query,
              engines: data.engines,
              total_results: data.metadata.number_of_results,
              results: data.results.map(r => ({
                title: r.title,
                url: r.url,
                snippet: r.snippet,
                position: r.position,
                engine: r.engine,
              })),
              suggestions: data.suggestions,
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        const msg = error.response?.data?.error || error.message;
        return {
          content: [{ type: 'text', text: `Search failed: ${msg}` }],
          isError: true,
        };
      }
      throw error;
    }
  }

• src/index.ts:90-113 (registration)

  Registration of the serpex_search tool in the ListTools handler, including name, description, and input schema.

      name: 'serpex_search',
      description: 'Search the web using Serpex API. Returns structured search results from multiple engines (Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex).',
      inputSchema: {
        type: 'object',
        properties: {
          q: {
            type: 'string',
            description: 'Search query (max 500 characters)',
          },
          engine: {
            type: 'string',
            description: 'Search engine (default: auto)',
            enum: ['auto', 'google', 'bing', 'duckduckgo', 'brave', 'yahoo', 'yandex'],
          },
          time_range: {
            type: 'string',
            description: 'Filter by time range',
            enum: ['all', 'day', 'week', 'month', 'year'],
          },
        },
        required: ['q'],
      },
    },
  ],

• src/index.ts:92-111 (schema)

  Input schema definition for the serpex_search tool, specifying parameters q (required), engine, and time_range.

  inputSchema: {
    type: 'object',
    properties: {
      q: {
        type: 'string',
        description: 'Search query (max 500 characters)',
      },
      engine: {
        type: 'string',
        description: 'Search engine (default: auto)',
        enum: ['auto', 'google', 'bing', 'duckduckgo', 'brave', 'yahoo', 'yandex'],
      },
      time_range: {
        type: 'string',
        description: 'Filter by time range',
        enum: ['all', 'day', 'week', 'month', 'year'],
      },
    },
    required: ['q'],
  },

• src/index.ts:116-147 (registration)

  Dispatch logic in the CallToolRequestSchema handler that validates arguments for serpex_search and invokes the handleSearch function.

    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      if (request.params.name !== 'serpex_search') {
        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
      }
  
      if (!request.params.arguments) {
        throw new McpError(ErrorCode.InvalidParams, 'Arguments are required');
      }
  
      const args = request.params.arguments as Record<string, unknown>;
      
      // Validate required parameter
      if (!args.q || typeof args.q !== 'string') {
        throw new McpError(ErrorCode.InvalidParams, 'Query parameter "q" is required and must be a string');
      }
  
      // Build typed params
      const searchParams: SearchParams = {
        q: args.q as string,
      };
  
      if (args.engine && typeof args.engine === 'string') {
        searchParams.engine = args.engine as SearchParams['engine'];
      }
  
      if (args.time_range && typeof args.time_range === 'string') {
        searchParams.time_range = args.time_range as SearchParams['time_range'];
      }
  
      return await this.handleSearch(searchParams);
    });
  }

• src/index.ts:17-49 (helper)

  TypeScript interfaces defining the structure for search parameters, results, metadata, and Serpex API response, used for type safety in the handler.

  interface SearchParams {
    q: string;
    engine?: 'auto' | 'google' | 'bing' | 'duckduckgo' | 'brave' | 'yahoo' | 'yandex';
    category?: 'web';
    time_range?: 'all' | 'day' | 'week' | 'month' | 'year';
    format?: 'json';
  }
  
  interface SearchResult {
    title: string;
    url: string;
    snippet: string;
    position: number;
    engine: string;
    published_date: string | null;
  }
  
  interface SearchMetadata {
    number_of_results: number;
    response_time: number;
    timestamp: string;
    credits_used: number;
  }
  
  interface SerpexResponse {
    metadata: SearchMetadata;
    id: string;
    query: string;
    engines: string[];
    results: SearchResult[];
    answers: any[];
    suggestions: string[];
  }