muslim-prayer-mcp

Muslim Prayer Reminder System (Cloudflare Remote MCP + Hybrid Middleware)

Production-ready Muslim prayer reminder system running on Cloudflare Workers, exposing both a Streamable HTTP Model Context Protocol (MCP) server and an ultra-fast edge REST API with deterministic host middleware.

🕌 Architecture Overview

• Remote Cloudflare MCP Worker (src/index.ts):

  • Uses modern Web Standard Streamable HTTP transport (@modelcontextprotocol/sdk).
  • Backed by Cloudflare KV for user preference storage and deduplication sentinels.
  • Calculates prayer times in-isolate via adhan (<1ms astronomical solar computation).
  • Layered location resolver (explicit coordinates -> user preference -> host headers -> request.cf geolocation -> Makkah fallback).
  • High-latitude polar day/night handling (fiqh-compliant 48° clamping).

• Deterministic Host Middleware (src/middleware/host-connector.ts):

  • Bridges the protocol limitation: generic MCP tools cannot intercept arbitrary model prompts or force response appending.
  • Runs alongside the LLM call (<5ms latency overhead), and deterministically appends \n\n🕌 It is time for [Prayer] prayer. to the final answer whenever a prayer is due.
  • Fail-open: network timeouts or worker outages never disrupt the primary AI conversation.

🛠️ MCP Tools

Tool Name	Type	Mandatory LLM Disclosure	Description
get_prayer_status	Read-only	Required	Checks whether an obligatory prayer is currently due and returns active reminder details, calculation authority, and selection justification.
get_today_prayer_times	Read-only	Required	Returns today's full timetable (Fajr, Sunrise, Dhuhr, Asr, Maghrib, Isha) in UTC and formatted local time, including authorityNotice.
get_next_prayer	Read-only	Required	Returns the immediate next prayer name, scheduled time, authority description, selection reason, and remaining countdown in minutes.
configure_prayer_preferences	State mutation	Optional override	Sets user calculation method, madhab, reminder mode, location mode (fixed vs auto), and language in KV storage.
get_prayer_preferences	Read-only	N/A	Inspects active user calculation settings and preferences.

⚖️ Mandatory Authority Disclosure & Geographic Calibration

To guarantee transparency and eliminate sectarian or jurisdictional ambiguity, the server enforces a Mandatory Authority Disclosure Directive on all AI clients (Claude, ChatGPT, Cursor, Copilot, etc.):

• Automatic Geographic Calibration: When not explicitly overridden by user preferences, the calculation authority, madhab, and regional solar safety adjustments are automatically resolved based on the user's location:

  • Palestine / Gaza / West Bank: Officially resolved to Palestinian Ministry of Awqaf standard (Egyptian Survey Authority with { maghrib: +3 min, dhuhr: -1 min } safety offsets, producing 100% exact matches with local printed calendars).
  • Saudi Arabia: Officially resolved to Umm al-Qura University, Makkah.
  • United Arab Emirates: Officially resolved to Awqaf UAE (Dubai method).
  • Qatar & Kuwait: Officially resolved to respective state Awqaf ministries.
  • Turkey & Balkans: Officially resolved to Diyanet İşleri Başkanlığı with Hanafi Asr.
  • South Asia (PK/IN/BD/AF): Officially resolved to University of Islamic Sciences, Karachi with Hanafi Asr.
  • North America: Officially resolved to ISNA (15° twilight).
  • Southeast Asia (SG/MY/ID/BN): Officially resolved to MUIS / JAKIM / MABIMS standard.
  • Global / Europe: Officially resolved to Muslim World League (MWL).

• Strict LLM Enforcement:

  • Server Instructions: The MCP server passes initialization instructions commanding the AI model to state the calculation authority and selection reason in every user response.
  • Tool Schemas: Every query tool's description explicitly marks disclosure as mandatory.
  • Payload Verification (authorityNotice): Every response payload includes a dedicated authorityNotice object with requiredDisplayInstruction.
  • Dedicated Agent Skill: skills/muslim-prayer-mcp/SKILL.md provides ready-to-load instructions and formatting templates for LLMs.

🚀 Quick Start & Deployment

1. Run Automated Test Suite Locally

npm test

Executes 44 automated tests covering 10 benchmark cities, DST transitions, Hanafi/Shafi Asr differences, deduplication, JSON-RPC MCP conformance, and end-to-end middleware post-processing.

2. Deploy to Cloudflare Workers

# 1. Create Cloudflare KV namespace
npx wrangler kv:namespace create PRAYER_KV

# 2. Update wrangler.toml with the returned namespace ID
# 3. Deploy
npx wrangler deploy

🔌 Connecting to AI Hosts

⚡ 1-Click Client Installation Matrix

Client / Environment	Support Mode	1-Click Deeplink / Quick Command
Cursor	Remote HTTP
Claude Desktop	Remote HTTP	Add URL https://muslim-prayer-mcp.najetareqz.workers.dev/mcp to config
VS Code	Local / NPX	npx -y muslim-prayer-mcp via .vscode/mcp.json
Windsurf / Devin	Remote HTTP	Add https://muslim-prayer-mcp.najetareqz.workers.dev/mcp to mcp_config.json
Gemini CLI	Auto-indexed	gemini-cli --mcp-server https://muslim-prayer-mcp.najetareqz.workers.dev/mcp
Autonomous Agents	All Modes	Agent setup: llms-install.md & Skill: SKILL.md

Option 1: Local Stdio via NPX (Claude Desktop, Cursor, Windsurf, VS Code)

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

Option 2: Remote Streamable HTTP (Cloudflare Workers)

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

Deterministic Host Middleware (Node.js / Express / Vercel AI SDK)

import { PrayerReminderMiddleware } from './src/middleware/host-connector.ts';

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

// Wrap any LLM completion
const rawAnswer = await callYourLlm('What is the best database for this project?');
const { responseText, reminderAppended } = await prayerMiddleware.processResponse(rawAnswer, {
  'X-User-Coordinates': '24.71, 46.68',
  'X-User-Timezone': 'Asia/Riyadh',
});

console.log(responseText);
// If Maghrib is due:
// PostgreSQL is the recommended database...
//
// 🕌 It is time for Maghrib prayer.

🔒 Privacy & Data Minimization

• Coordinate Truncation: All incoming latitude/longitude values are rounded to 2 decimal places (~1.1km precision), preventing street-level tracking while preserving sub-minute solar calculation accuracy.
• No Coordinate Leakage: MCP tool outputs return prayer names and reminders; raw coordinates are never passed into the LLM context.
• In-Isolate Execution: Calculations run directly within the Cloudflare V8 isolate; no user coordinates are sent across WAN to third-party prayer APIs.

🎨 Official Branding Assets

Official high-resolution branding assets with antialiased transparent corners:

• Official Icon (512×512 PNG): assets/icon.png
• Master High-Res (1024×1024 PNG): assets/official-logo-1024.png
• Documentation Favicon & Icons: docs/assets/

📜 Legal & Compliance

• Terms of Service: https://tareq7.github.io/muslim-prayer-mcp/terms-of-service/
• Privacy Policy: https://tareq7.github.io/muslim-prayer-mcp/privacy-policy/
• Documentation Portal: https://tareq7.github.io/muslim-prayer-mcp/