Serpex MCP

Instructions

Implementation Reference

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

  Core handler function that executes the serpex_search tool logic: validates query, calls Serpex API, parses response, formats structured results (query, engines, results with title/url/snippet/position/engine, suggestions) as JSON text content for MCP, handles API errors.
  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:92-111 (schema)

  Input schema definition for serpex_search tool, specifying required 'q' query string, optional 'engine' enum, optional 'time_range' enum.
  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:90-112 (registration)

  Tool registration in tools/list response: defines name 'serpex_search', 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:116-147 (handler)

  Dispatch handler for MCP tools/call requests. Checks if tool is 'serpex_search', validates and parses arguments, constructs SearchParams, invokes handleSearch.
  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:85-86 (helper)

  Setup function that registers the tools/list handler (with serpex_search metadata) and tools/call dispatcher for the serpex_search tool.
  private setupToolHandlers() {