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

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

🚀 Quick Start & Deployment

1. Run Automated Test Suite Locally

npm test

Executes 39 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	Direct agent setup: llms-install.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/