Muslim Prayer Reminder MCP

MCP gratuito y de código abierto para horarios de oración, con métodos de cálculo regionales, cuenta regresiva para la próxima oración y divulgación explícita del método de cálculo.

GitHub

Servidor MCP alojado

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

Se instala en Claude Code, Codex, Cursor y más

Documentación

🕌 Muslim Prayer Reminder MCP

Motor de cálculo astronómico de oraciones y notificaciones proactivas listo para producción en Cloudflare Workers para modelos de IA, agentes de codificación y entornos de desarrollo.

Documentación • Demo en vivo (1080p) • Demo de YouTube (48s) • Inicio rápido • Catálogo de herramientas • Rigor teológico • Política de seguridad

Estado del proyecto: 🟢 Mantenido activamente (v1.1.3) Publicado por: Smart Creations (Organización OpenAI: org-deULP4GGInsTcWmuaHWp3lxy) • Mantenedor principal: Tareq Naji
Compatible con Cloudflare Workers, Node.js 22/24 (Ubuntu y Windows) y todos los clientes del Model Context Protocol (MCP).

⚡ Inicio rápido

1. Ejecutar vía NPX (instalación cero)

Añade a tu configuración MCP de Claude Desktop o Cursor:

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

2. Conectar vía HTTP remoto por streaming (Cloudflare Workers)

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

3. Instalación en 1 clic en Cursor

Panel de análisis

/analytics es un panel privado respaldado por un SQLite Durable Object (AnalyticsDO). Realiza un seguimiento de usuarios activos (DAU, WAU, MAU), usuarios nuevos frente a recurrentes, retención, cohortes semanales, uso y estado de herramientas, errores, combinación de clientes, países, idiomas, uso por hora local y la autoridad de cálculo utilizada.

Protégelo: establece un secreto de Worker llamado ANALYTICS_TOKEN (panel de Cloudflare, Worker, Configuración, Variables y secretos). Abre /analytics e introduce cualquier nombre de usuario con el token como contraseña. /api/analytics también acepta Authorization: Bearer <token>.
Modelo de datos: una fila por llamada, clave por un hash con sal del _meta["openai/subject"] de OpenAI. Las llamadas se escriben de forma atómica, por lo que los recuentos no se desvían bajo tráfico concurrente.
Segmento verificado: limita cada gráfico a solicitudes de las IP de salida publicadas de OpenAI, lo que filtra tus propias llamadas de prueba. Actualiza la lista incluida con node scripts/update-openai-egress.mjs.
Límites: las instalaciones que nunca llaman a una herramienta y los usuarios cuyo host no envía ID de sujeto no pueden contarse.

📺 Demostración en vídeo en vivo

Observa Muslim Prayer Reminder MCP en acción dentro de ChatGPT, Claude y Cursor:

👉 Haz clic aquí para ver el vídeo de demostración completo en 1080p (MP4)

🏛️ Arquitectura del 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 y recursos MCP

Además de las cinco herramientas de cálculo y preferencias, los clientes MCP compatibles pueden usar dos funciones de aprendizaje de solo lectura nativas del protocolo:

Prompt: check_prayer_times_with_disclosure guía a un cliente para obtener horarios de oración reales usando la herramienta, solicitar la ubicación faltante y explicar la autoridad de cálculo, el motivo de la selección y los ajustes de alta latitud.
Recurso: prayer://calculation-guide proporciona una guía breve sobre los requisitos de ubicación, las convenciones de Asr, los métodos de crepúsculo y las diferencias con los horarios de las mezquitas locales.

Estas funciones no adivinan horarios de oración, no leen preferencias privadas ni reemplazan las herramientas de cálculo. Están disponibles a través del endpoint MCP alojado actual. Las versiones npm locales más antiguas pueden no proporcionar el nuevo prompt y recurso hasta que se actualicen.

🛠️ Catálogo de herramientas MCP

El servidor expone 5 herramientas finamente ajustadas que cumplen con el último estándar del Model Context Protocol con contratos de salida Zod completos:

Nombre de la herramienta	Modo de operación	Mundo abierto	Descripción
`get_prayer_status`	Escritura de estado temporal	Seguro	Comprueba si una oración obligatoria está actualmente pendiente. Devuelve la oración activa, la cuenta regresiva, la autoridad de cálculo y la justificación de selección.
`get_today_prayer_times`	Solo lectura	Seguro	Calcula el horario completo de hoy (Fajr, Amanecer, Dhuhr, Asr, Maghrib, Isha) en formato UTC y cadena localizada.
`get_next_prayer`	Solo lectura	Seguro	Devuelve la próxima oración inmediata, la marca de tiempo programada exacta, los minutos de cuenta regresiva y la autoridad regional.
`configure_prayer_preferences`	Sobrescribe la configuración guardada (`destructiveHint: true`)	Seguro	Actualiza las preferencias proporcionadas; cambiar la ubicación fija puede borrar la ubicación y la zona horaria anteriores. Los valores anteriores no se conservan para deshacer.
`get_prayer_preferences`	Solo lectura	Seguro	Lee la configuración de preferencias públicas guardadas.

📐 Rigor astronómico y teológico

Los cálculos de oración utilizan modelos astronómicos y métodos regionales configurados; los sustitutos de alta latitud y las heurísticas geográficas se divulgan:

Autoridad soberana	Jurisdicción	Ángulo de Fajr	Ángulo / intervalo de Isha	Madhab de Asr predeterminado
Universidad Umm al-Qura	Arabia Saudita	18.5°	+90 min	Shafi / Estándar
Levantamiento General de Egipto	Egipto, Palestina, Levante	19.5°	17.5°	Shafi (se aplican los desplazamientos de servicios palestinos configurados)
Diyanet İşleri Başkanlığı	Turquía, Balcanes, Asia Central	18.0°	17.0°	Hanafi (relación de doble sombra)
Univ. de Ciencias Islámicas, Karachi	Pakistán, India, Bangladés	18.0°	18.0°	Hanafi (relación de doble sombra)
ISNA	Estados Unidos, Canadá	15.0°	15.0°	Shafi / Estándar
Liga Mundial Musulmana (MWL)	Europa, respaldo global	18.0°	17.0°	Shafi / Estándar
Método de Singapur configurado	Malasia, Singapur, Indonesia	20.0°	18.0°	Shafi / Estándar

Ajustes polares de alta latitud

En latitudes superiores a 48° Norte o Sur donde el crepúsculo persiste durante toda la noche en verano, el motor activa automáticamente la limitación conforme al fiqh (Medio de la noche y Regla de un séptimo), evitando errores computacionales u horarios imposibles.

🔌 Instalación y configuración multiagente

Conecta Muslim Prayer Reminder a cualquier entorno de agente de IA, IDE de desarrollo o tiempo de ejecución de contenedor:

Descripción general de 1 clic y matriz

Entorno / Entorno de ejecución	Modo de protocolo	Comando rápido / Enlace profundo
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 de Copilot	`copilot plugin marketplace add tareq7/muslim-prayer-mcp`
Claude Desktop	CLI Stdio	`npx -y muslim-prayer-mcp` vía `claude_desktop_config.json`
VS Code y Cline	NPX local	`npx -y muslim-prayer-mcp` vía `.vscode/mcp.json`
Windsurf y Devin	HTTP remoto	URL remota a `mcp_config.json`
Gemini CLI	Extensión nativa	`gemini mcp add --transport http muslim-prayer https://muslim-prayer-mcp.najetareqz.workers.dev/mcp`
Entorno de agente Pi	Extensión Git	`pi install git:github.com/tareq7/muslim-prayer-mcp`
OpenCode	Plugin de agente	Carga automática vía `opencode.json` y `AGENTS.md`
Contenedor Docker	Contenedor	`docker build -t muslim-prayer-mcp .` luego `docker run --rm -i muslim-prayer-mcp` (stdio)

Claude Code

Ejecuta dentro de tu sesión de Claude Code:

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

(Nota: envía como dos prompts separados). En la aplicación de escritorio Claude Code, haz clic en el botón + junto al cuadro de prompt ➔ Plugins ➔ Añadir plugin para explorar e instalar desde el mercado.

Codex

Ejecuta en tu terminal:

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

Ejecuta codex y abre /hooks (o inicia un nuevo hilo). Esto también activa el plugin en la aplicación de escritorio Codex al reiniciar.

GitHub Copilot CLI

En tu terminal:

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

O dentro de una sesión interactiva de Copilot CLI:

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

Cursor IDE

Haz clic para instalar con un solo clic:

O añade manualmente a .cursor/mcp.json:

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

Claude Desktop

Añade a tu claude_desktop_config.json:

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

VS Code y Cline

Añade esto a .vscode/mcp.json usando el formato servers de VS Code:

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

La configuración de Cline usa el formato mcpServers que se muestra en Inicio rápido.

Windsurf y Devin

Añade a mcp_config.json:

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

Gemini CLI

Conéctate directamente usando el endpoint de borde en vivo:

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

Entorno de agente Pi

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

OpenCode

Añade a tu opencode.json:

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

OpenCode carga automáticamente el AGENTS.md y el skills/muslim-prayer-mcp/SKILL.md de este repositorio.

Contenedor Docker

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

💻 Middleware de host determinista

Para plataformas que construyen agentes de IA autónomos (Next.js, LangChain, Vercel AI SDK), el middleware incluido añade de forma determinista avisos de oración a las respuestas de IA sin alucinaciones:

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.

🧪 Suite de pruebas integral

El motor incluye 44 pruebas unitarias, de integración y de extremo a extremo que validan la precisión astronómica en 10 coordenadas de referencia en todo el mundo:

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 seguridad y privacidad

Truncamiento de coordenadas: Todas las coordenadas de usuario se truncan a 2 decimales al llegar (~resolución de 1.1 km). La ubicación precisa es matemáticamente irrecuperable.
Sin seguimiento saliente: El cálculo astronómico se realiza localmente dentro del tiempo de ejecución V8 aislado; se realizan cero solicitudes externas a API de seguimiento de terceros.
Arquitectura de apertura ante fallos: El middleware de host está diseñado para abrirse ante fallos; los problemas de red o los picos de latencia nunca bloquearán los flujos de conversación principales de IA.
Proceso de divulgación completa: Consulta SECURITY.md para conocer las versiones compatibles, el SLA y la notificación privada.

📄 Gobernanza, propiedad y comunidad

Editor y organización: Smart Creations (ID de organización OpenAI: org-deULP4GGInsTcWmuaHWp3lxy)
Mantenedor principal y autor: Tareq Naji (@tareq7)
Citación: CITATION.cff
Mantenedores: MAINTAINERS.md
Gobernanza: GOVERNANCE.md
Hoja de ruta del producto: ROADMAP.md
Directrices para agentes: AGENTS.md
Contribuciones: CONTRIBUTING.md
Código de conducta: CODE_OF_CONDUCT.md
Debates: Debates de GitHub

Hecho con precisión para la comunidad global de desarrolladores musulmanes.

Divulgaciones de ubicación y cálculo verificadas (v1.1.0)

Las herramientas de oración aceptan un city compatible, coordenadas con timezone o configuración fija completa almacenada. La ubicación faltante devuelve location_required; no se utilizan geolocalización por conector/IP ni respaldo automático de Makkah. Las entradas explícitas por llamada anulan las preferencias fijas. Los encabezados de host deben representar al usuario final. highLatitudeAdjustment revela sustituciones de crepúsculo y limitación polar; effectiveLatitude está presente solo para el sustituto de +/-48 grados y nunca refleja la coordenada original. calculationDetails informa la base de ubicación y los desplazamientos regionales, de usuario y de método. Los desplazamientos no válidos que invierten las ventanas de oración devuelven invalid_calculation. Las preferencias exponen fixedCoordinatesConfigured y fixedCityConfigured mientras redactan coordenadas.

La analítica es seudónima y aproximada: depósitos diarios de 60 días, hashes de sujetos de 90 días, sesiones de 7 días, contadores agregados sin caducidad. Los conteos no son métricas globales atómicas de entrega. Ambos alias del panel respetan la autenticación de servicio configurada. Consulte la política de privacidad para conocer los límites completos de retención y confianza.

Contratos de preferencia y tiempo de visualización

Las coordenadas explícitas requieren timezone en la misma solicitud. Las zonas horarias de ubicación fija almacenadas nunca se heredan para nuevas coordenadas explícitas. calculationDetails.timezoneSource identifica entrada explícita, de ciudad, almacenada o de host; las zonas horarias de ciudad deben coincidir con la zona canónica de la ciudad o un alias IANA. Las zonas horarias de coordenadas se verifican contra una búsqueda aproximada sin conexión y celdas límite cercanas; los valores contradictorios devuelven location_timezone_mismatch con expectedTimezone. Proporcione ciudad o coordenadas, nunca ambas. La autoridad geográfica predeterminada sigue la búsqueda, no la zona horaria de visualización proporcionada.

El modo fijo requiere una ciudad compatible o coordenadas con zona horaria. Las nuevas coordenadas fijas requieren zona horaria en la misma solicitud de configuración. Las actualizaciones de configuración fallidas no guardan nada. Cambiar a auto_travel conserva la ubicación fija para reutilización; clearFixedLocation:true elimina ciudad, coordenadas y zona horaria, y vuelve al modo de viaje automático, conservando preferencias no relacionadas. La limpieza no puede acompañar a una ubicación/zona horaria de reemplazo ni a un modo fijo incompleto.

Para usuarios identificados, prayer_window y exact_window se emiten una vez por oración/fecha/modo; persistent se emite durante todo el período de oración. Los cambios de configuración regional y la alternancia de recordatorios no restablecen la deduplicación. Las llamadas anónimas no persisten la deduplicación. expiresAtUtc conserva su significado de período de oración; prayerWindowExpiresAtUtc nombra el mismo límite, y reminderWindowExpiresAtUtc describe la elegibilidad, limitada por el límite de oración en modo exacto. Estos campos aparecen cuando se emite un recordatorio. Las actualizaciones de KV entre regiones y la deduplicación siguen siendo de mejor esfuerzo.

El perfil regional palestino es una heurística de servicio configurada que utiliza el método egipcio con desplazamientos de Dhuhr -1 y Maghrib +3 minutos. Sus reglas amplias de coordenadas/zona horaria/país no establecen jurisdicción. La adopción exacta de estos parámetros por parte del ministerio palestino no se ha verificado desde una fuente primaria. Los usuarios pueden anular el método y los desplazamientos. Otras opciones regionales son valores predeterminados del servicio, no mandatos nacionales. Las descripciones de métodos siguen la documentación de Adhan.

El vocabulario de ciudades compatible y los alias se anuncian en cada esquema de entrada de ubicación y habilidad generada. El servicio registra solo cinco herramientas. Las herramientas duplicadas con sufijo o esquemas antiguos en un conector requieren actualizar su registro; no son operaciones de servidor separadas.

La validación de zona horaria utiliza @photostructure/tz-lookup 11.7.0 (datos geográficos compactos y aproximados). Se aceptan alias canónicos IANA; coincidir con desplazamientos UTC muestreados no es suficiente, porque las fechas de transición de DST pueden diferir. Cerca de los límites, las zonas de búsqueda adyacentes dentro de aproximadamente 0.05 grados se aceptan y se revelan como nearby_boundary. Esto no es una detección precisa de jurisdicción. Los polos matemáticos conservan una elección explícita de zona horaria civil; las celdas oceánicas requieren una zona náutica coincidente o una zona civil cercana. Las preferencias de ciudad fija nuevas y actualizadas almacenan la zona horaria canónica de la ciudad; los valores contradictorios proporcionados se rechazan. Los registros de ciudad heredados se presentan canónicamente sin reescribir otros datos en una lectura.

El llamador debe proporcionar la ciudad actual o coordenadas/zona horaria en modo auto_travel; no hay geolocalización IP automática. Las preferencias de método almacenadas permanecen activas durante el viaje. exact_window utiliza la duración guardada o, si no está configurada, el valor predeterminado del servicio de 20 minutos a menos que un operador lo anule. Omitir la duración conserva las preferencias existentes.