quran-mcp-server

Instructions

Implementation Reference

• src/handlers/resources.ts:284-319 (handler)

  The main handler function for the 'languages' MCP tool. Validates input using languagesSchema, calls languagesService.listLanguages(), logs response/error, and formats output as MCP content.
  /** * Handler for the languages tool */ export async function handleLanguages(args: any) { try { // Validate arguments const validatedArgs = languagesSchema.parse(args); // Call the service const result = await languagesService.listLanguages(validatedArgs); // Log the response in verbose mode verboseLog('response', { tool: 'languages', result }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) } ] }; } catch (error) { verboseLog('error', { tool: 'languages', error: error instanceof Error ? error.message : String(error) }); // Use the standardized error response utility const { createErrorResponse } = require('../utils/error-handler'); return createErrorResponse(error, 'languages'); } }
• src/schemas/languages.ts:10-17 (schema)

  Zod schema for validating input arguments to the 'languages' tool (optional 'language' parameter).
  export const languagesSchema = z.object({ language: z.string().optional().describe("Language"), }); // Export all language-related schemas export default { languages: languagesSchema, };
• src/server.ts:232-236 (registration)

  Registration of the 'languages' tool in the MCP server's tools list, specifying name, description, input schema, and examples.
  name: ApiTools.languages, description: "Get all languages", inputSchema: zodToJsonSchema(languagesSchemas.languages), examples: toolExamples['languages'], },
• src/server.ts:309-310 (registration)

  Dispatch/registration in the tool call switch statement: calls handleLanguages for ApiTools.languages.
  case ApiTools.languages: return await handleLanguages(request.params.arguments);
• src/services/languages-service.ts:30-119 (helper)

  Core service logic for listing languages: checks cache, makes API request to Quran.com /resources/languages, falls back to mock data on error.
  async listLanguages(params: z.infer<typeof languagesSchema>): Promise<LanguagesResponse> { try { // Validate parameters const validatedParams = languagesSchema.parse(params); // Check cache first const now = Date.now(); if (this.languagesCache && (now - this.cacheTimestamp < CACHE_DURATION_MS)) { verboseLog('response', { method: 'listLanguages', source: 'cache', age: `${(now - this.cacheTimestamp) / 1000} seconds` }); return { success: true, message: "languages executed successfully (from cache)", data: this.languagesCache }; } try { // Make request to Quran.com API const url = `${API_BASE_URL}/resources/languages`; const response = await makeApiRequest(url, { language: validatedParams.language }); verboseLog('response', { method: 'listLanguages', source: 'api', dataSize: JSON.stringify(response).length }); // Update cache this.languagesCache = response; this.cacheTimestamp = now; return { success: true, message: "languages executed successfully", data: response }; } catch (axiosError) { verboseLog('error', { method: 'listLanguages', error: axiosError instanceof Error ? axiosError.message : String(axiosError) }); // If the API call fails, return mock data verboseLog('response', { method: 'listLanguages', source: 'mock', reason: 'API unavailable' }); const mockData = this.getLanguagesMockData(); return { success: true, message: "languages executed with mock data (API unavailable)", data: mockData }; } } catch (error) { verboseLog('error', { method: 'listLanguages', 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: 'listLanguages', source: 'mock', reason: 'error occurred' }); const mockData = this.getLanguagesMockData(); return { success: true, message: "languages executed with mock data (error occurred)", data: mockData }; } }