Metadata-Version: 2.5
Name: jalali-calendar-mcp
Version: 0.2.1
Summary: MCP server and library for the Iranian (Jalali) calendar: date conversion, months, official holidays and workdays. Offline, no account.
Project-URL: Homepage, https://github.com/SaeedNoshadi89/jalali-calendar-mcp
Project-URL: Repository, https://github.com/SaeedNoshadi89/jalali-calendar-mcp
Project-URL: Issues, https://github.com/SaeedNoshadi89/jalali-calendar-mcp/issues
Project-URL: Changelog, https://github.com/SaeedNoshadi89/jalali-calendar-mcp/blob/main/CHANGELOG.md
Author: Saeed Noshadi
License-Expression: MIT
License-File: LICENSE
Keywords: calendar,holidays,iran,jalali,legal,mcp,model-context-protocol,persian
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: Natural Language :: Persian
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: hijridate<3,>=2.5
Requires-Dist: jdatetime<7,>=5
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pydantic<3,>=2.7
Description-Content-Type: text/markdown

# jalali-calendar-mcp

An [MCP](https://modelcontextprotocol.io) server and Python library for the Iranian (Jalali, Solar Hijri) calendar: today in Iran, date conversion, months, official holidays and workdays.

**Fully offline.** It calls no web service and needs no account or token. Every date is calculated inside the package.

## Tools

| Tool | What it returns |
| --- | --- |
| `today()` | Today in Iran (Asia/Tehran), Jalali and Gregorian, weekday, and whether it is a day off |
| `convert_date(value)` | The same for any date, Jalali ↔ Gregorian |
| `get_month(year, month)` | Every day of a Jalali month, with Fridays and holidays |
| `get_holidays(year)` | Iran's official holidays in a Jalali year |
| `is_holiday(value)` | Whether a day is a Friday or an official holiday, and which |
| `count_workdays(start, end)` | Days in a range that are neither Fridays nor official holidays |

Dates are accepted as Gregorian `YYYY-MM-DD` or Jalali `YYYY/MM/DD`, with Persian or English digits; any year below 1700 is read as Jalali. Holidays are available for Jalali years 1304–1455.

## How sure is a holiday?

Every holiday carries a `status`:

| Status | Meaning |
| --- | --- |
| `official` | A fixed solar holiday set by law: Nowruz (1–4 Farvardin), 12 and 13 Farvardin, 14 and 15 Khordad, 22 Bahman, 29 Esfand |
| `listed` | A lunar (Hijri) holiday from the package's list for that year (currently 1405, taken from persian-calendar.ir and not yet checked against the official calendar) |
| `estimated` | A lunar holiday calculated with the Umm al-Qura calendar. Iran starts each lunar month from its own moon sighting, so it may be **one day off**. Check the official calendar before relying on it |

Lunar holidays move about 11 days earlier each year. A day can hold two holidays; in 1405, for example, Nowruz and Eid al-Fitr share 1 Farvardin. Fridays are the weekly day off and are reported as `is_friday`, not as holidays. `count_workdays` counts Thursdays as workdays. It is not a legal deadline calculator: legal periods have their own rules.

## Setup

For Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jalali-calendar": {
      "command": "uvx",
      "args": ["jalali-calendar-mcp"]
    }
  }
}
```

Or install it with `pip install jalali-calendar-mcp` and use `"command": "jalali-calendar-mcp"`.

## As a library

```python
from jalali_calendar_mcp import holidays, holidays_on, jalali, parse_date

parse_date("۱۴۰۵/۰۱/۰۱")  # date(2026, 3, 21)
jalali(parse_date("2026-11-22"))  # "1405/09/01"
[h.name for h in holidays_on(parse_date("1405/04/04"))]  # ["عاشورای حسینی"]
len(holidays(1405))  # 29
```

## Adding a year's lunar holidays

Add `src/jalali_calendar_mcp/data/<year>.json`, following `1405.json` (with a `source`), with the lunar holidays from the official calendar of the University of Tehran Geophysics Institute. Set `checked_against_official` to `true` once someone has compared it with that calendar.

## Development

```sh
uv sync
uv run ruff check . && uv run ruff format --check .
uv run pytest
```

---

## فارسی

سرور MCP و کتابخانهٔ پایتون برای **تقویم رسمی ایران (هجری شمسی)**: امروز به وقت ایران، تبدیل تاریخ شمسی و میلادی، روزهای هر ماه، تعطیلات رسمی و شمارش روزهای کاری.

**کاملاً آفلاین:** به هیچ سرویس اینترنتی وصل نمی‌شود و حساب کاربری یا توکن لازم ندارد.

### ابزارها

| ابزار | کاربرد |
| --- | --- |
| `today` | امروز به وقت ایران، شمسی و میلادی، و اینکه تعطیل است یا نه |
| `convert_date` | تبدیل تاریخ شمسی و میلادی به یکدیگر |
| `get_month` | همهٔ روزهای یک ماه شمسی با جمعه‌ها و تعطیلات |
| `get_holidays` | تعطیلات رسمی یک سال شمسی |
| `is_holiday` | آیا روزی جمعه یا تعطیل رسمی است |
| `count_workdays` | شمار روزهای کاری یک بازه، بدون جمعه‌ها و تعطیلات رسمی |

### میزان اطمینان تعطیلات

- **`official`:** تعطیلات خورشیدی ثابت که قانون تعیین کرده است، مانند نوروز و ۲۲ بهمن.
- **`listed`:** تعطیلات قمری از فهرست همان سال در این بسته (فعلاً ۱۴۰۵).
- **`estimated`:** تعطیلات قمری محاسبه‌شده. چون آغاز ماه قمری در ایران با رؤیت هلال تعیین می‌شود، ممکن است **یک روز** با تقویم رسمی فرق داشته باشد. پیش از استفاده برای کار مهم، تقویم رسمی را ببینید.

جمعه‌ها تعطیل هفتگی‌اند و جدا از تعطیلات رسمی نشان داده می‌شوند. شمارش روزهای کاری جایگزین محاسبهٔ مهلت‌های قانونی نیست.

## License

MIT
