search_quran
Search Quran verses by keywords or phrases to find relevant passages about specific topics like patience, prayer, or mercy using natural language queries.
Instructions
Search the Quran by keywords or phrases. This powerful tool allows you to find verses containing specific words or concepts without knowing the exact surah and ayah numbers. Perfect for finding verses about specific topics like "patience", "prayer", "mercy", etc. The AI agent can use natural language queries to search through the entire Quran.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query - keywords or phrases to search for in the Quran. Can be single words like "patience" or phrases like "those who believe". Minimum 2 characters. | |
| translation | No | Translation to search in (default: en.sahih). Options: en.asad, en.sahih, en.pickthall, en.yusufali, en.hilali | en.sahih |
| max_results | No | Maximum number of results to return (default: 20, max: 50) |
Implementation Reference
- src/tools/search.ts:163-254 (handler)The core handler function that executes the search_quran tool. Performs intelligent fuzzy matching across all 114 Quran surahs in parallel, with relevance scoring, Arabic normalization, caching, and helpful suggestions.export async function searchQuran( query: string, translationSlug: string = 'en.sahih', maxResults: number = 20 ): Promise<SearchResult[]> { if (!query || query.trim().length < 2) { throw new QuranMCPError( 'Search query must be at least 2 characters long', 'INVALID_SEARCH_QUERY' ); } // Validate translation const translation = TRANSLATIONS.find(t => t.slug === translationSlug); if (!translation) { throw new QuranMCPError( `Unknown translation: ${translationSlug}. Available: ${TRANSLATIONS.map(t => t.slug).join(', ')}`, 'INVALID_TRANSLATION' ); } const cacheKey = `search:quran:${translationSlug}:${query}:${maxResults}`; return searchCacheService.getOrSet(cacheKey, async () => { const results: SearchResult[] = []; const keywords = query.toLowerCase().split(/\s+/).filter(k => k.length > 1); const isArabicQuery = isArabic(query); // OPTIMIZED: Fetch ALL surahs in parallel for maximum speed const fetchSlug = isArabicQuery ? 'ar.alafasy' : translationSlug; // Fetch all 114 surahs in parallel (Cloudflare Workers can handle this) const allPromises = SURAH_INFO.map(async (surahInfo) => { try { const url = `https://api.alquran.cloud/v1/surah/${surahInfo.number}/${fetchSlug}`; const response = await fetchJSON<any>(url); if (response.code === 200 && response.data && response.data.ayahs) { const surahResults: SearchResult[] = []; for (const ayah of response.data.ayahs) { const { score, matchType } = calculateRelevance(ayah.text, keywords); if (score > 0) { surahResults.push({ surah: surahInfo.number, ayah: ayah.numberInSurah, surahName: surahInfo.name, text: ayah.text, translation: isArabicQuery ? 'Arabic' : translation.name, relevanceScore: score, matchType, }); } } return surahResults; } } catch (error) { // Continue searching other surahs even if one fails console.error(`Error searching surah ${surahInfo.number}:`, error); } return []; }); // Wait for ALL requests to complete in parallel const allResults = await Promise.all(allPromises); // Flatten results for (const surahResults of allResults) { results.push(...surahResults); } // Sort by relevance and match type const sorted = results.sort((a, b) => { // Prioritize exact matches if (a.matchType === 'exact' && b.matchType !== 'exact') return -1; if (b.matchType === 'exact' && a.matchType !== 'exact') return 1; // Then by score return b.relevanceScore - a.relevanceScore; }); const finalResults = sorted.slice(0, maxResults); // Add helpful message if no results or only fuzzy matches if (finalResults.length === 0) { console.log(`No results found for "${query}". Try different keywords or check spelling.`); } else if (finalResults.every(r => r.matchType !== 'exact')) { console.log(`No exact matches for "${query}". Showing ${finalResults.length} similar results.`); } return finalResults; }); }
- The MCP tool definition including name, description, and input schema (JSON Schema) for validating search_quran parameters.{ name: 'search_quran', description: 'Search the Quran by keywords or phrases. This powerful tool allows you to find verses containing specific words or concepts without knowing the exact surah and ayah numbers. Perfect for finding verses about specific topics like "patience", "prayer", "mercy", etc. The AI agent can use natural language queries to search through the entire Quran.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query - keywords or phrases to search for in the Quran. Can be single words like "patience" or phrases like "those who believe". Minimum 2 characters.', }, translation: { type: 'string', description: 'Translation to search in (default: en.sahih). Options: en.asad, en.sahih, en.pickthall, en.yusufali, en.hilali', default: 'en.sahih', }, max_results: { type: 'number', description: 'Maximum number of results to return (default: 20, max: 50)', default: 20, maximum: 50, }, }, required: ['query'], }, },
- src/shared/tool-executor.ts:123-127 (registration)The switch case in the central tool executor that handles dispatching calls to the search_quran handler based on tool name.case 'search_quran': { const { query, translation = 'en.sahih', max_results = 20 } = args; result = await searchQuran(query, translation, max_results); break; }
- src/shared/tool-executor.ts:20-24 (registration)Import statement that brings the searchQuran handler into the tool executor scope.searchHadith, searchHadithByTopic, searchQuran, searchQuranByTopic } from '../tools/search.js';
- src/types/index.ts:138-142 (schema)TypeScript interface defining expected parameters for Quran search (related to schema).export interface SearchQuranParams { query: string; language?: 'arabic' | 'english'; translation?: string; }