فهرست ابزارهای MCP نشان
سرور MCP نشان ۱۷ ابزار در اختیار ایجنت قرار می‌دهد. ایجنت بر اساس پرسش کاربر خودش ابزار مناسب را انتخاب و فراخوانی می‌کند؛ این صفحه برای توسعه‌دهنده‌ای است که می‌خواهد بداند پشت هر پاسخ چه اتفاقی می‌افتد. خروجی هر ابزار همان پاسخ وب‌سرویس نشان است، پس جزئیات کامل فیلدها در صفحه‌ی همان وب‌سرویس آمده است.
محتوای این صفحه بر اساس نسخه‌ی 0.3.0 پروژه‌ی Neshan-MCP نوشته شده است. فهرست به‌روز ابزارها همیشه در کد پروژه و در پاسخ tools/list خود سرور در دسترس است.
مختصات در همه‌ی ابزارها به‌صورت عرض جغرافیایی (lat) و طول جغرافیایی (lng) است و فهرست نقاط به شکل [[lat, lng], ...] ارسال می‌شود.
جستجو و آدرس
| ابزار | کاربرد | پارامترهای اصلی | وب‌سرویس |
|---|---|---|---|
neshan_search | جستجوی مکان، آدرس و کسب‌وکار در اطراف یک نقطه. | term، lat، lng؛ اختیاری: محدوده‌ی جستجو (sw_lat، sw_lng، ne_lat، ne_lng) و دسته‌ی مکانی (layer_slug) | جستجو |
neshan_get_point_by_hash | جزئیات کامل یک مکان، مانند ساعت کاری و شماره تماس. | hash (مقدار poiHash از نتیجه‌ی neshan_search) | اطلاعات مکان‌های شاخص |
neshan_reverse_geocode | تبدیل مختصات به آدرس فارسی. | lat، lng | تبدیل مختصات به آدرس |
neshan_geocode | تبدیل آدرس متنی فارسی به مختصات. | address | تبدیل آدرس به مختصات |
neshan_geocode_plus | تبدیل آدرسی که پلاک یا نام یک مکان شاخص دارد به مختصات. | address؛ اختیاری: city، province، نقطه‌ی مرجع (bias_lat، bias_lng) و محدوده | تبدیل آدرس به مختصات |
neshan_get_point_by_hash فقط برای نتیجه‌هایی کار می‌کند که در خروجی neshan_search مقدار verified_details_available آن‌ها true است، یعنی صاحب کسب‌وکار پروفایل آن را تأیید کرده است. نبودن این اطلاعات به معنای بسته بودن مکان نیست. این ابزار هزینه‌ی بیشتری دارد، پس ایجنت فقط برای چند نتیجه‌ی منتخب آن را فراخوانی می‌کند.
neshan_geocode ارزان‌تر است و ابزار پیش‌فرض تبدیل آدرس است. ایجنت فقط وقتی سراغ neshan_geocode_plus می‌رود که آدرس پلاک دارد یا به یک مکان شاخص با نام اشاره می‌کند. دادن شهر، استان، نقطه‌ی مرجع یا محدوده به neshan_geocode_plus دقت پاسخ را بالا می‌برد.
مسیریابی
| ابزار | کاربرد | پارامترهای اصلی | وب‌سرویس |
|---|---|---|---|
neshan_direction | مسیر بین دو نقطه، با یا بدون توقف میانی. | مبدأ و مقصد (origin_lat، origin_lng، dest_lat، dest_lng)، traffic_mode، vehicle؛ اختیاری: waypoints، avoid_traffic_zone، avoid_odd_even_zone، alternative، bearing | مسیریابی |
neshan_distance_matrix | فاصله و زمان سفر برای همه‌ی جفت‌های مبدأ و مقصد. | origins، destinations | ماتریس فاصله |
neshan_tsp | بهترین ترتیب بازدید از چند مقصد. | waypoints (نقطه‌ی اول، شروع مسیر است)؛ اختیاری: round_trip، source_is_any_point، last_is_any_point | مسیر چندتوقفه (TSP) |
neshan_map_matching | تطبیق نقاط خام GPS با شبکه‌ی راه. | path_points | تطبیق نقشه |
neshan_isochrone | محدوده‌ی قابل دسترس از یک نقطه در زمان یا فاصله‌ی مشخص. | lat، lng و دست‌کم یکی از time (دقیقه) یا distance (کیلومتر)؛ اختیاری: polygon، denoise | ایزوکرون |
حالت‌های ترافیک در neshan_direction
پارامتر traffic_mode تعیین می‌کند ترافیک چطور در محاسبه‌ی مسیر لحاظ شود:
| مقدار | توضیحات | وب‌سرویس |
|---|---|---|
live | ترافیک لحظه‌ای؛ برای پرسش‌هایی مثل «اگر همین الان راه بیفتم، چقدر طول می‌کشد؟». مقدار پیش‌فرض. | مسیریابی |
no_traffic | سرعت ثابت راه‌ها، بدون در نظر گرفتن ترافیک. | مسیریابی بدون ترافیک |
typical | ترافیک براساس الگوی معمول که هر ۱۵ دقیقه به‌روز می‌شود؛ برای زمان رسیدن پایدار. | مسیریابی معمول |
historical | زمان رسیدن برای یک تاریخ و ساعت آینده براساس الگوهای تاریخی. | مسیریابی پیش‌بینی |
حالت historical فقط برای تهران، مشهد و کرج و تا یک هفته‌ی آینده کار می‌کند. در این حالت پارامترهای routing_type (DepartAt یا ArriveAt) و date_time (به قالب YYYY-MM-DDThh:mm و به وقت UTC) اجباری‌اند، vehicle باید car بماند و waypoints و avoid_odd_even_zone قابل استفاده نیستند. پارامتر bearing هم فقط در حالت‌های live و typical پذیرفته می‌شود.
مقدار vehicle یکی از car، motorcycle یا pedestrian است.
لجستیک
| ابزار | کاربرد | پارامترهای اصلی | وب‌سرویس |
|---|---|---|---|
neshan_vrp_logistic | تخصیص سفارش‌ها به چند وسیله‌ی نقلیه با رعایت ظرفیت، مهارت و بازه‌ی زمانی. | vehicles، jobs، depot؛ اختیاری: plan_time (میلی‌ثانیه)، solution_strategy، cost_type، exploration_level، routing_engine، balance_workload، use_time_balancing، use_traffic_multiplier | مسیریابی ناوگان (VRP) |
خروجی این ابزار شامل مسیر هر وسیله (routes)، خلاصه‌ی مسافت و زمان کل و تعداد سفارش‌های تخصیص‌نیافته (summary)، و پیام‌های نقض قیدها (violationMessages) است. هر سفارش فقط به وسیله‌ای تخصیص داده می‌شود که مهارت‌های (skills) مورد نیاز آن را داشته باشد.
نقشه
| ابزار | کاربرد | پارامترهای اصلی | وب‌سرویس |
|---|---|---|---|
neshan_static_map | تصویر PNG نقشه با مرکز یک نقطه. | lat، lng؛ اختیاری: zoom (۱ تا ۲۰)، width و height (۱۶ تا ۲۰۴۸ پیکسل)، map_type (day یا night)، marker | نقشه‌ی استاتیک |
neshan_static_map_arc | تصویر PNG نقشه با کمان بین دو نقطه، بدون محاسبه‌ی مسیر. | مبدأ و مقصد؛ اختیاری: ابعاد تصویر، map_type، dashed، color، نشانگر سفارشی (marker1_token، marker2_token) | نقشه‌ی استاتیک با کمان |
neshan_map_view | ساخت فایل HTML یک نقشه‌ی تعاملی با نشانگر و مسیر، برای باز کردن در مرورگر. | اختیاری: title، markers، routes، show_traffic، show_poi، map_key | کیت توسعه‌ی وب MapLibre |
neshan_map_view برای نمایش نقشه‌ی پایه به کلید Web SDK نشان (map_key) نیاز دارد که با کلید سرویس‌ها فرق دارد. بدون این کلید، نشانگرها و مسیرها رسم می‌شوند ولی کاشی‌های نقشه بارگذاری نمی‌شوند. برای رسم مسیر می‌توانید مقدار overview_polyline خروجی neshan_direction را به‌عنوان encoded_polyline به این ابزار بدهید. فایل ساخته‌شده روی همان سیستمی ذخیره می‌شود که سرور MCP روی آن اجرا می‌شود.
ترافیک
| ابزار | کاربرد | پارامترهای اصلی |
|---|---|---|
neshan_traffic_analytics | تحلیل الگوی ترافیک اطراف یک نقطه در ۲۴ ساعت گذشته. | lat، lng |
خروجی سه بخش دارد: امتیاز کلی ترافیک محل (kpi؛ عدد بزرگ‌تر یعنی ترافیک سنگین‌تر)، نمودار ۲۴ ساعته با یک امتیاز و کد رنگ برای هر ساعت (chart)، و تصویر نقشه‌ی محدوده با لایه‌ی ترافیک (static_map).
ابزارهای کمکی
| ابزار | کاربرد | پارامترهای اصلی |
|---|---|---|
neshan_deeplink | ساخت لینک باز کردن یک نقطه یا مسیریابی در اپلیکیشن نشان. | link_type (point یا routing)، مختصات نقطه یا مبدأ و مقصد؛ اختیاری: vehicle |
اگر اپلیکیشن نشان نصب باشد لینک مستقیم در آن باز می‌شود و در غیر این صورت به نسخه‌ی وب نشان می‌رود. ابزار هر دو نسخه‌ی Android/وب و iOS را برمی‌گرداند. در Android و وب فقط وسیله‌های car و motorcycle پشتیبانی می‌شوند.
خروجی برخی ابزارها، مانند neshan_direction، neshan_reverse_geocode، neshan_geocode و neshan_get_point_by_hash، هم یک بخش neshan_links دارد تا ایجنت بتواند نتیجه را برای باز کردن در اپلیکیشن یا وب نشان به کاربر بدهد.