Quran MCP Server

Instructions

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;
    });
  }

• src/shared/tools-definition.ts:230-254 (schema)

  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;
  }