MCP Tools Reference: mapstools.googleapis.com

مرجع أدوات MCP:

يوضّح هذا المستند نقاط نهاية REST API التي يتم عرضها للمستخدمين وتُستخدَم لتفعيل أدوات "بروتوكول سياق النموذج" (MCP) عن بُعد من Google. تعمل واجهة برمجة التطبيقات هذه كوكيل آمن بين برنامج HTTP خارجي (مثل curl أو خدمة ويب) وخادم MCP الداخلي.

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

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

Curl Request 
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
}'

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

توضّح النماذج التالية كيفية استخدام curl لاستدعاء أداة MCP search_places.

Curl Request 
curl --location 'https://mapstools.googleapis.com/mcp'
--header 'content-type: application/json'
--header 'accept: application/json, text/event-stream'
--data '{
  "method": "tools/call",
  "params": {
    "name": search_places,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

الأداة: lookup_weather

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

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

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

  • الظروف الحالية: تتطلّب هذه السمة موقعًا جغرافيًا فقط (مثل مدينة أو عنوان). لا تحدِّد تاريخًا أو ساعة.

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

  • التوقعات اليومية: تتطلّب توفير موقع جغرافي وتاريخ كامل.

التعامل مع التواريخ (مهم): يجب تقديم التواريخ والساعات المقدَّمة من المستخدم حسب المنطقة الزمنية المحلية للموقع الجغرافي المطلوب. يجب تقسيم التواريخ إلى مَعلمات أعداد صحيحة منفصلة: السنة والشهر واليوم. التنسيق المطلوب لهذه المَعلمات هو: {"year": , "month": , "day": }

توضّح الأمثلة التالية كيفية استخدام curl لاستدعاء أداة lookup_weather MCP.

Curl Request 
curl --location 'https://mapstools.googleapis.com/mcp'
--header 'content-type: application/json'
--header 'accept: application/json, text/event-stream'
--data '{
  "method": "tools/call",
  "params": {
    "name": lookup_weather,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

الأداة: 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"}

توضّح العيّنات التالية كيفية استخدام curl لاستدعاء أداة MCP الخاصة بـ compute_routes.

Curl Request 
curl --location 'https://mapstools.googleapis.com/mcp'
--header 'content-type: application/json'
--header 'accept: application/json, text/event-stream'
--data '{
  "method": "tools/call",
  "params": {
    "name": compute_routes,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'