# 🕐 local-time-mcp

یک سرور MCP (Model Context Protocol) کوچک و قابل اعتماد که به عامل‌های هوش مصنوعی اجازه میده زمان و تاریخ دقیق سیستم رو دریافت کنن — شامل **تقویم جلالی (هجری شمسی)**.

> 🤖 Built with [Claude Code](https://claude.ai/claude-code) — Anthropic's CLI for Claude.

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## 🎯 چرا این پروژه؟

مدل‌های زبانی (LLM) ساعت داخلی قابل اعتمادی ندارن. وقتی میپرسید «الان چند ساعته؟»، مدل یا از داده‌های آموزشی حدس میزنه یا تاریخ ثابتی از system prompt میخونه — هر دو اشتباهه.

**این سرور MCP این مشکل رو حل می‌کنه** با دسترسی مستقیم به ساعت سیستم عامل در لحظه فراخوانی ابزار. هر پاسخ دقیق، به‌روز و time-zone-aware هست.

---

## ✨ امکانات

| امکان | توضیح |
|--------|--------|
| 🌍 **هر timezone IANA** | `Asia/Tehran`, `Europe/Berlin`, `America/New_York`, `UTC` و غیره |
| ⏰ **زمان دقیق** | تاریخ، ساعت (با ثانیه)، Unix timestamp |
| 📅 **تاریخ جلالی** | عددی (`1405/05/17`) و فارسی (`17 مرداد 1405`) |
| 🇮🇷 **نام روز و ماه فارسی** | روز هفته به انگلیسی و فارسی |
| 🌗 **DST خودکار** | مدیریت خودکار CET/CEST, EST/EDT و غیره |
| 🔌 **کاملاً آفلاین** | فقط از ساعت سیستم استفاده می‌کنه، بدون اتصال اینترنت |
| 🪶 **وابستگی‌های کم** | Python 3.11+, MCP SDK, jdatetime, tzdata |

---

## 📦 نصب و راه‌اندازی

### پیش‌نیازها

- Python 3.11 یا بالاتر
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (توصیه شده) یا pip

### نصب سریع

```bash
# کلون کردن مخزن
git clone https://github.com/karimi-mohammad/local-time-mcp.git
cd local-time-mcp

# نصب با uv (توصیه شده)
uv pip install -e .

# یا نصب با pip
pip install -e .
```

---

## ⚙️ پیکربندی Claude Code

### روش ۱ — اضافه کردن از CLI (توصیه شده)

```bash
claude mcp add local-time -s user -- uv run --directory "C:\path\to\local-time-mcp" python -m local_time_mcp
```

### روش ۲ — ویرایش دستی `settings.json`

این محتوا رو به فایل پیکربندی MCP Claude Code اضافه کنید (`~/.claude/settings.json` یا `.claude/settings.json` در سطح پروژه):

```json
{
  "mcpServers": {
    "local-time": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\path\\to\\local-time-mcp",
        "python",
        "-m",
        "local_time_mcp"
      ]
    }
  }
}
```

### روش ۳ — اجرای مستقیم Python (بعد از نصب)

```bash
cd local-time-mcp
pip install -e .
```

```json
{
  "mcpServers": {
    "local-time": {
      "command": "local-time-mcp"
    }
  }
}
```

---

## 🔧 مرجع ابزار MCP

### `get_current_datetime`

زمان و تاریخ فعلی رو به صورت JSON ساختاریافته برمی‌گردونه.

| پارامتر | نوع | ضروری | توضیح |
|----------|------|--------|-------|
| `timezone` | `string` | ❌ | نام timezone IANA (مثلاً `Asia/Tehran`, `UTC`). پیش‌فرض: ساعت محلی سیستم |

### فیلدهای پاسخ

| فیلد | نوع | مثال | توضیح |
|------|------|------|-------|
| `datetime` | `string` | `2026-08-10T14:31:59+03:30` | تاریخ و ساعت ISO 8601 با offset |
| `date` | `string` | `2026-08-10` | تاریخ میلادی (YYYY-MM-DD) |
| `time` | `string` | `14:31:59` | ساعت (HH:MM:SS) |
| `day_of_week` | `string` | `Monday` | نام روز به انگلیسی |
| `day_of_week_fa` | `string` | `دوشنبه` | نام روز به فارسی |
| `timezone` | `string` | `Asia/Tehran` | نام timezone IANA استفاده شده |
| `utc_offset` | `string` | `+03:30` | اختلاف با UTC (±HH:MM) |
| `unix_timestamp` | `integer` | `1786359719` | Unix epoch timestamp |
| `jalali_date` | `string` | `1405/05/19` | تاریخ جلالی (YYYY/MM/DD) |
| `jalali_date_fa` | `string` | `19 مرداد 1405` | تاریخ جلالی به فارسی |
| `jalali_year` | `integer` | `1405` | سال جلالی |
| `jalali_month` | `integer` | `5` | ماه جلالی (1-12) |
| `jalali_month_name` | `string` | `مرداد` | نام ماه فارسی |
| `jalali_day` | `integer` | `19` | روز جلالی (1-31) |

### نمونه استفاده

```
> get_current_datetime()
> get_current_datetime("Asia/Tehran")
> get_current_datetime("Europe/Berlin")
> get_current_datetime("UTC")
> get_current_datetime("America/New_York")
```

### نمونه پاسخ

```json
{
  "datetime": "2026-08-10T14:31:59+03:30",
  "date": "2026-08-10",
  "time": "14:31:59",
  "day_of_week": "Monday",
  "day_of_week_fa": "دوشنبه",
  "timezone": "Asia/Tehran",
  "utc_offset": "+03:30",
  "unix_timestamp": 1786359719,
  "jalali_date": "1405/05/19",
  "jalali_date_fa": "19 مرداد 1405",
  "jalali_year": 1405,
  "jalali_month": 5,
  "jalali_month_name": "مرداد",
  "jalali_day": 19
}
```

### پاسخ خطا (timezone نامعتبر)

```json
{
  "error": "Invalid timezone: 'Invalid/Zone'. Use IANA format like 'Asia/Tehran', 'UTC', etc."
}
```

---

## 🕐 اسکیل CLI local-time

علاوه بر MCP server، یک اسکیل CLI مستقل هم وجود داره که مستقیماً از خط فرمان قابل استفاده هست:

### نصب اسکیل

```bash
# فایل‌ها رو به دایرکتوری skills کپی کنید
cp -r skill/ ~/.claude/skills/local-time/
```

### دستورات

| دستور | توضیح | مثال |
|--------|--------|------|
| `now` | زمان فعلی با تمام جزئیات | `python local_time.py now` |
| `now --tz` | زمان با timezone مشخص | `python local_time.py now --tz Asia/Tehran` |
| `jalali` | تاریخ جلالی فعلی | `python local_time.py jalali` |
| `weekday` | روز هفته (انگلیسی + فارسی) | `python local_time.py weekday` |
| `to-jalali` | تبدیل میلادی به جلالی | `python local_time.py to-jalali 2026-08-10` |
| `to-gregorian` | تبدیل جلالی به میلادی | `python local_time.py to-gregorian 1405/05/19` |
| `timestamp` | Unix timestamp | `python local_time.py timestamp` |
| `timezones` | لیست timezoneهای رایج | `python local_time.py timezones` |

### نمونه خروجی

```json
{
  "datetime": "2026-08-10T14:31:59.027681+03:30",
  "date": "2026-08-10",
  "time": "14:31:59",
  "day_of_week": "Monday",
  "day_of_week_fa": "دوشنبه",
  "timezone": "Asia/Tehran",
  "utc_offset": "+03:30",
  "unix_timestamp": 1786359719,
  "jalali_date": "1405/05/19",
  "jalali_date_fa": "19 مرداد 1405"
}
```

---

## 🌍 timezoneهای پشتیبانی شده

هر نام timezone IANA معتبر کار می‌کنه. مثال‌های رایج:

| Timezone | توضیح | UTC Offset |
|----------|-------|------------|
| `UTC` | زمان هماهنگ جهانی | +00:00 |
| `Asia/Tehran` | ساعت ایران | +03:30 |
| `Europe/Berlin` | ساعت مرکز اروپا (CET/CEST) | +01:00 / +02:00 |
| `America/New_York` | ساعت شرق آمریکا (EST/EDT) | -05:00 / -04:00 |
| `America/Los_Angeles` | ساعت اقیانوس آرام (PST/PDT) | -08:00 / -07:00 |
| `Asia/Tokyo` | ساعت ژاپن | +09:00 |
| `Europe/London` | ساعت بریتانیا (GMT/BST) | +00:00 / +01:00 |
| `Asia/Dubai` | ساعت امارات | +04:00 |

---

## 🤖 راهنمای استفاده برای عامل‌های هوش مصنوعی

Claude (یا هر عامل هوش مصنوعی متصل) باید در موارد زیر `get_current_datetime` رو فراخوانی کنه:

- 🕐 زمان یا تاریخ فعلی
- 📆 روز هفته
- 📛 "امروز"، "فردا"، "دیروز"
- ⏳ مهلت‌ها یا استدلال‌های حساس به زمان
- 📊 تاریخ‌های نسبی ("۲ روز دیگه")
- 🔄 هر عملیاتی که دقت در اون مهمه

> **از حدس زدن تاریخ/ساعت از context مدل استفاده نکنید.** همیشه این ابزار رو فراخوانی کنید.

---

## 🧪 توسعه و تست‌ها

### ساختار پروژه

```
local-time-mcp/
├── pyproject.toml              # پیکربندی پکیج
├── README.md                   # این فایل
├── LICENSE                     # مجوز MIT
├── src/
│   └── local_time_mcp/
│       ├── __init__.py
│       ├── __main__.py         # python -m local_time_mcp
│       └── server.py           # پیاده‌سازی سرور MCP
├── skill/
│   ├── SKILL.md                # مستندات اسکیل CLI
│   └── local_time.py           # اسکریپت CLI
└── tests/
    ├── __init__.py
    └── test_server.py          # ۴۴ تست
```

### اجرای تست‌ها

```bash
# نصب وابستگی‌های توسعه
uv pip install -e ".[dev]"

# اجرای تمام تست‌ها
pytest

# اجرای با جزئیات
pytest -v

# اجرای یک کلاس تست خاص
pytest tests/test_server.py::TestJalaliDate -v
```

### پوشش تست‌ها

| کلاس تست | تعداد | توضیح |
|-----------|--------|-------|
| `TestLocalTimezone` | ۶ | timezone محلی سیستم |
| `TestAsiaTehran` | ۳ | timezone آسیا/تهران |
| `TestEuropeBerlin` | ۳ | timezone DST-aware |
| `TestUTC` | ۳ | timezone UTC |
| `TestAmericaNewYork` | ۲ | timezone EST/EDT |
| `TestInvalidTimezone` | ۳ | مدیریت خطا |
| `TestDayOfWeek` | ۴ | نام روز انگلیسی و فارسی |
| `TestUTCOffset` | ۳ | محاسبات offset |
| `TestUnixTimestamp` | ۲ | دقت timestamp |
| `TestFreshTimestamp` | ۲ | به‌روزرسانی بلادرنگ |
| `TestMCPTool` | ۳ | wrapper ابزار MCP |
| `TestJalaliDate` | ۱۰ | تبدیل تقویم جلالی |
| **مجموع** | **۴۴** | |

---

## 🔍 عیب‌یابی

### سرور MCP شروع نمیشه

```bash
# ۱. بررسی نسخه Python
python --version

# ۲. نصب مجدد وابستگی‌ها
uv pip install -e .

# ۳. تست مستقیم سرور
python -m local_time_mcp
```

### خطای timezone نامعتبر

از نام‌های timezone IANA معتبر استفاده کنید:

| ✅ درست | ❌ غلط |
|---------|--------|
| `Asia/Tehran` | `Tehran` |
| `Europe/Berlin` | `CET` |
| `America/New_York` | `EST` |
| `UTC` | `GMT` (بعضی سیستم‌ها) |

### مسائل مخصوص ویندوز

- سرور روی Windows 10+ با Python 3.11+ کار می‌کنه
- داده timezone از طریق ماژول `zoneinfo` پایتون در دسترسه
- نیازی به پایگاه داده timezone اضافی نیست

---

## 📄 مجوز

[MIT](LICENSE)

---

<p align="center">
  ساخته شده با ❤️ با استفاده از <a href="https://claude.ai/claude-code">Claude Code</a>
</p>