Metadata-Version: 2.5
Name: jalali-calendar-mcp
Version: 0.1.0
Summary: MCP server that reads a lawyer's case calendar (deadlines, hearings and due tasks), read only, with Jalali dates.
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,iran,jalali,legal,mcp,model-context-protocol,persian
Classifier: Development Status :: 4 - Beta
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: httpx<1,>=0.28
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 that lets an AI app on your computer (Claude Desktop, Cursor, VS Code, any MCP client) read a lawyer's case calendar: deadlines, hearings and tasks with a due day, across their active cases. Dates come in both Gregorian and Jalali (Persian) form, and "today" is Iran's day. It also converts dates between the two calendars without any account.

**Read only.** The server cannot create, change or delete anything.

## Tools

| Tool | Needs the API | What it returns |
| --- | --- | --- |
| `get_calendar(start, end, mine_only?)` | yes | Items due from `start` to `end` (both included, at most 62 days), plus overdue items. Dates as `YYYY-MM-DD` or Jalali `YYYY/MM/DD`, Persian digits accepted |
| `get_upcoming(days?, mine_only?)` | yes | Today (Iran) and the next days; `days` 1–62, default 7 |
| `get_overdue(mine_only?)` | yes | Open items due in the last 90 days that are not done (`overdue`, `overdue_total`) |
| `today()` | no | Today in Iran, Gregorian and Jalali, with the weekday |
| `convert_date(value)` | no | Jalali ↔ Gregorian conversion |

`mine_only` keeps deadlines and only the tasks assigned to the signed-in lawyer. `today` and `convert_date` run locally and send nothing over the network.

## Setup

Add the server to your MCP client. For Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jalali-calendar": {
      "command": "uvx",
      "args": ["jalali-calendar-mcp"],
      "env": {
        "JALALI_CALENDAR_URL": "https://your-calendar-service.example",
        "JALALI_CALENDAR_TOKEN": "your-calendar-token"
      }
    }
  }
}
```

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

| Variable | Meaning |
| --- | --- |
| `JALALI_CALENDAR_URL` | Address of the calendar API. Must be `https`; plain `http` only for `localhost` |
| `JALALI_CALENDAR_TOKEN` | A read-only calendar token from that service |

Set both, or neither: without them only `today` and `convert_date` work.

## The calendar API it reads

`GET {JALALI_CALENDAR_URL}/api/v1/calendar?from=YYYY-MM-DD&to=YYYY-MM-DD` with `Authorization: Bearer <token>`, answering:

```json
{
  "from": "2026-11-21", "to": "2026-11-27", "today": "2026-11-21", "truncated": false,
  "items": [
    {"type": "deadline", "id": "…", "title": "…", "due_on": "2026-11-22", "done": false,
     "kind": "hearing", "due_time": "09:30:00", "note": "…", "mine": false,
     "case": {"id": "…", "number": "1405-042", "display_title": "…"}},
    {"type": "task", "id": "…", "title": "…", "due_on": "2026-11-24", "done": false,
     "status": "in_progress", "mine": true, "case": {"id": "…", "number": "1405-042"}}
  ],
  "overdue": [], "overdue_total": 0
}
```

The range is at most 62 days. `note` and the case title may be left out. Errors use `{"code": "…"}` with codes such as `invalid_token`, `invalid_input` and `rate_limited`.

## Privacy

What a tool returns goes to your AI app and, from there, to that app's model provider. A case calendar holds client data, so decide whether that is acceptable for your practice before connecting it. Prefer a token that shares only case numbers, not titles or notes, and revoke it when you stop using it.

The server sends the token only to `JALALI_CALENDAR_URL`, never follows redirects and never puts the token in errors. Titles and notes are case data; the server tells the model to treat them as data, not instructions.

## As a library

```python
from datetime import date
from jalali_calendar_mcp import CalendarApiClient, jalali, parse_date

client = CalendarApiClient("your-calendar-token", base_url="https://your-calendar-service.example")
calendar = await client.calendar(date(2026, 11, 21), date(2026, 11, 27))
parse_date("۱۴۰۴/۰۱/۰۱")  # date(2025, 3, 21)
```

## Development

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

---

## فارسی

این سرور MCP به دستیار هوش مصنوعی روی رایانهٔ شما (مثل Claude Desktop) اجازه می‌دهد تقویم پرونده‌های یک وکیل را **فقط بخواند**: مهلت‌ها، جلسه‌ها و کارهای سررسیددار پرونده‌های فعال، با تاریخ شمسی و میلادی. هیچ چیزی را نمی‌سازد، تغییر نمی‌دهد یا حذف نمی‌کند. تبدیل تاریخ شمسی و میلادی و «امروز» به وقت ایران بدون حساب کاربری هم کار می‌کند.

۱. نشانی سرویس تقویم را در `JALALI_CALENDAR_URL` و توکن فقط‌خواندنی آن را در `JALALI_CALENDAR_TOKEN` بگذارید (نمونهٔ بالا).
۲. سرور را به برنامهٔ هوش مصنوعی خود اضافه کنید.

**حریم خصوصی:** آنچه این ابزارها برمی‌گردانند به برنامهٔ هوش مصنوعی شما و ارائه‌دهندهٔ مدل آن فرستاده می‌شود. پیش از اتصال، دربارهٔ محرمانگی اطلاعات پرونده‌ها تصمیم بگیرید و توکن را هر زمان که لازم نبود باطل کنید.

## License

MIT
