MCP Tools Reference: mapstools.googleapis.com

الأداة: 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'.
  • لا تستدعِ هذه الأداة إذا كانت الأدوات النهائية التي تخطّط لاستخدامها تقبل سلاسل العناوين أو أسماء الأماكن الأولية مباشرةً.

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

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

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

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

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

طلب Curl 
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": "resolve_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

رسالة الطلب الخاصة بوظيفة ResolveNames

ResolveNamesRequest

تمثيل JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
الحقول
queries[]

object (LocationQuery)

الحقل مطلوب. قائمة بطلبات البحث عن المواقع الجغرافية المطلوب حلّها. يمكنك تحديد ما يصل إلى 20 طلب بحث.
locationBias

object (LocationBias)

اختيارية: منطقة اختيارية لتفضيل نتائج تحديد الموقع الجغرافي. في حال تحديد هذه المنطقة، ستكون نتائج تحديد الموقع الجغرافي متحيزة نحو الكيانات الأقرب إلى هذه المنطقة. يؤدي تضمين location_bias أو region_code غالبًا إلى تقديم نتائج أفضل من خلال تضييق نطاق البحث.

في حال تحديد كل من location_bias وregion_code، تكون الأولوية لـ location_bias على region_code.
regionCode

string

اختيارية: رمز منطقة اختياري لتفضيل نتائج تحديد الموقع الجغرافي. في حال تحديدها، ستكون نتائج الحلّ متحيزة نحو الكيانات التي تقع في المنطقة المحدّدة أو بالقرب منها. يجب أن يكون هذا رمز CLDR للمنطقة. على سبيل المثال، "US" أو "CA". يؤدي تضمين location_bias أو region_code غالبًا إلى تقديم نتائج أفضل من خلال تضييق نطاق البحث.

في حال تحديد كل من location_bias وregion_code، تكون الأولوية لـ location_bias على region_code.

LocationQuery

تمثيل JSON 
{
  "text": string
}
الحقول
text

string

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

LocationBias

تمثيل JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
الحقول
حقل الربط type نوع التحيز المرتبط بالموقع الجغرافي يمكن أن يكون التعليق type إحدى القيم التالية فقط:
viewport

object (Viewport)

إطار عرض محدّد بمربّع حدود.

إطار العرض

تمثيل JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
الحقول
low

object (LatLng)

الحقل مطلوب. النقطة السفلية لإطار العرض
high

object (LatLng)

الحقل مطلوب. النقطة العليا لإطار العرض

LatLng

تمثيل JSON 
{
  "latitude": number,
  "longitude": number
}
الحقول
latitude

number

تمثّل هذه السمة خط العرض بالدرجات. يجب أن يكون ضمن النطاق [-90.0, +90.0].
longitude

number

تمثّل هذه السمة خط الطول بالدرجات. يجب أن تكون القيمة ضمن النطاق [-180.0, +180.0].

مخطط النتائج

رسالة الردّ على ResolveNames

ResolveNamesResponse

تمثيل JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
الحقول
results[]

object (Result)

النتائج فقط. قائمة الكيانات التي تمّت تسويتها من طلبات البحث عن المواقع الجغرافية يتم ضمان الربط بنسبة 1:1 مع فهارس الطلب queries. يشير السلسلة الفارغة في الفهرس i إلى تعذُّر التحويل لهذا الطلب. إذا تعذّر إكمال عملية التحويل، يُرجى التحقّق من الحقل failed_requests لمعرفة حالة الخطأ.
failedRequests

map (key: integer, value: object (Status))

النتائج فقط. خريطة تعرض حالات الفشل الجزئية المفتاح هو فهرس الطلب الذي تعذّر تنفيذه في الحقل queries. القيمة هي حالة الخطأ التي توضّح سبب تعذُّر إكمال عملية التحويل.

عنصر يحتوي على قائمة بأزواج "key": value مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

النتائج فقط. رابط لحفظ جميع الكيانات التي تم حلّها بنجاح في "خرائط Google"

النتيجة

تمثيل JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
الحقول
entity

object (Entity)

النتائج فقط. الكيان الذي تمّت تسويته من طلب البحث عن الموقع الجغرافي.
confidence

enum (Confidence)

النتائج فقط. مستوى الثقة في الحلّ.

الكيان

تمثيل JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
الحقول
حقل الربط entity نوع العنصر الذي تمّت تسويته. يمكن أن يكون التعليق entity إحدى القيم التالية فقط:
place

string

اسم المورد الخاص بالمكان الذي تمّت تسويته.

FailedRequestsEntry

تمثيل JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
الحقول
key

integer
value

object (Status)

الحالة

تمثيل JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
الحقول
code

integer

هو رمز الحالة، ويجب أن يكون قيمة محدّدة مسبقًا من google.rpc.Code.
message

string

يشير إلى رسالة خطأ موجّهة للمطوّرين، ويجب أن تكون الرسالة بالإنجليزية. أما رسائل الخطأ الموجّهة للمستخدمين، فيجب ترجمتها وإرسالها في حقل google.rpc.Status.details أو ترجمتها من قِبل العميل.
details[]

object

يشير إلى قائمة بالرسائل التي تتضمّن تفاصيل الخطأ. تتوفّر مجموعة شائعة من أنواع الرسائل التي يمكن لواجهات برمجة التطبيقات استخدامها.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.

أي

تمثيل JSON 
{
  "typeUrl": string,
  "value": string
}
الحقول
typeUrl

string

تحدّد هذه السمة نوع رسالة Protobuf المتسلسلة باستخدام مرجع URI يتألف من بادئة تنتهي بشرطة مائلة واسم النوع المؤهَّل بالكامل.

مثال: type.googleapis.com/google.protobuf.StringValue

يجب أن يحتوي هذا السلسلة على حرف واحد على الأقل من /، ويجب أن يكون المحتوى بعد آخر / هو الاسم المؤهّل بالكامل للنوع في النموذج الأساسي، بدون نقطة بادئة. لا تكتب نظامًا على مراجع معرّف الموارد المنتظم (URI) هذه حتى لا تحاول البرامج التواصل معها.

البادئة اختيارية، ومن المتوقّع أن تزيل عمليات تنفيذ Protobuf كل ما يسبق آخر / لتحديد النوع. ‫type.googleapis.com/ هو بادئة تلقائية شائعة تتطلّبها بعض عمليات التنفيذ القديمة. لا تشير هذه البادئة إلى مصدر النوع، ولا يُتوقّع أن تستجيب معرّفات الموارد المنتظمة التي تحتوي عليها لأي طلبات.

يجب أن تكون جميع سلاسل عناوين URL من النوع مراجع URI قانونية مع القيود الإضافية (بالنسبة إلى تنسيق النص) التي يجب أن يتألف محتوى المرجع منها فقط من أحرف أبجدية رقمية وعلامات الهروب المشفرة بالنسبة المئوية والأحرف في المجموعة التالية (باستثناء علامات الاقتباس المزدوجة الخارجية): /-.~_!$&()*+,;=. على الرغم من أنّنا نسمح باستخدام ترميز النسبة المئوية، يجب ألا يتم إلغاء ترميزها في عمليات التنفيذ لتجنُّب حدوث التباس مع المحلّلات الحالية. على سبيل المثال، يجب رفض type.googleapis.com%2FFoo.

في التصميم الأصلي لـ Any، تمّت مراعاة إمكانية تشغيل خدمة تحليل الأنواع في عناوين URL هذه، ولكن لم تنفّذ Protobuf أي خدمة من هذا النوع، وتعتبر أنّ التواصل مع عناوين URL هذه يمثّل مشكلة ومصدرًا محتملاً لمشاكل الأمان. لا تحاول الاتصال بعناوين URL الخاصة بالأنواع.
value

string (bytes format)

تحتوي على تسلسل Protobuf للنوع الموصوف بواسطة type_url.

سلسلة بترميز base64

الثقة

مستوى الثقة في الحلّ.

عمليات التعداد
CONFIDENCE_UNSPECIFIED القيمة التلقائية هذه القيمة غير مستخدَمة.
MEDIUM يشير مستوى الثقة المتوسط إلى أنّ الحلّ صحيح على الأرجح، ولكن قد تكون هناك حلول أخرى محتملة.
HIGH يشير مستوى الموثوقية العالي إلى أنّ درجة الدقة صحيحة وتمثّل كيانًا جغرافيًا مكانيًا محدّدًا (مثل مكان محدّد).

التعليقات التوضيحية للأدوات

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

بالإضافة إلى سلسلة العنوان، يتم تحديد تلميحات القيم المنطقية التالية على النحو التالي:

  • ‫readOnlyHint: إذا كانت القيمة صحيحة، لن تعدّل الأداة بيئتها. القيمة التلقائية: false.
  • ‫destructiveHint: إذا كانت القيمة صحيحة، يمكن للأداة تنفيذ إجراءات مدمّرة. إذا كانت القيمة "خطأ"، يمكن للأداة تنفيذ إجراءات إضافية فقط. القيمة التلقائية: true
  • idempotentHint: إذا كانت القيمة صحيحة، لن يكون لاستدعاء الأداة بشكل متكرر باستخدام الوسيطات نفسها أي تأثير إضافي على بيئتها. القيمة التلقائية: false.
  • openWorldHint: إذا كانت القيمة صحيحة، يمكن للأداة التفاعل مع "عالم مفتوح" من الكيانات الخارجية. إذا كانت القيمة false، يمكن للأداة التفاعل مع الكيانات الداخلية فقط. على سبيل المثال، ستكون أداة البحث على الويب عالمًا مفتوحًا، بينما لن تكون أداة الذاكرة عالمًا مفتوحًا.

تلميح تدميري: ❌ | تلميح متكرّر: ❌ | تلميح للقراءة فقط: ✅ | تلميح للعالم المفتوح: ❌