MCP Reference: mapstools.googleapis.com

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

إعداد الخادم

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

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

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

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

يحتوي خادم MCP الخاص بـ mapstools.googleapis.com على نقطة نهاية MCP التالية:

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

أدوات MCP

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • lat_lng: (object, {"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"}

التعرّف على مواصفات أداة 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
}'