quran-mcp-server

Instructions

Implementation Reference

• src/handlers/resources.ts:31-63 (handler)

  Main handler for the 'translations' MCP tool: validates input with translationsSchema, invokes translationsService.listTranslations(validatedArgs), logs verbose response, returns formatted JSON content or standardized error.
  export async function handleTranslations(args: any) { try { // Validate arguments const validatedArgs = translationsSchema.parse(args); // Call the service const result = await translationsService.listTranslations(validatedArgs); // Log the response in verbose mode verboseLog('response', { tool: 'translations', result }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) } ] }; } catch (error) { verboseLog('error', { tool: 'translations', error: error instanceof Error ? error.message : String(error) }); // Use the standardized error response utility const { createErrorResponse } = require('../utils/error-handler'); return createErrorResponse(error, 'translations'); } }
• src/schemas/translations.ts:31-34 (schema)

  Zod input validation schema for the 'translations' tool, defining optional 'language' parameter.
  export const translationsSchema = z.object({ language: z.string().optional().describe("Language"), });
• src/server.ts:191-196 (registration)

  MCP tool registration for 'translations' in server.setRequestHandler(ListToolsRequestSchema): specifies name, description, inputSchema from aggregated schemas, and examples.
  { name: ApiTools.translations, description: "Get list of available translations", inputSchema: zodToJsonSchema(translationsSchemas.translations), examples: toolExamples['translations'], },
• src/services/translations-service.ts:38-127 (helper)

  Core business logic for listing translations: caches results, fetches from Quran.com API (/resources/translations), falls back to mock data on API errors or validation issues.
  async listTranslations(params: z.infer<typeof translationsSchema>): Promise<TranslationsResponse> { try { // Validate parameters const validatedParams = translationsSchema.parse(params); // Check cache first const now = Date.now(); if (this.translationsCache && (now - this.cacheTimestamp < CACHE_DURATION_MS)) { verboseLog('response', { method: 'listTranslations', source: 'cache', age: `${(now - this.cacheTimestamp) / 1000} seconds` }); return { success: true, message: "translations executed successfully (from cache)", data: this.translationsCache }; } try { // Make request to Quran.com API const url = `${API_BASE_URL}/resources/translations`; const response = await makeApiRequest(url, { language: validatedParams.language }); verboseLog('response', { method: 'listTranslations', source: 'api', dataSize: JSON.stringify(response).length }); // Update cache this.translationsCache = response; this.cacheTimestamp = now; return { success: true, message: "translations executed successfully", data: response }; } catch (axiosError) { verboseLog('error', { method: 'listTranslations', error: axiosError instanceof Error ? axiosError.message : String(axiosError) }); // If the API call fails, return mock data verboseLog('response', { method: 'listTranslations', source: 'mock', reason: 'API unavailable' }); const mockData = this.getTranslationsMockData(); return { success: true, message: "translations executed with mock data (API unavailable)", data: mockData }; } } catch (error) { verboseLog('error', { method: 'listTranslations', 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); } // Return mock data as a fallback for any error verboseLog('response', { method: 'listTranslations', source: 'mock', reason: 'error occurred' }); const mockData = this.getTranslationsMockData(); return { success: true, message: "translations executed with mock data (error occurred)", data: mockData }; } }
• src/server.ts:288-291 (registration)

  Dispatch handler in server.setRequestHandler(CallToolRequestSchema): routes 'translations' tool calls to handleTranslations function.
  // Translation-related tools case ApiTools.translations: return await handleTranslations(request.params.arguments); case ApiTools.translation_info: