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

1. 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).

2. 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

---

⚖️ 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.):

1. 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).

2. 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

---

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/