# Neshan MCP Server

با این پروژه، دستیارهای هوش مصنوعی مثل **Claude Desktop** یا **Cursor** به قابلیت‌های نقشه [نشان](https://platform.neshan.org) دسترسی پیدا می‌کنند — یعنی می‌توانی مستقیم در چت با آن‌ها بگویی *«مسیر خونه تا محل کارم رو با ترافیک الان نشونم بده»* یا *«نزدیک‌ترین کافه به این مختصات کجاست؟»* و جواب را همان‌جا ببینی.

این پروژه یک [MCP Server](https://modelcontextprotocol.io) است: یک واسط استاندارد که سرویس‌های نشان را به شکلی در اختیار دستیار هوش مصنوعی می‌گذارد که خودش بتواند در لحظه تصمیم بگیرد از کدام‌شان استفاده کند.

## چه کارهایی می‌توان با آن انجام داد؟

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

- **جستجوی مکان** — پیدا کردن آدرس، کسب‌وکار یا نقطه‌ی موردنظر با اسم یا توضیح
- **تبدیل آدرس ↔ مختصات** — گرفتن آدرس از روی مختصات جغرافیایی یا برعکس
- **مسیریابی** — مسیر بین دو یا چند نقطه برای خودرو، موتور یا پیاده؛ با ترافیک لحظه‌ای، بدون ترافیک، یا بر اساس الگوی معمول/تاریخی
- **بهینه‌سازی مسیر چند ایستگاهی (TSP)** — بهترین ترتیب سر زدن به چند مقصد
- **تطبیق مسیر با جاده (Map Matching)** — تبدیل یک رشته نقطه GPS خام به مسیر واقعی روی جاده
- **ناحیه دسترس‌پذیری (Isochrone)** — مشخص کردن محدوده‌ای که در زمان/فاصله مشخص از یک نقطه قابل دسترسی است
- **ماتریس فاصله/زمان** — فاصله و زمان سفر بین چند مبدا و مقصد به‌صورت هم‌زمان
- **مسیریابی ناوگان (VRP)** — تخصیص بهینه‌ی سفارش‌ها به چند وسیله نقلیه با در نظر گرفتن ظرفیت و بازه زمانی
- **نقشه استاتیک** — گرفتن یک تصویر نقشه از یک نقطه، یا نقشه‌ای با کمانی بین مبدا و مقصد
- **نقشه تعاملی** — ساخت یک صفحه نقشه با نشانگر و مسیر، قابل باز کردن در مرورگر
- **تحلیل ترافیک** — وضعیت ترافیک یک منطقه در ۲۴ ساعت گذشته
- **جزئیات یک مکان** — گرفتن اطلاعات کامل یک نتیجه جستجو (آدرس، دسته‌بندی، محله)

همه‌ی این‌ها از طریق مکالمه‌ی طبیعی با دستیار اتفاق می‌افتد؛ خودت لازم نیست چیزی درباره‌ی API یا اندپوینت‌ها بدانی.

## سریع‌ترین راه: استفاده از سرور آماده

نیازی به نصب یا اجرای چیزی نیست — کافی است این را به تنظیمات کلاینت خودت (Claude Desktop، Cursor و…) اضافه کنی:

```json
{
  "mcpServers": {
    "neshan": {
      "type": "http",
      "url": "https://platform-stage.rajman.org/mcp",
      "headers": { "Neshan-Api-Key": "کلید_شما_اینجا" }
    }
  }
}
```

> آدرس سرور آماده: `https://platform-stage.rajman.org/mcp`

کلید API را هم از [پنل نشان](https://platform.neshan.org) بگیر (بخش «گرفتن و تنظیم کلید API» را ببین). همین — دستیارت الان به قابلیت‌های نقشه‌ی نشان دسترسی دارد.

اگر ترجیح می‌دهی سرور را خودت روی سیستم/سرور خودت اجرا کنی، ادامه‌ی این راهنما را دنبال کن.

## چیزهایی که لازم داری (برای اجرای خودت)

1. **Python 3.10 یا بالاتر**
2. **کلید API نشان** — از [platform.neshan.org](https://platform.neshan.org) ثبت‌نام کن و کلید سرویس(های) موردنظرت را بگیر (رایگان برای شروع)
3. یکی از این کلاینت‌ها: Claude Desktop، Cursor، یا هر کلاینت دیگری که از MCP پشتیبانی می‌کند

## نصب

```bash
pip install -e .
```

## گرفتن و تنظیم کلید API

کلید را از [پنل نشان](https://platform.neshan.org) بگیر، سپس یکی از دو روش زیر را انتخاب کن:

**روش ۱ — فایل env (ساده‌ترین حالت، برای Claude Desktop توصیه می‌شود):**

```bash
cp .env.example .env
# داخل فایل .env مقدار NESHAN_API_KEY را با کلید خودت جایگزین کن
```

**روش ۲ — ارسال کلید در هدر درخواست (برای حالت HTTP):**

اگر سرور را به‌صورت HTTP اجرا می‌کنی، می‌توانی کلید را در هر اتصال جداگانه بفرستی و نیازی به فایل env نیست (بخش «اتصال کلاینت» را ببین).

## اجرا

```bash
neshan-mcp          # حالت پیش‌فرض، برای Claude Desktop / Cursor
```

یا با Docker:

```bash
docker build -t neshan-mcp .
docker run -p 3000:3000 --env-file .env neshan-mcp
```

## اتصال به Claude Desktop

فایل تنظیمات Claude Desktop را باز کن و این را اضافه کن:

```json
{
  "mcpServers": {
    "neshan": {
      "command": "neshan-mcp",
      "env": { "NESHAN_API_KEY": "کلید_شما_اینجا" }
    }
  }
}
```

Claude Desktop را ری‌استارت کن — از این به بعد می‌توانی مستقیم درباره‌ی نقشه، مسیر و آدرس از آن بپرسی.

## اتصال از طریق HTTP (Cursor یا کلاینت‌های دیگر)

اگر سرور را با `neshan-mcp-http` اجرا کرده‌ای:

```json
{
  "mcpServers": {
    "neshan": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Neshan-Api-Key": "کلید_شما_اینجا" }
    }
  }
}
```

## سوالات متداول

**آیا کلید API رایگان است؟**
نشان یک پلن رایگان برای شروع دارد؛ برای مصرف بیشتر باید طبق پلن‌های [platform.neshan.org](https://platform.neshan.org) ارتقا بدهی.

**می‌توانم فقط بخشی از سرویس‌ها را فعال کنم؟**
بله — برای هر سرویس (جستجو، مسیریابی، نقشه استاتیک و…) می‌توانی کلید جدا بگیری و جدا تنظیم کنی؛ کافی است در فایل `.env` مقدار `NESHAN_KEY_<SERVICE>` را ست کنی (مثلاً `NESHAN_KEY_STATIC`).

**خطای مربوط به کلید می‌گیرم، چه کار کنم؟**
مطمئن شو کلید درست کپی شده و در پنل نشان برای IP/دامنه‌ای که از آن درخواست می‌زنی محدودیتی نگذاشته باشی.

## مستندات و پشتیبانی

- مستندات کامل API نشان: https://platform.neshan.org/docs