serpex_search
Search the web using multiple search engines through Serpex API. Get structured results from Google, Bing, DuckDuckGo, Brave, Yahoo, and Yandex with time filtering options.
Instructions
Search the web using Serpex API. Returns structured search results from multiple engines (Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query (max 500 characters) | |
| engine | No | Search engine (default: auto) | |
| time_range | No | Filter by time range |
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[]; }