🕐 local-time-mcp

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

🤖 Built with Claude Code — Anthropic's CLI for Claude.

Python 3.11+ License: MIT

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

مدل‌های زبانی (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 (توصیه شده) یا pip

نصب سریع

# کلون کردن مخزن
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 (توصیه شده)

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 در سطح پروژه):

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

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

cd local-time-mcp
pip install -e .

{
  "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")

نمونه پاسخ

{
  "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 نامعتبر)

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

🕐 اسکیل CLI local-time

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

نصب اسکیل

# فایل‌ها رو به دایرکتوری 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`

نمونه خروجی

{
  "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          # ۴۴ تست

اجرای تست‌ها

# نصب وابستگی‌های توسعه
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 شروع نمیشه

# ۱. بررسی نسخه 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