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

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

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

| 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/