# UAE Calendar Oracle (`thenightowl/uae-calendar-oracle`) Actor

UAE working days, public holidays with confirmation status (moon-sighting aware), Hijri conversion, Ramadan working hours, per-emirate and per-sector weekends, deadline arithmetic. MCP server + REST for AI agents. Every answer states its confidence and cites official sources. No logging.

- **URL**: https://apify.com/thenightowl/uae-calendar-oracle.md
- **Developed by:** [Mohamad Najia](https://apify.com/thenightowl) (community)
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 lookup tool calls

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## UAE Calendar Oracle — MCP server for AI agents

The UAE date logic your agent gets wrong: moon-sighted holidays with a confirmation status, public vs private sector, Sharjah's 4-day week, Ramadan hours and deadline arithmetic — every answer with a confidence level and an official source.

### What you get

Ten tools your agent can call over MCP (Streamable HTTP at this Actor's Standby URL + `/mcp`, with your Apify token):

`is_working_day` · `add_working_days` · `working_days_between` · `compute_deadline` · `list_holidays` · `next_holiday` ·
`gregorian_to_hijri` · `hijri_to_gregorian` · `ramadan_info` · `working_hours`

Every response includes `data_confidence` (`high` when all dates are officially announced/confirmed, `medium` when something
is still estimated), `estimated_items[]`, `sources[]` (official URLs), `data_version`, and — for deadline tools — a disclaimer.

### Why not a generic holiday API

Generic holiday APIs either have no UAE data at all or lag UAE announcements by months. They don't know that the federal government got 25 May 2026 off and the private sector didn't, that Hijri New Year 2025 was moved to a Friday, that Sharjah's government weekend is Friday–Sunday, or what the official Ramadan hours are. This service answers from versioned, source-cited data that is checked against WAM, FAHR, MOHRE and the emirates' media offices every 30 minutes and updated only after human review. It says `estimated` until the UAE announces, `announced`/`confirmed` after, and `moved` when the Cabinet relocates a day — so your agent can tell the user how sure it is.

### Example use cases

1. **HR & leave planning** — "How many working days does Fatima's leave from 18 May to 5 June 2026 cost, for a federal employee?" → `working_days_between` returns 10 (2 of them Friday half days), lists every skipped Eid day with its status.
2. **Logistics & delivery promises** — "Order placed Thursday 21 May 2026, delivery in 3 business days in Dubai" → `add_working_days` → Monday 1 June for a private company, Tuesday 2 June if the recipient is a government office; the Eid week is skipped and explained.
3. **Contract & notice deadline drafts** — "Notice served 26 November 2026, 7 calendar days to respond" → `compute_deadline` → raw date 3 December is National Day (still *estimated*), extended to Friday 4 December, `data_confidence: medium`, with a disclaimer that this is date arithmetic, not legal advice.
4. **Booking & scheduling agents** — "Is 13:00 on 5 March 2026 a good time to call a federal ministry?" → `working_hours` → yes, Ramadan hours 09:00–14:30 apply, source: FAHR Circular 1/2026.

### Connect

```
claude mcp add uae-calendar-oracle --transport http https://<your-username>--uae-calendar-oracle.apify.actor/mcp --header "Authorization: Bearer <APIFY_TOKEN>"
```

Any MCP client that supports Streamable HTTP works the same way. Default profile is `emirate=federal, sector=public`; use
`sector=private` for companies and the emirate name for that emirate's government.

### Pricing

Lookups (is_working_day, list_holidays, next_holiday, Hijri conversions, ramadan_info, working_hours) **$0.003 per call**. Computations with a full explanation trail (add_working_days, working_days_between, compute_deadline) **$0.01 per call**. Self-hosted endpoint: five lookup tools free at 30 requests/minute without a key.

### Privacy

No query logging (aggregate counters only), no AI calls — deterministic code plus data. Every response carries `data_version` and `sources[]`. The server is deterministic code plus versioned data; it makes no network calls while answering.

### Not legal advice

Deadline tools perform configurable date arithmetic with the rules you pass; they do not state what any law, court or contract requires. Verify with a qualified professional.

### Data

Public official sources only: UAE Government portal (u.ae), Cabinet Resolution 27/2024, FAHR circulars (public sector), MOHRE
releases (private sector), WAM, and the emirates' media offices; Islamic dates confirmed by the UAE Council for Fatwa, estimates
from the Umm al-Qura calendar. Sources are checked every 30 minutes; changes are applied after human review and listed in the
public data changelog.

***

### بالعربية

**عرّاف التقويم الإماراتي — أيام العمل، العطلات، الهجري، ساعات رمضان، المواعيد النهائية**

منطق التواريخ الإماراتي الذي يخطئ فيه وكيلك الذكي: عطلات مرتبطة برؤية الهلال مع حالة التأكيد، القطاع الحكومي مقابل الخاص، أسبوع الشارقة ذو الأربعة أيام، ساعات رمضان وحساب المواعيد النهائية — كل إجابة بمستوى ثقة ومصدر رسمي.

واجهات العطلات العامة إما لا تحوي بيانات إماراتية أصلاً أو تتأخر أشهراً عن الإعلانات الرسمية. لا تعرف أن الحكومة الاتحادية حصلت على عطلة يوم 25 مايو 2026 بينما لم يحصل القطاع الخاص عليها، ولا أن رأس السنة الهجرية 2025 نُقل إلى يوم الجمعة، ولا أن عطلة نهاية الأسبوع لحكومة الشارقة من الجمعة إلى الأحد، ولا ما هي ساعات العمل الرسمية في رمضان. هذه الخدمة تجيب من بيانات مُوثّقة بمصادرها ومُرقّمة بإصدارات، تُفحص مقابل وام والهيئة الاتحادية للموارد البشرية الحكومية ووزارة الموارد البشرية والتوطين والمكاتب الإعلامية للإمارات كل 30 دقيقة، ولا تُحدَّث إلا بعد مراجعة بشرية. تقول «تقديري» حتى تعلن الإمارات، ثم «مُعلن»/«مؤكد»، و«مُنقول» عندما ينقل مجلس الوزراء يوماً — ليتمكن وكيلك من إخبار المستخدم بمدى يقينه.

- **الموارد البشرية وتخطيط الإجازات** — «كم يوم عمل تستهلك إجازة فاطمة من 18 مايو إلى 5 يونيو 2026 لموظفة اتحادية؟» → تُرجع الأداة 10 أيام (منها يومان نصف دوام الجمعة) مع قائمة أيام العيد المتجاوزة وحالتها.
- **اللوجستيات ووعود التسليم** — «طلب يوم الخميس 21 مايو 2026، التسليم خلال 3 أيام عمل في دبي» → الاثنين 1 يونيو لشركة خاصة، والثلاثاء 2 يونيو إن كان المستلم جهة حكومية؛ مع تجاوز أسبوع العيد وتفسيره.
- **مسودات مواعيد العقود والإخطارات** — «إخطار مُسلَّم في 26 نوفمبر 2026 مع 7 أيام تقويمية للرد» → التاريخ الأولي 3 ديسمبر هو اليوم الوطني (ما زال تقديرياً)، يُمدَّد إلى الجمعة 4 ديسمبر، مستوى الثقة متوسط، مع تنويه بأن هذا حساب تواريخ لا استشارة قانونية.
- **وكلاء الحجز والمواعيد** — «هل الساعة 13:00 يوم 5 مارس 2026 وقت مناسب للاتصال بوزارة اتحادية؟» → نعم، تنطبق ساعات رمضان 09:00–14:30، المصدر: تعميم الهيئة رقم 1 لسنة 2026.

الاستعلامات 0.003 دولار للاستدعاء؛ الحسابات مع مسار تفسير كامل 0.01 دولار للاستدعاء. النقطة المستضافة ذاتياً: خمس أدوات استعلام مجانية بحد 30 طلباً في الدقيقة دون مفتاح.

لا تسجيل للاستعلامات (عدّادات إجمالية فقط)، لا استدعاءات لنماذج ذكاء اصطناعي — شيفرة حتمية وبيانات. كل استجابة تحمل رقم إصدار البيانات والمصادر.

أدوات المواعيد النهائية تُجري حساب تواريخ قابلاً للتهيئة وفق القواعد التي تمررها؛ ولا تقرر ما يقتضيه أي قانون أو محكمة أو عقد. راجع مختصاً مؤهلاً.

# Changelog

This Actor's version history is a separate document: https://apify.com/thenightowl/uae-calendar-oracle/changelog.md

# Actor input Schema

## Actor input object example

```json
{}
```

# Actor output Schema

## `mcpEndpoint` (type: `string`):

Point your MCP client here (Authorization: Bearer <Apify token>). Exposes 10 tools: is_working_day, add_working_days, working_days_between, compute_deadline, list_holidays, next_holiday, gregorian_to_hijri, hijri_to_gregorian, ramadan_info, working_hours.

## `readiness` (type: `string`):

Returns 200 with the loaded data_version when the server is ready.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("thenightowl/uae-calendar-oracle").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("thenightowl/uae-calendar-oracle").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call thenightowl/uae-calendar-oracle --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,thenightowl/uae-calendar-oracle"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/geEtnwA0Yr0dQUYHP/builds/pDR4BEK854aQ1qAat/openapi.json