Muslim Prayer Reminder MCP

MCP gratuito e de código aberto para horários de oração, com métodos regionais de cálculo, contagens regressivas para a próxima oração e divulgação explícita do método de cálculo.

GitHub

Servidor MCP hospedado

npx add-mcp 'https://muslim-prayer-mcp.najetareqz.workers.dev/mcp'

Instala no Claude Code, Codex, Cursor e outros

Documentação

🕌 Muslim Prayer Reminder MCP

Mecanismo de cálculo astronômico de horários de oração e notificação proativa, pronto para produção, executado em Cloudflare Workers para modelos de IA, agentes de codificação e ambientes de desenvolvimento.

Documentação • Demonstração ao Vivo (1080p) • Demonstração no YouTube (48s) • Início Rápido • Catálogo de Ferramentas • Rigor Teológico • Política de Segurança

Status do Projeto: 🟢 Mantido Ativamente (v1.1.3) Publicado por: Smart Creations (Organização OpenAI: org-deULP4GGInsTcWmuaHWp3lxy) • Mantenedor Principal: Tareq Naji
Suportado em Cloudflare Workers, Node.js 22/24 (Ubuntu e Windows) e todos os clientes Model Context Protocol (MCP).

⚡ Início Rápido

1. Executar via NPX (Instalação Zero)

Adicione à sua configuração MCP do Claude Desktop ou Cursor:

{
  "mcpServers": {
    "muslim-prayer": {
      "command": "npx",
      "args": ["-y", "muslim-prayer-mcp"]
    }
  }
}

2. Conectar via HTTP Remoto Streamable (Cloudflare Workers)

{
  "mcpServers": {
    "muslim-prayer": {
      "url": "https://muslim-prayer-mcp.najetareqz.workers.dev/mcp"
    }
  }
}

3. Instalação com 1 Clique no Cursor

Painel de análise

/analytics é um painel privado apoiado por um SQLite Durable Object (AnalyticsDO). Ele rastreia usuários ativos (DAU, WAU, MAU), usuários novos versus recorrentes, retenção, coortes semanais, uso e saúde das ferramentas, erros, mix de clientes, países, idiomas, uso por hora local e a autoridade de cálculo utilizada.

Proteja-o: defina um segredo do Worker chamado ANALYTICS_TOKEN (painel do Cloudflare, Worker, Configurações, Variáveis e Segredos). Abra /analytics e insira qualquer nome de usuário com o token como senha. /api/analytics também aceita Authorization: Bearer <token>.
Modelo de dados: uma linha por chamada, identificada por um hash salgado do _meta["openai/subject"] da OpenAI. As chamadas são gravadas atomicamente, portanto as contagens não divergem sob tráfego concorrente.
Segmento verificado: limita cada gráfico a solicitações dos IPs de saída publicados pela OpenAI, o que filtra suas próprias chamadas de teste. Atualize a lista incluída com node scripts/update-openai-egress.mjs.
Limitações: instalações que nunca chamam uma ferramenta e usuários cujo host não envia ID de assunto não podem ser contados.

📺 Demonstração em Vídeo ao Vivo

Assista ao Muslim Prayer Reminder MCP em ação dentro do ChatGPT, Claude e Cursor:

👉 Clique aqui para assistir ao vídeo de demonstração completo em 1080p (MP4)

🏛️ Arquitetura do Sistema

flowchart TD
    subgraph ClientLayer ["AI Clients & Environments"]
        Cursor["Cursor IDE"]
        Claude["Claude Desktop / Web"]
        ChatGPT["ChatGPT Apps Directory"]
        Agent["Autonomous AI Agent"]
    end

    subgraph TransportLayer ["Model Context Protocol"]
        HTTP["Streamable HTTP /mcp"]
        Stdio["Stdio Transport CLI"]
    end

    subgraph ResolverLayer ["Layered Location Resolver"]
        Explicit["User coordinates + timezone or supported city"] --> Truncate["2-Decimal Sanitizer ~1.1km"]
        UserPref["Stored KV Preferences"] --> Resolver["Location Normalizer"]
        Headers["Verified end-user location headers"] --> Resolver
        Resolver --> Missing["No usable user location: location_required"]
        Truncate --> Resolver
    end

    GeoIP["Cloudflare network metadata"] --> Analytics["Operational analytics only"]

    subgraph EngineLayer ["In-Isolate Solar Calculation Engine"]
        Resolver --> Authority["Authority Selector"]
        Authority --> AdhanEngine["Astronomical Solar Solver"]
        AdhanEngine --> FiqhRules["Fiqh Clamping 48° & Madhab Calibration"]
        FiqhRules --> DueLogic["Prayer Window & Due Evaluator"]
    end

    subgraph OutputLayer ["Formatted Payloads & Disclosures"]
        DueLogic --> MCPResponse["JSON-RPC Structured Output"]
        MCPResponse --> DisclosureNotice["Mandatory Theological Notice"]
        DisclosureNotice --> Middleware["Deterministic Host Middleware"]
        Middleware --> FinalOutput["Appended AI Response: 🕌 It is time for Maghrib prayer"]
    end

    ClientLayer --> TransportLayer
    TransportLayer --> ResolverLayer

Prompts e Recursos MCP

Além das cinco ferramentas de cálculo e preferências, clientes MCP compatíveis podem usar dois recursos de aprendizado somente leitura, nativos do protocolo:

Prompt: check_prayer_times_with_disclosure orienta um cliente a obter horários reais de oração usando a ferramenta, solicitar localização ausente e explicar a autoridade de cálculo, o motivo da seleção e os ajustes para altas latitudes.
Recurso: prayer://calculation-guide fornece um guia curto sobre requisitos de localização, convenções de Asr, métodos de crepúsculo e diferenças em relação aos horários das mesquitas locais.

Esses recursos não adivinham horários de oração, leem preferências privadas ou substituem as ferramentas de cálculo. Eles estão disponíveis por meio do endpoint MCP hospedado atual. Versões npm locais mais antigas podem não fornecer o novo prompt e recurso até serem atualizadas.

🛠️ Catálogo de Ferramentas MCP

O servidor expõe 5 ferramentas finamente ajustadas em conformidade com o padrão mais recente do Model Context Protocol, com contratos de saída Zod completos:

Nome da Ferramenta	Modo de Operação	Mundo Aberto	Descrição
`get_prayer_status`	Gravação de estado temporário	Seguro	Verifica se uma oração obrigatória é devida no momento. Retorna a oração ativa, contagem regressiva, autoridade de cálculo e justificativa de seleção.
`get_today_prayer_times`	Somente leitura	Seguro	Calcula o cronograma completo de hoje (Fajr, Nascer do Sol, Dhuhr, Asr, Maghrib, Isha) em UTC e formato de string localizado.
`get_next_prayer`	Somente leitura	Seguro	Retorna a próxima oração imediata, carimbo de data/hora agendado exato, minutos de contagem regressiva e autoridade regional.
`configure_prayer_preferences`	Substitui configurações salvas (`destructiveHint: true`)	Seguro	Atualiza as preferências fornecidas; alternar para localização fixa pode limpar a localização e o fuso horário anteriores. Os valores anteriores não são retidos para desfazer.
`get_prayer_preferences`	Somente leitura	Seguro	Lê as configurações de preferência pública salvas.

📐 Rigor Astronômico e Teológico

Os cálculos de oração usam modelos astronômicos e métodos regionais configurados; substitutos de alta latitude e heurísticas geográficas são divulgados:

Autoridade Soberana	Jurisdição	Ângulo Fajr	Ângulo/Intervalo Isha	Madhab Asr Padrão
Universidade Umm al-Qura	Arábia Saudita	18,5°	+90 min	Shafi / Padrão
Levantamento Geral Egípcio	Egito, Palestina, Levante	19,5°	17,5°	Shafi (deslocamentos de serviço palestinos configurados aplicados)
Diyanet İşleri Başkanlığı	Turquia, Bálcãs, Ásia Central	18,0°	17,0°	Hanafi (proporção de sombra dupla)
Univ. de Ciências Islâmicas, Karachi	Paquistão, Índia, Bangladesh	18,0°	18,0°	Hanafi (proporção de sombra dupla)
ISNA	Estados Unidos, Canadá	15,0°	15,0°	Shafi / Padrão
Liga Mundial Muçulmana (MWL)	Europa, Fallback Global	18,0°	17,0°	Shafi / Padrão
Método de Singapura configurado	Malásia, Singapura, Indonésia	20,0°	18,0°	Shafi / Padrão

Ajustes Polares de Alta Latitude

Em latitudes acima de 48° Norte ou Sul, onde o crepúsculo persiste durante toda a noite no verão, o mecanismo engaja automaticamente a limitação compatível com fiqh (Meio da Noite e Regra do Sétimo), evitando erros computacionais ou cronogramas impossíveis.

🔌 Instalação e Configuração Multiagente

Conecte o Muslim Prayer Reminder a qualquer ambiente de agente de IA, IDE de desenvolvedor ou runtime de contêiner:

Visão Geral de 1 Clique e Matriz

Ambiente / Ambiente	Modo de Protocolo	Comando Rápido / Deeplink
Cursor IDE	HTTP Remoto
Claude Code	Plugin Nativo	`/plugin marketplace add tareq7/muslim-prayer-mcp`
Codex	Plugin Nativo	`codex plugin marketplace add tareq7/muslim-prayer-mcp`
GitHub Copilot CLI	Plugin Copilot	`copilot plugin marketplace add tareq7/muslim-prayer-mcp`
Claude Desktop	Stdio CLI	`npx -y muslim-prayer-mcp` via `claude_desktop_config.json`
VS Code e Cline	NPX Local	`npx -y muslim-prayer-mcp` via `.vscode/mcp.json`
Windsurf e Devin	HTTP Remoto	URL Remota para `mcp_config.json`
Gemini CLI	Extensão Nativa	`gemini mcp add --transport http muslim-prayer https://muslim-prayer-mcp.najetareqz.workers.dev/mcp`
Pi Agent Harness	Extensão Git	`pi install git:github.com/tareq7/muslim-prayer-mcp`
OpenCode	Plugin de Agente	Carregado automaticamente via `opencode.json` e `AGENTS.md`
Contêiner Docker	Contêiner	`docker build -t muslim-prayer-mcp .` depois `docker run --rm -i muslim-prayer-mcp` (stdio)

Claude Code

Execute dentro da sua sessão do Claude Code:

/plugin marketplace add tareq7/muslim-prayer-mcp
/plugin install muslim-prayer-mcp@muslim-prayer-mcp

(Nota: Envie como dois prompts separados). No aplicativo Claude Code Desktop, clique no botão + ao lado da caixa de prompt ➔ Plugins ➔ Adicionar plugin para navegar e instalar do marketplace.

Codex

Execute no seu terminal:

codex plugin marketplace add tareq7/muslim-prayer-mcp
codex plugin add muslim-prayer-mcp@muslim-prayer-mcp

Execute codex e abra /hooks (ou inicie um novo thread). Isso também ativa o plugin no aplicativo Codex Desktop após reiniciar.

GitHub Copilot CLI

No seu terminal:

copilot plugin marketplace add tareq7/muslim-prayer-mcp
copilot plugin install muslim-prayer-mcp@muslim-prayer-mcp

Ou dentro de uma sessão interativa do Copilot CLI:

/plugin marketplace add tareq7/muslim-prayer-mcp
/plugin install muslim-prayer-mcp@muslim-prayer-mcp

Cursor IDE

Clique para instalar com um clique:

Ou adicione manualmente ao .cursor/mcp.json:

{
  "mcpServers": {
    "muslim-prayer": {
      "url": "https://muslim-prayer-mcp.najetareqz.workers.dev/mcp"
    }
  }
}

Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "muslim-prayer": {
      "command": "npx",
      "args": ["-y", "muslim-prayer-mcp"]
    }
  }
}

VS Code e Cline

Adicione isso ao .vscode/mcp.json usando o formato servers do VS Code:

{
  "servers": {
    "muslim-prayer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "muslim-prayer-mcp"]
    }
  }
}

As configurações do Cline usam o formato mcpServers mostrado no Início Rápido.

Windsurf e Devin

Adicione ao mcp_config.json:

{
  "mcpServers": {
    "muslim-prayer": {
      "url": "https://muslim-prayer-mcp.najetareqz.workers.dev/mcp"
    }
  }
}

Gemini CLI

Conecte-se diretamente usando o endpoint de borda ao vivo:

gemini mcp add --transport http muslim-prayer https://muslim-prayer-mcp.najetareqz.workers.dev/mcp

Pi Agent Harness

pi install git:github.com/tareq7/muslim-prayer-mcp

OpenCode

Adicione ao seu opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "muslim-prayer": {
      "type": "remote",
      "url": "https://muslim-prayer-mcp.najetareqz.workers.dev/mcp"
    }
  }
}

O OpenCode carrega automaticamente o AGENTS.md e o skills/muslim-prayer-mcp/SKILL.md deste repositório.

Contêiner Docker

docker build -t muslim-prayer-mcp .
docker run --rm -i muslim-prayer-mcp

💻 Middleware de Host Determinístico

Para plataformas que constroem agentes de IA autônomos (Next.js, LangChain, Vercel AI SDK), o middleware incluído anexa deterministicamente avisos de oração às respostas de IA sem alucinação:

import { PrayerReminderMiddleware } from 'muslim-prayer-mcp/middleware';

const prayerMiddleware = new PrayerReminderMiddleware({
  workerBaseUrl: 'https://muslim-prayer-mcp.najetareqz.workers.dev',
  userId: 'user_session_42',
});

// Wrap any LLM completion
const rawLlmOutput = await callLlm('Can you review this pull request?');
const { responseText, reminderAppended } = await prayerMiddleware.processResponse(rawLlmOutput, {
  'X-User-Coordinates': '24.71, 46.68', // Riyadh
  'X-User-Timezone': 'Asia/Riyadh',
});

console.log(responseText);
// => The code looks solid, but let's optimize line 42...
//
// 🕌 It is time for Asr prayer.

🧪 Suíte de Testes Abrangente

O mecanismo inclui 44 testes de unidade, integração e ponta a ponta que validam a precisão astronômica em 10 coordenadas de referência mundiais:

npm test

▶ Astronomical Prayer Calculation Suite
  ✔ calculates valid prayer timetable for Riyadh in correct chronological sequence
  ✔ calculates valid prayer timetable for Makkah in correct chronological sequence
  ✔ calculates valid prayer timetable for Cairo in correct chronological sequence
  ✔ calculates valid prayer timetable for Dubai in correct chronological sequence
  ✔ calculates valid prayer timetable for London in correct chronological sequence
  ✔ calculates valid prayer timetable for Paris in correct chronological sequence
  ✔ calculates valid prayer timetable for New York in correct chronological sequence
  ✔ calculates valid prayer timetable for Jakarta in correct chronological sequence
  ✔ calculates valid prayer timetable for Karachi in correct chronological sequence
  ✔ calculates valid prayer timetable for Sydney (Southern Hem) in correct chronological sequence
  ✔ verifies Hanafi Asr is strictly later than Shafi Asr
  ✔ handles Daylight Saving Time (DST) transitions safely
  ✔ automatically resolves Palestinian Awqaf standard for Gaza
  ✔ handles high-latitude polar city with MiddleOfTheNight rule safely
...
ℹ tests 44 | pass 44 | fail 0

🔒 Política de Segurança e Privacidade

Truncamento de Coordenadas: Todas as coordenadas do usuário são truncadas para 2 casas decimais na chegada (~resolução de 1,1 km). A localização precisa é matematicamente irrecuperável.
Sem Rastreamento de Saída: A matemática astronômica é calculada localmente dentro do runtime V8 isolado; zero solicitações externas são feitas a APIs de rastreamento de terceiros.
Arquitetura Fail-Open: O middleware do host é projetado para falhar abertamente; problemas de rede ou picos de latência nunca bloquearão os fluxos primários de conversa de IA.
Processo de Divulgação Completa: Consulte SECURITY.md para versões suportadas, SLA e relatórios privados.

📄 Governança, Propriedade e Comunidade

Editora e Organização: Smart Creations (ID da Organização OpenAI: org-deULP4GGInsTcWmuaHWp3lxy)
Mantenedor Principal e Autor: Tareq Naji (@tareq7)
Citação: CITATION.cff
Mantenedores: MAINTAINERS.md
Governança: GOVERNANCE.md
Roteiro do Produto: ROADMAP.md
Diretrizes do Agente: AGENTS.md
Contribuição: CONTRIBUTING.md
Código de Conduta: CODE_OF_CONDUCT.md
Discussões: Discussões do GitHub

Feito com precisão para a comunidade global de desenvolvedores muçulmanos.

Divulgações verificadas de localização e cálculo (v1.1.0)

As ferramentas de oração aceitam um city suportado, coordenadas com timezone ou configurações fixas completas armazenadas. Localização ausente retorna location_required; geolocalização por conector/IP e fallback automático de Makkah não são usados. Entradas explícitas por chamada substituem preferências fixas. Os cabeçalhos do host devem representar o usuário final. highLatitudeAdjustment divulga substituições de crepúsculo e fixação polar; effectiveLatitude está presente apenas para o substituto de +/-48 graus e nunca ecoa a coordenada original. calculationDetails relata a base de localização e deslocamentos regionais, do usuário e do método. Deslocamentos inválidos que invertem as janelas de oração retornam invalid_calculation. As preferências expõem fixedCoordinatesConfigured e fixedCityConfigured enquanto ocultam coordenadas.

A análise é pseudônima e aproximada: buckets diários de 60 dias, hashes de assunto por 90 dias, sessões por 7 dias, contadores agregados sem expiração. As contagens não são métricas globais atômicas de entrega. Ambos os aliases do painel honram a autenticação de serviço configurada. Consulte a política de privacidade para os limites completos de retenção e confiança.

Contratos de preferência e tempo de exibição

Coordenadas explícitas exigem timezone na mesma solicitação. Fusos horários de localização fixa armazenados nunca são herdados para novas coordenadas explícitas. calculationDetails.timezoneSource identifica entrada explícita, de cidade, armazenada ou de host; fusos horários de cidade devem corresponder ao fuso canônico da cidade ou a um alias IANA. Fusos horários de coordenadas são verificados contra uma consulta offline aproximada e células de fronteira próximas; valores contraditórios retornam location_timezone_mismatch com expectedTimezone. Forneça cidade ou coordenadas, nunca ambos. A autoridade geográfica padrão segue a consulta, não o fuso horário de exibição fornecido.

O modo fixo exige uma cidade suportada ou coordenadas com fuso horário. Novas coordenadas fixas exigem fuso horário na mesma solicitação de configuração. Atualizações de configuração com falha não salvam nada. Alternar para auto_travel preserva a localização fixa para reutilização; clearFixedLocation:true remove cidade, coordenadas e fuso horário e define como padrão viagem automática, preservando preferências não relacionadas. Limpar não pode acompanhar localização/fuso horário de substituição ou modo fixo incompleto.

Para usuários identificados, prayer_window e exact_window emitem uma vez por oração/data/modo; persistent emite durante todo o período de oração. Mudanças de localidade e alternância de lembretes não redefinem a deduplicação. Chamadas anônimas não persistem deduplicação. expiresAtUtc mantém seu significado de período de oração; prayerWindowExpiresAtUtc nomeia o mesmo limite, e reminderWindowExpiresAtUtc descreve elegibilidade, limitada pelo limite de oração no modo exato. Esses campos aparecem quando um lembrete é emitido. Atualizações de KV entre regiões e deduplicação permanecem como melhor esforço.

O perfil regional palestino é uma heurística de serviço configurada usando o método egípcio com deslocamentos de Dhuhr -1 e Maghrib +3 minutos. Suas regras amplas de coordenada/fuso horário/país não estabelecem jurisdição. A adoção exata desses parâmetros pelo ministério palestino não foi verificada a partir de uma fonte primária. Os usuários podem substituir método e deslocamentos. Outras escolhas regionais são padrões de serviço, não mandatos nacionais. As descrições de método seguem a documentação do Adhan.

O vocabulário de cidades suportadas e aliases é anunciado em cada esquema de entrada de localização e habilidade gerada. O serviço registra apenas cinco ferramentas. Ferramentas duplicadas com sufixo ou esquemas antigos em um conector exigem atualização de seu registro; elas não são operações separadas do servidor.

A validação de fuso horário usa @photostructure/tz-lookup 11.7.0 (dados geográficos compactos e aproximados). Aliases IANA canônicos são aceitos; correspondência de offsets UTC amostrados não é suficiente, porque as datas de transição de DST podem diferir. Perto de fronteiras, zonas de consulta adjacentes dentro de aproximadamente 0,05 graus são aceitas e divulgadas como nearby_boundary. Isso não é detecção precisa de jurisdição. Polos matemáticos mantêm uma escolha explícita de fuso horário civil; células oceânicas exigem uma zona náutica correspondente ou zona civil próxima. Preferências de cidade fixa novas e atualizadas armazenam o fuso horário canônico da cidade; valores contraditórios fornecidos são rejeitados. Registros de cidade legados são apresentados canonicamente sem reescrever outros dados em uma leitura.

O chamador deve fornecer cidade atual ou coordenadas/fuso horário no modo auto_travel; não há geolocalização automática por IP. Preferências de método armazenadas permanecem ativas durante viagens. exact_window usa a duração salva ou, quando não definida, o padrão de serviço de 20 minutos, a menos que um operador a substitua. Omitir a duração preserva as preferências existentes.