search
Find specific terms in the Quran by entering a search query, adjusting results per page, and selecting a language. Use pagination to navigate through results efficiently.
Instructions
Search the Quran for specific terms
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | ISO code of language, use this query params if you want to boost translations for specific language. | |
| page | No | Page number, well for pagination. You can use *p* as well | |
| q | Yes | Search query, you can use *query* as well | |
| size | No | Results per page. *s* is also valid parameter. |
Implementation Reference
- src/handlers/search.ts:13-58 (handler)Handler function for the 'search' tool. Validates input args using searchSchema, calls searchService.search(), logs verbose info, formats response as MCP content block, and handles Zod/validation errors.export async function handleSearch(args: any) { try { // Validate arguments const validatedArgs = searchSchema.parse(args); // Call the service const result = await searchService.search(validatedArgs); // Log the response in verbose mode verboseLog('response', { tool: 'search', result }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) } ] }; } catch (error) { verboseLog('error', { tool: 'search', error: error instanceof Error ? error.message : String(error) }); if (error instanceof z.ZodError) { return { content: [{ type: "text", text: `Validation error: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}` }], isError: true, }; } return { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }], isError: true, }; }
- src/schemas/search.ts:10-15 (schema)Zod input schema for the search tool defining parameters: q (string, required), size/page/language (optional strings).export const searchSchema = z.object({ q: z.string().describe("Search query, you can use *query* as well"), size: z.string().optional().describe("Results per page. *s* is also valid parameter."), page: z.string().optional().describe("Page number, well for pagination. You can use *p* as well"), language: z.string().optional().describe("ISO code of language, use this query params if you want to boost translations for specific language."), });
- src/server.ts:185-189 (registration)Tool registration in listTools handler: defines 'search' tool name (ApiTools.search), description, inputSchema from searchSchemas.search, and examples.name: ApiTools.search, description: "Search the Quran for specific terms", inputSchema: zodToJsonSchema(searchSchemas.search), examples: toolExamples['search'], },
- src/server.ts:285-286 (registration)Tool dispatch registration in callTool handler: switch case for 'search' that invokes handleSearch with arguments.case ApiTools.search: return await handleSearch(request.params.arguments);
- src/services/search-service.ts:24-57 (helper)Core search logic in SearchService.search(): validates params, constructs API URL, calls makeApiRequest to Quran.com /search endpoint with query params, returns formatted SearchResponse. Handles errors.async search(params: z.infer<typeof searchSchema>): Promise<SearchResponse> { try { // Validate parameters const validatedParams = searchSchema.parse(params); const url = `${API_BASE_URL}/search`; // Make request to Quran.com API const data = await makeApiRequest(url, { q: validatedParams.q, size: validatedParams.size, page: validatedParams.page, language: validatedParams.language }); return { success: true, message: "search executed successfully", data }; } catch (error) { verboseLog('error', { method: 'search', error: error instanceof Error ? error.message : String(error) }); if (error instanceof z.ZodError) { throw new ApiError(`Validation error: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`, 400); } // Re-throw other errors throw error; } }