Quran MCP Server

Instructions

Implementation Reference

• src/tools/search.ts:260-404 (handler)

  The primary handler function implementing the search_hadith tool. Performs advanced fuzzy keyword search across specified Hadith collections using relevance scoring, Levenshtein distance for similarity, Arabic normalization, parallel API calls, and intelligent sampling for efficient results.
  export async function searchHadith( query: string, collections?: string[], maxResults: number = 20 ): Promise<HadithSearchResult[]> { if (!query || query.trim().length < 2) { throw new QuranMCPError( 'Search query must be at least 2 characters long', 'INVALID_SEARCH_QUERY' ); } // Validate collections const searchCollections = collections && collections.length > 0 ? collections : HADITH_COLLECTIONS.map(c => c.slug); for (const col of searchCollections) { if (!HADITH_COLLECTIONS.find(c => c.slug === col)) { throw new QuranMCPError( `Unknown collection: ${col}. Available: ${HADITH_COLLECTIONS.map(c => c.slug).join(', ')}`, 'INVALID_COLLECTION' ); } } const cacheKey = `search:hadith:${searchCollections.join(',')}:${query}:${maxResults}`; return searchCacheService.getOrSet(cacheKey, async () => { const results: HadithSearchResult[] = []; const keywords = query.toLowerCase().split(/\s+/).filter(k => k.length > 1); const isArabicQuery = isArabic(query); // AGGRESSIVE optimization: Much smaller sample size, more parallel requests const SAMPLE_SIZE = 50; // Reduced from 200 to 50 for speed const PARALLEL_REQUESTS = 10; // Increased from 5 to 10 for speed const MAX_COLLECTIONS = 2; // Only search first 2 collections by default // Limit collections for performance const limitedCollections = searchCollections.slice(0, MAX_COLLECTIONS); // Process all collections in parallel const collectionPromises = limitedCollections.map(async (collectionSlug) => { const collectionInfo = HADITH_COLLECTIONS.find(c => c.slug === collectionSlug); if (!collectionInfo) return []; const collectionResults: HadithSearchResult[] = []; const sampleSize = Math.min(SAMPLE_SIZE, collectionInfo.totalHadiths); const step = Math.max(1, Math.floor(collectionInfo.totalHadiths / sampleSize)); // Create array of hadith numbers to search const hadithNumbers: number[] = []; for (let i = 1; i <= collectionInfo.totalHadiths && hadithNumbers.length < sampleSize; i += step) { hadithNumbers.push(i); } // Process ALL hadiths in parallel batches for (let i = 0; i < hadithNumbers.length; i += PARALLEL_REQUESTS) { const batch = hadithNumbers.slice(i, i + PARALLEL_REQUESTS); const batchPromises = batch.map(async (hadithNum) => { try { // Fetch Arabic if query is Arabic, otherwise fetch English const lang = isArabicQuery ? 'ara' : 'eng'; const url = `${API_ENDPOINTS.HADITH}/${lang}-${collectionSlug}/${hadithNum}.json`; const data = await fetchJSON<any>(url); if (!data) return null; // Handle the actual API structure: { metadata: {...}, hadiths: [{text: "..."}] } let text = ''; let book = undefined; let chapter = undefined; if (data.hadiths && Array.isArray(data.hadiths) && data.hadiths.length > 0) { // Find the hadith with matching number const hadith = data.hadiths.find((h: any) => h.hadithnumber === hadithNum) || data.hadiths[0]; text = hadith.text || ''; book = hadith.reference?.book; chapter = data.metadata?.section?.[book]; } else { // Fallback to old structure text = data.text || data.hadith || ''; book = data.book; chapter = data.chapter || data.chapterName; } if (!text || text.trim().length === 0) return null; const { score, matchType } = calculateRelevance(text, keywords); if (score > 0) { return { hadithNumber: hadithNum, collection: collectionSlug, collectionName: collectionInfo.name, text, book, chapter, relevanceScore: score, matchType, }; } } catch { // Silently fail and continue } return null; }); const batchResults = await Promise.all(batchPromises); collectionResults.push(...batchResults.filter(r => r !== null) as HadithSearchResult[]); // Early exit if we have enough high-quality results for this collection if (collectionResults.filter(r => r.matchType === 'exact').length >= maxResults) { break; } } return collectionResults; }); // Wait for all collections to finish const allCollectionResults = await Promise.all(collectionPromises); results.push(...allCollectionResults.flat()); // 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 hadiths 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 hadiths.`); } return finalResults; });
• src/shared/tools-definition.ts:255-282 (schema)

  JSON Schema definition for the search_hadith tool input validation, including parameters query, collections (array of strings), and max_results.
  { name: 'search_hadith', description: 'Search Hadith collections by keywords or phrases. Find hadiths about specific topics without knowing exact hadith numbers. Search across all major collections (Bukhari, Muslim, Abu Dawud, Tirmidhi, Nasai, Ibn Majah) or specific ones. Perfect for queries like "prayer times", "charity", "manners", etc.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query - keywords or phrases to search for in hadiths. Minimum 2 characters.', }, collections: { type: 'array', description: 'Specific collections to search in (optional). If not specified, searches all collections. Options: bukhari, muslim, abudawud, tirmidhi, nasai, ibnmajah', items: { type: 'string', enum: ['bukhari', 'muslim', 'abudawud', 'tirmidhi', 'nasai', 'ibnmajah'], }, }, 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:129-132 (registration)

  Registration and dispatch logic in the shared tool executor. Handles tool calls for 'search_hadith' by extracting arguments and invoking the searchHadith handler.
  case 'search_hadith': { const { query, collections, max_results = 20 } = args; result = await searchHadith(query, collections, max_results); break;
• src/http-server.ts:115-119 (registration)

  MCP tools/list handler in HTTP server that returns the full tools list including search_hadith.
  function handleMcpToolsList(id: string | number | null): JsonRpcResponse { return createJsonRpcResponse(id, { tools: tools, }); }
• src/index.ts:38-40 (registration)

  MCP tools/list handler in stdio server that registers all tools including search_hadith.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools }; });