MCP Reference: mapstools.googleapis.com

هذا خادم MCP توفّره أدوات تجربة الخرائط للوكلاء. يوفّر الخادم أدوات للمطوّرين لإنشاء تطبيقات LLM على "منصة خرائط Google".

يعمل خادم بروتوكول سياق النموذج (MCP) كخادم وكيل بين خدمة خارجية توفّر السياق أو البيانات أو الإمكانات لنموذج لغوي كبير (LLM) أو تطبيق ذكاء اصطناعي. تربط خوادم MCP تطبيقات الذكاء الاصطناعي بالأنظمة الخارجية، مثل قواعد البيانات وخدمات الويب، وتترجم ردودها إلى تنسيق يمكن لتطبيق الذكاء الاصطناعي فهمه.

إعداد الخادم

يجب تفعيل خوادم MCP وإعداد المصادقة قبل الاستخدام. لمزيد من المعلومات حول استخدام خوادم MCP عن بُعد في Google وGoogle Cloud، يُرجى الاطّلاع على نظرة عامة على خوادم MCP في Google Cloud.

نقاط نهاية الخادم

نقطة نهاية خدمة MCP هي عنوان الشبكة وواجهة الاتصال (عادةً ما تكون عنوان URL) لخادم MCP الذي يستخدمه تطبيق الذكاء الاصطناعي (المضيف لعميل MCP) لإنشاء اتصال آمن وموحّد. وهي نقطة الاتصال التي يستخدمها النموذج اللغوي الكبير لطلب السياق أو استدعاء أداة أو الوصول إلى مورد.

يحتوي خادم MCP لأدوات التجارب من خرائط Google للوكلاء على نقطة نهاية MCP العامة التالية:

  • https://mapstools.googleapis.com/mcp

أدوات MCP

أداة MCP هي وظيفة أو إمكانية قابلة للتنفيذ يوفّرها خادم MCP لنموذج لغوي كبير أو تطبيق ذكاء اصطناعي لتنفيذ إجراء في العالم الحقيقي.

الأدوات

يتضمّن خادم MCP‏ mapstools.googleapis.com الأدوات التالية:

أدوات MCP
search_places

يمكنك استدعاء هذه الأداة عندما يكون طلب المستخدم هو العثور على أماكن أو مؤسسات أو عناوين أو مواقع جغرافية أو معالم أو أي بحث آخر ذي صلة بـ "خرائط Google".

متطلبات الإدخال (مهمة):

  1. text_query (سلسلة - إلزامية): طلب البحث الأساسي. يجب أن يحدّد هذا بوضوح ما يبحث عنه المستخدم.

    • أمثلة: 'restaurants in New York' و'coffee shops near Golden Gate Park' و'SF MoMA' و'1600 Amphitheatre Pkwy, Mountain View, CA, USA' و'pets friendly parks in Manhattan, New York' و'date night restaurants in Chicago' و'accessible public libraries in Los Angeles'.
    • للحصول على تفاصيل مكان محدّد: أدرِج السمة المطلوبة (مثل 'Google Store Mountain View opening hours' أو 'SF MoMa phone number' أو 'Shoreline Park Mountain View address').

  2. ‫location_bias (عنصر - اختياري): استخدِم هذه المَعلمة لتحديد أولوية النتائج القريبة من منطقة جغرافية معيّنة.

    • التنسيق: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • الاستخدام:
      • للانحياز إلى نطاق جغرافي يبلغ 5 كيلومتر: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • للانحياز بشدة إلى النقطة المركزية: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (مع حذف radius_meters).

  3. language_code (سلسلة - اختيارية): اللغة التي سيظهر بها ملخّص نتائج البحث.

    • التنسيق: رمز لغة مكوّن من حرفَين (ISO 639-1)، متبوعًا اختياريًا بشرطة سفلية ورمز بلد مكوّن من حرفَين (ISO 3166-1 alpha-2)، مثل en أو ja أو en_US أو zh_CN أو es_MX. إذا لم يتم تقديم رمز اللغة، ستكون النتائج باللغة الإنجليزية.

  4. ‫region_code (سلسلة - اختياري): رمز CLDR للمنطقة بتنسيق Unicode الخاص بالمستخدم تُستخدَم هذه المَعلمة لعرض تفاصيل المكان، مثل اسم المكان الخاص بالمنطقة، إذا كان متاحًا. يمكن أن تؤثر المَعلمة في النتائج استنادًا إلى القانون الساري.

    • التنسيق: رمز بلد مكوّن من حرفَين (ISO 3166-1 alpha-2)، مثل US وCA.

  5. page_size (عدد صحيح - اختياري): الحد الأقصى لعدد الأماكن المطلوب عرضها، من 1 إلى 10. القيمة التلقائية هي 5. يجب ضبط القيمة على أكثر من 5 فقط عندما يريد المستخدم مقارنة أكثر من 5 أماكن. تؤدي القيم من 6 إلى 10 إلى زيادة التكلفة وزيادة وقت الاستجابة.

  6. include_extended_details (قيمة منطقية - اختياري): اضبط هذا الحقل على true عندما يتطلّب طلب المستخدم إحصاءات نوعية غنية أو ديناميكيات في الوقت الفعلي أو سمات كيانات متخصّصة. القيمة التلقائية هي false. يؤدي ضبط هذه القيمة على true إلى زيادة التكلفة وزمن الاستجابة.

تعليمات طلب استخدام الأداة:

  • معلومات عن الموقع الجغرافي للجهاز (مهمة): يجب أن يحتوي البحث على معلومات كافية عن الموقع الجغرافي للجهاز. إذا كان الموقع الجغرافي غامضًا (مثل "مطاعم بيتزا" فقط)، يجب تحديده في text_query (مثل "مطاعم بيتزا في نيويورك") أو استخدام المَعلمة location_bias. أدرِج اسم المدينة والولاية/المقاطعة والمنطقة/البلد إذا لزم الأمر لإزالة الغموض.

  • يجب دائمًا تقديم text_query الأكثر تحديدًا وثراءً بالسياق قدر الإمكان.

  • يجب استخدام location_bias فقط إذا تم توفير الإحداثيات بشكل صريح أو إذا كان استنتاج الموقع الجغرافي من سياق المستخدم المعروف مناسبًا وضروريًا للحصول على نتائج أفضل.

  • يجب أن تتم نسبة الناتج المستند إلى المصدر إلى المصدر باستخدام المعلومات من الحقل attribution عندما تكون متاحة.
lookup_weather تسترد هذه الواجهة معلومات بيئية شاملة لموقع جغرافي معيّن، بما في ذلك الطقس وجودة الهواء (مؤشر جودة الهواء والملوثات) وحبوب اللقاح (مستويات مسببات الحساسية من الأشجار والأعشاب والنباتات): الظروف الحالية والتوقعات/السجلّات لكل ساعة والتوقعات اليومية للطقس وجودة الهواء. أما بالنسبة إلى حبوب اللقاح، فتتوفّر توقعات يومية فقط (من اليوم إلى 4 أيام قادمة، ولا تتوفّر بيانات لكل ساعة أو بيانات سابقة). النطاقات البيئية والإمكانات المتاحة (capabilities: WEATHER وAIR_QUALITY وPOLLEN — مهمة): * الاختيار الصريح الإلزامي: يجب تضمين واحد على الأقل من WEATHER أو AIR_QUALITY أو POLLEN في capabilities في كل طلب. لا يُسمح بحذف capabilities. * الطلبات العامة أو الغامضة حول الأنشطة الخارجية (مجموعة كاملة من المعلومات حول الأنشطة الخارجية): إذا طرح المستخدم سؤالاً عامًا حول الأنشطة الخارجية أو السفر أو الظروف المحيطة بدون تقييده بمجال معيّن (مثلاً، "كيف هي الظروف الخارجية الآن للجري؟")، يجب تضمين جميع الإمكانات الثلاث بشكل صريح (capabilities: ["WEATHER", "AIR_QUALITY", "POLLEN"]) لعرض المجموعة الكاملة من المعلومات حول الأنشطة الخارجية (الطقس وجودة الهواء وحبوب اللقاح). بالنسبة إلى date أو hour في الماضي، يجب استبعاد POLLEN، لأنّه لا يتضمّن بيانات سابقة. * اختيار النطاق المستهدَف (طلبات بحث محدّدة): إذا طلب المستخدم تحديدًا نطاقًا واحدًا أو نطاقَين فقط (مثلاً، "ما هو مؤشر جودة الهواء في سياتل الآن؟")، يجب تضمين الإمكانات المطلوبة فقط (WEATHER و/أو AIR_QUALITY و/أو POLLEN). سيتم تنفيذ النطاقات المطلوبة فقط وعرضها. البيانات المحدّدة المتاحة حسب النطاق: * الطقس (weather): درجة الحرارة (الحالية، المحسوسة، القصوى/الدنيا، مؤشر الحرارة)، والرياح (السرعة، الهبّات، الاتجاه)، والأحداث الفلكية (الشروق/الغروب، طور القمر)، وهطول الأمطار (النوع، الاحتمالية، الكمية/التوقعات الكمية لهطول الأمطار)، والظروف الجوية (مؤشر الأشعة فوق البنفسجية، الرطوبة، الغطاء السحابي، احتمالية حدوث عاصفة رعدية، الضغط الجوي). * جودة الهواء (air_quality): مؤشرات جودة الهواء العالمية والمحلية (قيمة مؤشر جودة الهواء وفئته والملوّث السائد)، والنصائح الصحية لـ 7 مجموعات حساسية، وتركيزات الملوّثات (include_pollutant_concentration: true). لكل مؤشر ملوّث سائد خاص به، لذا يجب الإبلاغ عنه لكل مؤشر (على سبيل المثال، لا تقدِّم الملوّث الخاص بمؤشر جودة الهواء العالمي لمؤشر جودة الهواء في الولايات المتحدة). * حبوب اللقاح (pollen): مؤشر حبوب اللقاح العالمي (UPI، من 0 إلى 5) اليومي لكل فئة من الأشجار والأعشاب والحشائش ولكل نوع من النباتات (index.value مع index.category، على سبيل المثال 1 = "منخفض جدًا")، وحالة الموسم، والتفاعلات المتبادلة، والنصائح الصحية. * حقول حبوب اللقاح غير المتوفّرة: يشير عدم توفّر in_season إلى أنّ حبوب اللقاح ليست في موسمها. لا تذكر أنواع النباتات التي تظهر بدون index، إلا إذا سأل المستخدم عن ذلك النبات، وفي هذه الحالة، اذكر أنّه لم يتم الإبلاغ عن أي بيانات حول حبوب اللقاح الخاصة به اليوم (لا تستنتج مستوى). قواعد الموقع الجغرافي (مهمة): يجب تحديد الموقع الجغرافي المستهدف في location باستخدام حقل فرعي واحد فقط من الحقول الفرعية التالية في oneof: ‏1. الإحداثيات الجغرافية (lat_lng): * استخدِم هذه السمة عندما تكون إحداثيات خطوط العرض/الطول الدقيقة معروفة. * مثال: {"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}} 2. رقم تعريف المكان (place_id): * رقم تعريف مكان واضح على "خرائط Google" (مثلاً، تم الحصول عليه من search_places أو resolve_names). * مثال: {"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} 3. سلسلة العنوان (address): * مدينة/منطقة أو حي أو معلم أو نقطة اهتمام أو عنوان شارع أو رمز بريدي، ويُفضّل أن يكون مع المدينة/البلد. * مثال: {"location": {"address": "Paris, France"}} أوضاع الوقت والاستخدام (date وhour — مهمة): * مرجع المنطقة الزمنية المحلية: يجب التعبير عن جميع مدخلات date ({year, month, day}) وhour (0-23) في المنطقة الزمنية المدنية المحلية المطلوبة location (على سبيل المثال، يستخدم طلب البحث عن "Paris tomorrow at 13:00" التاريخ والساعة المحليين Europe/Paris 13)، وليس التوقيت العالمي المنسق أو المنطقة الزمنية للمتصل. * 1. الحالات الحالية (تم حذف date وhour): * يُرجى تقديم location والهدف capabilities (WEATHER وAIR_QUALITY وPOLLEN). يُرجى عدم تحديد date أو hour. * تعرض هذه المَعلمة "الظروف الحالية" (CC) في الوقت الفعلي للنطاقات المطلوبة (الطقس الحالي و/أو جودة الهواء في الساعة الحالية و/أو توقّعات حبوب اللقاح لليوم). * بالنسبة إلى جودة الهواء، تكون "الظروف الحالية" لساعة واحدة: لا تستخدِمها بمفردها للإجابة عن أسئلة حول جودة الهواء أو أسئلة عامة حول الأنشطة الخارجية اليوم ككل (استخدِم "طلبات البحث اليومية" أدناه). * ‫2. التوقعات/السجلّ لكل ساعة (تم تحديد date وhour 0-23): * يجب تقديم location وdate ({year, month, day}) وhour (0-23) وcapabilities المستهدَف. إذا تم ذكر الدقائق، يجب تقريبها إلى أقرب ساعة. * قيد مهم (يجب توفير السمة date عند ضبط السمة hour): لا يُسمح بتوفير السمة hour بدون السمة date (تم حذف السمة date وتم ضبط السمة hour)، وسيؤدي ذلك إلى حدوث خطأ. حتى عندما يسأل المستخدم عن ساعة محدّدة اليوم (مثلاً، "at 13:00 today")، يجب ملء كل من date (تاريخ اليوم في location) وhour. * يتم البحث كل ساعة عن بيانات الطقس و/أو جودة الهواء المطلوبة في YYYY-MM-DD-HH، ويتم البحث يوميًا عن بيانات حبوب اللقاح المطلوبة في YYYY-MM-DD. * أسئلة عن الطقس تتضمّن كلمة "متى": بالنسبة إلى الأسئلة عن الطقس التي تتضمّن كلمات متى / في أي وقت / أفضل وقت (مثل "what time will it stop raining?")، استخدِم طلبات WEATHER (date + hour) للحصول على معلومات عن الطقس في الساعات ذات الصلة. لا تتضمّن توقعات الطقس اليومية قيمًا لكل ساعة. بالنسبة إلى الأسئلة العامة حول الأنشطة الخارجية التي تتضمّن عبارة "متى / أفضل وقت" (مثل "when is the best time to go walking today?")، يجب إجراء هذه الطلبات كل ساعة WEATHER بالإضافة إلى الطلب الذي يغطي يومًا كاملاً للحصول على معلومات حول جودة الهواء (وحبوب اللقاح) الموضّحة ضمن "الطلبات اليومية". * ‫3. طلبات البحث اليومية (تم تحديد date وحذف hour): * يجب تقديم location وdate ({year, month, day} في التوقيت المدني المحلي المطلوب في location) بدون hour، وcapabilities المستهدَف لطلبات البحث عن يوم كامل (مثل "weather and pollen in London tomorrow"). * الأسئلة العامة حول جودة الهواء والأنشطة الخارجية لليوم: بالنسبة إلى الأسئلة حول جودة الهواء والأسئلة العامة حول الأنشطة الخارجية (التي تشمل جودة الهواء) لليوم (مثل "how will the air quality change today" و"is today a good day for a picnic?")، يجب ضبط date على تاريخ اليوم في location (مع حذف الساعة) للحصول على سلسلة جودة الهواء لكل ساعة في اليوم. لا يكفي طلب "الظروف الحالية" وحده لأنّه يعرض فقط جودة الهواء في الساعة الحالية. يمكنك إضافة طلب آخر إذا سأل المستخدم أيضًا عن "الآن". * النوافذ الزمنية لجودة الهواء: بالنسبة إلى سؤال حول جودة الهواء في نافذة زمنية خلال يوم واحد (مثل "air quality between noon and 6 PM")، يُفضَّل إجراء طلب واحد لبيانات يومية لهذا التاريخ وقراءة ساعات النافذة الزمنية من سلسلة جودة الهواء، بدلاً من أخذ عيّنات من ساعات فردية. إذا كنت تستخدم المكالمات بالساعة، عليك تغطية كل ساعة من الفترة الزمنية. * تعرض التوقعات اليومية لبيانات الطقس و/أو حبوب اللقاح المطلوبة، وسلسلة بيانات جودة الهواء لكل ساعة من اليوم والتي تغطي اليوم المحلي بالكامل (من الساعة 00:00 إلى الساعة 23:00 بالتوقيت المحلي): 24 ساعة سابقة لتاريخ سابق، و24 ساعة متوقعة لتاريخ مستقبلي، وبالنسبة إلى اليوم، الساعات السابقة (السجلّ) والساعة الحالية والساعات المتبقية (التوقعات). النطاقات الزمنية المتاحة حسب المجال: * الطقس: كل ساعة من آخر 24 ساعة وحتى 240 ساعة (10 أيام) قادمة (تتطلّب الساعات الماضية كلاً من date وhour)، ويوميًا لمدة تصل إلى 10 أيام بما في ذلك اليوم (اليوم وحتى 9 أيام قادمة)، ولا يتوفّر سجلّ يومي. * جودة الهواء: كل ساعة من 720 ساعة (30 يومًا) مضت وحتى 96 ساعة (4 أيام) قادمة، ويجب أن يتناسب طلب اليوم الكامل مع هذه الفترة (عمليًا اليوم من -29 يومًا إلى +3 أيام). * حبوب اللقاح: يوميًا فقط، من اليوم وحتى 4 أيام (5 أيام بما في ذلك اليوم)، ولا يتم عرض تواريخ سابقة، ويتم تجاهل hour. * (ملاحظة: في حال طلب عدة إمكانات وكان date/hour خارج أحد نطاقاتها، سيتم تنفيذ الطلب بنجاح وعرض الإمكانات المتوافقة فقط.) * الطلبات خارج النطاق: إذا كان التاريخ أو الساعة المطلوبان خارج النطاق المسموح به للنطاق أعلاه (على سبيل المثال، حبوب اللقاح لتاريخ سابق)، يُرجى الاتصال بـ lookup_weather للحصول على التاريخ/الساعة المطلوبين. يوضّح الخطأ النطاق المسموح به. لا تستخدِم تاريخًا أو ساعة أو نطاقًا مختلفًا كبديل. خيارات النطاق ومصدر البيانات: * اللغة (language_code): رمز اللغة الاختياري وفقًا لمعيار BCP-47 (مثلاً، "fr"). القيمة التلقائية هي "en". * وحدات الطقس (weather_options.units_system أو units_system): القيمة التلقائية هي METRIC. يجب ضبط هذه السمة على IMPERIAL (فهرنهايت/ميل في الساعة) إذا كان المستخدم يشير ضمنيًا إلى المعايير الأمريكية أو يطلب صراحةً استخدام الوحدات الإمبراطورية. يمكن استخدام هذه السمة في كلّ من weather_options.units_system (الخيار المفضّل) وunits_system على المستوى الأعلى، وإذا تم تحديد كليهما، يجب ألا يتعارضا. ‫* خيارات جودة الهواء (air_quality_options): اضبط include_pollutant_concentration: true عندما تكون هناك حاجة إلى تركيزات ملوّثات معيّنة (PM2.5 وPM10 وO3 وNO2 وSO2 وCO). يمكنك اختياريًا ضبط index_region_code (رمز بلد مكوّن من حرفَين وفقًا لمعيار ISO، مثل "US") لطلب مقياس محدّد لمؤشر جودة الهواء في منطقة معيّنة. يتضمّن الردّ تلقائيًا مؤشر جودة الهواء العالمي ومؤشر جودة الهواء الإقليمي للموقع الجغرافي. * تحديد المصدر: يجب تحديد مصدر المخرجات المستندة إلى معلومات موثوقة باستخدام الحقل attribution داخل كل حاوية نطاق يتم عرضها (weather.attribution وair_quality.attribution وpollen.attribution). * الأوقات المعروضة: تكون قيم جودة الهواء date_time بالتوقيت المحلي للموقع الجغرافي (بما في ذلك utc_offset). يجب عرضها كما هي. تكون أوقات الطقس date_time (الحالية وكل ساعة) وأوقات شروق الشمس وغروبها بالتوقيت العالمي المنسق (UTC). يجب تحويلها إلى التوقيت المحلي للموقع الجغرافي باستخدام time_zone. صنِّف جميع الأوقات على أنّها محلية.
compute_routes

تحسب هذه الخدمة مسارات السفر بين نقطة انطلاق ووجهة، ويمكن أن تتضمّن محطات توقّف وسيطة. تعرض المسافة والمدة لكل مسار.

متطلبات الإدخال (مهمة):

  1. ‫origin وdestination (عنصران - إلزاميان): يجب تقديم كل منهما باستخدام أحد الخيارات التالية فقط:

    • ‫address (سلسلة، مثل 'Eiffel Tower, Paris'): يتم حلّ الأماكن المسمّاة والمعالم والأنشطة التجارية مباشرةً، لذا لا تستدعِ search_places أولاً لمجرد الترميز الجغرافي لنقطة على المسار. يجب تضمين أي مدينة أو منطقة أو بلد ذكره المستخدم.
    • lat_lng (عنصر، {"latitude": number, "longitude": number}).
    • ‫place_id (سلسلة، مثل 'ChIJOwE_Id1w5EAR4Q27FkL6T_0')، على سبيل المثال من search_places.

  2. intermediate_waypoints (مصفوفة من العناصر - اختياري): ما يصل إلى 25 محطة توقّف للمرور بها، بالترتيب، بين نقطة الانطلاق والوجهة. التنسيق نفسه المستخدَم في origin. هذه الميزة غير متاحة مع TRANSIT. يجب تضمين المحطات التي طلبها المستخدم فقط، لأنّ تحديد أكثر من 10 نقاط على المسار سيؤدي إلى زيادة التكلفة وزمن الاستجابة.

  3. ‫travel_mode (تعداد - اختياري): DRIVE (تلقائي) أو WALK أو BICYCLE أو TRANSIT

  4. التوقيت (اختياري - اضبط قيمة واحدة على الأكثر): طوابع زمنية بتنسيق RFC 3339 مع فارق عن التوقيت العالمي المنسَّق، مثل '2026-09-19T08:00:00-07:00'. يتم ضبط الإعدادات التلقائية على المغادرة الآن. بالنسبة إلى TRANSIT، يمكن أن يصل الوقت إلى 7 أيام في الماضي أو إلى 100 يوم في المستقبل. بالنسبة إلى الأوضاع الأخرى، يمكن أن يصل الوقت إلى 365 يومًا في المستقبل ويجب ألا يكون في الماضي.

    • departure_time: يُستخدَم عندما يذكر المستخدم وقت مغادرته (مثلاً، "غدًا في الساعة 8 صباحًا").
    • arrival_time: يُستخدَم هذا المعامل عندما يحدّد المستخدم وقت الوصول (مثلاً، "أريد الوصول بحلول الساعة 9 صباحًا").

  5. ‫routing_preference (enum - اختياري):

    • ‫ROUTING_PREFERENCE_TRAFFIC_UNAWARE (تلقائي): يتجاهل حركة المرور المباشرة والحوادث وحالات الإغلاق. أقل وقت استجابة
    • ‫ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: يستخدم أحوال حركة المرور المباشرة عندما تكون متاحة. لا يتوفّر هذا الخيار لـ WALK أو BICYCLE. يجب ضبط هذه القيمة فقط عندما يسأل المستخدم عن حركة المرور أو الازدحام أو الوقت المقدّر للوصول المعدّل حسب حركة المرور. ويؤدي ذلك إلى زيادة التكلفة ووقت الاستجابة.

  6. location_bias (عنصر - اختياري): {"latitude": number, "longitude": number} يُستخدَم لإزالة الغموض عن أسماء الأماكن في عناوين النقاط على المسار. إذا كان الاسم غامضًا (مثل "الربيع") ولم يحدّد المستخدم منطقة، يجب الاحتفاظ بالاسم كما هو في address وضبط location_bias على المنطقة المقصودة بدلاً من تخمين منطقة.

  7. compute_alternative_routes (قيمة منطقية - اختيارية): يتم ضبطها على true فقط عندما يطلب المستخدم خيارات أو بدائل للمسار. الإعداد التلقائي هو false، والذي يعرض المسار المقترَح فقط.

  8. include_polyline (قيمة منطقية - اختياري): يتم ضبطه على true فقط عندما تكون هندسة المسار (encoded_polyline) مطلوبة. القيمة التلقائية هي false.

تعليمات طلب استخدام الأداة:

  • إذا لم يتم تحديد نقطة الانطلاق أو الوجهة، يجب أن تطلب من المستخدم توضيح ذلك قبل استدعاء الأداة.
  • بالنسبة إلى الأسئلة من نوع "ما المسافة بين "أ" و"ب"؟"، استخدِم "ب" كـ origin و"أ" كـ destination.

مثال على استدعاء الأداة: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

تعليمات الردّ:

  • عند طلب مسارات بديلة، يتم ترتيب المسارات من الأكثر إلى الأقل اقتراحًا.
  • إذا كانت السمة routes فارغة، أخبِر المستخدم بأنّه لم يتم العثور على أي مسار. لا تخمِّن المسار.
  • للعثور على أماكن على طول مسار DRIVE، مرِّر retrieval_token الخاص بالمسار إلى search_along_route. ويكون الرمز المميّز صالحًا لمدة 10 دقائق.
  • اذكر فقط الحقائق التي تعرضها الأداة. لا تخترع اتجاهات مفصّلة أو خطوط نقل عام أو محطات أو أرصفة أو عمليات نقل.
  • يجب أن تتم نسبة الناتج المستند إلى المصدر إلى المصدر باستخدام حقل attribution لكل مسار عندما يكون متاحًا.
search_along_route

يمكنك استدعاء هذه الأداة عندما يريد المستخدم العثور على أماكن أو أنشطة تجارية أو نقاط اهتمام على طول مسار السفر (مثلاً، "محطات وقود في طريقي إلى تاهو"، "مقاهٍ بين سان فرانسيسكو وسان خوسيه"). يؤدي استدعاء هذه الأداة إلى تكلفة أعلى من search_places، لذا استخدِم search_places بدلاً من ذلك عند البحث بالقرب من موقع جغرافي واحد بدلاً من البحث على طول مسار.

متطلبات الإدخال (مهمة):

  1. ‫text_query (سلسلة - إلزامية): وصف بلغة طبيعية لما يجب البحث عنه على طول المسار.

    • أمثلة: 'ev chargers' و'coffee' و'vegetarian restaurants' و'rest stops'

  2. مواصفات المسار (إلزامية - يجب تقديم سمة واحدة فقط من السمات التالية):

    • ‫retrieval_token (سلسلة): السمة retrieval_token التي يعرضها طلب compute_routes سابق لمسار DRIVE. يُفضَّل استخدام هذا الخيار عندما يكون المسار قد تم احتسابه مسبقًا. ويكون الرمز المميّز صالحًا لمدة 10 دقائق.
    • ‫route_endpoints (عنصر): السمتان origin وdestination للمسار. يجب تقديم كل منها باستخدام إحدى السمات address أو lat_lng أو place_id.
      • مثال: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • ‫encoded_polyline (سلسلة): خطوط متعدّدة مرمّزة تمثّل مسار DRIVE.

  3. travel_mode (enum - اختياري): DRIVE (تلقائي) أو WALK أو BICYCLE. لا يتوفّر كل من WALK وBICYCLE إلا مع route_endpoints. ‫"TRANSIT" غير متاح.

  4. ‫routing_preference (enum - اختياري):

    • ‫ROUTING_PREFERENCE_TRAFFIC_UNAWARE (تلقائي): يتم احتساب المسار والطرق البديلة بدون معلومات حركة المرور في الوقت الفعلي. أقل وقت استجابة
    • ‫ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: يستخدم أحوال حركة المرور المباشرة عندما تكون متاحة. لا يتوفّر هذا الخيار لـ WALK أو BICYCLE. يجب ضبط هذه السمة فقط عندما يسأل المستخدم عن حركة المرور أو الازدحام أو أوقات التحويلات المعدَّلة حسب حركة المرور. يؤدي إلى زيادة وقت الاستجابة.

  5. ‫include_extended_details (قيمة منطقية - اختيارية): يجب ضبطها على true فقط عندما يتطلّب الطلب إحصاءات مراجعة نوعية أو أصناف قائمة طعام أو عروض معيّنة أو أجواء أو نصائح للزوّار أو مستوى الازدحام أو مدى توفّر شاحن مركبة كهربائية أو أسعار الوقود أو تفاصيل نوعية غنية أخرى. القيمة التلقائية هي false. قد يؤدي تفعيلها إلى زيادة وقت الاستجابة.

  6. ‫language_code (سلسلة - اختيارية): لغة ملخّص النتائج وتفاصيل المكان، مثل en أو ja أو en-US. القيمة التلقائية هي en-US.

  7. ‫region_code (سلسلة - اختيارية): رمز منطقة CLDR بتنسيق Unicode للمستخدم، مثل US وCA.

تعليمات طلب استخدام الأداة:

  • تتضمّن كل نتيجة detour_summary (عند توفّرها) تصف المسافة الإضافية (localized_detour_distance)، والوقت الإضافي (detour_duration) الذي يستغرقه التوقّف في ذلك المكان، ما لم يتم تحديد المسار على أنّه encoded_polyline. استخدِمها لمقارنة الخيارات.
  • قد يتضمّن الرد summary اقتباسات مستندة إلى الصفر (مثل "[0]") تشير إلى إدخالات في results.
  • يجب أن يتم تحديد مصدر الناتج المستند إلى المصادر باستخدام حقل attribution لكل results[].place عندما يكون متاحًا.
resolve_names

تحوّل هذه الأداة قائمة مجمّعة من طلبات البحث عن مواقع جغرافية معيّنة (أسماء معالم أو عناوين دقيقة) إلى أرقام تعريف أماكن أساسية في "خرائط Google".

متطلبات الإدخال (مهمة):

  1. ‫queries (مصفوفة من العناصر - إلزامية): قائمة بطلبات البحث عن المواقع الجغرافية التي يجب حلّها. يمكنك تحديد ما يصل إلى 20 طلب بحث.

    • يجب أن يتضمّن كل عنصر طلب بحث ما يلي:
      • text (سلسلة - إلزامية): طلب البحث النصي الذي يمثّل اسم مكان أو عنوانًا معيّنًا لحلّه.
        • أمثلة: 'Googleplex, Mountain View, CA' و'1600 Amphitheatre Pkwy, Mountain View, CA' و'Eiffel Tower, Paris'

  2. ‫location_bias (عنصر - اختياري): استخدِم هذه المَعلمة لتحديد أولوية النتائج القريبة من منطقة جغرافية معيّنة.

    • التنسيق: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (سلسلة - اختيارية): رمز منطقة CLDR في Unicode (رمز بلد مكوّن من حرفَين، مثل US وCA) للمستخدم من أجل تحسين النتائج.

تعليمات طلب استخدام الأداة:

  • التحديد (مهم): يجب أن تمثّل طلبات البحث اسم مكان أو عنوانًا محدّدًا. لا يمكن إجراء عمليات بحث عامة مثل 'restaurants' أو أسماء سلاسل مثل 'Starbucks'.
  • يُرجى عدم استدعاء هذه الأداة إذا كانت الأدوات اللاحقة التي تخطّط لاستدعائها تقبل سلاسل العناوين أو أسماء الأماكن الأولية مباشرةً.

الحفظ في "خرائط Google":

  • يتضمّن الردّ حقل save_to_maps_url: رابط واحد إلى "خرائط Google" يحتوي على جميع الأماكن التي تم حلّها بنجاح.
  • عندما يريد المستخدم حفظ الأماكن التي تم حلّها أو مشاركتها أو فتحها كقائمة في "خرائط Google"، اعرض هذا الرابط له. يُرجى عدم إنشاء هذا الرابط بنفسك.

معالجة الأخطاء (مهمة):

  • هذه أداة للمعالجة على دفعات. قد يعرض الطلب "نتائج مختلطة" (على سبيل المثال، يتم حلّ بعض طلبات البحث بنجاح بينما يتعذّر حلّ البعض الآخر).
  • تضمن قائمة النتائج لـ results الربط بنسبة 1:1 مع مؤشرات queries المُدخَلة. سيؤدي طلب البحث الذي تعذّر تنفيذه إلى ظهور رسالة Result فارغة (لم يتم ضبط entity) في الفهرس المقابل في قائمة results.
  • يجب التحقّق من حقل الخريطة failed_requests في الاستجابة لتحديد فهرس طلب البحث الذي تعذّر تنفيذه. يمثّل مفتاح failed_requests الفهرس المستند إلى 0 لطلب البحث الذي تعذّر تنفيذه في الطلب. لا تفترض أنّ طلب الدفعة بالكامل قد تعذّر بسبب تعذّر جزئي.
resolve_maps_urls

تحوّل هذه الأداة قائمة بعناوين URL في "خرائط Google" إلى أرقام تعريف الأماكن الأساسية في "خرائط Google".

حالات استخدام هذه الأداة (مهم):

  • استخدِم هذه الأداة عندما يقدّم المستخدم رابطًا واحدًا أو أكثر من روابط المشاركة أو عناوين URL في "خرائط Google" (مثل https://maps.app.goo.gl/...‎ "https://www.google.com/maps/place/..." أو "https://maps.google.com/...") وتحتاج إلى استخراج أرقام تعريف الأماكن الأساسية الأساسية.
  • يمكنك تحديد ما يصل إلى 20 عنوان URL لحلّها في طلب مجمّع واحد.

متطلبات الإدخال (مهمة):

  • urls (صفيف من السلاسل - إلزامي): قائمة عناوين URL في "خرائط Google" المطلوب حلّها. يجب أن يكون كل عنوان URL صالحًا ويشير إلى مكان واحد على "خرائط Google".

الحفظ في "خرائط Google":

  • يتضمّن الردّ حقل save_to_maps_url: رابط واحد إلى "خرائط Google" يحتوي على جميع الأماكن التي تم حلّها بنجاح.
  • عندما يريد المستخدم حفظ الأماكن التي تم العثور عليها أو مشاركتها أو فتحها كقائمة في "خرائط Google" (مثلاً، جمع الأماكن التي تمت مشاركتها في محادثة)، اعرِض هذا الرابط للمستخدم. يُرجى عدم إنشاء هذا الرابط بنفسك.

معالجة الأخطاء (مهمة):

  • هذه أداة للمعالجة على دفعات. قد يعرض الطلب "نتائج مختلطة" (على سبيل المثال، يتم حلّ بعض عناوين URL بنجاح بينما يتعذّر حلّ البعض الآخر).
  • تضمن قائمة النتائج لـ entities الربط بنسبة 1:1 مع مؤشرات urls المُدخَلة. سيؤدي تعذُّر تحليل عنوان URL إلى ظهور رسالة Entity فارغة (لم يتم ضبط أي حقول) في الفهرس المقابل في قائمة entities.
  • يجب التحقّق من حقل الخريطة failed_requests في الاستجابة لتحديد فهرس عنوان URL الذي تعذّر إرساله. يمثّل مفتاح failed_requests الفهرس المستند إلى 0 لعنوان URL الذي تعذّر تنفيذه في الطلب. لا تفترض أنّ طلب الدفعة بالكامل قد تعذّر بسبب تعذّر جزئي.

الحصول على مواصفات أداة MCP

للحصول على مواصفات أدوات MCP لجميع الأدوات في خادم MCP، استخدِم طريقة tools/list. يوضّح المثال التالي كيفية استخدام curl لعرض جميع الأدوات ومواصفاتها المتاحة حاليًا في خادم MCP.

طلب Curl 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'