MCP Reference: mapstools.googleapis.com

هذا خادم MCP مقدَّم من Maps Grounding Lite API. يوفّر الخادم أدوات للمطوّرين لإنشاء تطبيقات نماذج لغوية كبيرة (LLM) استنادًا إلى "منصة خرائط Google".

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

إعداد الخادم

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

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

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

يحتوي خادم MCP في Maps Grounding Lite API على نقطة نهاية 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 (سلسلة - اختيارية): رمز Unicode CLDR للمنطقة التي يقيم فيها المستخدِم. تُستخدَم هذه المَعلمة لعرض تفاصيل المكان، مثل اسم المكان الخاص بالمنطقة، إذا كان متاحًا. يمكن أن تؤثر المَعلمة في النتائج استنادًا إلى القانون الساري.

    • التنسيق: رمز بلد مكوّن من حرفَين (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}}} // Los Angeles

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

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

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

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

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

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

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

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

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

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

  • يجب إسناد الناتج المستند إلى المصدر باستخدام المعلومات من حقل attribution متى توفّرت.
compute_routes

تحسب هذه الأداة مسارًا للسفر بين نقطة انطلاق ووجهة محدّدتَين. أوضاع السفر المتاحة: DRIVE (تلقائيًا) وWALK.

متطلبات الإدخال (مهمة): تتطلب هذه الأداة نقطة الانطلاق والوجهة. يجب تقديم كل منهما باستخدام إحدى الطرق التالية، مع تضمينها في الحقل الخاص بها:

  • address: (سلسلة، مثلاً "Eiffel Tower, Paris"). ملاحظة: كلما كانت تفاصيل العنوان المُدخَل أكثر دقة أو تحديدًا، كانت النتائج أفضل.

  • lat_lng: (كائن، {"latitude": number, "longitude": number})

  • place_id: (سلسلة، مثلاً "ChIJOwE_Id1w5EAR4Q27FkL6T_0") ملاحظة: يمكن الحصول على رقم التعريف هذا من أداة search_places. يُسمح بأي تركيبة من أنواع الإدخال (مثلاً، نقطة الانطلاق حسب العنوان والوجهة حسب lat_lng). إذا كانت نقطة الانطلاق أو الوجهة مفقودة، يجب أن تطلب من المستخدِم توضيحها قبل محاولة استدعاء الأداة.

مثال على استدعاء الأداة: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"travel_mode":"DRIVE"}

  • يجب إسناد الناتج المستند إلى المصدر باستخدام المعلومات من حقل 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 (سلسلة - اختيارية): رمز Unicode CLDR للمنطقة (رمز بلد مكوّن من حرفَين، مثلاً US أو CA) الخاص بالمستخدِم لترتيب النتائج حسب الأولوية.

تعليمات لاستدعاء الأداة:

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

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

  • هذه أداة معالجة على دفعات. قد يعرض الطلب "نتائج مختلطة" (مثلاً، يتم تحويل بعض طلبات البحث بنجاح بينما يتعذّر تحويل البعض الآخر).
  • يُضمن أن تتطابق قائمة 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 عنوان URL صالحًا في "خرائط 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
}'