Neshan MCP Server

با این پروژه، دستیارهای هوش مصنوعی مثل Claude Desktop یا Cursor به قابلیت‌های نقشه نشان دسترسی پیدا می‌کنند — یعنی می‌توانی مستقیم در چت با آن‌ها بگویی «مسیر خونه تا محل کارم رو با ترافیک الان نشونم بده» یا «نزدیک‌ترین کافه به این مختصات کجاست؟» و جواب را همان‌جا ببینی.

این پروژه یک MCP Server است: یک واسط استاندارد که سرویس‌های نشان را به شکلی در اختیار دستیار هوش مصنوعی می‌گذارد که خودش بتواند در لحظه تصمیم بگیرد از کدام‌شان استفاده کند.

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

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

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

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

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

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

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

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

کلید API را هم از پنل نشان بگیر (بخش «گرفتن و تنظیم کلید API» را ببین). همین — دستیارت الان به قابلیت‌های نقشه‌ی نشان دسترسی دارد.

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

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

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

نصب

pip install -e .

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

کلید را از پنل نشان بگیر، سپس یکی از دو روش زیر را انتخاب کن:

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

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

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

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

اجرا

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

یا با Docker:

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

اتصال به Claude Desktop

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

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

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

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

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

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

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

آیا کلید API رایگان است؟ نشان یک پلن رایگان برای شروع دارد؛ برای مصرف بیشتر باید طبق پلن‌های platform.neshan.org ارتقا بدهی.

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

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

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

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