# Divar Intelligence MCP

سرور مستقل و غیررسمی برای جست‌وجو، مقایسه، بررسی قیمت و پایش آگهی‌های دیوار. داده‌ها با منبع، تازگی، وضعیت نامعلوم و محدودیت پوشش ارائه می‌شوند. این پروژه عملیات انتشار آگهی، پرداخت، پیام به فروشنده یا دریافت شماره تلفن انجام نمی‌دهد.

## اجرا در ویندوز

Python 3.11 یا جدیدتر لازم است. از داخل پوشهٔ پروژه:

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m divar_mcp status
```

یا از `scripts/setup.ps1` استفاده کنید. متغیرهای نمونه در `.env.example` هستند؛ این فایل به‌صورت خودکار بارگذاری نمی‌شود. تنظیمات را در محیط فرایند یا بخش `env` کلاینت MCP قرار دهید.

### حالت واقعی و اجرای محلی MCP

```powershell
$env:DIVAR_PROVIDER = "public"
$env:DIVAR_STATE_DIR = "$PWD\.state"
.\.venv\Scripts\python.exe -m divar_mcp serve
```

این فرمان MCP را روی stdio اجرا می‌کند و منتظر کلاینت می‌ماند؛ رابط چت یا صفحهٔ وب جداگانه‌ای باز نمی‌کند. فایل آمادهٔ اتصال در `examples/mcp.local.json` است. مسیر Python و پوشهٔ وضعیت را در صورت جابه‌جایی پروژه اصلاح کنید.

### نمایش آفلاین، بدون نیاز به اینترنت

```powershell
$env:DIVAR_PROVIDER = "fixture"
.\.venv\Scripts\python.exe -m divar_mcp serve
```

این حالت دادهٔ **ساختگی و مشخص‌شده به‌عنوان نمونه** دارد. لینک‌های آن مثال قالب هستند و نباید به‌عنوان آگهی واقعی معرفی شوند.

### اتصال رسمی کنار

```powershell
$env:DIVAR_PROVIDER = "kenar"
$env:DIVAR_KENAR_API_KEY = "your-approved-app-key"
.\.venv\Scripts\python.exe -m divar_mcp serve
```

آداپتر رسمی از مسیرهای مستند جست‌وجو، جزئیات و assets استفاده می‌کند. کلید و مجوز `SEARCH_POST` را خودتان از کنار تهیه کنید. سهمیه و مجاز بودن کاربرد پایش باید برای برنامهٔ شما روشن باشد. صفحه‌بندی برای مسیر جست‌وجوی رسمی فرض نشده است و پوشش آن صریحاً نمونهٔ محدود گزارش می‌شود. هیچ تغییر مسیر خودکار به تأمین‌کنندهٔ عمومی انجام نمی‌شود.

### HTTP

برای اتصال محلی بدون احراز هویت، فعال‌سازی صریح لازم است:

```powershell
$env:DIVAR_ALLOW_LOCAL_HTTP = "1"
.\.venv\Scripts\python.exe -m divar_mcp serve --transport http --host 127.0.0.1 --port 8765
```

نشانی MCP: `http://127.0.0.1:8765/mcp`.

برای استفادهٔ چند حساب، `DIVAR_HTTP_TOKENS` را یک نگاشت JSON از توکن‌های تصادفی حداقل ۲۴ کاراکتری به شناسهٔ حساب قرار دهید. هر درخواست به هویت حاصل از Bearer token متصل می‌شود؛ نام کاربر پارامتر ابزارها نیست. Origin و Host با فهرست مجاز کنترل می‌شوند؛ برای دامنهٔ اختصاصی، `DIVAR_ALLOWED_HOSTS` و `DIVAR_ALLOWED_ORIGINS` را تنظیم کنید. توکن‌ها را در مخزن ثبت نکنید.

این نسخه از Bearer token ازپیش‌تنظیم‌شده استفاده می‌کند. جریان کامل OAuth برای ثبت و ورود عمومی مشتریان MCP و استقرار SaaS خودکار پیاده نشده است.

## ابزارها

پروفایل `core` دارای ۱۲ ابزار است:

- کشف و ورودی: `dv_resolve_entities`، `dv_filter_schema`، `dv_parse_search`.
- دریافت: `dv_search`، `dv_get_listing`، `dv_get_listings`.
- تصمیم: `dv_similar`، `dv_compare`، `dv_rank`، `dv_market_snapshot`، `dv_assess_price`.
- وضعیت: `dv_status`.

پروفایل پیش‌فرض `advanced` مجموعاً ۳۱ ابزار دارد و موارد زیر را اضافه می‌کند:

- `dv_count` و `dv_market_history`.
- `dv_nearby`، `dv_geocode`، `dv_locate`، `dv_boundaries`، `dv_neighbours`، `dv_place_mapping`.
- `dv_seller_summary` و `dv_dealer_summary`؛ فقط اطلاعات عمومیِ قابل دسترسی.
- `dv_watch_create`، `dv_watch_list`، `dv_watch_update`، `dv_watch_delete`، `dv_watch_check`، `dv_watch_events`، `dv_watch_ack`.
- `dv_price_history` و `dv_export_results`.

منابع MCP شامل شهرها، دسته‌ها، طرح فیلتر و خروجی‌های موقتِ متعلق به همان حساب هستند. چهار prompt برای بودجه، مقایسه، ارزیابی قیمت و پایش موجود است. فهرست دقیق ورودی‌ها و خروجی‌ها در `docs/tool-catalog.json` قرار دارد.

## نمونهٔ فراخوانی

```json
{
  "name": "dv_search",
  "arguments": {
    "request": {
      "city": "tehran",
      "category": "apartment-rent",
      "max_deposit_toman": 500000000,
      "max_price_toman": 20000000,
      "constraints": [{"field":"parking","value":true,"required":true}],
      "verify_details": true,
      "limit": 5,
      "pages": 2
    }
  }
}
```

در دستهٔ اجاره، حدود `price_toman` مربوط به اجارهٔ ماهانه‌اند؛ ودیعه حدود جدا دارد. `match_status=unknown` یعنی شرط ضروری تأیید نشده است و رتبه‌بندی آن مورد را کنار می‌گذارد. وجود فیلتر در طرح بالادست به‌تنهایی اثبات اعمال واقعی آن نیست.

`search_scope` محدودهٔ درخواستیِ حل‌شده را نگه می‌دارد؛ شهر و دستهٔ خود آگهی فقط از شاهد منبع پر می‌شوند. اگر فهرست، دستهٔ واقعی را ندهد، آن مقدار نامعلوم می‌ماند تا جزئیات خوانده شود. رتبه‌بندی به‌صورت محدود جزئیات را می‌خواند تا این ابهام را کاهش دهد.

برای ادامه، همان درخواست را همراه `next_cursor` به `cursor` بدهید. نتایج باقی‌ماندهٔ صفحه در SQLite نگهداری می‌شوند؛ cursor متعلق به حساب و جست‌وجوی مشخص است و دو ساعت اعتبار دارد. مرتب‌سازی قیمت روی نمونهٔ برگشتی است و ارزان‌ترینِ کل بازار را تضمین نمی‌کند.

## پایش و اعلان

ساخت پایش فقط پیکربندی را ذخیره می‌کند. یکی از این دو روش را برای اجرای آن انتخاب کنید:

```powershell
.\.venv\Scripts\python.exe -m divar_mcp serve --with-worker
# یا یک فرایند جدا با همان provider و DIVAR_STATE_DIR:
.\.venv\Scripts\python.exe -m divar_mcp worker
# یک نوبت برای زمان‌بند بیرونی:
.\.venv\Scripts\python.exe -m divar_mcp worker --once
```

پیش‌فرض، آگهی‌های موجود را خط مبنا قرار می‌دهد؛ `include_existing=true` آن‌ها را هم رویداد می‌کند. هر بخش اسکن و رویدادهایش با هم در تراکنش ثبت می‌شوند؛ cursor اسکن از نشانگر خواندن رویدادها جداست. `dv_watch_events` خواندن و `dv_watch_ack` تأیید دریافت است. در صورت انقضای cursor یا محدودیت منبع، شکاف پوشش اعلام می‌شود؛ پایش خوراک کامل و تضمین‌شدهٔ همهٔ بازار نیست.

اگر مقصد HTTPS در `DIVAR_NOTIFICATION_URL` و در صورت نیاز توکن آن در `DIVAR_NOTIFICATION_TOKEN` تنظیم شود، worker رویدادها را با کلید Idempotency تحویل می‌دهد و خطا را برای تلاش بعدی نگه می‌دارد. ابزارهای MCP نمی‌توانند مقصد دلخواه تعیین کنند. تحویل از نوع «حداقل یک بار» است؛ گیرنده باید کلید رویداد را برای حذف تکرار مصرف کند. بدون این تنظیم، هیچ پیام بیرونی ارسال نمی‌شود.

## قرارداد و محدودیت‌ها

- مبالغ صحیح و به تومان، با نوع مبلغ و شاهد استخراج؛ ودیعه، اجاره و فروش مستقل‌اند.
- «خیر»، «نامعلوم»، «توافقی» و صفرِ صریح با هم فرق دارند.
- زمان انتشار، ترتیب نمایش/نردبان و مشاهدهٔ سیستم جدا هستند. عدم دسترسی به معنی فروش نیست.
- جزئیات به‌صورت محدود، حداکثر ۱۰ مورد در هر فراخوانی جست‌وجو، تکمیل می‌شوند؛ محدودیت‌های باقی‌مانده آشکار می‌مانند.
- ارزیابی تخصصی در گوشی، خودرو و مسکن قواعد مشابهت دارد و در نبود حداقل شاهد کافی خودداری می‌کند. ارزیابی قیمت معامله یا کارشناسی اصالت نیست.
- قیمت اجاره به‌صورت دوبعدی مقایسه می‌شود؛ نرخ تبدیل ودیعه فقط با پارامتر صریح کاربر وارد رتبه‌بندی می‌شود.
- تأمین‌کنندهٔ عمومی مستندشده نیست و ممکن است دسترسی را رد کند؛ خطای ۴۰۳، سهمیه و `Retry-After` مخفی نمی‌شوند. دورزدن چالش، چرخش پراکسی و ورود خودکار وجود ندارد.
- SQLite برای اجرای محلی و چند فرایند روی همان فایل طراحی شده است. استقرار توزیع‌شدهٔ چند میزبان به پایگاه/صف مشترک و مدیریت اسرار مناسب نیاز دارد.
- تاریخچه از شروع مشاهده ساخته می‌شود؛ دادهٔ گذشته اختراع نمی‌شود. جابه‌جایی میانهٔ نمونهٔ روزانه لزوماً تغییر قیمت همان کالاها نیست.
- محتوا و نقل‌قول آگهی دادهٔ غیرقابل‌اعتمادند؛ دستور اجرای ابزار محسوب نمی‌شوند. پالایش شماره‌های رایج، تضمین حذف تمام صورت‌های ممکن اطلاعات شخصی نیست.
- محدودیت درخواست پیش‌فرضِ محلی ۱۰۰۰ در روز UTC و فاصلهٔ ۲ ثانیه است؛ این تنظیم، سهمیهٔ تأییدشدهٔ دیوار نیست و آن را افزایش نمی‌دهد.

## تست و توسعه

```powershell
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m ruff check src tests scripts
.\.venv\Scripts\python.exe -m ruff format --check src tests scripts
.\.venv\Scripts\python.exe scripts/smoke.py --provider fixture
```

`scripts/smoke.py --provider public` درخواست واقعی فقط‌خواندنی می‌فرستد؛ پیش‌فرض آن fixture است. آزمون رسمیِ زنده به کلید کنار نیاز دارد. تست‌های عادی از پاسخ‌های کنترل‌شده استفاده می‌کنند.

گزارش بررسی انجام‌شده در `docs/verification.md` ثبت شده است؛ شامل ۶۶ تست موفق و آزمون واقعی جست‌وجو، جزئیات و ادامهٔ نتایج.

تحلیل اولیه در `docs/analysis-fa.md` و معماری اجراشده در `docs/architecture.md` هستند. کدهای انتخاب‌شده از پروژهٔ MIT در `src/divar_mcp/_vendor` قرار دارند و مجوزشان در `licenses/sepehr071-MIT.txt` حفظ شده است. از کد، متن یا برندِ مخزن محدودِ mmdju کپی نشده است؛ شرح کامل در `THIRD_PARTY_NOTICES.md` آمده است.