MCP Reference: mapstools.googleapis.com

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

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

إعداد الخادم

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

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

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

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

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

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

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

  • يجب أن تتم نسبة الناتج المستند إلى المصدر إلى المصدر باستخدام المعلومات من حقل attribution عندما تكون متاحة.
lookup_weather

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

البيانات المحدّدة المتاحة: درجة الحرارة (الحالية، المحسوسة، القصوى/الدنيا، مؤشر الحرارة)، والرياح (السرعة، الهبّات، الاتجاه)، والأحداث الفلكية (الشروق/الغروب، طور القمر)، وهطول الأمطار (النوع، الاحتمالية، الكمية/التوقعات الكمية لهطول الأمطار)، والظروف الجوية (مؤشر الأشعة فوق البنفسجية، الرطوبة، الغطاء السحابي، احتمالية حدوث عاصفة رعدية)، وعنوان الموقع الجغرافي المرمّز جغرافيًا.

الموقع الجغرافي وقواعد الموقع الجغرافي (مهم):

يتم تحديد الموقع الجغرافي المطلوب الحصول على بيانات الطقس له باستخدام الحقل location. هذا الحقل هو بنية "oneof"، ما يعني أنّه يجب تقديم قيمة لحقل فرعي واحد فقط من الحقول الفرعية الثلاثة للموقع الجغرافي أدناه لضمان البحث عن بيانات الطقس بدقة.

  1. الإحداثيات الجغرافية (lat_lng)

    • استخدِم هذا الخيار عندما يتم تزويدك بإحداثيات دقيقة لخطوط العرض/الطول.
    • مثال: {"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}} // لوس أنجلوس

  2. رقم تعريف المكان (place_id)

    • معرّف سلسلة واضح (رقم تعريف المكان على "خرائط Google")
    • يمكن جلب place_id من أداة search_places.
    • مثال: {"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} // برج إيفل

  3. سلسلة العنوان (address)

    • سلسلة ذات شكل حر تتطلب تحديدًا للترميز الجغرافي.
    • المدينة والمنطقة: يجب دائمًا تضمين المنطقة/البلد (مثلاً، "لندن، المملكة المتحدة"، وليس "لندن").
    • عنوان الشارع: أدخِل العنوان الكامل (مثلاً، "1600 Pennsylvania Ave NW, Washington, DC").
    • الرموز البريدية: يجب أن تكون مصحوبة باسم بلد (مثلاً، "90210، الولايات المتحدة"، وليس "90210").
    • مثال: {"location": {"address": "1600 Pennsylvania Ave NW, Washington, DC"}}

أوضاع الاستخدام:

  • الطقس الحالي: قدِّم location فقط. لا تحدِّد السمتَين date وhour.

  • التوقعات لكل ساعة: يجب تقديم location وdate وhour (من 0 إلى 23). يمكنك استخدامها لأوقات محدّدة (مثل "في الساعة 5 مساءً") أو عبارات مثل "خلال الساعات القليلة القادمة" أو "في وقت لاحق اليوم". إذا حدّد المستخدم الدقيقة، يتم التقريب إلى أقرب ساعة. لا يمكن عرض توقعات الطقس كل ساعة لأكثر من 120 ساعة من الآن. تتوفّر بيانات الطقس السابقة لكل ساعة لمدة تصل إلى 24 ساعة في الماضي.

  • التوقعات اليومية: قدِّم location وdate. لا تحدِّد قيمة hour. يُستخدم هذا التنسيق للطلبات العامة المتعلقة باليوم (مثل "الطقس غدًا" أو "الطقس يوم الجمعة" أو "الطقس في 25 ديسمبر"). إذا لم يكن تاريخ اليوم مذكورًا في السياق، عليك توضيحه مع المستخدم. لا تتوفّر التوقعات اليومية لأكثر من 10 أيام، بما في ذلك اليوم. لا تتوفّر بيانات الطقس السابقة.

قيود المَعلمات:

  • المناطق الزمنية: يجب أن تكون جميع إدخالات date وhour مرتبطة بالمنطقة الزمنية المحلية للموقع الجغرافي، وليس بالمنطقة الزمنية للمستخدم.
  • تنسيق التاريخ: يجب فصل الإدخالات إلى {year, month, day} أعداد صحيحة.
  • الوحدات: القيمة التلقائية هي METRIC. اضبط units_system على IMPERIAL للفهرنهايت/الأميال إذا كان المستخدم يشير إلى المعايير الأمريكية أو يطلبها صراحةً.

  • يجب أن تتم نسبة الناتج المستند إلى المصدر إلى المصدر باستخدام المعلومات من حقل attribution عندما تكون متاحة.
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 (مصفوفة من العناصر - اختياري): ما يصل إلى 10 محطات توقّف يجب المرور بها بالترتيب بين نقطة الانطلاق والوجهة. التنسيق نفسه المستخدَم في origin. هذه الميزة غير متاحة مع TRANSIT. يجب تضمين المحطات التي طلبها المستخدم فقط.

  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 فارغًا، أخبِر المستخدم بأنّه لم يتم العثور على أي مسار. لا تخمِّن المسار.
  • اذكر فقط الحقائق التي تعرضها الأداة. لا تخترع اتجاهات مفصّلة أو خطوط نقل عام أو محطات أو أرصفة أو عمليات نقل.
  • يجب أن يتم تحديد مصدر المخرجات المستندة إلى المصادر باستخدام حقل attribution لكل مسار عندما يكون متاحًا.
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 مطابقة تمامًا لمؤشرات الإدخال 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 مطابقة تمامًا لمؤشرات الإدخال 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
}'