Quran.com API

Servidor MCP para Quran.com API

Servidor MCP para interagir com o corpus do Quran.com via a REST API v4 oficial.

Visão Geral

Este é um servidor Model Context Protocol (MCP) gerado a partir da OpenAPI specification.

Endpoints

Os seguintes endpoints da API foram disponibilizados como ferramentas, que LLMs podem usar via clientes compatíveis.

Capítulos

• GET /chapters - Listar Capítulos
• GET /chapters/{id} - Obter Capítulo
• GET /chapters/{chapter_id}/info - Obter Informações do Capítulo

Versículos

• GET /verses/by_chapter/{chapter_number} - Obter versículos por número de Capítulo / Surah
• GET /verses/by_page/{page_number} - Obter todos os versículos de uma página específica do Madani Mushaf
• GET /verses/by_juz/{juz_number} - Obter versículos por número de Juz
• GET /verses/by_hizb/{hizb_number} - Obter versículos por número de Hizb
• GET /verses/by_rub/{rub_el_hizb_number} - Obter versículos por número de Rub el Hizb
• GET /verses/by_key/{verse_key} - Obter versículo por chave
• GET /verses/random - Obter um versículo aleatório

Juzs

• GET /juzs - Obter lista de todos os juzs

Pesquisa

• GET /search - Pesquisar o Alcorão por termos específicos

Traduções

• GET /resources/translations - Obter lista de traduções disponíveis
• GET /resources/translations/{translation_id}/info - Obter informações de uma tradução específica

Tafsirs

• GET /resources/tafsirs - Obter lista de tafsirs disponíveis
• GET /resources/tafsirs/{tafsir_id}/info - Obter as informações de um tafsir específico
• GET /quran/tafsirs/{tafsir_id} - Obter um único tafsir

Áudio

• GET /resources/chapter_reciters - Lista de Recitadores de Capítulo
• GET /resources/recitation_styles - Obter os estilos de recitação disponíveis

Idiomas

• GET /resources/languages - Obter todos os idiomas

Configuração

Requisitos

• Node.js 22+
• Docker

Construindo a Imagem Docker

Antes de usar o modo de produção baseado em Docker, você precisa construir a imagem Docker:

# Build the Docker image
docker build -t quran-mcp-server .

Integração com Claude Desktop

Para usar este servidor MCP com o Claude Desktop, adicione a seguinte configuração ao seu arquivo claude_desktop_config.json (normalmente localizado em ~/Library/Application Support/Claude/claude_desktop_config.json no macOS ou %APPDATA%\Claude\claude_desktop_config.json no Windows):

Modo de Produção baseado em Docker

{
  "mcpServers": {
    "quran-api": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "API_KEY=your_api_key_if_needed", "-e", "VERBOSE_MODE=true", "quran-mcp-server"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Modo de Produção (Node.js)

{
  "mcpServers": {
    "quran-api": {
      "command": "node",
      "args": ["/path/to/quran-mcp-server/dist/src/server.js"],
      "env": {
        "API_KEY": "your_api_key_if_needed",
        "VERBOSE_MODE": "true" // Set to "true" to enable verbose logging
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Modo de Desenvolvimento

{
  "mcpServers": {
    "quran-api": {
      "command": "npx",
      "args": ["ts-node", "/path/to/quran-mcp-server/src/server.ts"],
      "env": {
        "API_KEY": "your_api_key_if_needed",
        "VERBOSE_MODE": "true" // Set to "true" to enable verbose logging
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Notas Importantes:

• Substitua /path/to/quran-mcp-server pelo caminho real deste repositório no seu sistema
• Você precisará construir o projeto primeiro com npm run build ou docker build -t quran-mcp-server . se estiver usando a configuração do modo de produção
• Substitua your_api_key_if_needed por uma chave de API real se exigido pela API do Quran.com
• Se você já tem outros servidores MCP configurados, adicione esta configuração ao objeto mcpServers existente
• Após atualizar a configuração, reinicie o Claude Desktop para que as alterações tenham efeito

Variáveis de Ambiente

• API_KEY: chave de API para autenticação
• PORT: porta do servidor (padrão: 8000 ou 3000 dependendo da linguagem)
• VERBOSE_MODE: Defina como 'true' para habilitar o registro detalhado de solicitações e respostas da API (padrão: false)

Modo Detalhado (Verbose)

Quando VERBOSE_MODE estiver definido como 'true', o servidor registrará informações detalhadas sobre solicitações e respostas da API no console. Isso é útil para depuração e monitoramento das interações com a API.

O registro detalhado inclui:

• Solicitações: Registra o nome da ferramenta e os argumentos para cada solicitação recebida
• Respostas: Registra o nome da ferramenta e os dados de resultado para cada resposta
• Erros: Registra informações detalhadas de erro, incluindo nome do erro, mensagem e rastreamento de pilha quando disponível

Cada entrada de registro é carimbada com data/hora e prefixada com o tipo de registro (REQUEST, RESPONSE ou ERROR) para fácil identificação.

Testes

# Run tests
npm test

Licença

Este projeto é licenciado sob a Licença MIT.